@juspay/neurolink 13.8.17 → 13.8.19

package/dist/server/adapters/expressAdapter.js

@@ -5,9 +5,14 @@
 import { logger } from "../../utils/logger.js";
 import { AlreadyRunningError, ServerAdapterError, ServerStartError, ServerStopError, wrapError, } from "../errors.js";
 import { BaseServerAdapter } from "../abstract/baseServerAdapter.js";
+import { resolveClientAddress } from "../utils/clientAddress.js";
+import { shapeRouteError } from "../utils/clientError.js";
+import { pathMatchesAny } from "../utils/pathMatch.js";
 import { isErrorResponse } from "../utils/validation.js";
 import { createBoundedBodyParser } from "../utils/expressBody.js";
 import { isRawBodyContentType, isWebResponse, readWebResponse, } from "../utils/rawBody.js";
+/** How long `listen()` may take; `config.timeout` is the per-request budget. */
+const STARTUP_TIMEOUT_MS = 30_000;
 /**
  * Express-specific server adapter
  */
@@ -16,6 +21,8 @@ export class ExpressServerAdapter extends BaseServerAdapter {
     server;
     frameworkInitialized = false;
     sockets = new Set();
+    // The rate limiter counts nothing it cannot attribute, and says so once.
+    warnedNoClientAddress = false;
     constructor(neurolink, config = {}) {
         super(neurolink, config);
     }
@@ -77,6 +84,13 @@ export class ExpressServerAdapter extends BaseServerAdapter {
             const limiter = rateLimit({
                 windowMs,
                 max: this.config.rateLimit.maxRequests,
+                // The key is resolved here, from the TCP peer or, behind a declared
+                // proxy, the client it reports; the library's own reading of the
+                // request (and its warnings about it) is not used. A request with no
+                // attributable address passes rather than share a bucket.
+                validate: false,
+                keyGenerator: (req) => this.clientKeyFor(req) ?? "",
+                skip: (req) => this.clientKeyFor(req) === undefined,
                 message: {
                     error: {
                         code: "RATE_LIMIT_EXCEEDED",
@@ -128,6 +142,20 @@ export class ExpressServerAdapter extends BaseServerAdapter {
         }
         this.frameworkInitialized = true;
     }
+    /** The address a request is counted against; `undefined` when there is none. */
+    clientKeyFor(req) {
+        const key = resolveClientAddress({
+            remoteAddress: req.socket?.remoteAddress,
+            forwardedFor: req.headers["x-forwarded-for"],
+            trustProxy: this.config.rateLimit.trustProxy,
+            trustedProxies: this.config.rateLimit.trustedProxies,
+        });
+        if (key === undefined && !this.warnedNoClientAddress) {
+            this.warnedNoClientAddress = true;
+            logger.alwaysStderr("[ExpressAdapter] A request arrived with no peer address, so the rate limiter cannot count it; configure rateLimit.keyGenerator to limit by another key.");
+        }
+        return key;
+    }
     /**
      * Override initialize to ensure async framework setup
      */
@@ -152,7 +180,7 @@ export class ExpressServerAdapter extends BaseServerAdapter {
      */
     registerFrameworkRoute(route) {
         const method = route.method.toLowerCase();
-        this.app[method](route.path, async (req, res, next) => {
+        this.app[method](route.path, async (req, res, _next) => {
             const requestId = req.headers["x-request-id"];
             const startTime = Date.now();
             // Create server context
@@ -164,12 +192,24 @@ export class ExpressServerAdapter extends BaseServerAdapter {
                 query: req.query,
                 params: req.params,
                 body: req.body,
+                remoteAddress: req.socket?.remoteAddress,
             });
             // Copy response headers from middleware (stored in res.locals by middleware)
             if (res.locals.responseHeaders) {
                 ctx.responseHeaders = { ...res.locals.responseHeaders };
             }
             this.restoreCarriedContext(ctx, res.locals.carriedContext);
+            // The handler learns of a client that went away, and a request over
+            // `config.timeout` is answered 504 and its work aborted. Express used
+            // to apply that timeout only to its own listen().
+            const abort = this.attachRequestAbort(ctx, {
+                onClientClose: (listener) => res.on("close", () => {
+                    if (!res.writableFinished) {
+                        listener();
+                    }
+                }),
+                applyTimeout: !route.streaming?.enabled,
+            });
             // Emit request event
             this.emit("request", {
                 requestId,
@@ -183,7 +223,9 @@ export class ExpressServerAdapter extends BaseServerAdapter {
                     return this.handleStreamingResponse(res, ctx, route);
                 }
                 // Execute handler
-                const result = await route.handler(ctx);
+                const result = abort.deadline
+                    ? await Promise.race([route.handler(ctx), abort.deadline])
+                    : await route.handler(ctx);
                 const duration = Date.now() - startTime;
                 // A route that answers in its own wire format returns a web Response.
                 if (isWebResponse(result)) {
@@ -255,7 +297,31 @@ export class ExpressServerAdapter extends BaseServerAdapter {
                 });
             }
             catch (error) {
-                next(error);
+                // The exception's text stays in the log under this request id; the
+                // client gets a fixed message for its category.
+                const shaped = shapeRouteError("ExpressAdapter", requestId, error);
+                this.emitRequestError({
+                    requestId,
+                    error: error instanceof Error ? error : new Error(String(error)),
+                    timestamp: new Date(),
+                });
+                this.emit("response", {
+                    requestId,
+                    statusCode: shaped.status,
+                    duration: Date.now() - startTime,
+                    timestamp: new Date(),
+                });
+                if (res.headersSent) {
+                    res.end();
+                    return;
+                }
+                res.status(shaped.status).json({
+                    error: { code: shaped.code, message: shaped.message },
+                    metadata: { requestId, timestamp: new Date().toISOString() },
+                });
+            }
+            finally {
+                abort.release();
             }
         });
         // Error handling middleware (should be registered once after all routes)
@@ -335,9 +401,13 @@ export class ExpressServerAdapter extends BaseServerAdapter {
             res.end();
         }
         catch (error) {
+            const shaped = shapeRouteError("ExpressAdapter", ctx.requestId, error);
             res.write(`event: error\n`);
             res.write(`data: ${JSON.stringify({
-                error: error instanceof Error ? error.message : "Stream error",
+                error: shaped.message,
+                code: shaped.code,
+                status: shaped.status,
+                requestId: ctx.requestId,
             })}\n\n`);
             res.end();
         }
@@ -350,7 +420,7 @@ export class ExpressServerAdapter extends BaseServerAdapter {
         for (const path of paths) {
             this.app.use(path, async (req, res, next) => {
                 // Skip excluded paths
-                if (middleware.excludePaths?.some((p) => req.path.startsWith(p))) {
+                if (pathMatchesAny(req.path, middleware.excludePaths)) {
                     return next();
                 }
                 // Initialize response headers storage in res.locals if not present
@@ -367,6 +437,7 @@ export class ExpressServerAdapter extends BaseServerAdapter {
                     query: req.query,
                     params: req.params,
                     body: req.body,
+                    remoteAddress: req.socket?.remoteAddress,
                 });
                 // Copy existing response headers to context
                 ctx.responseHeaders = { ...res.locals.responseHeaders };
@@ -408,13 +479,14 @@ export class ExpressServerAdapter extends BaseServerAdapter {
         }
         this.lifecycleState = "starting";
         const { port, host } = this.config;
-        const startupTimeout = this.config.timeout || 30000;
+        const startupTimeout = STARTUP_TIMEOUT_MS;
         const startPromise = new Promise((resolve, reject) => {
             try {
                 this.server = this.app.listen(port, host, () => {
                     this.isRunning = true;
                     this.startTime = new Date();
                     this.lifecycleState = "running";
+                    this.warnIfSensitiveRoutesUnauthenticated();
                     // Track connections for graceful shutdown
                     this.server?.on("connection", (socket) => {
                         const connectionId = `conn-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;

package/dist/server/adapters/fastifyAdapter.d.ts

@@ -13,6 +13,7 @@ import type { MiddlewareDefinition, RouteDefinition, ServerAdapterConfig } from
 export declare class FastifyServerAdapter extends BaseServerAdapter {
     private app;
     private frameworkInitialized;
+    private warnedNoClientAddress;
     private connectionIds;
     constructor(neurolink: NeuroLink, config?: ServerAdapterConfig);
     /**
@@ -24,6 +25,8 @@ export declare class FastifyServerAdapter extends BaseServerAdapter {
      * Initialize Fastify framework with async imports
      */
     private initializeFrameworkAsync;
+    /** The address a request is counted against; `undefined` when there is none. */
+    private clientKeyFor;
     /**
      * Parse body limit string to number (bytes)
      */

package/dist/server/adapters/fastifyAdapter.js

@@ -7,8 +7,13 @@ import { logger } from "../../utils/logger.js";
 import { AlreadyRunningError, ServerAdapterError, ServerStartError, ServerStopError, wrapError, } from "../errors.js";
 import { withTimeout } from "../../utils/errorHandling.js";
 import { BaseServerAdapter } from "../abstract/baseServerAdapter.js";
+import { resolveClientAddress } from "../utils/clientAddress.js";
+import { shapeRouteError } from "../utils/clientError.js";
+import { pathMatchesAny, stripQuery } from "../utils/pathMatch.js";
 import { isErrorResponse } from "../utils/validation.js";
 import { isRawBodyContentType, isWebResponse, readWebResponse, } from "../utils/rawBody.js";
+/** How long `listen()` may take; `config.timeout` is the per-request budget. */
+const STARTUP_TIMEOUT_MS = 30_000;
 /**
  * Fastify-specific server adapter
  * Provides high-performance HTTP server with schema validation
@@ -16,6 +21,8 @@ import { isRawBodyContentType, isWebResponse, readWebResponse, } from "../utils/
 export class FastifyServerAdapter extends BaseServerAdapter {
     app = null;
     frameworkInitialized = false;
+    // The rate limiter counts nothing it cannot attribute, and says so once.
+    warnedNoClientAddress = false;
     // The shutdown drain's record for each in-flight request. Fastify takes
     // `request.id` from the caller's X-Request-ID, so that id can repeat across
     // overlapping requests: a record named after it would be shared, and the
@@ -87,15 +94,19 @@ export class FastifyServerAdapter extends BaseServerAdapter {
             await this.app.register(rateLimitModule.default, {
                 max: this.config.rateLimit.maxRequests,
                 timeWindow: windowMs,
+                // The key is resolved here, from the TCP peer or, behind a declared
+                // proxy, the client it reports. A request with no attributable
+                // address passes rather than share a bucket.
+                keyGenerator: (request) => this.clientKeyFor(request) ?? "",
+                allowList: (request) => this.clientKeyFor(request) === undefined,
+                // The plugin throws what this builds, so the error handler below
+                // needs `statusCode` to answer 429; without it every exceeded limit
+                // was a 500.
                 errorResponseBuilder: (_request, context) => ({
-                    error: {
-                        code: "RATE_LIMIT_EXCEEDED",
-                        message: this.config.rateLimit.message,
-                    },
-                    metadata: {
-                        retryAfter: Math.ceil(context.ttl / 1000),
-                        timestamp: new Date().toISOString(),
-                    },
+                    statusCode: 429,
+                    code: "RATE_LIMIT_EXCEEDED",
+                    message: this.config.rateLimit.message,
+                    retryAfter: Math.ceil(context.ttl / 1000),
                 }),
             });
             // Add hook to set Retry-After header for 429 responses
@@ -131,7 +142,25 @@ export class FastifyServerAdapter extends BaseServerAdapter {
                 });
                 return;
             }
-            if (error.statusCode) {
+            // An exceeded rate limit, thrown by @fastify/rate-limit as the object
+            // errorResponseBuilder built.
+            if (error.statusCode === 429) {
+                reply.status(429).send({
+                    error: {
+                        code: "RATE_LIMIT_EXCEEDED",
+                        message: this.config.rateLimit.message,
+                    },
+                    metadata: {
+                        requestId,
+                        timestamp: new Date().toISOString(),
+                        retryAfter: error.retryAfter,
+                    },
+                });
+                return;
+            }
+            // Fastify's own client errors (an unparsable body, an unsupported
+            // media type) carry a message the client may see; a 5xx's does not.
+            if (error.statusCode && error.statusCode < 500) {
                 reply.status(error.statusCode).send({
                     error: {
                         code: `HTTP_${error.statusCode}`,
@@ -170,6 +199,21 @@ export class FastifyServerAdapter extends BaseServerAdapter {
         });
         this.frameworkInitialized = true;
     }
+    /** The address a request is counted against; `undefined` when there is none. */
+    clientKeyFor(request) {
+        const forwarded = request.headers["x-forwarded-for"];
+        const key = resolveClientAddress({
+            remoteAddress: request.socket?.remoteAddress ?? request.ip,
+            forwardedFor: Array.isArray(forwarded) ? forwarded.join(",") : forwarded,
+            trustProxy: this.config.rateLimit.trustProxy,
+            trustedProxies: this.config.rateLimit.trustedProxies,
+        });
+        if (key === undefined && !this.warnedNoClientAddress) {
+            this.warnedNoClientAddress = true;
+            logger.alwaysStderr("[FastifyAdapter] A request arrived with no peer address, so the rate limiter cannot count it; configure rateLimit.keyGenerator to limit by another key.");
+        }
+        return key;
+    }
     /**
      * Parse body limit string to number (bytes)
      */
@@ -233,11 +277,12 @@ export class FastifyServerAdapter extends BaseServerAdapter {
                 const ctx = this.createContext({
                     requestId,
                     method: request.method,
-                    path: request.url.split("?")[0], // Remove query string
+                    path: stripQuery(request.url),
                     headers: request.headers,
                     query: request.query,
                     params: request.params,
                     body: request.body,
+                    remoteAddress: request.socket?.remoteAddress ?? request.ip,
                 });
                 // Copy response headers from middleware (stored in request by middleware)
                 const reqWithHeaders = request;
@@ -245,6 +290,17 @@ export class FastifyServerAdapter extends BaseServerAdapter {
                     ctx.responseHeaders = { ...reqWithHeaders.responseHeaders };
                 }
                 this.restoreCarriedContext(ctx, reqWithHeaders.carriedContext);
+                // The handler learns of a client that went away, and a request over
+                // `config.timeout` is answered 504 and its work aborted. Fastify used
+                // to apply that timeout only to its own listen().
+                const abort = this.attachRequestAbort(ctx, {
+                    onClientClose: (listener) => request.raw.on("close", () => {
+                        if (!reply.raw.writableFinished) {
+                            listener();
+                        }
+                    }),
+                    applyTimeout: !route.streaming?.enabled,
+                });
                 // Emit request event
                 this.emit("request", {
                     requestId,
@@ -252,38 +308,66 @@ export class FastifyServerAdapter extends BaseServerAdapter {
                     path: ctx.path,
                     timestamp: new Date(),
                 });
-                // Handle streaming if configured
-                if (route.streaming?.enabled) {
-                    return this.handleStreamingResponse(reply, ctx, route);
-                }
-                // Execute handler
-                const result = await route.handler(ctx);
-                const duration = Date.now() - startTime;
-                // A route that answers in its own wire format returns a web Response.
-                if (isWebResponse(result)) {
-                    const raw = await readWebResponse(result);
-                    this.emit("response", {
-                        requestId,
-                        statusCode: raw.status,
-                        duration,
-                        timestamp: new Date(),
-                    });
-                    for (const [key, value] of Object.entries({
-                        ...ctx.responseHeaders,
-                        ...raw.headers,
-                    })) {
-                        reply.header(key, value);
+                try {
+                    // Handle streaming if configured
+                    if (route.streaming?.enabled) {
+                        return await this.handleStreamingResponse(reply, ctx, route);
                     }
-                    reply.status(raw.status);
-                    return reply.send(raw.body);
-                }
-                // Check if result is an error response
-                if (isErrorResponse(result)) {
-                    const statusCode = result.httpStatus ?? 500;
-                    // Emit response event with error status
+                    // Execute handler
+                    const result = abort.deadline
+                        ? await Promise.race([route.handler(ctx), abort.deadline])
+                        : await route.handler(ctx);
+                    const duration = Date.now() - startTime;
+                    // A route that answers in its own wire format returns a web Response.
+                    if (isWebResponse(result)) {
+                        const raw = await readWebResponse(result);
+                        this.emit("response", {
+                            requestId,
+                            statusCode: raw.status,
+                            duration,
+                            timestamp: new Date(),
+                        });
+                        for (const [key, value] of Object.entries({
+                            ...ctx.responseHeaders,
+                            ...raw.headers,
+                        })) {
+                            reply.header(key, value);
+                        }
+                        reply.status(raw.status);
+                        return reply.send(raw.body);
+                    }
+                    // Check if result is an error response
+                    if (isErrorResponse(result)) {
+                        const statusCode = result.httpStatus ?? 500;
+                        // Emit response event with error status
+                        this.emit("response", {
+                            requestId,
+                            statusCode,
+                            duration,
+                            timestamp: new Date(),
+                        });
+                        // Apply response headers from middleware and handler
+                        if (ctx.responseHeaders) {
+                            for (const [key, value] of Object.entries(ctx.responseHeaders)) {
+                                reply.header(key, value);
+                            }
+                        }
+                        // Return error response with proper status code
+                        reply.status(statusCode);
+                        return {
+                            error: result.error,
+                            metadata: {
+                                ...result.metadata,
+                                requestId,
+                                timestamp: new Date().toISOString(),
+                                duration,
+                            },
+                        };
+                    }
+                    // Emit response event
                     this.emit("response", {
                         requestId,
-                        statusCode,
+                        statusCode: 200,
                         duration,
                         timestamp: new Date(),
                     });
@@ -293,40 +377,43 @@ export class FastifyServerAdapter extends BaseServerAdapter {
                             reply.header(key, value);
                         }
                     }
-                    // Return error response with proper status code
-                    reply.status(statusCode);
+                    // Return formatted response
                     return {
-                        error: result.error,
+                        data: result,
                         metadata: {
-                            ...result.metadata,
                             requestId,
                             timestamp: new Date().toISOString(),
                             duration,
                         },
                     };
                 }
-                // Emit response event
-                this.emit("response", {
-                    requestId,
-                    statusCode: 200,
-                    duration,
-                    timestamp: new Date(),
-                });
-                // Apply response headers from middleware and handler
-                if (ctx.responseHeaders) {
-                    for (const [key, value] of Object.entries(ctx.responseHeaders)) {
-                        reply.header(key, value);
+                catch (error) {
+                    // The exception's text stays in the log under this request id; the
+                    // client gets a fixed message for its category.
+                    const shaped = shapeRouteError("FastifyAdapter", requestId, error);
+                    this.emitRequestError({
+                        requestId,
+                        error: error instanceof Error ? error : new Error(String(error)),
+                        timestamp: new Date(),
+                    });
+                    this.emit("response", {
+                        requestId,
+                        statusCode: shaped.status,
+                        duration: Date.now() - startTime,
+                        timestamp: new Date(),
+                    });
+                    if (reply.sent || reply.raw.headersSent) {
+                        return;
                     }
+                    reply.status(shaped.status);
+                    return {
+                        error: { code: shaped.code, message: shaped.message },
+                        metadata: { requestId, timestamp: new Date().toISOString() },
+                    };
+                }
+                finally {
+                    abort.release();
                 }
-                // Return formatted response
-                return {
-                    data: result,
-                    metadata: {
-                        requestId,
-                        timestamp: new Date().toISOString(),
-                        duration,
-                    },
-                };
             },
         });
     }
@@ -363,9 +450,13 @@ export class FastifyServerAdapter extends BaseServerAdapter {
             reply.raw.end();
         }
         catch (error) {
+            const shaped = shapeRouteError("FastifyAdapter", ctx.requestId, error);
             reply.raw.write(`event: error\n`);
             reply.raw.write(`data: ${JSON.stringify({
-                error: error instanceof Error ? error.message : "Stream error",
+                error: shaped.message,
+                code: shaped.code,
+                status: shaped.status,
+                requestId: ctx.requestId,
             })}\n\n`);
             reply.raw.end();
         }
@@ -378,14 +469,16 @@ export class FastifyServerAdapter extends BaseServerAdapter {
             throw new Error("Fastify app not initialized. Call initialize() before registering middleware.");
         }
         this.app.addHook("preHandler", async (request, _reply) => {
+            // Matched on the path alone, at segment boundaries: `request.url`
+            // carries the query string, so `/api/health?x` used to miss an
+            // exemption for `/api/health` and `/api/healthz` used to take it.
+            const requestPath = stripQuery(request.url);
             // Skip excluded paths
-            if (middleware.excludePaths?.some((p) => request.url.startsWith(p))) {
+            if (pathMatchesAny(requestPath, middleware.excludePaths)) {
                 return;
             }
             // Check if path matches
-            const paths = middleware.paths || ["/"];
-            const matches = paths.some((p) => request.url.startsWith(p) || p === "*");
-            if (!matches) {
+            if (!pathMatchesAny(requestPath, middleware.paths || ["/"])) {
                 return;
             }
             // Initialize response headers storage if not present
@@ -397,11 +490,12 @@ export class FastifyServerAdapter extends BaseServerAdapter {
             const ctx = this.createContext({
                 requestId: request.id,
                 method: request.method,
-                path: request.url.split("?")[0],
+                path: requestPath,
                 headers: request.headers,
                 query: request.query,
                 params: request.params,
                 body: request.body,
+                remoteAddress: request.socket?.remoteAddress ?? request.ip,
             });
             // Copy existing response headers to context
             ctx.responseHeaders = { ...reqWithHeaders.responseHeaders };
@@ -438,7 +532,7 @@ export class FastifyServerAdapter extends BaseServerAdapter {
         const app = this.app;
         this.lifecycleState = "starting";
         const { port, host } = this.config;
-        const startupTimeout = this.config.timeout || 30000;
+        const startupTimeout = STARTUP_TIMEOUT_MS;
         // Track connections via Fastify hooks (must be registered before listen)
         app.addHook("onRequest", async (request) => {
             const connectionId = `conn-${this.generateRequestId()}`;
@@ -457,6 +551,7 @@ export class FastifyServerAdapter extends BaseServerAdapter {
             this.startTime = new Date();
             this.lifecycleState = "running";
             logger.info(`[FastifyAdapter] Server started on ${host}:${port}`);
+            this.warnIfSensitiveRoutesUnauthenticated();
             this.emit("started", {
                 port,
                 host,

package/dist/server/adapters/honoAdapter.d.ts

@@ -17,9 +17,10 @@ export declare class HonoServerAdapter extends BaseServerAdapter {
     private rateLimitCleanupInterval?;
     private requestContextStore;
     private requestIds;
-    private HTTPExceptionCtor;
     private streamSSEFn;
     private parseFormBody;
+    private getConnInfoFn?;
+    private warnedNoClientAddress;
     constructor(neurolink: NeuroLink, config?: ServerAdapterConfig);
     /**
      * Create rate limiter middleware for Hono
@@ -84,6 +85,13 @@ export declare class HonoServerAdapter extends BaseServerAdapter {
     getFrameworkInstance(): unknown;
     getNativeServer(): unknown;
     private extractHeaders;
+    /**
+     * The runtime's connection-info helper: `@hono/node-server`'s on Node, the
+     * Bun or Deno adapter's there. Absent on a runtime that offers none.
+     */
+    private loadConnInfo;
+    /** The TCP peer of this request, when the runtime reports one. */
+    private remoteAddressFor;
     private extractQuery;
     /**
      * A request's context, or the 413 that answers a JSON or form body over its