@grest-ts/websocket 0.0.5

package/dist/src/schema/GGWebSocketMiddleware.d.ts

@@ -0,0 +1,40 @@
+/**
+ * WebSocket-specific middleware interface.
+ * Independent from @grest-ts/http - WebSocket has its own middleware system.
+ */
+/**
+ * Context available during WebSocket handshake.
+ */
+export interface GGWebSocketHandshakeContext {
+    /**
+     * Headers from the handshake message (client-sent or server-received).
+     */
+    headers: Record<string, string>;
+    /**
+     * Query parameters from the WebSocket URL.
+     */
+    queryArgs: Record<string, string>;
+}
+/**
+ * WebSocket middleware interface for both client and server.
+ * Unlike HTTP middleware, WebSocket middleware works with handshake data.
+ */
+export interface GGWebSocketMiddleware {
+    /**
+     * Client-side: Add headers to the handshake message before sending.
+     * Called by GGSocketPool when establishing a connection.
+     */
+    updateHandshake?(context: GGWebSocketHandshakeContext): void;
+    /**
+     * Server-side: Parse headers from the received handshake message.
+     * Called by GGSocketServer when receiving a connection.
+     */
+    parseHandshake?(context: GGWebSocketHandshakeContext): void;
+    /**
+     * Server-side: Async processing after parseHandshake.
+     * Can be used for authentication, authorization, etc.
+     * Throwing an error will reject the connection.
+     */
+    process?(): Promise<void>;
+}
+//# sourceMappingURL=GGWebSocketMiddleware.d.ts.map

package/dist/src/schema/GGWebSocketMiddleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GGWebSocketMiddleware.d.ts","sourceRoot":"","sources":["../../../src/schema/GGWebSocketMiddleware.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,WAAW,2BAA2B;IACxC;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IAClC;;;OAGG;IACH,eAAe,CAAC,CAAC,OAAO,EAAE,2BAA2B,GAAG,IAAI,CAAC;IAE7D;;;OAGG;IACH,cAAc,CAAC,CAAC,OAAO,EAAE,2BAA2B,GAAG,IAAI,CAAC;IAE5D;;;;OAIG;IACH,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B"}

package/dist/src/schema/GGWebSocketMiddleware.js

@@ -0,0 +1,6 @@
+/**
+ * WebSocket-specific middleware interface.
+ * Independent from @grest-ts/http - WebSocket has its own middleware system.
+ */
+export {};
+//# sourceMappingURL=GGWebSocketMiddleware.js.map

package/dist/src/schema/GGWebSocketMiddleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GGWebSocketMiddleware.js","sourceRoot":"","sources":["../../../src/schema/GGWebSocketMiddleware.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/src/schema/GGWebSocketSchema.d.ts

@@ -0,0 +1,31 @@
+import { GGWebSocketMiddleware } from "./GGWebSocketMiddleware";
+import { GGContractApiDefinition, GGContractClass } from "@grest-ts/schema";
+/**
+ * WebSocket API Schema - pure data definition with typed context
+ *
+ * Type parameters:
+ * - TClientToServer: Client-facing type for clientToServer methods (returns GGPromise)
+ * - TServerToClient: Client-facing type for serverToClient methods (returns GGPromise)
+ * - TContext: Accumulated context type (parseHandshake return types)
+ * - TQuery: Query parameters on connect
+ * - TClientToServerImpl: Server implementation type for clientToServer handlers (returns Promise)
+ */
+export declare class GGWebSocketSchema<TClientToServer, TServerToClient, TContext = {}, TQuery = undefined, TClientToServerImpl = TClientToServer> {
+    readonly name: string;
+    readonly path: string;
+    readonly middlewares: readonly GGWebSocketMiddleware[];
+    private readonly contractFactory;
+    private contractCache;
+    constructor(name: string, path: string, contractFactory: () => GGWebSocketContractRuntime, middlewares?: readonly GGWebSocketMiddleware[]);
+    get contract(): GGWebSocketContractRuntime;
+}
+/**
+ * Runtime contract structure for WebSocket APIs.
+ * Contains GGContractClass instances for proper validation via implement().
+ */
+export interface GGWebSocketContractRuntime {
+    apiName: string;
+    clientToServer: GGContractClass<GGContractApiDefinition>;
+    serverToClient: GGContractClass<GGContractApiDefinition>;
+}
+//# sourceMappingURL=GGWebSocketSchema.d.ts.map

