@socket-mesh/server 19.0.0 → 19.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 SocketMesh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/server-options.d.ts

@@ -23,6 +23,9 @@ export interface ServerOptions<TIncoming extends PublicMethodMap = {}, TOutgoing
     pingIntervalMs?: number;
     pingTimeoutMs?: number;
     plugins?: ServerPlugin<TIncoming, TOutgoing, TChannel, TService, TState, TPrivateIncoming, TPrivateOutgoing, TServerState>[];
+    serviceHandlers?: {
+        [TServiceName in keyof TService & string]?: HandlerMap<TService[TServiceName], TState & ServerSocketState, ServerSocket<TIncoming, TOutgoing, TChannel, TService, TState, TPrivateIncoming, TPrivateOutgoing, TServerState>, ServerTransport<TIncoming, TOutgoing, TChannel, TService, TState, TPrivateIncoming, TPrivateOutgoing, TServerState>>;
+    };
     socketChannelLimit?: number;
     socketStreamCleanupMode?: StreamCleanupMode;
     strictHandshake?: boolean;

package/dist/server-socket.d.ts

@@ -1,6 +1,6 @@
 import { ChannelMap } from '@socket-mesh/channels';
 import { ClientPrivateMap, ServerPrivateMap } from '@socket-mesh/client';
-import { AuthenticateEvent, AuthStateChangeEvent, BadAuthTokenEvent, BaseSocket, BaseSocketOptions, CloseEvent, ConnectEvent, ConnectingEvent, DeauthenticateEvent, DisconnectEvent, ErrorEvent, FunctionReturnType, InvokeMethodOptions, InvokeServiceOptions, LooseHandlerMap, MessageEvent, PingEvent, PongEvent, PrivateMethodMap, PublicMethodMap, RemoveAuthTokenEvent, RequestEvent, ResponseEvent, ServiceMap, ServiceMethodName, ServiceName, Socket, TypedRequestEvent, TypedResponseEvent, TypedSocketEvent } from '@socket-mesh/core';
+import { AuthenticateEvent, AuthStateChangeEvent, BadAuthTokenEvent, BaseSocket, BaseSocketOptions, CloseEvent, ConnectEvent, ConnectingEvent, DeauthenticateEvent, DisconnectEvent, ErrorEvent, FunctionReturnType, InvokeMethodOptions, InvokeServiceOptions, MessageEvent, PingEvent, PongEvent, PrivateMethodMap, PublicMethodMap, RemoveAuthTokenEvent, RequestEvent, ResponseEvent, ServiceMap, ServiceMethodName, ServiceName, Socket, TypedRequestEvent, TypedResponseEvent, TypedSocketEvent } from '@socket-mesh/core';
 import { DemuxedConsumableStream, StreamEvent } from '@socket-mesh/stream-demux';
 import { IncomingMessage } from 'http';
 import { WebSocket } from 'ws';
