rpc-express-toolkit 4.2.0 → 4.3.2

package/src/index.js

@@ -2,8 +2,19 @@ const path = require('path');
 const express = require('express');
 const expressPkg = require('express/package.json');
 const NestedError = require('nested-error-stacks');
+const {
+  RpcClient,
+  RpcError,
+  RpcHttpError,
+  RpcSafeClient,
+} = require('rpc-toolkit-js-client');
 const pkg = require('../package.json');
 
+const rpcClientAssetsPath = path.dirname(
+  require.resolve('rpc-toolkit-js-client')
+);
+const DEFAULT_MAX_SERIALIZATION_DEPTH = 100;
+
 /** @typedef {import("express").Router} Router */
 /** @typedef {import("express").Request} Request */
 /** @typedef {import("express").Response} Response */
@@ -16,6 +27,7 @@ const {
   SchemaBuilder,
 } = require('./validation');
 const BatchHandler = require('./batch');
+const { hasOwn, validateEnvelope } = require('./protocol');
 
 /**
  * Default properties to include in error serialization.
@@ -93,7 +105,7 @@ class RpcEndpoint {
    *    The path from which client scripts will be served.
    */
   static serveScripts(router, url = '/vendor/rpc-client') {
-    router.use(url, express.static(path.join(__dirname, 'clients')));
+    router.use(url, express.static(rpcClientAssetsPath));
   }
 
   /** @type {string} */
