@grest-ts/websocket 0.0.23 → 0.0.24

package/src/server/GGSocketServer.ts

@@ -29,6 +29,53 @@ export interface GGSocketServerConfig<TContext, Query> {
     middlewares: readonly GGWebSocketMiddleware[];
 }
 
+/**
+ * Shared path-dispatching upgrade registry per http.Server.
+ *
+ * The `ws` library's `{server, path}` mode aborts the HTTP handshake with 400
+ * whenever the upgrade path doesn't match — so attaching two WebSocketServer
+ * instances to the same http.Server causes whichever one fires first to reject
+ * requests meant for the other. We install a single shared 'upgrade' listener
+ * on each http.Server and dispatch by path instead.
+ */
+interface WsRegistry {
+    readonly wssByPath: Map<string, WebSocketServer>
+}
+
+const wsRegistryByHttpServer = new WeakMap<http.Server, WsRegistry>();
+
+function attachUpgradeDispatch(httpServer: http.Server, path: string, wss: WebSocketServer): void {
+    let registry = wsRegistryByHttpServer.get(httpServer);
+    if (!registry) {
+        registry = {wssByPath: new Map()};
+        wsRegistryByHttpServer.set(httpServer, registry);
+        const captured = registry;
+        httpServer.on('upgrade', (req, socket, head) => {
+            const pathname = (req.url ?? '').split('?')[0];
+            const matched = captured.wssByPath.get(pathname);
+            if (matched) {
+                matched.handleUpgrade(req, socket, head, (ws) => {
+                    matched.emit('connection', ws, req);
+                });
+            } else {
+                socket.write('HTTP/1.1 404 Not Found\r\nConnection: close\r\n\r\n');
+                socket.destroy();
+            }
+        });
+    }
+    if (registry.wssByPath.has(path)) {
+        throw new Error(`WebSocket path "${path}" is already registered on this HTTP server.`);
+    }
+    registry.wssByPath.set(path, wss);
+}
+
+function detachUpgradeDispatch(httpServer: http.Server, path: string): void {
+    const registry = wsRegistryByHttpServer.get(httpServer);
+    if (registry) {
+        registry.wssByPath.delete(path);
+    }
+}
+
 export class GGSocketServer<TContext, Query> {
 
     private readonly wss: WebSocketServer;
@@ -50,8 +97,9 @@ export class GGSocketServer<TContext, Query> {
         this.apiName = config.apiName;
         this.middlewares = config.middlewares;
         this.queryValidator = config.queryValidator;
-        this.wss = new WebSocketServer({server: http.httpServer, path: this.path});
+        this.wss = new WebSocketServer({noServer: true});
         this.wss.on('connection', this.scope.wrapWithEnter(this._onConnection));
+        attachUpgradeDispatch(http.httpServer, this.path, this.wss);
         this.http = http
             .onStart(() => {
                 GGLog.info(this, "WebSocket server started", {api: config.apiName, path: config.path});
@@ -68,7 +116,8 @@ export class GGSocketServer<TContext, Query> {
             .onTeardown(async () => {
                 GGLog.info(this, "WebSocket server closing");
                 try {
-                    this.wss.close(); // We use external http, so this does not close existing connections.
+                    detachUpgradeDispatch(http.httpServer, this.path);
+                    this.wss.close();
                 } catch (error) {
                     GGLog.error(this, error);
                 }

package/src/server/GGWebSocketSchema.startServer.ts

@@ -24,12 +24,14 @@ export interface WebSocketSchemaConfig {
 }
 
 declare module "../schema/GGWebSocketSchema" {
-    interface GGWebSocketSchema<TClientToServer, TServerToClient, TContext = {}, TQuery = undefined, TClientToServerImpl = TClientToServer> {
+    interface GGWebSocketSchema<TClientToServer, TServerToClient, TContext = {}, TQuery = undefined, TClientToServerImpl = TClientToServer, TServerToClientImpl = TServerToClient> {
         /**
          * Start the WebSocket server for this API.
+         * The onConnection handler receives validated query parameters as its 3rd argument
+         * (only populated when the schema declares `queryOnConnect(validator)`).
          */
         startServer(
-            onConnection: (incoming: WebSocketIncoming<TClientToServerImpl>, outgoing: WebSocketOutgoing<TServerToClient>) => void,
+            onConnection: (incoming: WebSocketIncoming<TClientToServerImpl>, outgoing: WebSocketOutgoing<TServerToClient>, query: TQuery) => void,
             config: WebSocketSchemaConfig
         ): GGSocketServer<TContext, TQuery>
 
@@ -38,14 +40,14 @@ declare module "../schema/GGWebSocketSchema" {
          * Uses GGHttpServerAdapter from locator if not explicitly provided.
          */
         register(
-            onConnection: (incoming: WebSocketIncoming<TClientToServerImpl>, outgoing: WebSocketOutgoing<TServerToClient>) => void,
+            onConnection: (incoming: WebSocketIncoming<TClientToServerImpl>, outgoing: WebSocketOutgoing<TServerToClient>, query: TQuery) => void,
             config?: WebSocketSchemaConfig
         ): void
     }
 }
 
 GGWebSocketSchema.prototype.startServer = function (
-    this: GGWebSocketSchema<any, any, any, any>,
+    this: GGWebSocketSchema<any, any, any, any, any, any>,
     onConnection: any,
     config: WebSocketSchemaConfig
 ): GGSocketServer<any, any> {
@@ -57,15 +59,17 @@ GGWebSocketSchema.prototype.startServer = function (
     const normalizedPath = this.path.startsWith('/') ? this.path : '/' + this.path
     const schemaName = this.name
     const http = config.http ?? GGLocator.getScope().get(GG_HTTP_SERVER);
+    http._registerWebSocketSchema(this as any);
 
     // @TODO We might want some lookup here based on path/middlewares etc. If I use same socket for multiple paths, we need to reuse also same GGSocketServer.
     const socketServer = new GGSocketServer(http, {
         apiName: schemaName,
         path: normalizedPath,
-        middlewares: [...this.middlewares, ...(config?.middlewares ?? [])]
+        middlewares: [...this.middlewares, ...(config?.middlewares ?? [])],
+        queryValidator: this.queryValidator,
     });
 
-    socketServer.onConnection((socket: GGSocket) => {
+    socketServer.onConnection((socket: GGSocket, queryArgs: any) => {
         const clientToServerContract = contract.clientToServer
         const serverToClientContract = contract.serverToClient
 
@@ -86,7 +90,7 @@ GGWebSocketSchema.prototype.startServer = function (
                     };
                 }
 
-                const incomingInstance = clientToServerContract.implement(impl);
+                const incomingInstance = clientToServerContract.implement(impl, {skipLocatorRegistration: true});
 
                 for (const methodName of Object.keys(clientToServerContract.methods)) {
                     socket.registerHandler({
@@ -106,18 +110,18 @@ GGWebSocketSchema.prototype.startServer = function (
             };
         }
 
-        const outgoingInstance = serverToClientContract.implement(impl);
+        const outgoingInstance = serverToClientContract.implement(impl, {skipLocatorRegistration: true});
         (outgoingInstance as any).onClose = (callback: () => void) => {
             socket.onClose(callback)
         }
-        onConnection(incoming, outgoingInstance)
+        onConnection(incoming, outgoingInstance, queryArgs)
     });
 
     return socketServer;
 }
 
 GGWebSocketSchema.prototype.register = function (
-    this: GGWebSocketSchema<any, any, any, any>,
+    this: GGWebSocketSchema<any, any, any, any, any, any>,
     onConnection: any,
     config?: WebSocketSchemaConfig
 ): void {

package/src/socket/GGSocket.ts

@@ -232,11 +232,13 @@ export class GGSocket {
      * @param path - The message path/route
      * @param body - The message data (already validated)
      * @param expectsResponse - Whether to wait for a response
+     * @param timeoutMs - Timeout for req/res in ms. Ignored for fire-and-forget. Defaults to 30_000.
      */
     public async send(
         path: string,
         body: any,
-        expectsResponse: boolean
+        expectsResponse: boolean,
+        timeoutMs: number = 30000
     ): Promise<any> {
         const labels: MetricLabels = {api: this.apiName, path: this.socketPath, method: path};
         const startTime = performance.now();
@@ -247,7 +249,7 @@ export class GGSocket {
         }
 
         if (expectsResponse) {
-            return this.pendingRequests.create(path, 30000, async (id, waitForResponse) => {
+            return this.pendingRequests.create(path, timeoutMs, async (id, waitForResponse) => {
                 this.socket.send(Message.create(MessageType.REQ, path, id, body));
                 const result = await waitForResponse;
                 const resultType = result?.success === true ? 'OK' : (result?.type ?? 'SERVER_ERROR');
@@ -307,6 +309,58 @@ export class GGSocket {
         return this;
     }
 
+    // --------------------------------------------------------------------------------------
+    // Heartbeat (PING/PONG) — dead-connection detection
+    // --------------------------------------------------------------------------------------
+
+    /**
+     * Start a heartbeat loop that sends protocol-level PINGs and closes the socket
+     * if no PONG comes back within `intervalMs + timeoutMs`. Returns a stop function.
+     *
+     * No-op (returns an empty stop fn) if the underlying adapter does not support
+     * ping/pong — e.g. the browser WebSocket API cannot initiate pings.
+     */
+    public startHeartbeat(config: {intervalMs: number; timeoutMs: number}): () => void {
+        // Adapter doesn't support ping/pong (e.g. browser WebSocket) — no-op.
+        if (!this.socket.ping || !this.socket.onPong) {
+            return () => {};
+        }
+        // Socket is already closed — starting heartbeat would leak intervals
+        // because the onCloseCallbacks push below won't fire (isCleanedUp guard).
+        if (!this.isActive) {
+            return () => {};
+        }
+        let lastActivity = Date.now();
+        const onPong = () => { lastActivity = Date.now(); };
+        this.socket.onPong(onPong);
+
+        const sender = setInterval(() => {
+            if (!this.isActive) return;
+            try {
+                this.socket.ping!();
+            } catch (_) { /* adapter may throw if socket already closing */ }
+        }, config.intervalMs);
+
+        const watchdog = setInterval(() => {
+            if (!this.isActive) return;
+            if (Date.now() - lastActivity > config.intervalMs + config.timeoutMs) {
+                this.log.warn(this, 'Heartbeat timeout — no PONG received; closing socket');
+                clearInterval(sender);
+                clearInterval(watchdog);
+                this.close();
+            }
+        }, config.timeoutMs);
+
+        // Auto-cleanup on close
+        const cleanup = () => {
+            clearInterval(sender);
+            clearInterval(watchdog);
+        };
+        this.onCloseCallbacks.push(cleanup);
+
+        return cleanup;
+    }
+
     // --------------------------------------------------------------------------------------
     // Teardown
     // --------------------------------------------------------------------------------------

package/src/socket/SocketAdapter.ts

@@ -18,4 +18,17 @@ export interface SocketAdapter {
     offClose(handler: () => void): void;
 
     offError(handler: (error: Error) => void): void;
+
+    /**
+     * Send a protocol-level PING frame. The peer auto-responds with a PONG.
+     * Optional: browsers cannot initiate pings (the native WebSocket API does not expose it).
+     * Node can; use this for dead-connection detection.
+     */
+    ping?(): void;
+
+    /**
+     * Register a handler for PONG frames received from the peer.
+     * Paired with `ping()` — only supported by adapters that also support ping.
+     */
+    onPong?(handler: () => void): void;
 }

package/dist/src/client/GGSocketClient.d.ts

@@ -1,10 +0,0 @@
-import { GGSocket } from "../socket/GGSocket";
-import { GGContractMethod } from "@grest-ts/schema";
-export declare abstract class GGSocketClient {
-    readonly socket: GGSocket;
-    constructor(socket: GGSocket);
-    onClose(onClose: () => void): this;
-    close(): void;
-    __defineApi<T extends Record<string, GGContractMethod<any, any, any>>>(api: T): T;
-}
-//# sourceMappingURL=GGSocketClient.d.ts.map

package/dist/src/client/GGSocketClient.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"GGSocketClient.d.ts","sourceRoot":"","sources":["../../../src/client/GGSocketClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,QAAQ,EAAC,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAC,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AAElD,8BAAsB,cAAc;IAEhC,SAAgB,MAAM,EAAE,QAAQ,CAAA;gBAEpB,MAAM,EAAE,QAAQ;IAIrB,OAAO,CAAC,OAAO,EAAE,MAAM,IAAI;IAK3B,KAAK,IAAI,IAAI;IAIb,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC;CAI3F"}

package/dist/src/client/GGSocketClient.js

@@ -1,17 +0,0 @@
-export class GGSocketClient {
-    socket;
-    constructor(socket) {
-        this.socket = socket;
-    }
-    onClose(onClose) {
-        this.socket.onClose(onClose);
-        return this;
-    }
-    close() {
-        this.socket.close();
-    }
-    __defineApi(api) {
-        return api;
-    }
-}
-//# sourceMappingURL=GGSocketClient.js.map

package/dist/src/client/GGSocketClient.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"GGSocketClient.js","sourceRoot":"","sources":["../../../src/client/GGSocketClient.ts"],"names":[],"mappings":"AAGA,MAAM,OAAgB,cAAc;IAEhB,MAAM,CAAU;IAEhC,YAAY,MAAgB;QACxB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACzB,CAAC;IAEM,OAAO,CAAC,OAAmB;QAC9B,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;QAC5B,OAAO,IAAI,CAAA;IACf,CAAC;IAEM,KAAK;QACR,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAA;IACvB,CAAC;IAEM,WAAW,CAA4D,GAAM;QAChF,OAAO,GAAG,CAAC;IACf,CAAC;CAEJ"}

package/src/client/GGSocketClient.ts

@@ -1,25 +0,0 @@
-import {GGSocket} from "../socket/GGSocket";
-import {GGContractMethod} from "@grest-ts/schema";
-
-export abstract class GGSocketClient {
-
-    public readonly socket: GGSocket
-
-    constructor(socket: GGSocket) {
-        this.socket = socket;
-    }
-
-    public onClose(onClose: () => void) {
-        this.socket.onClose(onClose)
-        return this
-    }
-
-    public close(): void {
-        this.socket.close()
-    }
-
-    public __defineApi<T extends Record<string, GGContractMethod<any, any, any>>>(api: T): T {
-        return api;
-    }
-
-}