package/dist/src/schema/GGWebSocketSchema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GGWebSocketSchema.d.ts","sourceRoot":"","sources":["../../../src/schema/GGWebSocketSchema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,qBAAqB,EAAC,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAC,uBAAuB,EAAE,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAE1E;;;;;;;;;GASG;AACH,qBAAa,iBAAiB,CAC1B,eAAe,EACf,eAAe,EACf,QAAQ,GAAG,EAAE,EACb,MAAM,GAAG,SAAS,EAClB,mBAAmB,GAAG,eAAe;IAErC,SAAgB,IAAI,EAAE,MAAM,CAAA;IAC5B,SAAgB,IAAI,EAAE,MAAM,CAAA;IAC5B,SAAgB,WAAW,EAAE,SAAS,qBAAqB,EAAE,CAAA;IAC7D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkC;IAClE,OAAO,CAAC,aAAa,CAA0C;gBAG3D,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,MAAM,0BAA0B,EACjD,WAAW,GAAE,SAAS,qBAAqB,EAAO;IAStD,IAAI,QAAQ,IAAI,0BAA0B,CAMzC;CACJ;AAED;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACvC,OAAO,EAAE,MAAM,CAAA;IACf,cAAc,EAAE,eAAe,CAAC,uBAAuB,CAAC,CAAA;IACxD,cAAc,EAAE,eAAe,CAAC,uBAAuB,CAAC,CAAA;CAC3D"}

package/dist/src/schema/GGWebSocketSchema.js

@@ -0,0 +1,32 @@
+/**
+ * WebSocket API Schema - pure data definition with typed context
+ *
+ * Type parameters:
+ * - TClientToServer: Client-facing type for clientToServer methods (returns GGPromise)
+ * - TServerToClient: Client-facing type for serverToClient methods (returns GGPromise)
+ * - TContext: Accumulated context type (parseHandshake return types)
+ * - TQuery: Query parameters on connect
+ * - TClientToServerImpl: Server implementation type for clientToServer handlers (returns Promise)
+ */
+export class GGWebSocketSchema {
+    name;
+    path;
+    middlewares;
+    contractFactory;
+    contractCache = null;
+    constructor(name, path, contractFactory, middlewares = []) {
+        this.name = name;
+        this.path = path;
+        this.middlewares = middlewares;
+        this.contractFactory = contractFactory;
+        Object.freeze(this.middlewares);
+    }
+    get contract() {
+        if (!this.contractCache) {
+            this.contractCache = this.contractFactory();
+        }
+        Object.freeze(this);
+        return this.contractCache;
+    }
+}
+//# sourceMappingURL=GGWebSocketSchema.js.map

package/dist/src/schema/GGWebSocketSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GGWebSocketSchema.js","sourceRoot":"","sources":["../../../src/schema/GGWebSocketSchema.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,MAAM,OAAO,iBAAiB;IAOV,IAAI,CAAQ;IACZ,IAAI,CAAQ;IACZ,WAAW,CAAkC;IAC5C,eAAe,CAAkC;IAC1D,aAAa,GAAsC,IAAI,CAAA;IAE/D,YACI,IAAY,EACZ,IAAY,EACZ,eAAiD,EACjD,cAAgD,EAAE;QAElD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAA;QAC9B,IAAI,CAAC,eAAe,GAAG,eAAe,CAAA;QACtC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAA;IACnC,CAAC;IAED,IAAI,QAAQ;QACR,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;YACtB,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,eAAe,EAAE,CAAA;QAC/C,CAAC;QACD,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QACnB,OAAO,IAAI,CAAC,aAAa,CAAA;IAC7B,CAAC;CACJ"}

package/dist/src/schema/webSocketSchema.d.ts

