@wishcore/wish-rpc 0.6.14 → 0.6.15

package/dist/src/rpc-server.js

@@ -1,43 +1,96 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Server = void 0;
+const method_registry_1 = require("./method-registry");
+const debug = console.log;
 /**
- * The idea is to be able to easily register methods/functions to be called
- * remotely, to enable access control and return data directly, asynchronously or
- * opening a stream which delivers data for long running tasks or large data
- * transfers.
+ * RPC Server for registering and handling remote procedure calls.
+ *
+ * Supports both modern endpoint registration and legacy underscore-prefixed methods.
+ * Provides real-time communication with support for streaming, events, and async operations.
+ *
+ * Type-safe endpoint registration with custom configuration:
+ * ```typescript
+ * interface ReasonEndpoint extends BaseEndpointConfig {
+ *     validateArgs?: (args: any[], context: any) => boolean;
+ *     permissions?: string[];
+ *     rateLimit?: number;
+ * }
  *
- * When registerCore is run with the wish core instance, it reads all objects
- * that have a property named "_". It scans those properties for properties
- * which have a descriptor property with the same name prepended with "_".
+ * const server = new Server<ReasonEndpoint>();
+ * server.endpoint('user.get', {
+ *     doc: 'Get user by ID',
+ *     args: 'userId: string',
+ *     validateArgs: (args, context) => validateUserArgs(args),
+ *     permissions: ['user', 'admin'],
+ *     rateLimit: 100
+ * }, async (req, res) => {
+ *     const user = await getUserById(req.args[0]);
+ *     res.send(user);
+ * });
+ * ```
  *
- * Sub modules are not implemented yet, but an example should look like the
- * relay, module below.
+ * Default usage (backwards compatible):
+ * ```typescript
+ * const server = new Server();
+ * server.endpoint('user.get', {
+ *     doc: 'Get user by ID',
+ *     args: 'userId: string',
+ *     validate: (args, context) => validateUserArgs(args)
+ * }, async (req, res) => {
+ *     const user = await getUserById(req.args[0]);
+ *     res.send(user);
+ * });
+ * ```
  *
- * Ex.
- *   rpc.insertMethods({
- *       _doThis: {
- *           doc: "This function does this, and emits progress each second and end.",
- *       },
- *       doThis: function(req,res) {
- *           ...
- *       },
- *       _relay: {
- *           doc: "A bunch of relay related functions"
- *       },
- *       relay: {
- *           _test: {},
- *           test: function() {},
- *           _list: {},
- *           list: function() {}
- *       }
- *   });
+ * Legacy method registration (backwards compatibility):
+ * ```typescript
+ * server.insertMethods({
+ *     _getUser: {
+ *         doc: 'Get user by ID',
+ *         args: 'userId: string'
+ *     },
+ *     getUser: async (req, res) => {
+ *         const user = await getUserById(req.args[0]);
+ *         res.send(user);
+ *     }
+ * });
+ * ```
+ *
+ * Accessing metadata for custom validation and introspection:
+ * ```typescript
+ * // Get method metadata and check for custom validation properties
+ * const meta = server.getMethodMeta('user.get');
+ * if (meta?.validateArgs) {
+ *     const isValid = meta.validateArgs(args, context);
+ * }
+ * if (meta?.schema) {
+ *     const result = meta.schema.safeParse(args); // e.g., Zod
+ * }
+ * if (meta?.validator) {
+ *     meta.validator.validate(args); // e.g., Joi
+ * }
+ *
+ * // Generate documentation from all methods
+ * const allMeta = server.getAllMethodMeta();
+ * for (const [name, config] of Object.entries(allMeta)) {
+ *     console.log(`${name}: ${config.doc || 'No documentation'}`);
+ *     if (config.args) console.log(`  Args: ${config.args}`);
+ * }
+ * ```
+ *
+ * Features:
+ * - Type-safe endpoint registration with TypeScript
+ * - Streaming support for large data transfers
+ * - Real-time events and signals
+ * - Request validation and error handling
+ * - Session management and cleanup
+ * - Method discovery and documentation
+ * - Metadata access for external validation and introspection
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Server = void 0;
-const debug = console.log;
 class Server {
     constructor(methods) {
-        this.modules = {};
-        this.methods = {};
+        this.registry = new method_registry_1.MethodRegistry();
         this.requests = {};
         this.clientIdCounter = 0;
         /** internal request id counter */
