@grest-ts/websocket 0.0.5 → 0.0.7

package/src/server/GGSocketServer.ts

@@ -1,217 +1,217 @@
-/**
- * Manages WebSocket connections for a single endpoint
- * Handles connection acceptance, effect parsing via handshake, and socket lifecycle
- */
-
-import {WebSocket, WebSocketServer} from "ws";
-import {ERROR, GGValidator} from "@grest-ts/schema";
-import {NodeSocketAdapter} from "../adapter/NodeSocketAdapter";
-import * as http from "http";
-import * as url from "url";
-import {GGLog} from "@grest-ts/logger";
-import {GG_WS_CONNECTION} from "./GG_WS_CONNECTION";
-import {GGWebSocketMetrics} from "./GGWebSocketMetrics";
-import {Message, MessageType} from "../socket/SocketMessage";
-import {GG_TRACE} from "@grest-ts/trace";
-import {GGSocket} from "../socket/GGSocket";
-import {GGLocator, GGLocatorScope} from "@grest-ts/locator";
-import {GG_METRICS} from "@grest-ts/metrics";
-import {withTimeout} from "@grest-ts/common";
-import {GGContext} from "@grest-ts/context";
-import {GG_DISCOVERY} from "@grest-ts/discovery";
-import {GGWebSocketHandshakeContext, GGWebSocketMiddleware} from "../schema/GGWebSocketMiddleware";
-import {GGHttpServer} from "@grest-ts/http";
-
-export interface GGSocketServerConfig<TContext, Query> {
-    path: string;
-    apiName: string;
-    queryValidator?: GGValidator<Query>;
-    middlewares: readonly GGWebSocketMiddleware[];
-}
-
-export class GGSocketServer<TContext, Query> {
-
-    private readonly wss: WebSocketServer;
-    private readonly http: GGHttpServer;
-    public readonly path: string;
-    private readonly apiName: string;
-    private readonly middlewares: readonly GGWebSocketMiddleware[];
-    private readonly queryValidator: GGValidator<Query>;
-
-    private readonly activeSockets: Set<GGSocket> = new Set();
-    private readonly onConnectionHandlers: Array<(socket: GGSocket, query: Query) => void> = [];
-
-    // Capture context at construction - WebSocket events lose AsyncLocalStorage context
-    private readonly scope: GGLocatorScope;
-
-    constructor(http: GGHttpServer, config: GGSocketServerConfig<TContext, Query>) {
-        this.scope = GGLocator.getScope();
-        this.path = config.path;
-        this.apiName = config.apiName;
-        this.middlewares = config.middlewares;
-        this.queryValidator = config.queryValidator;
-        this.wss = new WebSocketServer({server: http.httpServer, path: this.path});
-        this.wss.on('connection', this.scope.wrapWithEnter(this._onConnection));
-        this.http = http
-            .onStart(() => {
-                GGLog.info(this, "WebSocket server started", {api: config.apiName, path: config.path});
-                if (GG_DISCOVERY.has()) {
-                    GG_DISCOVERY.get().registerRoutes([{
-                        runtime: this.scope.serviceName,
-                        api: this.apiName,
-                        pathPrefix: this.path,
-                        protocol: "ws",
-                        port: http.port
-                    }]);
-                }
-            })
-            .onTeardown(async () => {
-                GGLog.info(this, "WebSocket server closing");
-                try {
-                    this.wss.close(); // We use external http, so this does not close existing connections.
-                } catch (error) {
-                    GGLog.error(this, error);
-                }
-                await Promise.allSettled(Array.from(this.activeSockets).map(socket => socket.teardown()));
-                GGLog.info(this, "WebSocket server stopped");
-            });
-    }
-
-    public onConnection(handler: (socket: GGSocket, query: Query) => void): void {
-        this.onConnectionHandlers.push(handler);
-    }
-
-    private _onConnection = async (ws: WebSocket, req: http.IncomingMessage) => {
-        const connectionLabels = {api: this.apiName, path: this.path};
-
-        const context = new GGContext("ws-connection");
-        await context.run(async () => {
-            GG_TRACE.init()
-            GG_WS_CONNECTION.set({
-                port: this.http.port,
-                path: this.path
-            })
-            try {
-                // Parse and validate query parameters
-                const parsedUrl = url.parse(req.url || '', true);
-                let queryArgs = parsedUrl.query as Query;
-
-                if (this.queryValidator) {
-                    const result = this.queryValidator.safeParse(queryArgs, true)
-                    if (result.success === false) {
-                        ws.close(4000, "Invalid query parameters");
-                        GGLog.warn(this, "REJECTED - bad query", result.issues);
-                        if (GG_METRICS.has()) GGWebSocketMetrics.connections.inc(1, {...connectionLabels, result: 'QUERY_INVALID'});
-                        return;
-                    }
-                    queryArgs = result.value as Query
-                }
-
-                const adapter = new NodeSocketAdapter(ws);
-
-                // Wait for handshake message with headers
-                const handshakeResult = await this.handleHandshake(context, adapter, queryArgs);
-
-                if (!handshakeResult.success) {
-                    GGLog.warn(this, "REJECTED - handshake failed", (handshakeResult as { success: false; error: any }).error);
-                    if (GG_METRICS.has()) GGWebSocketMetrics.connections.inc(1, {...connectionLabels, result: 'HANDSHAKE_FAILED'});
-                    adapter.send(Message.create(MessageType.HANDSHAKE_ERR, "", "", (handshakeResult as { success: false; error: any }).error));
-                    ws.close(4001, "Handshake failed");
-                    return;
-                }
-
-                // Send handshake success
-                adapter.send(Message.create(MessageType.HANDSHAKE_OK, "", "", null));
-
-                GGLog.debug(this, "New websocket connection", queryArgs);
-                const socket = new GGSocket(adapter, {
-                    apiName: this.apiName,
-                    socketPath: this.path,
-                    connectionContext: context
-                });
-                this.activeSockets.add(socket);
-
-                // Track connection metrics
-                if (GG_METRICS.has()) {
-                    GGWebSocketMetrics.connections.inc(1, {...connectionLabels, result: 'OK'});
-                    GGWebSocketMetrics.connectionsActive.inc(1, connectionLabels);
-                }
-
-                socket.onClose(() => {
-                    this.activeSockets.delete(socket);
-                    if (GG_METRICS.has()) GGWebSocketMetrics.connectionsActive.dec(1, connectionLabels);
-                });
-
-                // Run connection handlers inside the connectionScope so they can access context
-                for (const handler of this.onConnectionHandlers) {
-                    try {
-                        handler(socket, queryArgs);
-                    } catch (error) {
-                        GGLog.error(this, error);
-                    }
-                }
-            } catch (error) {
-                GGLog.error(this, error);
-                if (GG_METRICS.has()) GGWebSocketMetrics.connections.inc(1, {...connectionLabels, result: 'ERROR'});
-                // Only close if socket is still open (fix #5 - avoid double close)
-                if (ws.readyState === ws.OPEN || ws.readyState === ws.CONNECTING) {
-                    ws.close(4001, "Connection rejected");
-                }
-            }
-        });
-    }
-
-    /**
-     * Handle handshake message from client.
-     * Waits for HANDSHAKE message with headers, runs effects, returns context.
-     */
-    private async handleHandshake(
-        context: GGContext,
-        adapter: NodeSocketAdapter,
-        queryArgs: Query
-    ): Promise<{ success: true } | { success: false; error: any }> {
-        type HandshakeResult = { success: true } | { success: false; error: any };
-        return withTimeout<HandshakeResult>(
-            new Promise<HandshakeResult>((resolve) => {
-                // Wrap with scope.wrapWithEnter to preserve locator scope when callback fires
-                const onMessage = this.scope.wrapWithEnter((data: string) => {
-                    const msg = Message.parse(data);
-                    if (!msg) return;
-
-                    if (msg.type === MessageType.HANDSHAKE) {
-                        adapter.offMessage(onMessage);
-                        context.run(async () => {
-                            try {
-                                // Build handshake context from headers
-                                const headers = msg.data || {};
-                                const handshakeContext: GGWebSocketHandshakeContext = {
-                                    headers,
-                                    queryArgs: queryArgs as Record<string, string>
-                                };
-
-                                // Run middlewares
-                                for (const middleware of this.middlewares) {
-                                    middleware.parseHandshake?.(handshakeContext);
-                                    await middleware.process?.();
-                                }
-                                resolve({success: true});
-                            } catch (error: any) {
-                                const errorJson = error instanceof ERROR
-                                    ? error.toJSON()
-                                    : {message: String(error)};
-                                resolve({success: false, error: errorJson});
-                            }
-                        });
-                    }
-                });
-
-                adapter.onMessage(onMessage);
-            }),
-            5000,
-            'Handshake timeout'
-        ).catch((error): { success: false; error: any } => ({
-            success: false,
-            error: {message: error.message || 'Handshake timeout'}
-        }));
-    }
-}
+/**
+ * Manages WebSocket connections for a single endpoint
+ * Handles connection acceptance, effect parsing via handshake, and socket lifecycle
+ */
+
+import {WebSocket, WebSocketServer} from "ws";
+import {ERROR, GGValidator} from "@grest-ts/schema";
+import {NodeSocketAdapter} from "../adapter/NodeSocketAdapter";
+import * as http from "http";
+import * as url from "url";
+import {GGLog} from "@grest-ts/logger";
+import {GG_WS_CONNECTION} from "./GG_WS_CONNECTION";
+import {GGWebSocketMetrics} from "./GGWebSocketMetrics";
+import {Message, MessageType} from "../socket/SocketMessage";
+import {GG_TRACE} from "@grest-ts/trace";
+import {GGSocket} from "../socket/GGSocket";
+import {GGLocator, GGLocatorScope} from "@grest-ts/locator";
+import {GG_METRICS} from "@grest-ts/metrics";
+import {withTimeout} from "@grest-ts/common";
+import {GGContext} from "@grest-ts/context";
+import {GG_DISCOVERY} from "@grest-ts/discovery";
+import {GGWebSocketHandshakeContext, GGWebSocketMiddleware} from "../schema/GGWebSocketMiddleware";
+import {GGHttpServer} from "@grest-ts/http";
+
+export interface GGSocketServerConfig<TContext, Query> {
+    path: string;
+    apiName: string;
+    queryValidator?: GGValidator<Query>;
+    middlewares: readonly GGWebSocketMiddleware[];
+}
+
+export class GGSocketServer<TContext, Query> {
+
+    private readonly wss: WebSocketServer;
+    private readonly http: GGHttpServer;
+    public readonly path: string;
+    private readonly apiName: string;
+    private readonly middlewares: readonly GGWebSocketMiddleware[];
+    private readonly queryValidator: GGValidator<Query>;
+
+    private readonly activeSockets: Set<GGSocket> = new Set();
+    private readonly onConnectionHandlers: Array<(socket: GGSocket, query: Query) => void> = [];
+
+    // Capture context at construction - WebSocket events lose AsyncLocalStorage context
+    private readonly scope: GGLocatorScope;
+
+    constructor(http: GGHttpServer, config: GGSocketServerConfig<TContext, Query>) {
+        this.scope = GGLocator.getScope();
+        this.path = config.path;
+        this.apiName = config.apiName;
+        this.middlewares = config.middlewares;
+        this.queryValidator = config.queryValidator;
+        this.wss = new WebSocketServer({server: http.httpServer, path: this.path});
+        this.wss.on('connection', this.scope.wrapWithEnter(this._onConnection));
+        this.http = http
+            .onStart(() => {
+                GGLog.info(this, "WebSocket server started", {api: config.apiName, path: config.path});
+                if (GG_DISCOVERY.has()) {
+                    GG_DISCOVERY.get().registerRoutes([{
+                        runtime: this.scope.serviceName,
+                        api: this.apiName,
+                        pathPrefix: this.path,
+                        protocol: "ws",
+                        port: http.port
+                    }]);
+                }
+            })
+            .onTeardown(async () => {
+                GGLog.info(this, "WebSocket server closing");
+                try {
+                    this.wss.close(); // We use external http, so this does not close existing connections.
+                } catch (error) {
+                    GGLog.error(this, error);
+                }
+                await Promise.allSettled(Array.from(this.activeSockets).map(socket => socket.teardown()));
+                GGLog.info(this, "WebSocket server stopped");
+            });
+    }
+
+    public onConnection(handler: (socket: GGSocket, query: Query) => void): void {
+        this.onConnectionHandlers.push(handler);
+    }
+
+    private _onConnection = async (ws: WebSocket, req: http.IncomingMessage) => {
+        const connectionLabels = {api: this.apiName, path: this.path};
+
+        const context = new GGContext("ws-connection");
+        await context.run(async () => {
+            GG_TRACE.init()
+            GG_WS_CONNECTION.set({
+                port: this.http.port,
+                path: this.path
+            })
+            try {
+                // Parse and validate query parameters
+                const parsedUrl = url.parse(req.url || '', true);
+                let queryArgs = parsedUrl.query as Query;
+
+                if (this.queryValidator) {
+                    const result = this.queryValidator.safeParse(queryArgs, true)
+                    if (result.success === false) {
+                        ws.close(4000, "Invalid query parameters");
+                        GGLog.warn(this, "REJECTED - bad query", result.issues);
+                        if (GG_METRICS.has()) GGWebSocketMetrics.connections.inc(1, {...connectionLabels, result: 'QUERY_INVALID'});
+                        return;
+                    }
+                    queryArgs = result.value as Query
+                }
+
+                const adapter = new NodeSocketAdapter(ws);
+
+                // Wait for handshake message with headers
+                const handshakeResult = await this.handleHandshake(context, adapter, queryArgs);
+
+                if (!handshakeResult.success) {
+                    GGLog.warn(this, "REJECTED - handshake failed", (handshakeResult as { success: false; error: any }).error);
+                    if (GG_METRICS.has()) GGWebSocketMetrics.connections.inc(1, {...connectionLabels, result: 'HANDSHAKE_FAILED'});
+                    adapter.send(Message.create(MessageType.HANDSHAKE_ERR, "", "", (handshakeResult as { success: false; error: any }).error));
+                    ws.close(4001, "Handshake failed");
+                    return;
+                }
+
+                // Send handshake success
+                adapter.send(Message.create(MessageType.HANDSHAKE_OK, "", "", null));
+
+                GGLog.debug(this, "New websocket connection", queryArgs);
+                const socket = new GGSocket(adapter, {
+                    apiName: this.apiName,
+                    socketPath: this.path,
+                    connectionContext: context
+                });
+                this.activeSockets.add(socket);
+
+                // Track connection metrics
+                if (GG_METRICS.has()) {
+                    GGWebSocketMetrics.connections.inc(1, {...connectionLabels, result: 'OK'});
+                    GGWebSocketMetrics.connectionsActive.inc(1, connectionLabels);
+                }
+
+                socket.onClose(() => {
+                    this.activeSockets.delete(socket);
+                    if (GG_METRICS.has()) GGWebSocketMetrics.connectionsActive.dec(1, connectionLabels);
+                });
+
+                // Run connection handlers inside the connectionScope so they can access context
+                for (const handler of this.onConnectionHandlers) {
+                    try {
+                        handler(socket, queryArgs);
+                    } catch (error) {
+                        GGLog.error(this, error);
+                    }
+                }
+            } catch (error) {
+                GGLog.error(this, error);
+                if (GG_METRICS.has()) GGWebSocketMetrics.connections.inc(1, {...connectionLabels, result: 'ERROR'});
+                // Only close if socket is still open (fix #5 - avoid double close)
+                if (ws.readyState === ws.OPEN || ws.readyState === ws.CONNECTING) {
+                    ws.close(4001, "Connection rejected");
+                }
+            }
+        });
+    }
+
+    /**
+     * Handle handshake message from client.
+     * Waits for HANDSHAKE message with headers, runs effects, returns context.
+     */
+    private async handleHandshake(
+        context: GGContext,
+        adapter: NodeSocketAdapter,
+        queryArgs: Query
+    ): Promise<{ success: true } | { success: false; error: any }> {
+        type HandshakeResult = { success: true } | { success: false; error: any };
+        return withTimeout<HandshakeResult>(
+            new Promise<HandshakeResult>((resolve) => {
+                // Wrap with scope.wrapWithEnter to preserve locator scope when callback fires
+                const onMessage = this.scope.wrapWithEnter((data: string) => {
+                    const msg = Message.parse(data);
+                    if (!msg) return;
+
+                    if (msg.type === MessageType.HANDSHAKE) {
+                        adapter.offMessage(onMessage);
+                        context.run(async () => {
+                            try {
+                                // Build handshake context from headers
+                                const headers = msg.data || {};
+                                const handshakeContext: GGWebSocketHandshakeContext = {
+                                    headers,
+                                    queryArgs: queryArgs as Record<string, string>
+                                };
+
+                                // Run middlewares
+                                for (const middleware of this.middlewares) {
+                                    middleware.parseHandshake?.(handshakeContext);
+                                    await middleware.process?.();
+                                }
+                                resolve({success: true});
+                            } catch (error: any) {
+                                const errorJson = error instanceof ERROR
+                                    ? error.toJSON()
+                                    : {message: String(error)};
+                                resolve({success: false, error: errorJson});
+                            }
+                        });
+                    }
+                });
+
+                adapter.onMessage(onMessage);
+            }),
+            5000,
+            'Handshake timeout'
+        ).catch((error): { success: false; error: any } => ({
+            success: false,
+            error: {message: error.message || 'Handshake timeout'}
+        }));
+    }
+}

