prosody-nodejs/docs/API.md

API Documentation

Core Classes

Server

Main server class that orchestrates all components.

const Server = require('./core/server');
const server = new Server(config);

await server.initialize();
await server.start();

Methods

• async initialize() - Initialize server components
• async start() - Start all servers
• async stop() - Stop all servers gracefully
• getStatus() - Get server status

ConfigManager

Singleton configuration manager.

const ConfigManager = require('./core/config-manager');
const config = ConfigManager.getInstance();

await config.load('./config.yaml');
const port = config.get('network.c2s.port', 5222);

Methods

• async load(configPath) - Load configuration
• get(key, defaultValue) - Get configuration value
• set(key, value) - Set configuration value
• has(key) - Check if key exists
• getAll() - Get all configuration

SessionManager

Manages active client sessions.

const session = sessionManager.createSession({
  id: 'session-id',
  jid: 'user@domain/resource',
  type: 'c2s'
});

Methods

• createSession(options) - Create new session
• getSession(sessionId) - Get session by ID
• getSessionByJid(jid) - Get session by full JID
• getSessionsByBareJid(bareJid) - Get all sessions for bare JID
• getBestSessionForBareJid(bareJid) - Get best session (highest priority)
• updateSession(sessionId, updates) - Update session
• authenticateSession(sessionId, jid, resource) - Authenticate session
• closeSession(sessionId, reason) - Close session
• getSessionCount() - Get total session count
• getAllSessions() - Get all sessions

StanzaRouter

Routes XMPP stanzas to their destinations.

stanzaRouter.route(stanza, session);

Methods

• route(stanza, session) - Route a stanza
• addFilter(filter) - Add routing filter
• removeFilter(filter) - Remove routing filter
• sendError(stanza, session, errorType) - Send error response

Events

• message - Message stanza routed
• presence - Presence stanza routed
• iq - IQ stanza routed
• stanza:routed - Any stanza routed
• stanza:recipient-unavailable - Recipient not found

HostManager

Manages virtual hosts.

const host = hostManager.addHost({
  domain: 'example.com',
  enabled: true,
  modules: ['roster', 'disco']
});

Methods

• async initialize() - Initialize host manager
• addHost(hostConfig) - Add virtual host
• removeHost(domain) - Remove virtual host
• getHost(domain) - Get host by domain
• hasHost(domain) - Check if host exists
• getHosts() - Get all host domains
• getEnabledHosts() - Get enabled host domains
• isLocalJid(jid) - Check if JID is local

ModuleManager

Manages server modules.

await moduleManager.loadModuleForHost('localhost', 'disco');

Methods

• async initialize() - Initialize module manager
• registerModuleDefinition(name, definition) - Register module
• async loadGlobalModule(moduleName) - Load global module
• async loadModuleForHost(host, moduleName) - Load module for host
• async loadModulesForAllHosts() - Load modules for all hosts
• async unloadModule(host, moduleName) - Unload module
• async reloadModule(host, moduleName) - Reload module
• getModule(host, moduleName) - Get module instance
• getLoadedModules(host) - Get loaded module names
• isModuleLoaded(host, moduleName) - Check if module loaded

StorageManager

Manages data persistence.

const store = storageManager.getStore('localhost', 'roster');
await store.set('user@localhost', rosterData);

Methods

• async initialize() - Initialize storage
• getStore(host, name) - Get storage store
• async shutdown() - Shutdown storage

Store

Key-value store interface.

const store = storageManager.getStore(host, name);

await store.set('key', value);
const value = await store.get('key');
await store.delete('key');

Methods

• async get(key) - Get value
• async set(key, value) - Set value
• async delete(key) - Delete value
• async has(key) - Check if key exists
• async keys() - Get all keys
• async values() - Get all values
• async entries() - Get all entries
• async clear() - Clear all data
• async size() - Get size
• async find(predicate) - Find values matching predicate
• async findOne(predicate) - Find first value matching predicate

Network Servers

C2SServer

Client-to-Server connection handler.

const c2s = new C2SServer(config, {
  sessionManager,
  stanzaRouter,
  moduleManager
});

await c2s.start();

Events

• session:authenticated - Client authenticated

BOSHServer

HTTP binding (BOSH) server.

const bosh = new BOSHServer(config, {
  sessionManager,
  stanzaRouter
});

await bosh.start();

WebSocketServer

WebSocket XMPP server.

const ws = new WebSocketServer(config, {
  sessionManager,
  stanzaRouter
});

await ws.start();

S2SServer

Server-to-Server federation.

const s2s = new S2SServer(config, {
  sessionManager,
  stanzaRouter
});

await s2s.start();

ComponentServer

External component handler.

const component = new ComponentServer(config, {
  stanzaRouter
});

await component.start();

Utilities

Logger

Winston-based logger.

const Logger = require('./utils/logger');
const logger = Logger.createLogger('mymodule');

logger.info('Information message');
logger.warn('Warning message');
logger.error('Error message', error);
logger.debug('Debug message');

Data Types

Session Object

{
  id: 'session-123',
  jid: 'user@domain/resource',
  bareJid: 'user@domain',
  resource: 'resource',
  authenticated: true,
  type: 'c2s',
  priority: 0,
  presence: <presence/>,
  createdAt: 1234567890,
  lastActivity: 1234567890,
  features: Set(['carbons', 'csi']),
  metadata: {}
}

Stanza Object (ltx)

const ltx = require('ltx');

const message = new ltx.Element('message', {
  to: 'user@domain',
  from: 'sender@domain',
  type: 'chat'
}).c('body').t('Hello!');

Module API

See MODULE_DEVELOPMENT.md for detailed module API documentation.

Error Handling

All async operations should be wrapped in try-catch:

try {
  await server.start();
} catch (error) {
  logger.error('Failed to start server:', error);
  process.exit(1);
}

Events

The server uses EventEmitter for event-driven architecture:

sessionManager.on('session:authenticated', (session) => {
  console.log('User authenticated:', session.jid);
});

stanzaRouter.on('message', (stanza, session) => {
  console.log('Message received');
});

Configuration Schema

See CONFIGURATION.md for complete configuration schema.