@service-bridge/node 0.1.3

package/dist/trace.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Result of extracting trace context from incoming HTTP headers.
+ * traceId    — the trace this request belongs to (carry-over or newly generated).
+ * parentSpanId — the caller's span ID to use as parent, empty string if unknown.
+ */
+export interface IncomingTraceContext {
+    traceId: string;
+    parentSpanId: string;
+}
+/**
+ * Extract distributed trace context from incoming HTTP request headers.
+ *
+ * Priority:
+ *  1. W3C `traceparent` — full parent info (traceId + parentSpanId)
+ *  2. `x-trace-id`      — traceId only, no parent span known
+ *  3. Nothing           — generate a fresh traceId, no parent
+ */
+export declare function extractTraceFromHeaders(headers: Record<string, string | string[] | undefined>): IncomingTraceContext;
+//# sourceMappingURL=trace.d.ts.map

package/http/dist/express.d.ts

@@ -0,0 +1,51 @@
+import type { ServiceBridgeService } from "@service-bridge/node";
+import type { Application, NextFunction, Request, Response } from "express";
+import type { IncomingTraceContext } from "./trace";
+import { extractTraceFromHeaders } from "./trace";
+export { extractTraceFromHeaders };
+export type { IncomingTraceContext };
+declare global {
+    namespace Express {
+        interface Request {
+            servicebridge: ServiceBridgeService;
+            traceId?: string;
+            spanId?: string;
+        }
+    }
+}
+export interface ServiceBridgeExpressOptions {
+    /** ServiceBridge client (from servicebridge()). Required. */
+    client: ServiceBridgeService;
+    /** Paths to skip tracing. Default: [] */
+    excludePaths?: string[];
+    /** Set x-trace-id response header for propagation. Default: true */
+    propagateTraceHeader?: boolean;
+    /**
+     * Auto-register route patterns in the ServiceBridge HTTP catalog on first hit.
+     * Routes appear in the UI after their first request. Default: true.
+     * Use registerExpressRoutes() for eager (pre-traffic) registration.
+     */
+    autoRegister?: boolean;
+}
+export declare function servicebridgeMiddleware(options: ServiceBridgeExpressOptions): (req: Request, res: Response, next: NextFunction) => void;
+export interface RegisterExpressRoutesOptions {
+    /** Stable identifier for this process instance used in http_instances. */
+    instanceId?: string;
+    /** Address where this service can be reached, e.g. "http://10.0.0.1:3000" */
+    endpoint?: string;
+    /** Service names allowed to call these endpoints. Default: [] */
+    allowedCallers?: string[];
+    /** Path prefixes to exclude from registration. Default: [] */
+    excludePaths?: string[];
+}
+/**
+ * Scan an Express application's route table and register every route pattern
+ * in the ServiceBridge HTTP catalog. Safe to call multiple times (idempotent).
+ *
+ * @example
+ * app.get('/users/:id', handler);
+ * app.post('/orders', handler);
+ * app.listen(3000, () => registerExpressRoutes(app, sb));
+ */
+export declare function registerExpressRoutes(app: Application, client: ServiceBridgeService, opts?: RegisterExpressRoutesOptions): Promise<void>;
+//# sourceMappingURL=express.d.ts.map

package/http/dist/express.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.d.ts","sourceRoot":"","sources":["../src/express.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAEjE,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAElD,OAAO,EAAE,uBAAuB,EAAE,CAAC;AACnC,YAAY,EAAE,oBAAoB,EAAE,CAAC;AAErC,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,OAAO,CAAC;QAChB,UAAU,OAAO;YACf,aAAa,EAAE,oBAAoB,CAAC;YACpC,OAAO,CAAC,EAAE,MAAM,CAAC;YACjB,MAAM,CAAC,EAAE,MAAM,CAAC;SACjB;KACF;CACF;AAED,MAAM,WAAW,2BAA2B;IAC1C,6DAA6D;IAC7D,MAAM,EAAE,oBAAoB,CAAC;IAC7B,yCAAyC;IACzC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,oEAAoE;IACpE,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,2BAA2B,IAaxE,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,MAAM,YAAY,KACjB,IAAI,CA8DR;AAOD,MAAM,WAAW,4BAA4B;IAC3C,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,oBAAoB,EAC5B,IAAI,GAAE,4BAAiC,GACtC,OAAO,CAAC,IAAI,CAAC,CAiBf"}