@@ -58,85 +111,87 @@ class Server {
             delete this.requests[i];
         }
     }
-    insertMethods(o) {
-        const path = '';
-        this.addMethods(path, o);
-    }
-    addMethods(path, o) {
-        //console.log("addMethods", path, o);
-        const prefix = path ? path + '.' : '';
-        for (const i in o) {
-            if (i === '_') {
-                // module meta
-            }
-            else if (i.substring(0, 1) !== '_') {
-                if (o['_' + i]) {
-                    // publish is _funcName exists for funcName
-                    if (typeof o[i] === 'function') {
-                        const ip = o['_' + i].name || i;
-                        o['_' + i].fullname = prefix + ip;
-                        try {
-                            this.modules[prefix + ip] = o['_' + i];
-                            this.methods[prefix + ip] = o[i];
-                        }
-                        catch (e) {
-                            console.log('Kaboom! ', e);
-                        }
-                    }
-                    else if (typeof o[i] === 'object') {
-                        // this is a sub item
-                        //this.modules[prefix + i] = o['_' + i];
-                        this.addMethods(prefix + i, o[i]);
-                    }
-                }
-                else {
-                    // no _funcName found, do not publish via RPC
-                }
-            }
-        }
+    /**
+     * Legacy method for backwards compatibility
+     * Registers methods using the old underscore-prefixed structure
+     */
+    insertMethods(methodMap) {
+        this.registry.registerLegacyMethods(methodMap);
     }
-    listMethods(args, context, cb) {
-        const result = {};
-        function copy(s, filter) {
-            const d = {};
-            for (const j in s) {
-                if (filter[j]) {
-                    continue;
-                }
-                d[j] = s[j];
-            }
-            return d;
+    /**
+     * Lists all available methods and their configurations
+     */
+    listMethods(args, context, callback) {
+        try {
+            const result = this.registry.getMethodListing();
+            callback(null, result);
         }
-        const filter = { fullname: true };
-        //console.log("no acl.");
-        for (const i in this.modules) {
-            result[i] = copy(this.modules[i], filter);
+        catch (error) {
+            callback(error);
         }
-        cb(null, result);
     }
+    /**
+     * Cleanup when a client goes offline
+     */
     clientOffline(clientId) {
-        for (const i in this.requests[clientId]) {
-            if (typeof this.requests[clientId][i].end === 'function') {
-                this.requests[clientId][i].end();
+        if (!this.requests[clientId]) {
+            return; // Client not found
+        }
+        try {
+            for (const requestId in this.requests[clientId]) {
+                this.cleanupRequest(clientId, requestId);
             }
-            //console.log("Ended due to client offline:", this.requests[clientId][i]);
-            delete this.requests[clientId][i];
+            delete this.requests[clientId];
+        }
+        catch (error) {
+            console.error(`Error during client ${clientId} offline cleanup:`, error);
         }
     }
+    /**
+     * Close all active connections and cleanup
+     */
     closeAll() {
-        for (const i in this.requests) {
-            for (const j in this.requests[i]) {
-                if (typeof this.requests[i][j].end === 'function') {
-                    this.requests[i][j].end();
+        try {
+            for (const clientId in this.requests) {
+                for (const requestId in this.requests[clientId]) {
+                    this.cleanupRequest(parseInt(clientId), requestId);
                 }
-                //console.log("Ended due to client offline:", this.requests[i][j]);
-                delete this.requests[i][j];
+                delete this.requests[clientId];
+            }
+        }
+        catch (error) {
+            console.error('Error during closeAll cleanup:', error);
+        }
+    }
+    /**
+     * Safely cleanup a specific request
+     */
+    cleanupRequest(clientId, requestId) {
+        var _a, _b;
+        try {
+            const request = (_a = this.requests[clientId]) === null || _a === void 0 ? void 0 : _a[requestId];
+            if (request && typeof request.end === 'function') {
+                request.end();
             }
+            (_b = this.requests[clientId]) === null || _b === void 0 ? true : delete _b[requestId];
+        }
+        catch (error) {
+            console.error(`Error cleaning up request ${requestId} for client ${clientId}:`, error);
         }
     }
+    /**
+     * Parse and handle incoming RPC messages
+     */
     parse(msg, respond, context, clientId) {
         if (typeof clientId !== 'number') {
-            //console.log("Got RPC request from unspecified client, setting clientId to __none.");
+            console.warn('Got RPC request from unspecified client');
+            return;
+        }
+        if (!msg || typeof msg.op !== 'string') {
+            respond({
+                err: msg === null || msg === void 0 ? void 0 : msg.id,
+                data: { code: 400, msg: 'Invalid message format' }
+            });
             return;
         }
         try {
@@ -154,7 +209,6 @@ class Server {
             }
             if (msg.end) {
                 const id = msg.end;
-                //console.log("end this request:", clientId, id, this.requests[clientId] ? this.requests[clientId][id] : this.requests);
                 if (this.requests[clientId] && this.requests[clientId][id]) {
                     if (typeof this.requests[clientId][id].end === 'function') {
                         this.requests[clientId][id].end();
@@ -164,10 +218,10 @@ class Server {
                     return;
                 }
                 if (!this.requests[clientId][id]) {
-                    return; // console.log("No such request...", id, clientId, new Error().stack, this.requests[clientId], this.requests);
+                    return;
                 }
                 if (typeof this.requests[clientId][id].end === 'function') {
-                    this.requests[id].end();
+                    this.requests[clientId][id].end();
                 }
                 return;
             }
@@ -177,8 +231,7 @@ class Server {
                 });
                 return;
             }
-            if (typeof this.methods[msg.op] === 'undefined') {
-                // service not found
+            if (!this.registry.hasMethod(msg.op)) {
                 respond({ err: msg.id, data: { code: 300, msg: 'No method found: ' + msg.op } });
                 return;
             }
@@ -207,140 +260,156 @@ class Server {
             }
         }
     }
+    /**
+     * Process raw RPC invocation
+     */
     invokeRaw(msg, respond, context, clientId) {
-        var _a, _b;
         ++this.requestId;
         if (!this.requests[clientId]) {
             return console.log('Session not opened for client. Use Server.open() first');
         }
         if (msg.push) {
-            // we got a sig from client... neat, must be streaming!
-            const ctx = this.requests[clientId][msg.push];
-            //console.log('stream context:', ctx);
-            if (msg.data === null) {
-                console.log('msg.data is null:', msg);
-                return;
-            }
-            ctx.data(msg.data);
+            this.handlePushMessage(msg, clientId);
             return;
         }
         if (msg.sig) {
-            // we got a sig from client... neat, must be streaming!
-            const ctx = this.requests[clientId][msg.sig];
-            // call the actual method
-            try {
-                this.methods[ctx.op].call(this.requests[clientId][msg.sig], msg.data, {
-                    send: (data) => {
-                        if (typeof ctx.end === 'function') {
-                            ctx.end();
-                        }
-                        if (this.requests[clientId][msg.sig]) {
-                            delete this.requests[clientId][msg.sig];
-                        }
-                        respond({ ack: msg.sig, data: data });
-                    },
-                    emit: (data) => {
-                        if (!this.requests[clientId][msg.sig]) {
-                            if (typeof ctx.end === 'function') {
-                                ctx.end();
-                            }
-                        }
-                        return respond({ sig: msg.sig, data: data });
-                    },
-                    error: (data) => {
-                        if (typeof ctx.end === 'function') {
-                            ctx.end();
-                        }
-                        delete this.requests[clientId][msg.sig];
-                        respond({ err: msg.sig, data: data });
-                    },
-                    close: (data) => {
-                        if (typeof ctx.end === 'function') {
-                            ctx.end();
-                        }
-                        delete this.requests[clientId][msg.sig];
-                        respond({ fin: msg.sig });
-                    }
-                }, context);
-            }
-            catch (e) {
-                console.log('Calling the method in RPC failed:', msg.op, msg.args, e.stack);
-                delete this.requests[clientId][msg.sig];
-                respond({ err: msg.sig, data: { msg: 'rpc failed during execution of ' + msg.op, code: 578 } });
-            }
+            this.handleSignalMessage(msg, respond, context, clientId);
             return;
         }
         if (typeof msg.id === 'undefined') {
-            // this is an event
-            const reqCtx = {};
-            this.methods[msg.op].call(reqCtx, { args: msg.args }, {
+            this.handleEventMessage(msg, respond, context);
+        }
+        else {
+            this.handleRegularRequest(msg, respond, context, clientId);
+        }
+    }
+    /**
+     * Handle push (streaming data) messages
+     */
+    handlePushMessage(msg, clientId) {
+        if (!msg.push) {
+            return;
+        }
+        const ctx = this.requests[clientId][msg.push];
+        if (!ctx) {
+            return;
+        }
+        if (msg.data === null) {
+            console.log('msg.data is null:', msg);
+            return;
+        }
+        ctx.data(msg.data);
+    }
+    /**
+     * Handle signal (streaming) messages
+     */
+    handleSignalMessage(msg, respond, context, clientId) {
+        if (!msg.sig) {
+            return;
+        }
+        const ctx = this.requests[clientId][msg.sig];
+        if (!ctx) {
+            return;
+        }
+        try {
+            const method = this.registry.getMethod(ctx.op);
+            if (method) {
+                method.call(this.requests[clientId][msg.sig], msg.data, this.createSignalResponseHandlers(msg.sig, respond, ctx, clientId), context);
+            }
+        }
+        catch (e) {
+            console.log('Calling the method in RPC failed:', msg.op, msg.args, e.stack);
+            delete this.requests[clientId][msg.sig];
+            respond({ err: msg.sig, data: { msg: 'rpc failed during execution of ' + msg.op, code: 578 } });
+        }
+    }
+    /**
+     * Create response handlers for signal messages
+     */
+    createSignalResponseHandlers(sigId, respond, ctx, clientId) {
+        return {
+            send: (data) => {
+                if (typeof ctx.end === 'function') {
+                    ctx.end();
+                }
+                if (this.requests[clientId][sigId]) {
+                    delete this.requests[clientId][sigId];
+                }
+                respond({ ack: sigId, data: data });
+            },
+            emit: (data) => {
+                if (!this.requests[clientId][sigId]) {
+                    if (typeof ctx.end === 'function') {
+                        ctx.end();
+                    }
+                }
+                return respond({ sig: sigId, data: data });
+            },
+            error: (data) => {
+                if (typeof ctx.end === 'function') {
+                    ctx.end();
+                }
+                delete this.requests[clientId][sigId];
+                respond({ err: sigId, data: data });
+            },
+            close: (data) => {
+                if (typeof ctx.end === 'function') {
+                    ctx.end();
+                }
+                delete this.requests[clientId][sigId];
+                respond({ fin: sigId });
+            }
+        };
+    }
+    /**
+     * Handle event messages (no response expected)
+     */
+    handleEventMessage(msg, respond, context) {
+        const reqCtx = {};
+        const method = this.registry.getMethod(msg.op);
+        if (method) {
+            method.call(reqCtx, { args: msg.args }, {
                 send: () => { debug('Trying to send response to event (' + msg.op + '). Dropping.'); },
                 emit: () => { debug('Trying to emit response to event (' + msg.op + '). Dropping.'); },
                 error: () => { debug('Trying to respond with error to event (' + msg.op + '). Dropping.'); },
                 close: () => { debug('Trying to close event (' + msg.op + '). Dropping.'); }
             }, context);
         }
-        else {
-            // this is a regular rpc request
-            const reqCtx = {
-                id: msg.id,
-                op: msg.op,
-                args: msg.args,
-                context,
-                end: null,
-                send: respond,
-            };
-            if (!this.requests[clientId]) {
-                this.requests[clientId] = {};
+    }
+    /**
+     * Handle regular RPC requests
+     */
+    handleRegularRequest(msg, respond, context, clientId) {
+        var _a, _b;
+        const reqCtx = {
+            id: msg.id,
+            op: msg.op,
+            args: msg.args,
+            context,
+            end: null,
+            send: respond,
+        };
+        if (!this.requests[clientId]) {
+            this.requests[clientId] = {};
+        }
+        // Check for duplicate request ID
+        if (msg.id && ((_a = this.requests[clientId]) === null || _a === void 0 ? void 0 : _a[msg.id])) {
+            console.log("Serious warning. There is already a request by that id, we'll kill it off! This session is likely not clean. clientId:", clientId, 'msg', msg, 'stack trace:', new Error().stack);
+            if (msg.id && typeof this.requests[clientId][msg.id].end === 'function') {
+                this.requests[clientId][msg.id].end();
             }
-            if ((_a = this.requests[clientId]) === null || _a === void 0 ? void 0 : _a[msg.id]) {
-                console.log("Serious warning. There is already a request by that id, we'll kill it off! This session is likely not clean. clientId:", clientId, 'msg', msg, 'stack trace:', new Error().stack);
-                if (typeof this.requests[clientId][msg.id].end === 'function') {
-                    this.requests[clientId][msg.id].end();
-                }
+            if (msg.id) {
                 delete this.requests[clientId][msg.id];
-                console.log('Removed old request by same id from same client...');
             }
+            console.log('Removed old request by same id from same client...');
+        }
+        if (msg.id) {
             this.requests[clientId][msg.id] = reqCtx;
-            // call the actual method
             try {
-                this.methods[msg.op].call(reqCtx, { args: msg.args }, {
-                    send: (data) => {
-                        var _a;
-                        if (typeof reqCtx.end === 'function') {
-                            reqCtx.end();
-                        }
-                        if ((_a = this.requests[clientId]) === null || _a === void 0 ? void 0 : _a[msg.id]) {
-                            delete this.requests[clientId][msg.id];
-                        }
-                        respond({ ack: msg.id, data: data });
-                    },
-                    emit: (data) => {
-                        var _a;
-                        if (!((_a = this.requests[clientId]) === null || _a === void 0 ? void 0 : _a[msg.id])) {
-                            if (typeof reqCtx.end === 'function') {
-                                reqCtx.end();
-                            }
-                        }
-                        return respond({ sig: msg.id, data: data });
-                    },
-                    error: (data) => {
-                        var _a;
-                        if (typeof reqCtx.end === 'function') {
-                            reqCtx.end();
-                        }
-                        (_a = this.requests[clientId]) === null || _a === void 0 ? true : delete _a[msg.id];
-                        respond({ err: msg.id, data: data });
-                    },
-                    close: (data) => {
-                        var _a;
-                        if (typeof reqCtx.end === 'function') {
-                            reqCtx.end();
-                        }
-                        (_a = this.requests[clientId]) === null || _a === void 0 ? true : delete _a[msg.id];
-                        respond({ fin: msg.id });
-                    }
-                }, context);
+                const method = this.registry.getMethod(msg.op);
+                if (method) {
+                    method.call(reqCtx, { args: msg.args }, this.createRegularResponseHandlers(msg.id, respond, reqCtx, clientId), context);
+                }
             }
             catch (e) {
                 console.log('Calling the method in RPC failed:', msg.op, msg.args, e.stack);
@@ -349,39 +418,48 @@ class Server {
             }
         }
     }
-    /*
-    invoke(op: string, args: any[], stream: any, cb): void {
-        if(typeof stream === 'function') { cb = stream; stream = null; }
-
-        if( !Array.isArray(args) ) {
-            args = [args];
-        }
-
-        if (typeof cb !== 'function') {
-            throw new Error('RPC invoke requires callback function as third argument');
-        }
-
-        const msg: RequestMessage = {
-            op,
-            args,
-            stream,
-            id: ++this.invokeId
-        };
-        const context = {
-            clientType: 'invoke',
-            clientId: 'invokedViaRPCInvoke'
-        };
-
-        const response = (reply) => {
-            const ctx = { cancel: () => { this.parse({ end: msg.id }, () => { }, {}, 0); }, id: msg.id };
-            process.nextTick(() => {
-                cb.call(ctx, reply.err ? true : null, reply.data);
-            });
+    /**
+     * Create response handlers for regular requests
+     */
+    createRegularResponseHandlers(msgId, respond, reqCtx, clientId) {
+        return {
+            send: (data) => {
+                var _a;
+                if (typeof reqCtx.end === 'function') {
+                    reqCtx.end();
+                }
+                if ((_a = this.requests[clientId]) === null || _a === void 0 ? void 0 : _a[msgId]) {
+                    delete this.requests[clientId][msgId];
+                }
+                respond({ ack: msgId, data: data });
+            },
+            emit: (data) => {
+                var _a;
+                if (!((_a = this.requests[clientId]) === null || _a === void 0 ? void 0 : _a[msgId])) {
+                    if (typeof reqCtx.end === 'function') {
+                        reqCtx.end();
+                    }
+                }
+                return respond({ sig: msgId, data: data });
+            },
+            error: (data) => {
+                var _a;
+                if (typeof reqCtx.end === 'function') {
+                    reqCtx.end();
+                }
+                (_a = this.requests[clientId]) === null || _a === void 0 ? true : delete _a[msgId];
+                respond({ err: msgId, data: data });
+            },
+            close: (data) => {
+                var _a;
+                if (typeof reqCtx.end === 'function') {
+                    reqCtx.end();
+                }
+                (_a = this.requests[clientId]) === null || _a === void 0 ? true : delete _a[msgId];
+                respond({ fin: msgId });
+            }
         };
-
-        this.parse(msg, response, context, '__invoke');
     }
-    */
     close(clientId) {
         for (const i in this.requests[clientId]) {
             if (typeof this.requests[clientId][i].end === 'function') {
@@ -403,40 +481,22 @@ class Server {
      * @param handler - The endpoint handler function
      */
     endpoint(name, config, handler) {
-        // Parse the endpoint name into parts
-        const parts = name.split('.');
-        const methodName = parts[parts.length - 1];
-        const namespaceParts = parts.slice(0, -1);
-        // Build the nested object structure
-        const methods = {};
-        let current = methods;
-        // Navigate/create the namespace structure
-        for (let i = 0; i < namespaceParts.length; i++) {
-            const part = namespaceParts[i];
-            if (!current[part]) {
-                current[part] = {};
-            }
-            current = current[part];
-        }
-        // Add the validation object (with _ prefix)
-        const validationKey = `_${methodName}`;
-        current[validationKey] = {};
-        if (config.doc) {
-            current[validationKey].doc = config.doc;
-        }
-        if (config.args) {
-            current[validationKey].args = config.args;
-        }
-        if (config.validate) {
-            current[validationKey].validate = config.validate;
-        }
-        if (config.validateResult) {
-            current[validationKey].validateResult = config.validateResult;
-        }
-        // Add the handler
-        current[methodName] = handler;
-        // Register with the RPC server
-        this.insertMethods(methods);
+        this.registry.registerEndpoint(name, config, handler);
+    }
+    /**
+     * Get metadata for a specific method (including all custom properties)
+     * @param name - Method name
+     * @returns The complete method configuration or undefined if not found
+     */
+    getMethodMeta(name) {
+        return this.registry.getModule(name);
+    }
+    /**
+     * Get metadata for all registered methods
+     * @returns Object containing all method configurations
+     */
+    getAllMethodMeta() {
+        return this.registry.getModules();
     }
 }
 exports.Server = Server;