@@ -0,0 +1,52 @@
+import { GGWebSocketSchema } from "./GGWebSocketSchema";
+import { GGWebSocketMiddleware } from "./GGWebSocketMiddleware";
+import { GGContractClient, GGContractImplementation, GGContractMethod } from "@grest-ts/schema";
+/**
+ * Bidirectional websocket contract methods
+ */
+export interface GGSocketContractMethods {
+    clientToServer: Record<string, GGContractMethod>;
+    serverToClient: Record<string, GGContractMethod>;
+}
+/**
+ * WebSocket contract definition
+ */
+export interface GGSocketContract<TDef extends GGSocketContractMethods = GGSocketContractMethods> {
+    name: string;
+    methods: TDef;
+}
+/**
+ * Create a websocket contract
+ */
+export declare function defineSocketContract<TDef extends GGSocketContractMethods>(name: string, methods: TDef): GGSocketContract<TDef>;
+/**
+ * Create a WebSocket API schema builder from a contract.
+ *
+ * @example
+ * export const ChatContract = defineSocketContract("Chat", {
+ *     clientToServer: {
+ *         sendMessage: { input: IsMessage, success: IsVoid, errors: [SERVER_ERROR] }
+ *     },
+ *     serverToClient: {
+ *         onMessage: { input: IsMessage }
+ *     }
+ * })
+ *
+ * export const ChatApi = webSocketSchema(ChatContract)
+ *     .path("/chat")
+ *     .use(AuthMiddleware)
+ *     .done()
+ */
+export declare function webSocketSchema<TDef extends GGSocketContractMethods>(contract: GGSocketContract<TDef>): GGWebSocketSchemaBuilder<GGContractClient<TDef["clientToServer"]>, GGContractClient<TDef["serverToClient"]>, undefined, undefined, GGContractImplementation<TDef["clientToServer"]>>;
+declare class GGWebSocketSchemaBuilder<TClientToServer, TServerToClient, TContext = undefined, TQuery = undefined, TClientToServerImpl = TClientToServer> {
+    private readonly _contract;
+    private _path;
+    private _middlewares;
+    constructor(_contract: GGSocketContract);
+    path(path: string): this;
+    use<M extends GGWebSocketMiddleware>(middleware: M): GGWebSocketSchemaBuilder<TClientToServer, TServerToClient, TContext | M, TQuery, TClientToServerImpl>;
+    queryOnConnect<TNewQuery>(): GGWebSocketSchemaBuilder<TClientToServer, TServerToClient, TContext, TNewQuery, TClientToServerImpl>;
+    done(): GGWebSocketSchema<TClientToServer, TServerToClient, TContext, TQuery, TClientToServerImpl>;
+}
+export {};
+//# sourceMappingURL=webSocketSchema.d.ts.map

package/dist/src/schema/webSocketSchema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webSocketSchema.d.ts","sourceRoot":"","sources":["../../../src/schema/webSocketSchema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,iBAAiB,EAA6B,MAAM,qBAAqB,CAAC;AAClF,OAAO,EAAC,qBAAqB,EAAC,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAkB,gBAAgB,EAAE,wBAAwB,EAAE,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AAE/G;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACpC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;IAChD,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;CACnD;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB,CAAC,IAAI,SAAS,uBAAuB,GAAG,uBAAuB;IAC5F,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,IAAI,CAAA;CAChB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,SAAS,uBAAuB,EACrE,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,IAAI,GACd,gBAAgB,CAAC,IAAI,CAAC,CAExB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,IAAI,SAAS,uBAAuB,EAChE,QAAQ,EAAE,gBAAgB,CAAC,IAAI,CAAC,GACjC,wBAAwB,CACvB,gBAAgB,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,EACxC,gBAAgB,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,EACxC,SAAS,EACT,SAAS,EACT,wBAAwB,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CACnD,CAEA;AAED,cAAM,wBAAwB,CAC1B,eAAe,EACf,eAAe,EACf,QAAQ,GAAG,SAAS,EACpB,MAAM,GAAG,SAAS,EAClB,mBAAmB,GAAG,eAAe;IAMjC,OAAO,CAAC,QAAQ,CAAC,SAAS;IAJ9B,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,YAAY,CAA8B;gBAG7B,SAAS,EAAE,gBAAgB;IAIhD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKxB,GAAG,CAAC,CAAC,SAAS,qBAAqB,EAAE,UAAU,EAAE,CAAC,GAAG,wBAAwB,CAAC,eAAe,EAAE,eAAe,EAAE,QAAQ,GAAG,CAAC,EAAE,MAAM,EAAE,mBAAmB,CAAC;IAK1J,cAAc,CAAC,SAAS,KAAK,wBAAwB,CAAC,eAAe,EAAE,eAAe,EAAE,QAAQ,EAAE,SAAS,EAAE,mBAAmB,CAAC;IAIjI,IAAI,IAAI,iBAAiB,CAAC,eAAe,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,EAAE,mBAAmB,CAAC;CAmBrG"}