package/http/dist/express.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=express.test.d.ts.map

package/http/dist/express.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.test.d.ts","sourceRoot":"","sources":["../src/express.test.ts"],"names":[],"mappings":""}

package/http/dist/fastify.d.ts

@@ -0,0 +1,43 @@
+import type { ServiceBridgeService } from "@service-bridge/node";
+import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+declare module "fastify" {
+    interface FastifyRequest {
+        servicebridge: ServiceBridgeService;
+        traceId?: string;
+        spanId?: string;
+    }
+}
+export interface ServiceBridgeFastifyOptions {
+    /** ServiceBridge client (from servicebridge()). Required. */
+    client: ServiceBridgeService;
+    /** Paths to skip tracing. Default: [] */
+    excludePaths?: string[];
+    /** Set x-trace-id response header for propagation. Default: true */
+    propagateTraceHeader?: boolean;
+    /**
+     * Auto-register every route in the ServiceBridge HTTP catalog via Fastify's
+     * onRoute hook. Routes appear in the UI as soon as the server starts (before
+     * any traffic). Default: true.
+     */
+    autoRegister?: boolean;
+    /**
+     * Options forwarded to registerHttpEndpoint for each auto-discovered route.
+     */
+    register?: {
+        /** Stable identifier for this process instance. */
+        instanceId?: string;
+        /** Address where this service can be reached, e.g. "http://10.0.0.1:3000" */
+        endpoint?: string;
+        /** Service names allowed to call these endpoints. Default: [] */
+        allowedCallers?: string[];
+        /** Path prefixes to exclude from registration. Default: [] */
+        excludePaths?: string[];
+    };
+}
+export declare function servicebridgePlugin(fastify: FastifyInstance, options: ServiceBridgeFastifyOptions): Promise<void>;
+/**
+ * Wraps a route handler to run inside trace context.
+ * Use when the handler calls req.servicebridge.rpc() or event() — ensures trace propagation.
+ */
+export declare function wrapHandler<T>(handler: (request: FastifyRequest, reply: FastifyReply) => T): (request: FastifyRequest, reply: FastifyReply) => T;
+//# sourceMappingURL=fastify.d.ts.map

package/http/dist/fastify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fastify.d.ts","sourceRoot":"","sources":["../src/fastify.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAEjE,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAI7E,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,cAAc;QACtB,aAAa,EAAE,oBAAoB,CAAC;QACpC,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB;CACF;AAED,MAAM,WAAW,2BAA2B;IAC1C,6DAA6D;IAC7D,MAAM,EAAE,oBAAoB,CAAC;IAC7B,yCAAyC;IACzC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,oEAAoE;IACpE,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;OAEG;IACH,QAAQ,CAAC,EAAE;QACT,mDAAmD;QACnD,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,6EAA6E;QAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,iEAAiE;QACjE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;QAC1B,8DAA8D;QAC9D,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;KACzB,CAAC;CACH;AAED,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CA8Ff;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,OAAO,EAAE,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,CAAC,GAC3D,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,CAAC,CAWrD"}

package/http/dist/fastify.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=fastify.test.d.ts.map

package/http/dist/fastify.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fastify.test.d.ts","sourceRoot":"","sources":["../src/fastify.test.ts"],"names":[],"mappings":""}

package/http/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { RegisterExpressRoutesOptions, ServiceBridgeExpressOptions, } from "./express";
+export { registerExpressRoutes, servicebridgeMiddleware } from "./express";
+export type { ServiceBridgeFastifyOptions } from "./fastify";
+export { servicebridgePlugin, wrapHandler } from "./fastify";
+export type { IncomingTraceContext } from "./trace";
+export { extractTraceFromHeaders } from "./trace";
+//# sourceMappingURL=index.d.ts.map

package/http/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,4BAA4B,EAC5B,2BAA2B,GAC5B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AAC3E,YAAY,EAAE,2BAA2B,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7D,YAAY,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC"}