@@ -102,6 +114,12 @@ class RpcEndpoint {
   /** @type {{ [name: string]: any }} */
   #methods = {};
 
+  /** @type {string} */
+  #introspectionPrefix = '__rpc';
+
+  /** @type {boolean} */
+  #isInternalRegistration = false;
+
   /** @type {Logger} */
   #logger;
 
@@ -143,10 +161,21 @@ class RpcEndpoint {
     this.#options.safeEnabled = this.#options.safeEnabled === true; // Default false
     this.#options.warnOnUnsafe = this.#options.warnOnUnsafe !== false; // Default true
     this.#options.strictMode = this.#options.strictMode !== false; // Default true
+    this.#options.enableIntrospection =
+      this.#options.enableIntrospection === true; // Default false
+    this.#options.introspectionPrefix =
+      this.#options.introspectionPrefix || '__rpc'; // Default __rpc
+
+    this.#introspectionPrefix = this.#options.introspectionPrefix;
 
     // Validate that the router can handle JSON parsing
     this.#validateJsonMiddleware();
 
+    // Register introspection methods if enabled
+    if (this.#options.enableIntrospection) {
+      this.#registerIntrospectionMethods();
+    }
+
     // Setup built-in middleware if configured
     this.#setupBuiltInMiddleware();
 
@@ -184,6 +213,145 @@ class RpcEndpoint {
     }
   }
 
+  /**
+   * Register introspection methods (__rpc.*)
+   * @private
+   */
+  #registerIntrospectionMethods() {
+    this.#isInternalRegistration = true;
+
+    // __rpc.listMethods - List all user methods (excludes __rpc.* methods)
+    this.addMethod(
+      `${this.#introspectionPrefix}.listMethods`,
+      async (_req, _context, _params) =>
+        Object.keys(this.#methods).filter(
+          (name) => !name.startsWith(this.#introspectionPrefix)
+        ),
+      {
+        description: 'List all available RPC methods',
+        exposeSchema: true,
+      }
+    );
+
+    // __rpc.describe - Get schema and description of a specific method
+    this.addMethod(
+      `${this.#introspectionPrefix}.describe`,
+      async (_req, _context, params) => {
+        const methodName = params?.method;
+
+        if (!methodName || typeof methodName !== 'string') {
+          throw {
+            code: -32602,
+            message: 'Invalid params: method name required',
+          };
+        }
+
+        // Prevent introspection of __rpc.* methods
+        if (methodName.startsWith(this.#introspectionPrefix)) {
+          throw {
+            code: -32601,
+            message: 'Cannot describe introspection methods',
+          };
+        }
+
+        const methodConfig = this.#methods[methodName];
+        if (!methodConfig) {
+          throw { code: -32601, message: `Method not found: ${methodName}` };
+        }
+
+        // Check if schema is exposed
+        const config = typeof methodConfig === 'function' ? {} : methodConfig;
+        if (!config.exposeSchema) {
+          throw { code: -32601, message: 'Method schema not available' };
+        }
+
+        return {
+          name: methodName,
+          schema: config.schema || null,
+          description: config.description || '',
+        };
+      },
+      {
+        schema: {
+          type: 'object',
+          properties: {
+            method: { type: 'string' },
+          },
+          required: ['method'],
+        },
+        description: 'Get schema and description of a specific method',
+        exposeSchema: true,
+      }
+    );
+
+    // __rpc.describeAll - Get all methods with public schemas
+    this.addMethod(
+      `${this.#introspectionPrefix}.describeAll`,
+      async (_req, _context, _params) => {
+        const publicMethods = [];
+
+        for (const [name, methodConfig] of Object.entries(this.#methods)) {
+          // Skip introspection methods
+          if (name.startsWith(this.#introspectionPrefix)) continue;
+
+          const config = typeof methodConfig === 'function' ? {} : methodConfig;
+          if (config.exposeSchema) {
+            publicMethods.push({
+              name,
+              schema: config.schema || null,
+              description: config.description || '',
+            });
+          }
+        }
+
+        return publicMethods;
+      },
+      {
+        description: 'List all methods with public schemas',
+        exposeSchema: true,
+      }
+    );
+
+    // __rpc.version - Get toolkit version
+    this.addMethod(
+      `${this.#introspectionPrefix}.version`,
+      async (_req, _context, _params) => ({
+        toolkit: 'rpc-express-toolkit',
+        version: pkg.version,
+        expressVersion: expressPkg.version,
+        nodeVersion: process.version,
+      }),
+      {
+        description: 'Get RPC toolkit version information',
+        exposeSchema: true,
+      }
+    );
+
+    // __rpc.capabilities - Get server capabilities
+    this.addMethod(
+      `${this.#introspectionPrefix}.capabilities`,
+      async (_req, _context, _params) => ({
+        safeMode: this.#options.safeEnabled,
+        batch: true,
+        introspection: true,
+        introspectionPrefix: this.#introspectionPrefix,
+        validation: !!this.#options.validation,
+        cors: !!this.#options.cors,
+        auth: !!this.#options.auth,
+        rateLimit: !!this.#options.rateLimit,
+        methodCount: Object.keys(this.#methods).filter(
+          (n) => !n.startsWith(this.#introspectionPrefix)
+        ).length,
+      }),
+      {
+        description: 'Get server capabilities and configuration',
+        exposeSchema: true,
+      }
+    );
+
+    this.#isInternalRegistration = false;
+  }
+
   /**
    * Validate JSON middleware functionality and Express compatibility
    * @private
@@ -281,7 +449,13 @@ class RpcEndpoint {
           );
 
           // Only send response if there are results (non-notification requests)
-          if (results.length > 0) {
+          if (!Array.isArray(results)) {
+            res.setHeader(
+              'X-RPC-Safe-Enabled',
+              this.#options.safeEnabled ? 'true' : 'false'
+            );
+            res.json(results);
+          } else if (results.length > 0) {
             // Align batch responses with single-call header negotiation
             res.setHeader(
               'X-RPC-Safe-Enabled',
@@ -294,7 +468,7 @@ class RpcEndpoint {
 
           this.#logger.info('Batch request completed', {
             batchSize: req.body.length,
-            responseCount: results.length,
+            responseCount: Array.isArray(results) ? results.length : 1,
             duration: Date.now() - startTime,
           });
 
@@ -330,34 +504,26 @@ class RpcEndpoint {
    * @param {number} startTime
    */
   async #processSingleRequest(req, res, context, startTime) {
-    const { jsonrpc, method, params, id } = req.body || {};
+    const { method, params, id } = req.body || {};
+    const envelope = validateEnvelope(req.body);
 
     // Log the incoming request
     this.#logger.rpcCall(method, params, id, req);
 
-    // Validate JSON-RPC 2.0 request
-    if (jsonrpc !== '2.0') {
+    if (!envelope.valid) {
       return this.reply(res, {
-        id,
-        error: {
-          code: -32600,
-          message: `Invalid Request: 'jsonrpc' must be '2.0'.`,
-        },
-      });
-    }
-
-    if (typeof method !== 'string') {
-      return this.reply(res, {
-        id,
-        error: {
-          code: -32600,
-          message: `Invalid Request: 'method' must be a string.`,
-        },
+        id: envelope.responseId,
+        error: envelope.error,
       });
     }
 
     const methodConfig = this.#methods[method];
     if (!methodConfig) {
+      if (envelope.isNotification) {
+        res.status(204).end();
+        return null;
+      }
+
       return this.reply(res, {
         id,
         error: { code: -32601, message: `Method "${method}" not found` },
@@ -379,6 +545,11 @@ class RpcEndpoint {
         this.#options.safeEnabled &&
         !clientSafeHeader
       ) {
+        if (envelope.isNotification) {
+          res.status(204).end();
+          return null;
+        }
+
         return this.reply(res, {
           id,
           error: {
@@ -403,7 +574,7 @@ class RpcEndpoint {
       };
 
       // Deserialize parameters using client's safe options
-      const deserializedParams = params
+      const deserializedParams = hasOwn(req.body, 'params')
         ? this.deserializeBigIntsAndDates(params, deserializationOptions)
         : params;
 
@@ -470,6 +641,11 @@ class RpcEndpoint {
 
       // Convert any BigInt/Date values before JSON-stringifying
       const safeResult = this.serializeBigIntsAndDates(result);
+      if (envelope.isNotification) {
+        res.status(204).end();
+        return null;
+      }
+
       this.reply(res, { id, result: safeResult });
     } catch (err) {
       const duration = Date.now() - startTime;
@@ -494,6 +670,11 @@ class RpcEndpoint {
         });
       }
 
+      if (envelope.isNotification) {
+        res.status(204).end();
+        return null;
+      }
+
       this.reply(res, {
         id,
         error: {
@@ -511,23 +692,60 @@ class RpcEndpoint {
   /**
    * Register a new JSON-RPC method.
    * @param {string} name The method name.
-   * @param {Function|Object} handlerOrConfig The function to handle calls or config object.
-   * @param {Object} [schema] Optional schema for parameter validation.
+   * @param {Function|Object} handlerOrConfig The function to handle calls or config object with handler, schema, exposeSchema, description.
+   * @param {Object} [optionsOrSchema] Optional config object or schema for backward compatibility.
    */
-  addMethod(name, handlerOrConfig, schema = null) {
+  addMethod(name, handlerOrConfig, optionsOrSchema = null) {
+    // Prevent users from registering introspection methods
+    if (
+      name.startsWith(this.#introspectionPrefix) &&
+      !this.#isInternalRegistration
+    ) {
+      throw new Error(
+        `Method names starting with '${this.#introspectionPrefix}.' are reserved for RPC introspection`
+      );
+    }
+
+    let methodConfig;
+
     if (typeof handlerOrConfig === 'function') {
-      this.#methods[name] = schema
-        ? { handler: handlerOrConfig, schema }
-        : handlerOrConfig;
+      // Function handler - optionsOrSchema can be schema (backward compat) or options object
+      if (
+        optionsOrSchema &&
+        (optionsOrSchema.schema ||
+          optionsOrSchema.exposeSchema ||
+          optionsOrSchema.description)
+      ) {
+        // New format: options object
+        methodConfig = {
+          handler: handlerOrConfig,
+          ...optionsOrSchema,
+        };
+      } else if (optionsOrSchema) {
+        // Old format: schema directly
+        methodConfig = {
+          handler: handlerOrConfig,
+          schema: optionsOrSchema,
+        };
+      } else {
+        // Just the handler
+        methodConfig = handlerOrConfig;
+      }
     } else if (typeof handlerOrConfig === 'object' && handlerOrConfig.handler) {
-      this.#methods[name] = handlerOrConfig;
+      // Config object
+      methodConfig = handlerOrConfig;
     } else {
       throw new Error('Invalid handler configuration');
     }
 
+    this.#methods[name] = methodConfig;
+
+    const config = typeof methodConfig === 'function' ? {} : methodConfig;
     this.#logger.debug('Method registered', {
       method: name,
-      hasSchema: !!schema,
+      hasSchema: !!config.schema,
+      exposeSchema: !!config.exposeSchema,
+      hasDescription: !!config.description,
     });
   }
 
@@ -603,6 +821,14 @@ class RpcEndpoint {
     return this.#validator;
   }
 
+  /**
+   * Get endpoint options
+   * @returns {Object}
+   */
+  get options() {
+    return { ...this.#options };
+  }
+
   /**
    * Get metrics data
    * @returns {Object}
@@ -658,14 +884,28 @@ class RpcEndpoint {
    * @returns {any} A version of `value` safe for JSON serialization.
    */
   serializeBigIntsAndDates(value) {
-    return this.#serializeValue(value, false);
+    return this.#serializeValue(value, false, false, {
+      depth: 0,
+      seen: new WeakSet(),
+    });
   }
 
   /**
    * Internal serialization method with BigInt and Date warning tracking
    * @private
    */
-  #serializeValue(value, hasBigInt = false, hasDate = false) {
+  #serializeValue(
+    value,
+    hasBigInt = false,
+    hasDate = false,
+    state = { depth: 0, seen: new WeakSet() }
+  ) {
+    const maxDepth =
+      this.#options.maxSerializationDepth || DEFAULT_MAX_SERIALIZATION_DEPTH;
+    if (state.depth > maxDepth) {
+      throw new Error('Serialization depth limit exceeded');
+    }
+
     if (typeof value === 'bigint') {
       // Warn if safeEnabled is disabled and we have BigInt
       if (
@@ -703,16 +943,47 @@ class RpcEndpoint {
       return value;
     }
     if (Array.isArray(value)) {
+      if (state.seen.has(value)) {
+        throw new Error('Circular reference detected during serialization');
+      }
+
+      state.seen.add(value);
       // Recurse into arrays - don't pass hasBigInt/hasDate to children
       // Each element should be checked independently for warnings
-      return value.map((v) => this.#serializeValue(v, false, false));
+      try {
+        return value.map((v) =>
+          this.#serializeValue(v, false, false, {
+            depth: state.depth + 1,
+            seen: state.seen,
+          })
+        );
+      } finally {
+        state.seen.delete(value);
+      }
     }
     if (value && typeof value === 'object') {
+      if (state.seen.has(value)) {
+        throw new Error('Circular reference detected during serialization');
+      }
+
+      state.seen.add(value);
       // Recurse into plain objects - don't pass hasBigInt/hasDate to children
       // Each property should be checked independently for warnings
       const result = {};
-      for (const [key, val] of Object.entries(value)) {
-        result[key] = this.#serializeValue(val, false, false);
+      try {
+        Object.entries(value).forEach(([key, val]) => {
+          Object.defineProperty(result, key, {
+            value: this.#serializeValue(val, false, false, {
+              depth: state.depth + 1,
+              seen: state.seen,
+            }),
+            enumerable: true,
+            configurable: true,
+            writable: true,
+          });
+        });
+      } finally {
+        state.seen.delete(value);
       }
       return result;
     }
@@ -761,7 +1032,17 @@ class RpcEndpoint {
    * @param {boolean} [options.safeEnabled] Whether to expect safe prefixes for strings and dates.
    * @returns {any} The re-hydrated value.
    */
-  deserializeBigIntsAndDates(value, options = null) {
+  deserializeBigIntsAndDates(value, options = null, state = null) {
+    const traversalState = state || {
+      depth: 0,
+      seen: new WeakSet(),
+    };
+    const maxDepth =
+      this.#options.maxDeserializationDepth || DEFAULT_MAX_SERIALIZATION_DEPTH;
+    if (traversalState.depth > maxDepth) {
+      throw new Error('Deserialization depth limit exceeded');
+    }
+
     // Use provided options or fall back to server options
     const safeEnabled = options
       ? options.safeEnabled
@@ -808,17 +1089,47 @@ class RpcEndpoint {
 
     // 2. If it's an array, handle each element
     if (Array.isArray(value)) {
-      return value.map((v) => this.deserializeBigIntsAndDates(v, options));
+      if (traversalState.seen.has(value)) {
+        throw new Error('Circular reference detected during deserialization');
+      }
+
+      traversalState.seen.add(value);
+      try {
+        return value.map((v) =>
+          this.deserializeBigIntsAndDates(v, options, {
+            depth: traversalState.depth + 1,
+            seen: traversalState.seen,
+          })
+        );
+      } finally {
+        traversalState.seen.delete(value);
+      }
     }
 
     // 3. If it's a plain object, recurse into each property
     if (value && typeof value === 'object') {
-      return Object.fromEntries(
-        Object.entries(value).map(([key, val]) => [
-          key,
-          this.deserializeBigIntsAndDates(val, options),
-        ])
-      );
+      if (traversalState.seen.has(value)) {
+        throw new Error('Circular reference detected during deserialization');
+      }
+
+      traversalState.seen.add(value);
+      const result = {};
+      try {
+        Object.entries(value).forEach(([key, val]) => {
+          Object.defineProperty(result, key, {
+            value: this.deserializeBigIntsAndDates(val, options, {
+              depth: traversalState.depth + 1,
+              seen: traversalState.seen,
+            }),
+            enumerable: true,
+            configurable: true,
+            writable: true,
+          });
+        });
+      } finally {
+        traversalState.seen.delete(value);
+      }
+      return result;
     }
 
     // 4. For everything else (number, boolean, null, undefined, etc.), return as-is
@@ -826,13 +1137,13 @@ class RpcEndpoint {
   }
 }
 
-// Import the client class
-const RpcClient = require('./clients/rpc-client');
-
 // Export both server and client, plus utilities
 module.exports = RpcEndpoint;
 module.exports.RpcEndpoint = RpcEndpoint;
 module.exports.RpcClient = RpcClient;
+module.exports.RpcError = RpcError;
+module.exports.RpcHttpError = RpcHttpError;
+module.exports.RpcSafeClient = RpcSafeClient;
 module.exports.Logger = Logger;
 module.exports.MiddlewareManager = MiddlewareManager;
 module.exports.builtInMiddlewares = builtInMiddlewares;

package/src/logger.js

@@ -54,9 +54,14 @@ class Logger {
    */
   safeStringify(obj) {
     try {
+      const seen = new WeakSet();
       return JSON.stringify(obj, (key, value) => {
         if (typeof value === 'bigint') return `${value.toString()}n`;
         if (value instanceof Date) return value.toISOString();
+        if (value && typeof value === 'object') {
+          if (seen.has(value)) return '[Circular]';
+          seen.add(value);
+        }
         return value;
       });
     } catch (e) {
@@ -156,7 +161,8 @@ class Logger {
       duration: `${duration}ms`,
       error: error.message,
       code: error.code,
-      stack: error.stack,
+      stack:
+        this.levels[this.level] >= this.levels.debug ? error.stack : undefined,
     });
   }
 
@@ -175,14 +181,19 @@ class Logger {
       'secret',
       'auth',
       'authorization',
+      'credential',
+      'cookie',
+      'session',
     ];
-    const sanitized = Array.isArray(params) ? [...params] : { ...params };
+    const seen = new WeakSet();
 
     const sanitizeObj = (input) => {
       if (typeof input !== 'object' || input === null) return input;
+      if (seen.has(input)) return '[Circular]';
 
+      seen.add(input);
       const output = Array.isArray(input) ? [] : {};
-      for (const [key, value] of Object.entries(input)) {
+      Object.entries(input).forEach(([key, value]) => {
         const isSensitive = sensitiveKeys.some((sensitive) =>
           key.toLowerCase().includes(sensitive)
         );
@@ -193,11 +204,12 @@ class Logger {
         } else {
           output[key] = value;
         }
-      }
+      });
+      seen.delete(input);
       return output;
     };
 
-    return sanitizeObj(sanitized);
+    return sanitizeObj(params);
   }
 }