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
, andmessage
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
).
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
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.
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.
Command Routing:
- Commands are routed using the format
namespace:method
. - Only methods decorated with
@Expose()
in controllers decorated with@Controller(namespace)
are registered.
- Commands are routed using the format
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.