@@ -9,7 +9,6 @@ import { ServerPlugin } from './plugin/server-plugin.js';
 import { ServerSocketState } from './server-socket-state.js';
 import { Server } from './server.js';
 export interface ServerSocketOptions<TIncoming extends PublicMethodMap, TOutgoing extends PublicMethodMap, TChannel extends ChannelMap, TService extends ServiceMap, TState extends object, TPrivateIncoming extends PrivateMethodMap, TPrivateOutgoing extends PrivateMethodMap, TServerState extends object> extends BaseSocketOptions<TState & ServerSocketState> {
-    handlers: LooseHandlerMap;
     id?: string;
     plugins?: ServerPlugin<TIncoming, TOutgoing, TChannel, TService, TState, TPrivateIncoming, TPrivateOutgoing, TServerState>[];
     request: IncomingMessage;

package/dist/server.d.ts

@@ -1,7 +1,8 @@
 import { AsyncStreamEmitter } from '@socket-mesh/async-stream-emitter';
 import { AuthEngine } from '@socket-mesh/auth-engine';
 import { ChannelMap } from '@socket-mesh/channels';
-import { PrivateMethodMap, PublicMethodMap, ServiceMap, StreamCleanupMode } from '@socket-mesh/core';
+import { ServerPrivateMap } from '@socket-mesh/client';
+import { HandlerMap, MethodMap, PrivateMethodMap, PublicMethodMap, ServiceMap, StreamCleanupMode } from '@socket-mesh/core';
 import { CodecEngine } from '@socket-mesh/formatter';
 import { DemuxedConsumableStream, StreamEvent } from '@socket-mesh/stream-demux';
 import { Server as HttpServer } from 'http';
@@ -10,10 +11,12 @@ import { Exchange } from './broker/exchange.js';
 import { CloseEvent, ConnectionEvent, ErrorEvent, HandshakeEvent, HeadersEvent, ListeningEvent, ServerEvent, SocketAuthenticateEvent, SocketAuthStateChangeEvent, SocketBadAuthTokenEvent, SocketCloseEvent, SocketConnectEvent, SocketConnectingEvent, SocketDeauthenticateEvent, SocketDisconnectEvent, SocketErrorEvent, SocketMessageEvent, SocketPingEvent, SocketPongEvent, SocketRemoveAuthTokenEvent, SocketRequestEvent, SocketResponseEvent, SocketSubscribeEvent, SocketSubscribeFailEvent, SocketSubscribeStateChangeEvent, SocketUnsubscribeEvent, WarningEvent } from './events/index.js';
 import { ServerPlugin } from './plugin/server-plugin.js';
 import { ServerOptions } from './server-options.js';
+import { ServerSocketState } from './server-socket-state.js';
 import { ServerSocket } from './server-socket.js';
+import { ServerTransport } from './server-transport.js';
 export declare class Server<TIncoming extends PublicMethodMap = {}, TOutgoing extends PublicMethodMap = {}, TChannel extends ChannelMap = {}, TService extends ServiceMap = {}, TState extends object = {}, TPrivateIncoming extends PrivateMethodMap = {}, TPrivateOutgoing extends PrivateMethodMap = {}, TServerState extends object = {}> extends AsyncStreamEmitter<ServerEvent<TIncoming, TOutgoing, TChannel, TService, TState, TPrivateIncoming, TPrivateOutgoing, TServerState>> {
     private readonly _callIdGenerator;
-    private _handlers;
+    private readonly _handlers;
     private _isListening;
     private _isReady;
     private _pingIntervalRef;
@@ -41,6 +44,41 @@ export declare class Server<TIncoming extends PublicMethodMap = {}, TOutgoing ex
     readonly socketStreamCleanupMode: StreamCleanupMode;
     strictHandshake: boolean;
     constructor(options?: ServerOptions<TIncoming, TOutgoing, TChannel, TService, TState, TPrivateIncoming, TPrivateOutgoing, TServerState>);
+    /**
+     * Register a group of strongly-typed request handlers.
+     *
+     * Handlers added this way can be added or replaced after the server has
+     * started and are immediately visible to all existing and future
+     * connections (the underlying handler map is shared by reference).
+     *
+     * When called with a service name, the handlers are grouped under that
+     * service and surfaced via {@link services} so UI/tooling can list which
+     * groups are currently installed. When the service name is known to the
+     * server's `TService` generic, TypeScript validates the handler shape
+     * against the declared method map. For ad-hoc/dynamic services not
+     * present in `TService`, pass an explicit generic argument with the
+     * method map for the new service.
+     *
+     * When called without a service name, the handlers are registered as
+     * flat (top-level) handlers routed by method name alone — the same
+     * surface as `options.handlers` on the server constructor. These do not
+     * appear in {@link services}.
+     *
+     * @example
+     * // Flat handlers (no service name):
+     * server.addHandlers({ doThing: async (args) => { ... } });
+     *
+     * @example
+     * // Statically declared on the server generic:
+     * server.addHandlers('account', { find: async (args) => { ... } });
+     *
+     * @example
+     * // Dynamically added from a module at runtime:
+     * server.addHandlers<'inventory', InventoryMethodMap>('inventory', handlers);
+     */
+    addHandlers(handlers: HandlerMap<TIncoming & TPrivateIncoming & ServerPrivateMap, TState & ServerSocketState, ServerSocket<TIncoming, TOutgoing, TChannel, TService, TState, TPrivateIncoming, TPrivateOutgoing, TServerState>, ServerTransport<TIncoming, TOutgoing, TChannel, TService, TState, TPrivateIncoming, TPrivateOutgoing, TServerState>>): void;
+    addHandlers<TServiceName extends keyof TService & string>(service: TServiceName, handlers: HandlerMap<TService[TServiceName], TState & ServerSocketState, ServerSocket<TIncoming, TOutgoing, TChannel, TService, TState, TPrivateIncoming, TPrivateOutgoing, TServerState>, ServerTransport<TIncoming, TOutgoing, TChannel, TService, TState, TPrivateIncoming, TPrivateOutgoing, TServerState>>): void;
+    addHandlers<TServiceName extends string, TServiceMethodMap extends MethodMap>(service: TServiceName, handlers: HandlerMap<TServiceMethodMap, TState & ServerSocketState, ServerSocket<TIncoming, TOutgoing, TChannel, TService, TState, TPrivateIncoming, TPrivateOutgoing, TServerState>, ServerTransport<TIncoming, TOutgoing, TChannel, TService, TState, TPrivateIncoming, TPrivateOutgoing, TServerState>>): void;
     addPlugin(...plugin: ServerPlugin<TIncoming, TOutgoing, TChannel, TService, TState, TPrivateIncoming, TPrivateOutgoing, TServerState>[]): void;
     private bind;
     close(keepSocketsOpen?: boolean): Promise<void>;
@@ -74,6 +112,8 @@ export declare class Server<TIncoming extends PublicMethodMap = {}, TOutgoing ex
     emit(event: 'socketUnsubscribe', data: SocketUnsubscribeEvent<TIncoming, TOutgoing, TChannel, TService, TState, TPrivateIncoming, TPrivateOutgoing, TServerState>): void;
     emit(event: 'warning', data: WarningEvent): void;
     get exchange(): Exchange<TChannel>;
+    /** Method names registered under a given service, or an empty array if none. */
+    getServiceMethods(service: string): string[];
     get isListening(): boolean;
     get isReady(): boolean;
     listen(): DemuxedConsumableStream<StreamEvent<ServerEvent<TIncoming, TOutgoing, TChannel, TService, TState, TPrivateIncoming, TPrivateOutgoing, TServerState>>>;
@@ -111,6 +151,19 @@ export declare class Server<TIncoming extends PublicMethodMap = {}, TOutgoing ex
     private onError;
     private onHeaders;
     private onListening;
+    /**
+     * Unregister either a whole service (when `methods` is omitted) or a
+     * specific set of methods within a service. Removing a service empties
+     * the group and drops the key so it no longer appears in {@link services}.
+     *
+     * Call with an array of method names (no service) to remove flat
+     * (top-level) handlers by name. The flat slot itself is never dropped
+     * because it holds the built-in protocol handlers.
+     */
+    removeHandlers(methods: readonly string[]): void;
+    removeHandlers(service: string, methods?: readonly string[] | string): void;
+    /** Names of all service handler groups currently registered on the server. */
+    get services(): string[];
     private socketDisconnected;
     private startPinging;
     private stopPinging;

package/dist/server.js

@@ -58,14 +58,23 @@ export class Server extends AsyncStreamEmitter {
         this.clients = {};
         this.clientCount = 0;
         this.codecEngine = options.codecEngine || defaultCodec;
-        this._handlers = Object.assign({
-            '#authenticate': authenticateHandler,
-            '#handshake': handshakeHandler,
-            '#publish': publishHandler,
-            '#removeAuthToken': removeAuthTokenHandler,
-            '#subscribe': subscribeHandler,
-            '#unsubscribe': unsubscribeHandler
-        }, options.handlers);
+        // Flat handlers live under the empty-string service key so dispatch
+        // (and Server.addHandlers/removeHandlers) only has to consult one map.
+        this._handlers = {
+            '': Object.assign({
+                '#authenticate': authenticateHandler,
+                '#handshake': handshakeHandler,
+                '#publish': publishHandler,
+                '#removeAuthToken': removeAuthTokenHandler,
+                '#subscribe': subscribeHandler,
+                '#unsubscribe': unsubscribeHandler
+            }, options.handlers)
+        };
+        if (options.serviceHandlers) {
+            for (const service of Object.keys(options.serviceHandlers)) {
+                this._handlers[service] = { ...options.serviceHandlers[service] };
+            }
+        }
         this.httpServer = options.server;
         this.plugins = options.plugins || [];
         this.origins = options.origins || '*:*';
@@ -104,6 +113,14 @@ export class Server extends AsyncStreamEmitter {
             })();
         }
     }