package/http/dist/trace.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Result of extracting trace context from incoming HTTP headers.
+ * traceId    — the trace this request belongs to (carry-over or newly generated).
+ * parentSpanId — the caller's span ID to use as parent, empty string if unknown.
+ */
+export interface IncomingTraceContext {
+    traceId: string;
+    parentSpanId: string;
+}
+/**
+ * Extract distributed trace context from incoming HTTP request headers.
+ *
+ * Priority:
+ *  1. W3C `traceparent` — full parent info (traceId + parentSpanId)
+ *  2. `x-trace-id`      — traceId only, no parent span known
+ *  3. Nothing           — generate a fresh traceId, no parent
+ */
+export declare function extractTraceFromHeaders(headers: Record<string, string | string[] | undefined>): IncomingTraceContext;
+//# sourceMappingURL=trace.d.ts.map

package/http/dist/trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../src/trace.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB;AAqBD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,GACrD,oBAAoB,CAgBtB"}

package/http/dist/trace.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=trace.test.d.ts.map

package/http/dist/trace.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.test.d.ts","sourceRoot":"","sources":["../src/trace.test.ts"],"names":[],"mappings":""}

package/http/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@servicebridge/http-node",
+  "version": "0.1.0",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./express": {
+      "import": "./dist/express.js",
+      "types": "./dist/express.d.ts"
+    },
+    "./fastify": {
+      "import": "./dist/fastify.js",
+      "types": "./dist/fastify.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "bun build src/index.ts src/express.ts src/fastify.ts --outdir=dist --target=node"
+  },
+  "dependencies": {
+    "@servicebridge/sdk-node": "^0.1.0"
+  },
+  "peerDependencies": {
+    "express": ">=4.0.0",
+    "fastify": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    },
+    "fastify": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.0.0",
+    "fastify": "^4.29.0",
+    "typescript": "^5.3.0"
+  }
+}

package/http/src/express.test.ts

@@ -0,0 +1,125 @@
+// @ts-nocheck
+import { describe, expect, it } from "bun:test";
+import { EventEmitter } from "node:events";
+import { getTraceContext } from "@service-bridge/node";
+import { servicebridgeMiddleware } from "./express";
+
+class FakeResponse extends EventEmitter {
+  headers: Record<string, string> = {};
+  statusCode = 200;
+
+  setHeader(name: string, value: string) {
+    this.headers[name.toLowerCase()] = value;
+  }
+}
+
+describe("servicebridgeMiddleware", () => {
+  it("starts span, propagates trace context and ends it once", () => {
+    const ended: Array<Record<string, unknown>> = [];
+    const client = {
+      startHttpSpan(opts: Record<string, unknown>) {
+        expect(opts.method).toBe("GET");
+        expect(opts.path).toBe("/orders");
+        expect(opts.traceId).toBe("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");
+        expect(opts.parentSpanId).toBe("1111111111111111");
+        return {
+          traceId: "span-trace",
+          spanId: "span-id",
+          end(opts: Record<string, unknown>) {
+            ended.push(opts);
+          },
+        };
+      },
+    };
+    const middleware = servicebridgeMiddleware({ client: client as never });
+
+    const req = {
+      method: "GET",
+      path: "/orders",
+      url: "/orders?limit=10",
+      headers: {
+        traceparent: "00-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-1111111111111111-01",
+      },
+    };
+    const res = new FakeResponse();
+    let nextCalls = 0;
+
+    middleware(req as never, res as never, () => {
+      nextCalls++;
+      const trace = getTraceContext();
+      expect(trace).toEqual({ traceId: "span-trace", spanId: "span-id" });
+      expect(req.servicebridge).toBe(client);
+      expect(req.traceId).toBe("span-trace");
+      expect(req.spanId).toBe("span-id");
+    });
+
+    expect(nextCalls).toBe(1);
+    expect(res.headers["x-trace-id"]).toBe("span-trace");
+
+    res.emit("finish");
+    res.emit("close");
+
+    expect(ended).toEqual([{ statusCode: 200, success: true }]);
+  });
+
+  it("respects excludePaths and skips tracing", () => {
+    let started = 0;
+    const client = {
+      startHttpSpan() {
+        started++;
+        throw new Error("must not be called");
+      },
+    };
+    const middleware = servicebridgeMiddleware({
+      client: client as never,
+      excludePaths: ["/health"],
+    });
+
+    const req = {
+      method: "GET",
+      path: "/health/ready",
+      url: "/health/ready",
+      headers: {},
+    };
+    const res = new FakeResponse();
+    let nextCalls = 0;
+
+    middleware(req as never, res as never, () => {
+      nextCalls++;
+      expect(getTraceContext()).toBeUndefined();
+    });
+
+    expect(nextCalls).toBe(1);
+    expect(started).toBe(0);
+    expect(req.servicebridge).toBe(client);
+    expect(res.headers["x-trace-id"]).toBeUndefined();
+  });
+
+  it("can disable x-trace-id propagation", () => {
+    const client = {
+      startHttpSpan() {
+        return {
+          traceId: "trace-id",
+          spanId: "span-id",
+          end() {},
+        };
+      },
+    };
+    const middleware = servicebridgeMiddleware({
+      client: client as never,
+      propagateTraceHeader: false,
+    });
+
+    const req = {
+      method: "POST",
+      path: "/events",
+      url: "/events",
+      headers: {},
+    };
+    const res = new FakeResponse();
+
+    middleware(req as never, res as never, () => {});
+
+    expect(res.headers["x-trace-id"]).toBeUndefined();
+  });
+});

