330
docs/API.md
Archivo normal
330
docs/API.md
Archivo normal
@@ -0,0 +1,330 @@
|
||||
# API Documentation
|
||||
|
||||
## Core Classes
|
||||
|
||||
### Server
|
||||
|
||||
Main server class that orchestrates all components.
|
||||
|
||||
```javascript
|
||||
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.
|
||||
|
||||
```javascript
|
||||
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.
|
||||
|
||||
```javascript
|
||||
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.
|
||||
|
||||
```javascript
|
||||
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.
|
||||
|
||||
```javascript
|
||||
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.
|
||||
|
||||
```javascript
|
||||
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.
|
||||
|
||||
```javascript
|
||||
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.
|
||||
|
||||
```javascript
|
||||
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.
|
||||
|
||||
```javascript
|
||||
const c2s = new C2SServer(config, {
|
||||
sessionManager,
|
||||
stanzaRouter,
|
||||
moduleManager
|
||||
});
|
||||
|
||||
await c2s.start();
|
||||
```
|
||||
|
||||
#### Events
|
||||
|
||||
- `session:authenticated` - Client authenticated
|
||||
|
||||
### BOSHServer
|
||||
|
||||
HTTP binding (BOSH) server.
|
||||
|
||||
```javascript
|
||||
const bosh = new BOSHServer(config, {
|
||||
sessionManager,
|
||||
stanzaRouter
|
||||
});
|
||||
|
||||
await bosh.start();
|
||||
```
|
||||
|
||||
### WebSocketServer
|
||||
|
||||
WebSocket XMPP server.
|
||||
|
||||
```javascript
|
||||
const ws = new WebSocketServer(config, {
|
||||
sessionManager,
|
||||
stanzaRouter
|
||||
});
|
||||
|
||||
await ws.start();
|
||||
```
|
||||
|
||||
### S2SServer
|
||||
|
||||
Server-to-Server federation.
|
||||
|
||||
```javascript
|
||||
const s2s = new S2SServer(config, {
|
||||
sessionManager,
|
||||
stanzaRouter
|
||||
});
|
||||
|
||||
await s2s.start();
|
||||
```
|
||||
|
||||
### ComponentServer
|
||||
|
||||
External component handler.
|
||||
|
||||
```javascript
|
||||
const component = new ComponentServer(config, {
|
||||
stanzaRouter
|
||||
});
|
||||
|
||||
await component.start();
|
||||
```
|
||||
|
||||
## Utilities
|
||||
|
||||
### Logger
|
||||
|
||||
Winston-based logger.
|
||||
|
||||
```javascript
|
||||
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
|
||||
|
||||
```javascript
|
||||
{
|
||||
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)
|
||||
|
||||
```javascript
|
||||
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](MODULE_DEVELOPMENT.md) for detailed module API documentation.
|
||||
|
||||
## Error Handling
|
||||
|
||||
All async operations should be wrapped in try-catch:
|
||||
|
||||
```javascript
|
||||
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:
|
||||
|
||||
```javascript
|
||||
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](CONFIGURATION.md) for complete configuration schema.
|
||||
Referencia en una nueva incidencia
Block a user