@service-bridge/node 0.1.3

package/http/src/fastify.test.ts

@@ -0,0 +1,142 @@
+// @ts-nocheck
+import { describe, expect, it } from "bun:test";
+import { EventEmitter } from "node:events";
+import { getTraceContext } from "@service-bridge/node";
+import { servicebridgePlugin, wrapHandler } from "./fastify";
+
+describe("servicebridgePlugin", () => {
+  it("decorates request, propagates header and closes span on finish", async () => {
+    let onRequest: unknown;
+    const ended: Array<Record<string, unknown>> = [];
+    const client = {
+      startHttpSpan(opts: Record<string, unknown>) {
+        expect(opts.method).toBe("POST");
+        expect(opts.path).toBe("/rpc");
+        expect(opts.traceId).toBe("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");
+        expect(opts.parentSpanId).toBe("1111111111111111");
+        return {
+          traceId: "trace-id",
+          spanId: "span-id",
+          end(opts: Record<string, unknown>) {
+            ended.push(opts);
+          },
+        };
+      },
+    };
+    const fastify = {
+      decorateRequest() {},
+      addHook(name: string, handler: unknown) {
+        if (name === "onRequest") {
+          onRequest = handler;
+        }
+      },
+    };
+
+    await servicebridgePlugin(fastify as never, { client: client as never });
+
+    const request = {
+      method: "POST",
+      url: "/rpc?x=1",
+      headers: {
+        traceparent: "00-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-1111111111111111-01",
+      },
+      raw: new EventEmitter(),
+    };
+    const reply = {
+      statusCode: 201,
+      sent: true,
+      headers: {} as Record<string, string>,
+      raw: new EventEmitter(),
+      header(name: string, value: string) {
+        this.headers[name.toLowerCase()] = value;
+      },
+    };
+
+    await (onRequest as (request: unknown, reply: unknown) => Promise<void>)(
+      request,
+      reply,
+    );
+
+    expect(request.servicebridge).toBe(client);
+    expect(request.traceId).toBe("trace-id");
+    expect(request.spanId).toBe("span-id");
+    expect(reply.headers["x-trace-id"]).toBe("trace-id");
+
+    reply.raw.emit("finish");
+    request.raw.emit("close");
+
+    expect(ended).toEqual([{ statusCode: 201, success: true }]);
+  });
+
+  it("skips tracing for excluded paths", async () => {
+    let onRequest: unknown;
+    const client = {
+      startHttpSpan() {
+        throw new Error("must not be called");
+      },
+    };
+    const fastify = {
+      decorateRequest() {},
+      addHook(_name: string, handler: unknown) {
+        onRequest = handler;
+      },
+    };
+
+    await servicebridgePlugin(fastify as never, {
+      client: client as never,
+      excludePaths: ["/health"],
+      propagateTraceHeader: false,
+    });
+
+    const request = {
+      method: "GET",
+      url: "/health/live",
+      headers: {},
+      raw: new EventEmitter(),
+    };
+    const reply = {
+      statusCode: 200,
+      sent: false,
+      headers: {} as Record<string, string>,
+      raw: new EventEmitter(),
+      header(name: string, value: string) {
+        this.headers[name.toLowerCase()] = value;
+      },
+    };
+
+    await (onRequest as (request: unknown, reply: unknown) => Promise<void>)(
+      request,
+      reply,
+    );
+
+    expect(request.servicebridge).toBe(client);
+    expect(request.traceId).toBeUndefined();
+    expect(request.spanId).toBeUndefined();
+    expect(reply.headers["x-trace-id"]).toBeUndefined();
+  });
+});
+
+describe("wrapHandler", () => {
+  it("runs handler inside trace context when trace ids exist", () => {
+    const handler = wrapHandler((request: { traceId?: string }) => {
+      expect(request.traceId).toBe("trace-id");
+      expect(getTraceContext()).toEqual({
+        traceId: "trace-id",
+        spanId: "span-id",
+      });
+      return "ok";
+    });
+
+    const result = handler(
+      { traceId: "trace-id", spanId: "span-id" } as never,
+      {} as never,
+    );
+    expect(result).toBe("ok");
+  });
+
+  it("calls handler directly when there is no trace context", () => {
+    const handler = wrapHandler(() => getTraceContext());
+    const result = handler({} as never, {} as never);
+    expect(result).toBeUndefined();
+  });
+});

