@juspay/neurolink 13.8.17 → 13.8.18

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

package/dist/server/adapters/honoAdapter.js

@@ -7,6 +7,9 @@ import { logger } from "../../utils/logger.js";
 import { AlreadyRunningError, ServerAdapterError, ServerStopError, wrapError, } from "../errors.js";
 import { BaseServerAdapter } from "../abstract/baseServerAdapter.js";
 import { markContextCarried } from "../utils/carriedContextMark.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 { isRawBodyContentType, isWebResponse, parseByteLimit, RawBodyTooLargeError, readBoundedRequestBody, } from "../utils/rawBody.js";
 /**
@@ -32,9 +35,13 @@ export class HonoServerAdapter extends BaseServerAdapter {
     // Populated by initializeFramework's dynamic imports; used by methods that
     // run after initialization (route registration, streaming) and so cannot
     // rely on initializeFramework's own local closure variables.
-    HTTPExceptionCtor;
     streamSSEFn;
     parseFormBody;
+    // The runtime's view of the TCP peer (Node, Bun or Deno); undefined where the
+    // runtime offers none, and then requests carry no address.
+    getConnInfoFn;
+    // The rate limiter counts nothing it cannot attribute, and says so once.
+    warnedNoClientAddress = false;
     constructor(neurolink, config = {}) {
         super(neurolink, config);
     }
@@ -44,12 +51,8 @@ export class HonoServerAdapter extends BaseServerAdapter {
     createRateLimiter() {
         return async (c, next) => {
             // Skip rate limiting for excluded paths
-            if (this.config.rateLimit.skipPaths) {
-                for (const skipPath of this.config.rateLimit.skipPaths) {
-                    if (c.req.path.startsWith(skipPath)) {
-                        return next();
-                    }
-                }
+            if (pathMatchesAny(c.req.path, this.config.rateLimit.skipPaths)) {
+                return next();
             }
             // Use custom keyGenerator if provided, otherwise default to IP-based key
             let key;
@@ -71,14 +74,29 @@ export class HonoServerAdapter extends BaseServerAdapter {
                     externalServerManager: this.externalServerManager,
                     timestamp: Date.now(),
                     metadata: {},
+                    remoteAddress: this.remoteAddressFor(c),
                 };
                 key = this.config.rateLimit.keyGenerator(minCtx);
             }
             else {
-                key =
-                    c.req.header("x-forwarded-for") ||
-                        c.req.header("x-real-ip") ||
-                        "unknown";
+                // The TCP peer, or behind a declared proxy the client it reports. A
+                // header alone used to be the key, so one shared "unknown" bucket
+                // served every direct client and a rotating X-Forwarded-For escaped
+                // the limit; a request with no attributable address is now let
+                // through rather than pooled with every other such request.
+                key = resolveClientAddress({
+                    remoteAddress: this.remoteAddressFor(c),
+                    forwardedFor: c.req.header("x-forwarded-for"),
+                    trustProxy: this.config.rateLimit.trustProxy,
+                    trustedProxies: this.config.rateLimit.trustedProxies,
+                });
+                if (key === undefined) {
+                    if (!this.warnedNoClientAddress) {
+                        this.warnedNoClientAddress = true;
+                        logger.alwaysStderr("[HonoAdapter] The runtime reports no peer address for requests, so the rate limiter cannot count them; configure rateLimit.keyGenerator to limit by another key.");
+                    }
+                    return next();
+                }
             }
             const now = Date.now();
             const windowMs = this.config.rateLimit.windowMs;
@@ -137,9 +155,9 @@ export class HonoServerAdapter extends BaseServerAdapter {
             this.importFrameworkDependency("hono/timeout", "hono"),
             this.importFrameworkDependency("hono/utils/body", "hono"),
         ]);
-        this.HTTPExceptionCtor = HTTPException;
         this.streamSSEFn = streamSSE;
         this.parseFormBody = parseBody;
+        this.getConnInfoFn = await this.loadConnInfo();
         this.app = new Hono();
         // Add secure headers
         this.app.use("*", secureHeaders());
@@ -235,6 +253,7 @@ export class HonoServerAdapter extends BaseServerAdapter {
             const startTime = Date.now();
             // Track connection for graceful shutdown
             this.trackConnection(connectionId, undefined, requestId);
+            let abort;
             try {
                 // Extract path parameters
                 const params = c.req.param();
@@ -263,6 +282,15 @@ export class HonoServerAdapter extends BaseServerAdapter {
                     }
                     ctx = created;
                 }
+                // The handler learns of a client that went away through the request's
+                // own signal, and of the request timeout through the same controller
+                // (Hono's timeout middleware answers 504; this stops the work).
+                abort = this.attachRequestAbort(ctx, {
+                    onClientClose: (listener) => c.req.raw.signal.addEventListener("abort", listener, {
+                        once: true,
+                    }),
+                    applyTimeout: !route.streaming?.enabled,
+                });
                 // Emit request event
                 this.emit("request", {
                     requestId,
@@ -344,15 +372,23 @@ export class HonoServerAdapter extends BaseServerAdapter {
                 });
             }
             catch (error) {
-                const errorMessage = error instanceof Error ? error.message : String(error);
-                logger.error("[HonoAdapter] Handler error", {
+                // The exception's text stays in the log under this request id; the
+                // client gets a fixed message for its category. It used to get the
+                // text itself, environment variable names and upstream bodies included.
+                const shaped = shapeRouteError("HonoAdapter", requestId, error);
+                this.emit("response", {
                     requestId,
-                    route: route.path,
-                    error: errorMessage,
+                    statusCode: shaped.status,
+                    duration: Date.now() - startTime,
+                    timestamp: new Date(),
                 });
-                throw new this.HTTPExceptionCtor(500, { message: errorMessage });
+                return c.json({
+                    error: { code: shaped.code, message: shaped.message },
+                    metadata: { requestId, timestamp: new Date().toISOString() },
+                }, shaped.status);
             }
             finally {
+                abort?.release();
                 // Untrack connection when request completes
                 this.untrackConnection(connectionId);
                 // Clean up context store to prevent memory leaks
@@ -417,13 +453,14 @@ export class HonoServerAdapter extends BaseServerAdapter {
                 });
             }
             catch (error) {
+                const shaped = shapeRouteError("HonoAdapter", ctx.requestId, error);
                 await stream.writeSSE({
                     data: JSON.stringify({
                         type: "error",
                         error: {
-                            code: "STREAM_ERROR",
-                            message: error instanceof Error ? error.message : "Stream error",
-                            status: 500,
+                            code: shaped.code,
+                            message: shaped.message,
+                            status: shaped.status,
                         },
                         timestamp: Date.now(),
                     }),
@@ -482,7 +519,7 @@ export class HonoServerAdapter extends BaseServerAdapter {
         for (const path of paths) {
             this.app.use(path, async (c, next) => {
                 // Skip excluded paths
-                if (middleware.excludePaths?.some((p) => c.req.path.startsWith(p))) {
+                if (pathMatchesAny(c.req.path, middleware.excludePaths)) {
                     return next();
                 }
                 // Extract path parameters
@@ -566,6 +603,7 @@ export class HonoServerAdapter extends BaseServerAdapter {
             this.startTime = new Date();
             this.lifecycleState = "running";
             logger.info(`[HonoAdapter] Server started on ${host}:${port}`);
+            this.warnIfSensitiveRoutesUnauthenticated();
             this.emit("started", {
                 port,
                 host,
@@ -684,6 +722,45 @@ export class HonoServerAdapter extends BaseServerAdapter {
         });
         return headers;
     }
+    /**
+     * 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.
+     */
+    async loadConnInfo() {
+        try {
+            if (typeof Bun !== "undefined") {
+                const bun = await import("hono/bun");
+                return bun.getConnInfo;
+            }
+            if (typeof Deno !== "undefined") {
+                const deno = await import("hono/deno");
+                return deno.getConnInfo;
+            }
+            const node = await import("@hono/node-server/conninfo");
+            return node.getConnInfo;
+        }
+        catch (error) {
+            logger.debug("[HonoAdapter] No connection-info helper for this runtime", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return undefined;
+        }
+    }
+    /** The TCP peer of this request, when the runtime reports one. */
+    remoteAddressFor(c) {
+        if (!this.getConnInfoFn) {
+            return undefined;
+        }
+        try {
+            const address = this.getConnInfoFn(c).remote.address;
+            return typeof address === "string" && address.length > 0
+                ? address
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
     extractQuery(c) {
         const query = {};
         const url = new URL(c.req.url);
@@ -726,6 +803,7 @@ export class HonoServerAdapter extends BaseServerAdapter {
             query: this.extractQuery(c),
             params,
             body,
+            remoteAddress: this.remoteAddressFor(c),
         });
     }
     async extractBody(c) {

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

@@ -18,6 +18,7 @@ export declare class KoaServerAdapter extends BaseServerAdapter {
     private rateLimitStore;
     private rateLimitCleanupInterval?;
     private sockets;
+    private warnedNoClientAddress;
     private registeredMiddleware;
     constructor(neurolink: NeuroLink, config?: ServerAdapterConfig);
     /**