package/src/server/GGWebSocketMetrics.ts

@@ -1,58 +1,58 @@
-import {GGCounterKey, GGGaugeKey, GGHistogramKey, GGMetrics} from "@grest-ts/metrics";
-import {EXISTS, FORBIDDEN, NOT_AUTHORIZED, NOT_FOUND, OK, ROUTE_NOT_FOUND, SERVER_ERROR, VALIDATION_ERROR} from "@grest-ts/schema";
-
-/**
- * Result type for WebSocket operations.
- * Known types listed for documentation, but accepts any string for custom error types.
- */
-type ResultType =
-    | typeof OK.TYPE
-    | typeof VALIDATION_ERROR.TYPE
-    | typeof NOT_AUTHORIZED.TYPE
-    | typeof FORBIDDEN.TYPE
-    | typeof NOT_FOUND.TYPE
-    | typeof ROUTE_NOT_FOUND.TYPE
-    | typeof EXISTS.TYPE
-    | typeof SERVER_ERROR.TYPE
-    | string;
-
-type SocketConnectionResult = 'OK' | 'AUTH_FAILED' | 'QUERY_INVALID' | string;
-
-export const GGWebSocketMetrics = GGMetrics.define('/websocket/', () => ({
-    connectionsActive: new GGGaugeKey<{ api: string, path: string }>('connections_active', {
-        help: 'Active WebSocket connections',
-        labelNames: ['api', 'path'],
-        groupBy: {labels: ["api"]}
-    }),
-    connections: new GGCounterKey<{ api: string, path: string, result: SocketConnectionResult }>('connections_total', {
-        help: 'Total WebSocket connection attempts',
-        labelNames: ['api', 'path', 'result'],
-        groupBy: {labels: ["api"]}
-    }),
-
-    // Incoming (server handling REQ + MSG)
-    requests: new GGCounterKey<{ api: string, path: string, method: string, result: ResultType }>('requests_total', {
-        help: 'Total incoming WebSocket commands (REQ + MSG)',
-        labelNames: ['api', 'path', 'method', 'result'],
-        groupBy: {labels: ["api", "method"], template: "{api}.{method}"}
-    }),
-    requestDuration: new GGHistogramKey<{ api: string, path: string, method: string }>('request_duration_ms', {
-        help: 'Incoming WebSocket command processing duration in milliseconds',
-        labelNames: ['api', 'path', 'method'],
-        buckets: [1, 5, 10, 25, 50, 100, 250, 500, 1000],
-        groupBy: {labels: ["api", "method"], template: "{api}.{method}"}
-    }),
-
-    // Outgoing (client calls via socket)
-    outRequests: new GGCounterKey<{ api: string, path: string, method: string, result: ResultType }>('out_requests_total', {
-        help: 'Total outgoing WebSocket commands (REQ + MSG)',
-        labelNames: ['api', 'path', 'method', 'result'],
-        groupBy: {labels: ["api", "method"], template: "{api}.{method}"}
-    }),
-    outRequestDuration: new GGHistogramKey<{ api: string, path: string, method: string }>('out_request_duration_ms', {
-        help: 'Outgoing WebSocket request round-trip duration in milliseconds (REQ only)',
-        labelNames: ['api', 'path', 'method'],
-        buckets: [1, 5, 10, 25, 50, 100, 250, 500, 1000, 2500],
-        groupBy: {labels: ["api", "method"], template: "{api}.{method}"}
-    }),
-}));
+import {GGCounterKey, GGGaugeKey, GGHistogramKey, GGMetrics} from "@grest-ts/metrics";
+import {EXISTS, FORBIDDEN, NOT_AUTHORIZED, NOT_FOUND, OK, ROUTE_NOT_FOUND, SERVER_ERROR, VALIDATION_ERROR} from "@grest-ts/schema";
+
+/**
+ * Result type for WebSocket operations.
+ * Known types listed for documentation, but accepts any string for custom error types.
+ */
+type ResultType =
+    | typeof OK.TYPE
+    | typeof VALIDATION_ERROR.TYPE
+    | typeof NOT_AUTHORIZED.TYPE
+    | typeof FORBIDDEN.TYPE
+    | typeof NOT_FOUND.TYPE
+    | typeof ROUTE_NOT_FOUND.TYPE
+    | typeof EXISTS.TYPE
+    | typeof SERVER_ERROR.TYPE
+    | string;
+
+type SocketConnectionResult = 'OK' | 'AUTH_FAILED' | 'QUERY_INVALID' | string;
+
+export const GGWebSocketMetrics = GGMetrics.define('/websocket/', () => ({
+    connectionsActive: new GGGaugeKey<{ api: string, path: string }>('connections_active', {
+        help: 'Active WebSocket connections',
+        labelNames: ['api', 'path'],
+        groupBy: {labels: ["api"]}
+    }),
+    connections: new GGCounterKey<{ api: string, path: string, result: SocketConnectionResult }>('connections_total', {
+        help: 'Total WebSocket connection attempts',
+        labelNames: ['api', 'path', 'result'],
+        groupBy: {labels: ["api"]}
+    }),
+
+    // Incoming (server handling REQ + MSG)
+    requests: new GGCounterKey<{ api: string, path: string, method: string, result: ResultType }>('requests_total', {
+        help: 'Total incoming WebSocket commands (REQ + MSG)',
+        labelNames: ['api', 'path', 'method', 'result'],
+        groupBy: {labels: ["api", "method"], template: "{api}.{method}"}
+    }),
+    requestDuration: new GGHistogramKey<{ api: string, path: string, method: string }>('request_duration_ms', {
+        help: 'Incoming WebSocket command processing duration in milliseconds',
+        labelNames: ['api', 'path', 'method'],
+        buckets: [1, 5, 10, 25, 50, 100, 250, 500, 1000],
+        groupBy: {labels: ["api", "method"], template: "{api}.{method}"}
+    }),
+
+    // Outgoing (client calls via socket)
+    outRequests: new GGCounterKey<{ api: string, path: string, method: string, result: ResultType }>('out_requests_total', {
+        help: 'Total outgoing WebSocket commands (REQ + MSG)',
+        labelNames: ['api', 'path', 'method', 'result'],
+        groupBy: {labels: ["api", "method"], template: "{api}.{method}"}
+    }),
+    outRequestDuration: new GGHistogramKey<{ api: string, path: string, method: string }>('out_request_duration_ms', {
+        help: 'Outgoing WebSocket request round-trip duration in milliseconds (REQ only)',
+        labelNames: ['api', 'path', 'method'],
+        buckets: [1, 5, 10, 25, 50, 100, 250, 500, 1000, 2500],
+        groupBy: {labels: ["api", "method"], template: "{api}.{method}"}
+    }),
+}));