package/http/src/express.ts

@@ -0,0 +1,209 @@
+import type { ServiceBridgeService } from "@service-bridge/node";
+import { runWithTraceContext } from "@service-bridge/node";
+import type { Application, NextFunction, Request, Response } from "express";
+import type { IncomingTraceContext } from "./trace";
+import { extractTraceFromHeaders } from "./trace";
+
+export { extractTraceFromHeaders };
+export type { IncomingTraceContext };
+
+declare global {
+  namespace Express {
+    interface Request {
+      servicebridge: ServiceBridgeService;
+      traceId?: string;
+      spanId?: string;
+    }
+  }
+}
+
+export interface ServiceBridgeExpressOptions {
+  /** ServiceBridge client (from servicebridge()). Required. */
+  client: ServiceBridgeService;
+  /** Paths to skip tracing. Default: [] */
+  excludePaths?: string[];
+  /** Set x-trace-id response header for propagation. Default: true */
+  propagateTraceHeader?: boolean;
+  /**
+   * Auto-register route patterns in the ServiceBridge HTTP catalog on first hit.
+   * Routes appear in the UI after their first request. Default: true.
+   * Use registerExpressRoutes() for eager (pre-traffic) registration.
+   */
+  autoRegister?: boolean;
+}
+
+export function servicebridgeMiddleware(options: ServiceBridgeExpressOptions) {
+  const {
+    client,
+    excludePaths = [],
+    propagateTraceHeader = true,
+    autoRegister = true,
+  } = options;
+
+  // Tracks which "METHOD:pattern" keys have already been registered so we
+  // fire the catalog call only once per unique route pattern per process.
+  const registeredPatterns = new Set<string>();
+
+  return function middleware(
+    req: Request,
+    res: Response,
+    next: NextFunction,
+  ): void {
+    const path = req.path ?? req.url?.split("?")[0] ?? "/";
+    if (excludePaths.some((p) => path.startsWith(p))) {
+      req.servicebridge = client;
+      next();
+      return;
+    }
+
+    const headers: Record<string, string | string[] | undefined> = {};
+    for (const [k, v] of Object.entries(req.headers)) {
+      if (v != null) headers[k.toLowerCase()] = v;
+    }
+    const traceCtx: IncomingTraceContext = extractTraceFromHeaders(headers);
+
+    const span = client.startHttpSpan({
+      method: req.method,
+      path,
+      traceId: traceCtx.traceId,
+      parentSpanId: traceCtx.parentSpanId,
+    });
+
+    req.servicebridge = client;
+    req.traceId = span.traceId;
+    req.spanId = span.spanId;
+
+    if (propagateTraceHeader) {
+      res.setHeader("x-trace-id", span.traceId);
+    }
+
+    const onFinish = () => {
+      res.off("finish", onFinish);
+      res.off("close", onFinish);
+      span.end({
+        statusCode: res.statusCode,
+        success: res.statusCode < 400,
+      });
+
+      // Auto-register the route pattern in the catalog on first hit.
+      if (autoRegister) {
+        const routePattern = req.route?.path as string | undefined;
+        if (routePattern && typeof routePattern === "string") {
+          const key = `${req.method}:${routePattern}`;
+          if (!registeredPatterns.has(key)) {
+            registeredPatterns.add(key);
+            client
+              .registerHttpEndpoint({ method: req.method, route: routePattern })
+              .catch(() => {
+                // Non-fatal: catalog registration is best-effort.
+                registeredPatterns.delete(key);
+              });
+          }
+        }
+      }
+    };
+
+    res.on("finish", onFinish);
+    res.on("close", onFinish);
+
+    runWithTraceContext({ traceId: span.traceId, spanId: span.spanId }, () => {
+      next();
+    });
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Eager registration: scan Express router and register all routes up-front.
+// Call after all app.get/post/... declarations and before (or right after) listen.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface RegisterExpressRoutesOptions {
+  /** Stable identifier for this process instance used in http_instances. */
+  instanceId?: string;
+  /** Address where this service can be reached, e.g. "http://10.0.0.1:3000" */
+  endpoint?: string;
+  /** Service names allowed to call these endpoints. Default: [] */
+  allowedCallers?: string[];
+  /** Path prefixes to exclude from registration. Default: [] */
+  excludePaths?: string[];
+}
+
+/**
+ * Scan an Express application's route table and register every route pattern
+ * in the ServiceBridge HTTP catalog. Safe to call multiple times (idempotent).
+ *
+ * @example
+ * app.get('/users/:id', handler);
+ * app.post('/orders', handler);
+ * app.listen(3000, () => registerExpressRoutes(app, sb));
+ */
+export async function registerExpressRoutes(
+  app: Application,
+  client: ServiceBridgeService,
+  opts: RegisterExpressRoutesOptions = {},
+): Promise<void> {
+  const { instanceId, endpoint, allowedCallers = [], excludePaths = [] } = opts;
+  const routes = extractExpressRoutes(app);
+
+  await Promise.allSettled(
+    routes
+      .filter(({ path }) => !excludePaths.some((p) => path.startsWith(p)))
+      .map(({ method, path: route }) =>
+        client.registerHttpEndpoint({
+          method,
+          route,
+          instanceId,
+          endpoint,
+          allowedCallers,
+        }),
+      ),
+  );
+}
+
+interface RouteEntry {
+  method: string;
+  path: string;
+}
+
+/** Express internal layer shape (router stack entry). */
+interface ExpressLayer {
+  route?: { path?: string; methods?: Record<string, unknown> };
+  name?: string;
+  handle?: ExpressRouterLike;
+}
+
+/** App or Router: has stack of layers. */
+interface ExpressRouterLike {
+  _router?: { stack?: ExpressLayer[] };
+  router?: { stack?: ExpressLayer[] };
+  stack?: ExpressLayer[];
+}
+
+function getLayerStack(app: ExpressRouterLike): ExpressLayer[] {
+  const r = app._router ?? app.router;
+  return r?.stack ?? (app as ExpressRouterLike).stack ?? [];
+}
+
+function extractExpressRoutes(
+  app: Application | ExpressRouterLike,
+  prefix = "",
+): RouteEntry[] {
+  const routes: RouteEntry[] = [];
+  const stack = getLayerStack(app as ExpressRouterLike);
+
+  for (const layer of stack) {
+    if (layer.route) {
+      const routePath = prefix + (layer.route.path ?? "");
+      const methods = Object.keys(layer.route.methods ?? {}).filter(
+        (m) => m !== "_all",
+      );
+      for (const method of methods) {
+        routes.push({ method: method.toUpperCase(), path: routePath });
+      }
+    } else if (layer.name === "router" && layer.handle) {
+      routes.push(...extractExpressRoutes(layer.handle, prefix));
+    }
+  }
+
+  return routes;
+}