package/dist/src/schema/webSocketSchema.js

@@ -0,0 +1,62 @@
+import { GGWebSocketSchema } from "./GGWebSocketSchema.js";
+import { GGContractClass } from "@grest-ts/schema";
+/**
+ * Create a websocket contract
+ */
+export function defineSocketContract(name, methods) {
+    return { name, methods };
+}
+/**
+ * Create a WebSocket API schema builder from a contract.
+ *
+ * @example
+ * export const ChatContract = defineSocketContract("Chat", {
+ *     clientToServer: {
+ *         sendMessage: { input: IsMessage, success: IsVoid, errors: [SERVER_ERROR] }
+ *     },
+ *     serverToClient: {
+ *         onMessage: { input: IsMessage }
+ *     }
+ * })
+ *
+ * export const ChatApi = webSocketSchema(ChatContract)
+ *     .path("/chat")
+ *     .use(AuthMiddleware)
+ *     .done()
+ */
+export function webSocketSchema(contract) {
+    return new GGWebSocketSchemaBuilder(contract);
+}
+class GGWebSocketSchemaBuilder {
+    _contract;
+    _path = "";
+    _middlewares = [];
+    constructor(_contract) {
+        this._contract = _contract;
+    }
+    path(path) {
+        this._path = path;
+        return this;
+    }
+    use(middleware) {
+        this._middlewares.push(middleware);
+        return this;
+    }
+    queryOnConnect() {
+        return this;
+    }
+    done() {
+        const contract = this._contract;
+        const contractFactory = () => {
+            const methods = contract.methods;
+            const name = contract.name;
+            return {
+                apiName: name,
+                clientToServer: new GGContractClass(name + ".clientToServer", methods.clientToServer),
+                serverToClient: new GGContractClass(name + ".serverToClient", methods.serverToClient)
+            };
+        };
+        return new GGWebSocketSchema(contract.name, this._path, contractFactory, this._middlewares);
+    }
+}
+//# sourceMappingURL=webSocketSchema.js.map

package/dist/src/schema/webSocketSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webSocketSchema.js","sourceRoot":"","sources":["../../../src/schema/webSocketSchema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,iBAAiB,EAA6B,MAAM,qBAAqB,CAAC;AAElF,OAAO,EAAC,eAAe,EAA+D,MAAM,kBAAkB,CAAC;AAkB/G;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAChC,IAAY,EACZ,OAAa;IAEb,OAAO,EAAC,IAAI,EAAE,OAAO,EAAC,CAAA;AAC1B,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,eAAe,CAC3B,QAAgC;IAQhC,OAAO,IAAI,wBAAwB,CAAC,QAAQ,CAAC,CAAA;AACjD,CAAC;AAED,MAAM,wBAAwB;IAWL;IAJb,KAAK,GAAW,EAAE,CAAA;IAClB,YAAY,GAA4B,EAAE,CAAA;IAElD,YACqB,SAA2B;QAA3B,cAAS,GAAT,SAAS,CAAkB;IAEhD,CAAC;IAED,IAAI,CAAC,IAAY;QACb,IAAI,CAAC,KAAK,GAAG,IAAI,CAAA;QACjB,OAAO,IAAI,CAAA;IACf,CAAC;IAED,GAAG,CAAkC,UAAa;QAC9C,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;QAClC,OAAO,IAAW,CAAA;IACtB,CAAC;IAED,cAAc;QACV,OAAO,IAAW,CAAA;IACtB,CAAC;IAED,IAAI;QACA,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,MAAM,eAAe,GAAG,GAA+B,EAAE;YACrD,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;YACjC,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC;YAC3B,OAAO;gBACH,OAAO,EAAE,IAAI;gBACb,cAAc,EAAE,IAAI,eAAe,CAAC,IAAI,GAAG,iBAAiB,EAAE,OAAO,CAAC,cAAc,CAAC;gBACrF,cAAc,EAAE,IAAI,eAAe,CAAC,IAAI,GAAG,iBAAiB,EAAE,OAAO,CAAC,cAAc,CAAC;aACxF,CAAC;QACN,CAAC,CAAC;QAEF,OAAO,IAAI,iBAAiB,CACxB,QAAQ,CAAC,IAAI,EACb,IAAI,CAAC,KAAK,EACV,eAAe,EACf,IAAI,CAAC,YAAY,CACpB,CAAA;IACL,CAAC;CACJ"}

