Server SDK Reference

Complete reference for sockr-server. All classes, methods, configuration options, plugins, and adapters.

SocketServer

The central class that wires together the HTTP server, Socket.IO, plugins, and providers.

import { SocketServer } from 'sockr-server';

const server = new SocketServer(config?: ServerConfig);

ServerConfig

All fields are optional. Defaults are production-friendly out of the box.

Initialization Methods

Call exactly one of these before registering plugins. All return this for chaining.

createStandalone(): this

Creates and owns an internal HTTP server. Use listen() to start it.

server.createStandalone().useAuth(handler).useMessaging();
await server.listen(3000);

attach(httpServer: HTTPServer | HTTPSServer): this

Attaches Socket.IO to an existing Node.js HTTP or HTTPS server. After registering plugins, call initialize() (not listen()), then start your own server.

import { createServer } from 'http';
const httpServer = createServer(app);
server.attach(httpServer).useAuth(handler).useMessaging();
await server.initialize();
httpServer.listen(3000);

attachToExpress(app: Express): this

Wraps an Express app in an HTTP server internally. Use listen() to start.

server.attachToExpress(expressApp).useAuth(handler).useMessaging();
await server.listen(3000);

Plugin Registration

All plugin methods return this for fluent chaining. Register plugins before calling listen() or initialize().

useAuth(handler: AuthHandler): this

Enables token-based authentication. AuthHandler is defined as:

type AuthHandler = (token: string) => Promise<{ userId: string } | null>;

Return { userId } to authenticate, or null to reject. Rejected connections receive an auth_error event.

usePresence(): this

Enables online/offline presence broadcasting. Broadcasts user_online when a user authenticates and user_offline when their last socket disconnects.

useMessaging(): this

Enables direct 1:1 messaging, read receipts, typing indicators, and message history retrieval. Requires useAuth().

useGroupMessaging(): this

Enables full group chat: create, join, leave, group messaging, group typing indicators, and group message history. Requires useAuth().

useVoice(config?: VoiceConfig): this

Enables WebRTC P2P voice (and video) calling via ICE/STUN/TURN signaling. Requires useAuth(). Pass an optional VoiceConfig to supply ICE servers and TURN credentials, or read them from the top-level voice field of ServerConfig.

server.useVoice({
  iceServers: [{ urls: 'stun:stun.l.google.com:19302' }],
  turn: {
    urls: 'turn:turn.example.com:3478',
    secret: process.env.TURN_SECRET!,
    ttl: 3600,
  },
});

useConference(sfuProvider: ISFUProvider, sfuUrl: string): this

Enables SFU-based group conference calling. The sfuProvider creates rooms and generates access tokens on the server; the sfuUrl is delivered to clients so they can connect directly to the SFU. Requires useAuth() and useGroupMessaging().

import { LiveKitSFUProvider } from 'sockr-server';

server.useConference(
  new LiveKitSFUProvider({
    apiKey: process.env.LIVEKIT_API_KEY!,
    apiSecret: process.env.LIVEKIT_API_SECRET!,
    host: 'https://your-livekit.example.com',
  }),
  'wss://your-livekit.example.com'
);

use(plugin: Plugin): this

Register a custom plugin. See Custom Plugins.

Lifecycle Methods

listen(port?: number): Promise<void>

Connects all providers, initializes plugins, then starts listening. Use with createStandalone() or attachToExpress(). The port argument overrides the config value.

initialize(): Promise<this>

Connects providers and initializes plugins without starting a listener. Use when attached to an external HTTP server.

close(): Promise<void>

Disconnects all providers and closes Socket.IO (and the HTTP server if owned by Sockr).

Accessors

AuthPlugin

Registered via .useAuth(handler). Handles the authentication handshake.

Flow

1. Client connects and emits authenticate with { token: string }.
2. Server calls your AuthHandler with the token.
3. On success: server emits authenticated with { userId, socketId } to the client, then fires the internal authenticated event to trigger message flushing and group restore.
4. On failure: server emits auth_error with { message: string }.

server.useAuth(async (token: string) => {
  // JWT verification example
  try {
    const payload = jwt.verify(token, process.env.JWT_SECRET!);
    return { userId: payload.sub as string };
  } catch {
    return null; // reject
  }
});