package/http/src/fastify.ts

@@ -0,0 +1,159 @@
+import type { ServiceBridgeService } from "@service-bridge/node";
+import { runWithTraceContext } from "@service-bridge/node";
+import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+import type { IncomingTraceContext } from "./trace";
+import { extractTraceFromHeaders } from "./trace";
+
+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 async function servicebridgePlugin(
+  fastify: FastifyInstance,
+  options: ServiceBridgeFastifyOptions,
+): Promise<void> {
+  const {
+    client,
+    excludePaths = [],
+    propagateTraceHeader = true,
+    autoRegister = true,
+    register: registerOpts = {},
+  } = options;
+
+  fastify.decorateRequest("servicebridge", null);
+  fastify.decorateRequest("traceId", null);
+  fastify.decorateRequest("spanId", null);
+
+  // Auto-register each route in the catalog as soon as it's declared.
+  if (autoRegister) {
+    const excludeReg = registerOpts.excludePaths ?? [];
+    fastify.addHook("onRoute", (routeOptions) => {
+      const routePath = routeOptions.url ?? routeOptions.path ?? "";
+      if (excludeReg.some((p) => routePath.startsWith(p))) return;
+
+      const methods = Array.isArray(routeOptions.method)
+        ? routeOptions.method
+        : [routeOptions.method];
+
+      for (const method of methods) {
+        // HEAD/OPTIONS are framework-managed and rarely meaningful in the catalog.
+        if (method === "HEAD" || method === "OPTIONS") continue;
+        client
+          .registerHttpEndpoint({
+            method,
+            route: routePath,
+            instanceId: registerOpts.instanceId,
+            endpoint: registerOpts.endpoint,
+            allowedCallers: registerOpts.allowedCallers ?? [],
+          })
+          .catch(() => {
+            // Non-fatal: server may not be reachable yet at plugin-load time.
+          });
+      }
+    });
+  }
+
+  fastify.addHook(
+    "onRequest",
+    async (request: FastifyRequest, reply: FastifyReply) => {
+      request.servicebridge = client;
+
+      const path = request.url?.split("?")[0] ?? "/";
+      if (excludePaths.some((p) => path.startsWith(p))) {
+        return;
+      }
+
+      const headers: Record<string, string | string[] | undefined> = {};
+      for (const [k, v] of Object.entries(request.headers)) {
+        if (typeof v === "string" || Array.isArray(v)) {
+          headers[k.toLowerCase()] = v;
+        }
+      }
+      const traceCtx: IncomingTraceContext = extractTraceFromHeaders(headers);
+
+      const span = client.startHttpSpan({
+        method: request.method,
+        path,
+        traceId: traceCtx.traceId,
+        parentSpanId: traceCtx.parentSpanId,
+      });
+      let ended = false;
+      const endSpan = (opts: Parameters<typeof span.end>[0]) => {
+        if (ended) return;
+        ended = true;
+        span.end(opts);
+      };
+
+      request.traceId = span.traceId;
+      request.spanId = span.spanId;
+
+      if (propagateTraceHeader) {
+        reply.header("x-trace-id", span.traceId);
+      }
+
+      request.raw.once("close", () => {
+        if (!reply.sent) {
+          endSpan({ success: false, error: "connection closed" });
+        }
+      });
+
+      reply.raw.once("finish", () => {
+        endSpan({
+          statusCode: reply.statusCode,
+          success: reply.statusCode < 400,
+        });
+      });
+    },
+  );
+}
+
+/**
+ * Wraps a route handler to run inside trace context.
+ * Use when the handler calls req.servicebridge.rpc() or event() — ensures trace propagation.
+ */
+export function wrapHandler<T>(
+  handler: (request: FastifyRequest, reply: FastifyReply) => T,
+): (request: FastifyRequest, reply: FastifyReply) => T {
+  return (request: FastifyRequest, reply: FastifyReply) => {
+    const traceId = request.traceId;
+    const spanId = request.spanId;
+    if (traceId && spanId) {
+      return runWithTraceContext({ traceId, spanId }, () =>
+        handler(request, reply),
+      ) as T;
+    }
+    return handler(request, reply);
+  };
+}

package/http/src/index.ts

@@ -0,0 +1,10 @@
+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";

package/http/src/sdk-augment.d.ts