package/dist/src/server/GGSocketServer.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Manages WebSocket connections for a single endpoint
+ * Handles connection acceptance, effect parsing via handshake, and socket lifecycle
+ */
+import { GGValidator } from "@grest-ts/schema";
+import { GGSocket } from "../socket/GGSocket";
+import { 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 declare class GGSocketServer<TContext, Query> {
+    private readonly wss;
+    private readonly http;
+    readonly path: string;
+    private readonly apiName;
+    private readonly middlewares;
+    private readonly queryValidator;
+    private readonly activeSockets;
+    private readonly onConnectionHandlers;
+    private readonly scope;
+    constructor(http: GGHttpServer, config: GGSocketServerConfig<TContext, Query>);
+    onConnection(handler: (socket: GGSocket, query: Query) => void): void;
+    private _onConnection;
+    /**
+     * Handle handshake message from client.
+     * Waits for HANDSHAKE message with headers, runs effects, returns context.
+     */
+    private handleHandshake;
+}
+//# sourceMappingURL=GGSocketServer.d.ts.map

package/dist/src/server/GGSocketServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GGSocketServer.d.ts","sourceRoot":"","sources":["../../../src/server/GGSocketServer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAQ,WAAW,EAAC,MAAM,kBAAkB,CAAC;AASpD,OAAO,EAAC,QAAQ,EAAC,MAAM,oBAAoB,CAAC;AAM5C,OAAO,EAA8B,qBAAqB,EAAC,MAAM,iCAAiC,CAAC;AACnG,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAE5C,MAAM,WAAW,oBAAoB,CAAC,QAAQ,EAAE,KAAK;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC;IACpC,WAAW,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACjD;AAED,qBAAa,cAAc,CAAC,QAAQ,EAAE,KAAK;IAEvC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAkB;IACtC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IACpC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmC;IAC/D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IAEpD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4B;IAC1D,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAuD;IAG5F,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;gBAE3B,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,oBAAoB,CAAC,QAAQ,EAAE,KAAK,CAAC;IAiCtE,YAAY,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI;IAI5E,OAAO,CAAC,aAAa,CA8EpB;IAED;;;OAGG;YACW,eAAe;CAiDhC"}

package/dist/src/server/GGSocketServer.js

@@ -0,0 +1,186 @@
+/**
+ * Manages WebSocket connections for a single endpoint
+ * Handles connection acceptance, effect parsing via handshake, and socket lifecycle
+ */
+import { WebSocketServer } from "ws";
+import { ERROR } from "@grest-ts/schema";
+import { NodeSocketAdapter } from "../adapter/NodeSocketAdapter.js";
+import * as url from "url";
+import { GGLog } from "@grest-ts/logger";
+import { GG_WS_CONNECTION } from "./GG_WS_CONNECTION.js";
+import { GGWebSocketMetrics } from "./GGWebSocketMetrics.js";
+import { Message, MessageType } from "../socket/SocketMessage.js";
+import { GG_TRACE } from "@grest-ts/trace";
+import { GGSocket } from "../socket/GGSocket.js";
+import { GGLocator } 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";
+export class GGSocketServer {
+    wss;
+    http;
+    path;
+    apiName;
+    middlewares;
+    queryValidator;
+    activeSockets = new Set();
+    onConnectionHandlers = [];
+    // Capture context at construction - WebSocket events lose AsyncLocalStorage context
+    scope;
+    constructor(http, config) {
+        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");
+        });
+    }
+    onConnection(handler) {
+        this.onConnectionHandlers.push(handler);
+    }
+    _onConnection = async (ws, req) => {
+        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;
+                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;
+                }
+                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.error);
+                    if (GG_METRICS.has())
+                        GGWebSocketMetrics.connections.inc(1, { ...connectionLabels, result: 'HANDSHAKE_FAILED' });
+                    adapter.send(Message.create(MessageType.HANDSHAKE_ERR, "", "", handshakeResult.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.
+     */
+    async handleHandshake(context, adapter, queryArgs) {
+        return withTimeout(new Promise((resolve) => {
+            // Wrap with scope.wrapWithEnter to preserve locator scope when callback fires
+            const onMessage = this.scope.wrapWithEnter((data) => {
+                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 = {
+                                headers,
+                                queryArgs: queryArgs
+                            };
+                            // Run middlewares
+                            for (const middleware of this.middlewares) {
+                                middleware.parseHandshake?.(handshakeContext);
+                                await middleware.process?.();
+                            }
+                            resolve({ success: true });
+                        }
+                        catch (error) {
+                            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: { message: error.message || 'Handshake timeout' }
+        }));
+    }
+}
+//# sourceMappingURL=GGSocketServer.js.map

package/dist/src/server/GGSocketServer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GGSocketServer.js","sourceRoot":"","sources":["../../../src/server/GGSocketServer.ts"],"names":[],"mappings":"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"}

package/dist/src/server/GGWebSocketMetrics.d.ts

@@ -0,0 +1,43 @@
+import { GGCounterKey, GGGaugeKey, GGHistogramKey } 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 declare const GGWebSocketMetrics: import("@grest-ts/metrics").GGMetricsDefinition<{
+    connectionsActive: GGGaugeKey<{
+        api: string;
+        path: string;
+    }>;
+    connections: GGCounterKey<{
+        api: string;
+        path: string;
+        result: SocketConnectionResult;
+    }>;
+    requests: GGCounterKey<{
+        api: string;
+        path: string;
+        method: string;
+        result: ResultType;
+    }>;
+    requestDuration: GGHistogramKey<{
+        api: string;
+        path: string;
+        method: string;
+    }>;
+    outRequests: GGCounterKey<{
+        api: string;
+        path: string;
+        method: string;
+        result: ResultType;
+    }>;
+    outRequestDuration: GGHistogramKey<{
+        api: string;
+        path: string;
+        method: string;
+    }>;
+}>;
+export {};
+//# sourceMappingURL=GGWebSocketMetrics.d.ts.map

package/dist/src/server/GGWebSocketMetrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GGWebSocketMetrics.d.ts","sourceRoot":"","sources":["../../../src/server/GGWebSocketMetrics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,YAAY,EAAE,UAAU,EAAE,cAAc,EAAY,MAAM,mBAAmB,CAAC;AACtF,OAAO,EAAC,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,SAAS,EAAE,EAAE,EAAE,eAAe,EAAE,YAAY,EAAE,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AAEnI;;;GAGG;AACH,KAAK,UAAU,GACT,OAAO,EAAE,CAAC,IAAI,GACd,OAAO,gBAAgB,CAAC,IAAI,GAC5B,OAAO,cAAc,CAAC,IAAI,GAC1B,OAAO,SAAS,CAAC,IAAI,GACrB,OAAO,SAAS,CAAC,IAAI,GACrB,OAAO,eAAe,CAAC,IAAI,GAC3B,OAAO,MAAM,CAAC,IAAI,GAClB,OAAO,YAAY,CAAC,IAAI,GACxB,MAAM,CAAC;AAEb,KAAK,sBAAsB,GAAG,IAAI,GAAG,aAAa,GAAG,eAAe,GAAG,MAAM,CAAC;AAE9E,eAAO,MAAM,kBAAkB;;aACc,MAAM;cAAQ,MAAM;;;aAKxB,MAAM;cAAQ,MAAM;gBAAU,sBAAsB;;;aAOvD,MAAM;cAAQ,MAAM;gBAAU,MAAM;gBAAU,UAAU;;;aAK/C,MAAM;cAAQ,MAAM;gBAAU,MAAM;;;aAQ1C,MAAM;cAAQ,MAAM;gBAAU,MAAM;gBAAU,UAAU;;;aAK/C,MAAM;cAAQ,MAAM;gBAAU,MAAM;;EAMnF,CAAC"}

package/dist/src/server/GGWebSocketMetrics.js

@@ -0,0 +1,38 @@
+import { GGCounterKey, GGGaugeKey, GGHistogramKey, GGMetrics } from "@grest-ts/metrics";
+export const GGWebSocketMetrics = GGMetrics.define('/websocket/', () => ({
+    connectionsActive: new GGGaugeKey('connections_active', {
+        help: 'Active WebSocket connections',
+        labelNames: ['api', 'path'],
+        groupBy: { labels: ["api"] }
+    }),
+    connections: new GGCounterKey('connections_total', {
+        help: 'Total WebSocket connection attempts',
+        labelNames: ['api', 'path', 'result'],
+        groupBy: { labels: ["api"] }
+    }),
+    // Incoming (server handling REQ + MSG)
+    requests: new GGCounterKey('requests_total', {
+        help: 'Total incoming WebSocket commands (REQ + MSG)',
+        labelNames: ['api', 'path', 'method', 'result'],
+        groupBy: { labels: ["api", "method"], template: "{api}.{method}" }
+    }),
+    requestDuration: new GGHistogramKey('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('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('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}" }
+    }),
+}));
+//# sourceMappingURL=GGWebSocketMetrics.js.map

package/dist/src/server/GGWebSocketMetrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GGWebSocketMetrics.js","sourceRoot":"","sources":["../../../src/server/GGWebSocketMetrics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,SAAS,EAAC,MAAM,mBAAmB,CAAC;AAoBtF,MAAM,CAAC,MAAM,kBAAkB,GAAG,SAAS,CAAC,MAAM,CAAC,aAAa,EAAE,GAAG,EAAE,CAAC,CAAC;IACrE,iBAAiB,EAAE,IAAI,UAAU,CAAgC,oBAAoB,EAAE;QACnF,IAAI,EAAE,8BAA8B;QACpC,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC;QAC3B,OAAO,EAAE,EAAC,MAAM,EAAE,CAAC,KAAK,CAAC,EAAC;KAC7B,CAAC;IACF,WAAW,EAAE,IAAI,YAAY,CAAgE,mBAAmB,EAAE;QAC9G,IAAI,EAAE,qCAAqC;QAC3C,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC;QACrC,OAAO,EAAE,EAAC,MAAM,EAAE,CAAC,KAAK,CAAC,EAAC;KAC7B,CAAC;IAEF,uCAAuC;IACvC,QAAQ,EAAE,IAAI,YAAY,CAAoE,gBAAgB,EAAE;QAC5G,IAAI,EAAE,+CAA+C;QACrD,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC;QAC/C,OAAO,EAAE,EAAC,MAAM,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,QAAQ,EAAE,gBAAgB,EAAC;KACnE,CAAC;IACF,eAAe,EAAE,IAAI,cAAc,CAAgD,qBAAqB,EAAE;QACtG,IAAI,EAAE,gEAAgE;QACtE,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC;QACrC,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC;QAChD,OAAO,EAAE,EAAC,MAAM,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,QAAQ,EAAE,gBAAgB,EAAC;KACnE,CAAC;IAEF,qCAAqC;IACrC,WAAW,EAAE,IAAI,YAAY,CAAoE,oBAAoB,EAAE;QACnH,IAAI,EAAE,+CAA+C;QACrD,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC;QAC/C,OAAO,EAAE,EAAC,MAAM,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,QAAQ,EAAE,gBAAgB,EAAC;KACnE,CAAC;IACF,kBAAkB,EAAE,IAAI,cAAc,CAAgD,yBAAyB,EAAE;QAC7G,IAAI,EAAE,2EAA2E;QACjF,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC;QACrC,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC;QACtD,OAAO,EAAE,EAAC,MAAM,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,QAAQ,EAAE,gBAAgB,EAAC;KACnE,CAAC;CACL,CAAC,CAAC,CAAC"}

package/dist/src/server/GGWebSocketSchema.startServer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Server extension for WebSocketSchema - adds startServer and register methods
+ * This file should only be imported in server (Node.js) context
+ */
+import { GGWebSocketMiddleware } from "../schema/GGWebSocketMiddleware";
+import { GGSocketServer } from "./GGSocketServer";
+import { WebSocketIncoming, WebSocketOutgoing } from "../socket/WebSocketTypes";
+import { GGHttpServer } from "@grest-ts/http";
+export interface WebSocketSchemaConfig {
+    /**
+     * The HTTP server adapter to attach the WebSocket server to.
+     * If not provided, will look up from locator.
+     */
+    http?: GGHttpServer;
+    /**
+     * Additional middlewares to apply to all connections.
+     */
+    middlewares?: GGWebSocketMiddleware[];
+}
+declare module "../schema/GGWebSocketSchema" {
+    interface GGWebSocketSchema<TClientToServer, TServerToClient, TContext = {}, TQuery = undefined, TClientToServerImpl = TClientToServer> {
+        /**
+         * Start the WebSocket server for this API.
+         */
+        startServer(onConnection: (incoming: WebSocketIncoming<TClientToServerImpl>, outgoing: WebSocketOutgoing<TServerToClient>) => void, config: WebSocketSchemaConfig): GGSocketServer<TContext, TQuery>;
+        /**
+         * Register this WebSocket API with the default HTTP server.
+         * Uses GGHttpServerAdapter from locator if not explicitly provided.
+         */
+        register(onConnection: (incoming: WebSocketIncoming<TClientToServerImpl>, outgoing: WebSocketOutgoing<TServerToClient>) => void, config?: WebSocketSchemaConfig): void;
+    }
+}
+//# sourceMappingURL=GGWebSocketSchema.startServer.d.ts.map

package/dist/src/server/GGWebSocketSchema.startServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GGWebSocketSchema.startServer.d.ts","sourceRoot":"","sources":["../../../src/server/GGWebSocketSchema.startServer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAC,qBAAqB,EAAC,MAAM,iCAAiC,CAAC;AACtE,OAAO,EAAC,cAAc,EAAC,MAAM,kBAAkB,CAAC;AAEhD,OAAO,EAAC,iBAAiB,EAAE,iBAAiB,EAAC,MAAM,0BAA0B,CAAC;AAC9E,OAAO,EAAiB,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAE5D,MAAM,WAAW,qBAAqB;IAClC;;;OAGG;IACH,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB;;OAEG;IACH,WAAW,CAAC,EAAE,qBAAqB,EAAE,CAAC;CACzC;AAED,OAAO,QAAQ,6BAA6B,CAAC;IACzC,UAAU,iBAAiB,CAAC,eAAe,EAAE,eAAe,EAAE,QAAQ,GAAG,EAAE,EAAE,MAAM,GAAG,SAAS,EAAE,mBAAmB,GAAG,eAAe;QAClI;;WAEG;QACH,WAAW,CACP,YAAY,EAAE,CAAC,QAAQ,EAAE,iBAAiB,CAAC,mBAAmB,CAAC,EAAE,QAAQ,EAAE,iBAAiB,CAAC,eAAe,CAAC,KAAK,IAAI,EACtH,MAAM,EAAE,qBAAqB,GAC9B,cAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;QAEnC;;;WAGG;QACH,QAAQ,CACJ,YAAY,EAAE,CAAC,QAAQ,EAAE,iBAAiB,CAAC,mBAAmB,CAAC,EAAE,QAAQ,EAAE,iBAAiB,CAAC,eAAe,CAAC,KAAK,IAAI,EACtH,MAAM,CAAC,EAAE,qBAAqB,GAC/B,IAAI,CAAA;KACV;CACJ"}