PresencePlugin

Registered via .usePresence(). Broadcasts online/offline events to all connected clients.

Events emitted to clients

Events received from clients

MessagePlugin (Direct Messaging)

Registered via .useMessaging(). Handles all 1:1 messaging, typing indicators, read receipts, and message history.

Events received from clients

Events emitted to clients

GroupPlugin

Registered via .useGroupMessaging(). Handles group creation, membership, messaging, typing, and history.

Group management events

Group messaging events

VoicePlugin (P2P Voice & Video)

Registered via .useVoice(). Acts as the signaling layer for WebRTC peer-to-peer calls. It relays SDP offers/answers and ICE candidates between peers — it does not process media itself.

VoiceConfig

Events received from clients

Events emitted to clients

Automatic cleanup

When a user disconnects while in an active or ringing call, cleanupCallsForUser() is called automatically. The remote peer receives a call_ended event.

Video support

The VoicePlugin is video-capable — it relays SDP without inspecting media types. On the client, pass { video: true } to useVoiceCall() to include a video track in the offer.

ConferencePlugin (SFU Group Calls)

Registered via .useConference(sfuProvider, sfuUrl). Enables multi-party group conference calling via a Selective Forwarding Unit (SFU). The server handles room creation and token generation; clients connect directly to the SFU using the delivered token.

ISFUProvider interface

Implement this interface to connect any SFU. Sockr ships LiveKitSFUProvider as the reference implementation.

interface ISFUProvider {
  connect?(): Promise<void>;
  disconnect?(): Promise<void>;
  generateToken(roomName: string, participantIdentity: string, opts?: TokenOptions): Promise<string>;
  createRoom?(roomName: string, opts?: RoomOptions): Promise<void>;
  deleteRoom?(roomName: string): Promise<void>;
}

LiveKitSFUProvider

The built-in LiveKit provider. Uses lazy require('livekit-server-sdk') — install it separately:

npm install livekit-server-sdk

import { LiveKitSFUProvider } from 'sockr-server';

const provider = new LiveKitSFUProvider({
  apiKey: process.env.LIVEKIT_API_KEY!,
  apiSecret: process.env.LIVEKIT_API_SECRET!,
  host: 'https://your-livekit.example.com',
});

Events received from clients

Events emitted to clients

Automatic conference cleanup

When a user disconnects while in a conference, cleanupParticipant() is called automatically. If they were the last participant, the SFU room is deleted and all group members receive conference_ended. Multi-device connections are handled — only the last socket triggers cleanup.

Database Adapters

Pass any of these to providers.messageStore in ServerConfig. All implement the IMessageStore interface from sockr-shared.

import { MongoMessageStore } from 'sockr-server/adapters/db/mongo';

const server = new SocketServer({
  providers: {
    messageStore: new MongoMessageStore('mongodb://localhost:27017/myapp'),
  },
});

Queue Adapters

Pass to providers.queue. Used for offline message queuing. All implement IQueueProvider.

Cache Adapters

Pass to providers.cache. All implement ICacheProvider.

Custom Plugins

Extend the Plugin abstract class from sockr-server. Override initialize() and handleConnection().

import { Plugin } from 'sockr-server';
import { Socket, Server } from 'socket.io';
import { ConnectionManager } from 'sockr-server';

class AnalyticsPlugin extends Plugin {
  private eventCount = 0;

  // Called once after server.listen() / server.initialize()
  initialize(): void {
    console.log('[Analytics] Plugin initialized');
  }

  // Called for every new socket connection
  handleConnection(socket: Socket): void {
    this.eventCount++;
    console.log(`[Analytics] Connection #${this.eventCount}: ${socket.id}`);

    socket.on('my_custom_event', (data) => {
      // handle custom event
      socket.emit('my_custom_response', { received: true, data });
    });

    socket.on('disconnect', () => {
      console.log(`[Analytics] Disconnected: ${socket.id}`);
    });
  }
}

// Register with the server
// The Plugin constructor receives (io, connectionManager)
const io = server.getIO();
const cm = server.getConnectionManager();
server.use(new AnalyticsPlugin(io, cm));