@@ -0,0 +1,11 @@
+declare module "@service-bridge/node" {
+  interface ServiceBridgeService {
+    registerHttpEndpoint(opts: {
+      method: string;
+      route: string;
+      instanceId?: string;
+      endpoint?: string;
+      allowedCallers?: string[];
+    }): Promise<void>;
+  }
+}

package/http/src/servicebridge.d.ts

@@ -0,0 +1,23 @@
+declare module "@service-bridge/node" {
+  export interface TraceCtx {
+    traceId: string;
+    spanId: string;
+  }
+
+  export interface HttpSpan {
+    traceId: string;
+    spanId: string;
+    end(opts: { statusCode?: number; success?: boolean; error?: string }): void;
+  }
+
+  export interface ServiceBridgeService {
+    startHttpSpan(opts: {
+      method: string;
+      path: string;
+      traceId?: string;
+      parentSpanId?: string;
+    }): HttpSpan;
+  }
+
+  export function runWithTraceContext<T>(ctx: TraceCtx, fn: () => T): T;
+}

package/http/src/trace.test.ts

@@ -0,0 +1,97 @@
+// @ts-nocheck
+import { describe, expect, it } from "bun:test";
+import { extractTraceFromHeaders } from "./trace";
+
+describe("extractTraceFromHeaders", () => {
+  it("parses valid W3C traceparent and extracts parent span", () => {
+    const ctx = extractTraceFromHeaders({
+      traceparent: "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
+    });
+    expect(ctx.traceId).toBe("4bf92f3577b34da6a3ce929d0e0e4736");
+    expect(ctx.parentSpanId).toBe("00f067aa0ba902b7");
+  });
+
+  it("uses x-trace-id when traceparent is absent, no parent span", () => {
+    const ctx = extractTraceFromHeaders({
+      "x-trace-id": "trace-from-header",
+    });
+    expect(ctx.traceId).toBe("trace-from-header");
+    // x-trace-id provides no parent span info — parentSpanId must be empty
+    expect(ctx.parentSpanId).toBe("");
+  });
+
+  it("generates fresh trace when no headers present", () => {
+    const ctx = extractTraceFromHeaders({});
+    expect(ctx.traceId.length).toBeGreaterThan(0);
+    expect(ctx.parentSpanId).toBe("");
+  });
+
+  it("ignores malformed traceparent and falls back", () => {
+    const ctx = extractTraceFromHeaders({
+      traceparent: "bad-value",
+      "x-trace-id": "fallback-trace",
+    });
+    expect(ctx.traceId).toBe("fallback-trace");
+    expect(ctx.parentSpanId).toBe("");
+  });
+
+  it("uses the first traceparent value when header is an array", () => {
+    const ctx = extractTraceFromHeaders({
+      traceparent: [
+        "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
+        "00-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-bbbbbbbbbbbbbbbb-01",
+      ],
+    });
+    expect(ctx.traceId).toBe("4bf92f3577b34da6a3ce929d0e0e4736");
+    expect(ctx.parentSpanId).toBe("00f067aa0ba902b7");
+  });
+
+  it("rejects unsupported traceparent versions and falls back", () => {
+    const ctx = extractTraceFromHeaders({
+      traceparent: "ff-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
+      "x-trace-id": "fallback-trace",
+    });
+    expect(ctx.traceId).toBe("fallback-trace");
+    expect(ctx.parentSpanId).toBe("");
+  });
+
+  it("rejects malformed traceparent lengths and falls back", () => {
+    const ctx = extractTraceFromHeaders({
+      traceparent: "00-short-too-short-01",
+      "x-trace-id": "fallback-trace",
+    });
+    expect(ctx.traceId).toBe("fallback-trace");
+    expect(ctx.parentSpanId).toBe("");
+  });
+
+  it("preserves current behavior for non-hex traceparent ids", () => {
+    const ctx = extractTraceFromHeaders({
+      traceparent: "00-zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz-yyyyyyyyyyyyyyyy-01",
+    });
+    expect(ctx.traceId).toBe("zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz");
+    expect(ctx.parentSpanId).toBe("yyyyyyyyyyyyyyyy");
+  });
+
+  it("trims x-trace-id without inventing a parent span", () => {
+    const ctx = extractTraceFromHeaders({
+      "x-trace-id": "  external-trace-id  ",
+    });
+    expect(ctx.traceId).toBe("external-trace-id");
+    expect(ctx.parentSpanId).toBe("");
+  });
+
+  it("keeps empty x-trace-id as current fallback behavior", () => {
+    const ctx = extractTraceFromHeaders({
+      "x-trace-id": "   ",
+    });
+    expect(ctx.traceId).toBe("");
+    expect(ctx.parentSpanId).toBe("");
+  });
+
+  it("generates a 32-char trace id when nothing is provided", () => {
+    const ctx = extractTraceFromHeaders({});
+    expect(ctx.traceId).toHaveLength(32);
+    expect(ctx.traceId.includes("-")).toBe(false);
+    expect(ctx.parentSpanId).toBe("");
+  });
+});

