Skip to content

WsService

This file defines the WsService class, which manages WebSocket (WS) connections, controllers, and middleware for the @sodacore/core framework. It integrates with the HTTP service, handles WebSocket events, dispatches commands to controllers, and manages the lifecycle of WebSocket connections.


Features

  • WebSocket Event Handling: Attaches listeners for open, close, drain, and message events on the HTTP service.
  • Controller & Middleware Discovery: Automatically discovers and registers WebSocket controllers and middleware from the DI registry.
  • Command Routing: Maps incoming WebSocket commands to controller methods using a namespace:method format.
  • Connection Management: Manages active WebSocket connections via the WsConnections provider.
  • Event Dispatching: Dispatches custom events (wsOpen, wsClose, wsDrain) using the Sodacore event system.
  • Data Injection: Injects parsed message data into the connection context before invoking controller methods.
  • Response Handling: Sends results back to the client, supporting primitive and object responses.

Usage

The WsService is registered and started automatically by the Sodacore WebSocket plugin. It is not typically instantiated directly.

typescript
import WsService from './service/ws';

const wsService = new WsService();
await wsService.init();

API

Properties

  • config: WebSocket configuration, injected via DI.
  • httpService: Reference to the Sodacore HTTP service, injected via DI.
  • connections: The WsConnections provider for managing active connections.
  • events: Sodacore event dispatcher.
  • controllers: Map of command strings to controller methods.
  • middlewares: Array of registered middleware modules.

Methods

async init()

Initializes the service:

  • Attaches WebSocket event listeners to the HTTP service.
  • Discovers and registers controllers and middleware from the DI registry.
  • Maps controller methods to command strings (namespace:method).

async start()

Starts the WebSocket/HTTP server (if not already started by HTTP service).

async stop()

Stops the WebSocket/HTTP server (if not already stopped by HTTP service).

private async handleOpen(socket: ServerWebSocket<IServerWsContext>)

Handles new WebSocket connections:

  • Creates a WsContext for the connection.
  • Adds the connection to the provider.
  • Dispatches a wsOpen event.

private async handleClose(socket: ServerWebSocket<IServerContext>, code: number, reason: string)

Handles connection closure:

  • Removes the connection from the provider.
  • Dispatches a wsClose event.

private async handleDrain(socket: ServerWebSocket<IServerContext>)

Handles socket drain events:

  • Dispatches a wsDrain event.

private async handleMessage(socket: ServerWebSocket<IServerContext>, message: string | Buffer)

Handles incoming messages:

  • Parses the message as JSON.
  • Extracts the command and data.
  • Looks up the corresponding controller method.
  • Injects data into the connection context.
  • Executes the method and sends the result back to the client.

How It Works

  1. Initialization:

    • Attaches event listeners to the HTTP service for WebSocket events.
    • Discovers all modules from the registry, registering controllers and middleware.
    • Maps controller methods to command strings for routing.
  2. Event Handling:

    • On connection open, creates a context and adds it to the provider.
    • On message, parses and routes the command to the correct controller method.
    • On close or drain, removes the connection and dispatches events.
  3. Command Routing:

    • Commands are routed using the format namespace:method.
    • Only methods decorated with @Expose() in controllers decorated with @Controller(namespace) are registered.
  4. Response Handling:

    • Sends results back to the client, supporting primitives and objects.

Notes

  • This service is designed for internal use by the Sodacore WebSocket system.
  • Controllers and middleware must be registered using the appropriate decorators.
  • Integrates tightly with the HTTP service for unified server management.
  • Uses Bun's native WebSocket API for performance and reliability.

Released under the Apache-2.0 License.