+    addHandlers(serviceOrHandlers, handlers) {
+        const service = typeof serviceOrHandlers === 'string' ? serviceOrHandlers : '';
+        const map = typeof serviceOrHandlers === 'string' ? handlers : serviceOrHandlers;
+        if (!this._handlers[service]) {
+            this._handlers[service] = {};
+        }
+        Object.assign(this._handlers[service], map);
+    }
     addPlugin(...plugin) {
         this.plugins.push(...plugin);
     }
@@ -180,6 +197,16 @@ export class Server extends AsyncStreamEmitter {
     get exchange() {
         return this.brokerEngine.exchange;
     }
+    /** Method names registered under a given service, or an empty array if none. */
+    getServiceMethods(service) {
+        if (service === '') {
+            // The empty-string slot stores flat (non-service) handlers internally
+            // and is not part of the public service surface.
+            return [];
+        }
+        const group = this._handlers[service];
+        return group ? Object.keys(group) : [];
+    }
     get isListening() {
         return this._isListening;
     }
@@ -204,10 +231,10 @@ export class Server extends AsyncStreamEmitter {
             ackTimeoutMs: this.ackTimeoutMs,
             callIdGenerator: this._callIdGenerator,
             codecEngine: this.codecEngine,
-            handlers: this._handlers,
             plugins: this.plugins,
             request: upgradeReq,
             server: this,
+            serviceHandlers: this._handlers,
             socket: wsSocket,
             state: {},
             streamCleanupMode: this.socketStreamCleanupMode
@@ -232,6 +259,41 @@ export class Server extends AsyncStreamEmitter {
         this._isListening = true;
         this.emit('listening', {});
     }
+    removeHandlers(serviceOrMethods, methods) {
+        let service;
+        let list;
+        if (Array.isArray(serviceOrMethods)) {
+            service = '';
+            list = serviceOrMethods;
+        }
+        else {
+            service = serviceOrMethods;
+            list = typeof methods === 'string' ? [methods] : methods;
+        }
+        const group = this._handlers[service];
+        if (!group) {
+            return;
+        }
+        if (list === undefined) {
+            // Never drop the flat slot — it holds built-in protocol handlers.
+            if (service !== '') {
+                delete this._handlers[service];
+            }
+            return;
+        }
+        for (const method of list) {
+            delete group[method];
+        }
+        if (service !== '' && Object.keys(group).length === 0) {
+            delete this._handlers[service];
+        }
+    }
+    /** Names of all service handler groups currently registered on the server. */
+    get services() {
+        // The empty-string slot holds flat (non-service) handlers internally
+        // and is not part of the public service surface.
+        return Object.keys(this._handlers).filter(service => service !== '');
+    }
     socketDisconnected(socket) {
         if (this.pendingClients[socket.id]) {
             delete this.pendingClients[socket.id];

package/package.json

@@ -1,81 +1,83 @@
-{
-	"name": "@socket-mesh/server",
-	"description": "A TCP socket pair for easily transmitting full messages without worrying about request size limits.",
-	"version": "19.0.0",
-	"type": "module",
-	"main": "dist/index.js",
-	"types": "dist/index.d.ts",
-	"files": ["./dist"],
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.js",
-			"default": "./dist/index.js"
-		},
-		"./broker": {
-			"types": "./dist/broker/index.d.ts",
-			"import": "./dist/broker/index.js",
-			"default": "./dist/broker/index.js"
-		},
-		"./events": {
-			"types": "./dist/events/index.d.ts",
-			"import": "./dist/events/index.js",
-			"default": "./dist/events/index.js"
-		},
-		"./handlers": {
-			"types": "./dist/handlers/index.d.ts",
-			"import": "./dist/handlers/index.js",
-			"default": "./dist/handlers/index.js"
-		}
-	},
-	"author": {
-		"name": "Greg Kimmy"
-	},
-	"scripts": {
-		"build": "node ../../scripts/build.mjs && tsc --project tsconfig.build.json",
-		"deploy": "node ../../scripts/publish.mjs",
-		"lint": "eslint . --c ../../eslint.config.mjs",
-		"lint:fix": "eslint . --c ../../eslint.config.mjs --fix",
-		"test": "tsx --tsconfig ./tsconfig.build.json --test ./src/**/*.{spec,test}.ts ./test/**/*.{spec,test}.ts"
-	},
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/socket-mesh/client-server.git"
-	},
-	"bugs": {
-		"url": "https://github.com/socket-mesh/client-server/labels/server"
-	},	
-	"devDependencies": {
-		"@socket-mesh/local-storage": "workspace:^",
-		"@socket-mesh/typescript-config": "workspace:^",
-		"@types/base64id": "catalog:base64id",
-		"@types/jsonwebtoken": "catalog:json-web-token",
-		"@types/ws": "catalog:ws"
-	},
-	"dependencies": {
-		"@socket-mesh/async-stream-emitter": "workspace:^",
-		"@socket-mesh/auth": "workspace:^",
-		"@socket-mesh/auth-engine": "workspace:^",
-		"@socket-mesh/channels": "workspace:^",
-		"@socket-mesh/client": "workspace:^",
-		"@socket-mesh/core": "workspace:^",
-		"@socket-mesh/errors": "workspace:^",
-		"@socket-mesh/formatter": "workspace:^",
-		"@socket-mesh/stream-demux": "workspace:^",
-		"@socket-mesh/writable-consumable-stream": "workspace:^",
-		"base64id": "catalog:base64id",
-		"events": "catalog:",
-		"jsonwebtoken": "catalog:json-web-token",
-		"ws": "catalog:ws"
-	},
-	"keywords": [
-		"ncom",
-		"tcp",
-		"simple",
-		"socket",
-		"messages"
-	],
-	"engines": {
-		"node": ">= 0.8.0"
-	}
-}
+{
+  "name": "@socket-mesh/server",
+  "description": "A TCP socket pair for easily transmitting full messages without worrying about request size limits.",
+  "version": "19.1.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "./dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./broker": {
+      "types": "./dist/broker/index.d.ts",
+      "import": "./dist/broker/index.js",
+      "default": "./dist/broker/index.js"
+    },
+    "./events": {
+      "types": "./dist/events/index.d.ts",
+      "import": "./dist/events/index.js",
+      "default": "./dist/events/index.js"
+    },
+    "./handlers": {
+      "types": "./dist/handlers/index.d.ts",
+      "import": "./dist/handlers/index.js",
+      "default": "./dist/handlers/index.js"
+    }
+  },
+  "author": {
+    "name": "Greg Kimmy"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/socket-mesh/client-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/socket-mesh/client-server/labels/server"
+  },
+  "devDependencies": {
+    "@types/base64id": "^2.0.2",
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/ws": "^8.18.1",
+    "@socket-mesh/local-storage": "^1.0.5",
+    "@socket-mesh/typescript-config": "^0.0.0"
+  },
+  "dependencies": {
+    "base64id": "^2.0.0",
+    "events": "^3.3.0",
+    "jsonwebtoken": "^9.0.3",
+    "ws": "^8.20.0",
+    "@socket-mesh/auth": "^2.2.2",
+    "@socket-mesh/async-stream-emitter": "^7.2.3",
+    "@socket-mesh/channels": "^6.1.6",
+    "@socket-mesh/auth-engine": "^1.0.3",
+    "@socket-mesh/client": "^19.1.1",
+    "@socket-mesh/errors": "^3.2.2",
+    "@socket-mesh/core": "^2.1.1",
+    "@socket-mesh/stream-demux": "^10.2.5",
+    "@socket-mesh/writable-consumable-stream": "^4.3.3",
+    "@socket-mesh/formatter": "^4.1.2"
+  },
+  "keywords": [
+    "ncom",
+    "tcp",
+    "simple",
+    "socket",
+    "messages"
+  ],
+  "engines": {
+    "node": ">= 0.8.0"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build.mjs && tsc --project tsconfig.build.json",
+    "deploy": "node ../../scripts/publish.mjs",
+    "lint": "eslint . --c ../../eslint.config.mjs",
+    "lint:fix": "eslint . --c ../../eslint.config.mjs --fix",
+    "test": "tsx --tsconfig ./tsconfig.build.json --test ./src/**/*.{spec,test}.ts ./test/**/*.{spec,test}.ts"
+  }
+}