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.

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).
• Applies additional configuration to the HTTP service.

async start()

Starts the WebSocket/HTTP server, if the HTTP service is not already available.

async stop()

Stops the WebSocket/HTTP server, if the HTTP service is not already available.

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 context.
• 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.