package/http/src/trace.ts

@@ -0,0 +1,56 @@
+/**
+ * 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;
+}
+
+/** Parse W3C traceparent: 00-{32hex}-{16hex}-{flags} */
+function parseTraceparent(traceparent: string): IncomingTraceContext | null {
+  const parts = traceparent.trim().split("-");
+  if (parts.length !== 4 || parts[0] !== "00") return null;
+  const [, traceId, parentSpanId] = parts;
+  if (
+    !traceId ||
+    !parentSpanId ||
+    traceId.length !== 32 ||
+    parentSpanId.length !== 16
+  )
+    return null;
+  return { traceId, parentSpanId };
+}
+
+function randomTraceId(): string {
+  return crypto.randomUUID().replace(/-/g, "");
+}
+
+/**
+ * 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 function extractTraceFromHeaders(
+  headers: Record<string, string | string[] | undefined>,
+): IncomingTraceContext {
+  const traceparent = headers.traceparent;
+  const tp = Array.isArray(traceparent) ? traceparent[0] : traceparent;
+  if (tp) {
+    const parsed = parseTraceparent(tp);
+    if (parsed) return parsed;
+  }
+
+  const xTraceId = headers["x-trace-id"];
+  const traceId = Array.isArray(xTraceId) ? xTraceId[0] : xTraceId;
+  if (traceId && typeof traceId === "string") {
+    // Caller provided a trace ID but no parent span — this request is the root of this trace.
+    return { traceId: traceId.trim(), parentSpanId: "" };
+  }
+
+  return { traceId: randomTraceId(), parentSpanId: "" };
+}

package/http/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": { "@service-bridge/node": ["../dist/index"] },
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"]
+}

package/http/tsconfig.test.json

@@ -0,0 +1,6 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "paths": { "@service-bridge/node": ["../sdk/src/index"] }
+  }
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@service-bridge/node",
+  "version": "0.1.3",
+  "type": "module",
+  "private": false,
+  "license": "SEE LICENSE IN LICENSE",
+  "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": {
+    "generate:proto": "bun run sdk/scripts/generate-proto.ts",
+    "build:core": "bun run generate:proto && bun build sdk/src/index.ts --outdir=dist --target=node",
+    "build:types": "bunx tsc -p sdk/tsconfig.json --emitDeclarationOnly --outDir dist && bunx tsc -p http/tsconfig.json --emitDeclarationOnly --outDir http/dist && cp http/dist/express.d.ts http/dist/fastify.d.ts http/dist/trace.d.ts dist/",
+    "build:express": "bun build ./http/src/express.ts --outfile=dist/express.js --target=node -e @service-bridge/node",
+    "build:fastify": "bun build ./http/src/fastify.ts --outfile=dist/fastify.js --target=node -e @service-bridge/node",
+    "build": "bun run build:core && bun run build:express && bun run build:fastify && bun run build:types",
+    "test:sdk": "bun test sdk",
+    "test:http": "bun test --tsconfig-override http/tsconfig.test.json http",
+    "test": "bun run test:sdk && bun run test:http",
+    "typecheck": "bunx tsc -p sdk/tsconfig.json --noEmit && bunx tsc -p http/tsconfig.json --noEmit",
+    "lint": "bunx biome check .",
+    "lint:fix": "bunx biome check . --write"
+  },
+  "dependencies": {
+    "@grpc/grpc-js": "^1.9.0",
+    "@grpc/proto-loader": "^0.7.10",
+    "protobufjs": "^8.0.0"
+  },
+  "peerDependencies": {
+    "express": ">=4.0.0",
+    "fastify": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    },
+    "fastify": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.5",
+    "@types/bun": "latest",
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.0.0",
+    "fastify": "^4.29.0",
+    "typescript": "^5.3.0"
+  }
+}