@checkstack/backend-api 0.16.0 → 0.17.1

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # @checkstack/backend-api
 
+## 0.17.1
+
+### Patch Changes
+
+- Updated dependencies [ba07ae2]
+  - @checkstack/healthcheck-common@1.2.0
+  - @checkstack/cache-api@0.3.5
+  - @checkstack/queue-api@0.3.5
+
+## 0.17.0
+
+### Minor Changes
+
+- f23f3c9: Add `correlationMiddleware` to `@checkstack/backend-api` and apply it
+  to every plugin/core router so each request carries a stable
+  `x-correlation-id` (read from the inbound header, or freshly minted
+  via `crypto.randomUUID()` when absent) and an auto-injected child
+  logger bound with `{ correlationId, pluginId, userId? }`. The ID is
+  echoed back on the response header so the caller can correlate their
+  client-side trace to the server logs.
+
+  The `Logger` interface in `@checkstack/backend-api` now formally
+  documents the structured-metadata convention (`logger.info("msg",
+{ ...meta })`) alongside the long-standing varargs shape. Winston's
+  splat handling already routes both shapes through the same vararg
+  slot, so existing call sites are unaffected. A new optional
+  `Logger.child(meta)` method captures the metadata-binding contract the
+  new middleware relies on; production loggers always implement it,
+  minimal test mocks may omit it (the middleware falls back gracefully).
+
+  `RpcContext` grew two optional `Headers` bags, `requestHeaders` and
+  `responseHeaders`, populated by the outer Hono `/api/*` and `/rest/*`
+  handlers in `@checkstack/backend`. They are write-through observation
+  points for middleware; an `RpcContext` constructed without them (S2S
+  clients, tests) keeps working — the echo is a silent no-op and the ID
+  is still bound onto the child logger for server-side correlation.
+
+  The scaffolding template in `@checkstack/scripts` was updated so any
+  new plugin generated via `bun run create` wires the middleware in the
+  expected `.use(correlationMiddleware).use(autoAuthMiddleware)` order
+  out of the box.
+
+### Patch Changes
+
+- Updated dependencies [f23f3c9]
+- Updated dependencies [f23f3c9]
+  - @checkstack/common@0.11.0
+  - @checkstack/healthcheck-common@1.1.2
+  - @checkstack/signal-common@0.2.4
+  - @checkstack/cache-api@0.3.4
+  - @checkstack/queue-api@0.3.4
+
 ## 0.16.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/backend-api",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "./src/index.ts",
@@ -10,11 +10,11 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/common": "0.10.0",
-    "@checkstack/healthcheck-common": "1.1.0",
-    "@checkstack/cache-api": "0.3.2",
-    "@checkstack/queue-api": "0.3.2",
-    "@checkstack/signal-common": "0.2.3",
+    "@checkstack/common": "0.11.0",
+    "@checkstack/healthcheck-common": "1.1.2",
+    "@checkstack/cache-api": "0.3.4",
+    "@checkstack/queue-api": "0.3.4",
+    "@checkstack/signal-common": "0.2.4",
     "@orpc/client": "^1.13.14",
     "@orpc/contract": "^1.13.14",
     "@orpc/openapi": "^1.13.2",
@@ -28,7 +28,7 @@
   "devDependencies": {
     "@types/bun": "latest",
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/scripts": "0.3.2"
+    "@checkstack/scripts": "0.3.3"
   },
   "peerDependencies": {
     "hono": "^4.12.14",

package/src/correlation-middleware.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, it, mock, type Mock } from "bun:test";
+import { call, implement } from "@orpc/server";
+import { z } from "zod";
+import { proc } from "@checkstack/common";
+import {
+  autoAuthMiddleware,
+  CORRELATION_ID_HEADER,
+  correlationMiddleware,
+  RpcContext,
+} from "./rpc";
+import { createMockRpcContext } from "./test-utils";
+import { Logger } from "./types";
+
+const echoLoggerProcedure = proc({
+  userType: "anonymous",
+  operationType: "query",
+  access: [],
+}).output(
+  z.object({
+    correlationIdFromMeta: z.string().optional(),
+    pluginIdFromMeta: z.string().optional(),
+    userIdFromMeta: z.string().optional(),
+  }),
+);
+
+const testContract = {
+  echo: echoLoggerProcedure,
+};
+
+type LastChildMeta = Record<string, unknown> | undefined;
+
+function buildRouterCapturingChildMeta(captureRef: { value: LastChildMeta }) {
+  const os = implement(testContract)
+    .$context<RpcContext>()
+    .use(correlationMiddleware)
+    .use(autoAuthMiddleware);
+
+  return os.router({
+    echo: os.echo.handler(({ context }) => {
+      // The capture happens in the child() mock on the test's logger.
+      // We just return the metadata that the middleware should have bound.
+      void context.logger;
+      return {
+        correlationIdFromMeta: captureRef.value?.correlationId as
+          | string
+          | undefined,
+        pluginIdFromMeta: captureRef.value?.pluginId as string | undefined,
+        userIdFromMeta: captureRef.value?.userId as string | undefined,
+      };
+    }),
+  });
+}
+
+function buildContextWithCapture(
+  overrides: Partial<RpcContext> = {},
+): {
+  context: RpcContext;
+  capture: { value: LastChildMeta };
+  childMock: Mock<(meta: Record<string, unknown>) => Logger>;
+} {
+  const capture: { value: LastChildMeta } = { value: undefined };
+  const childMock = mock((meta: Record<string, unknown>): Logger => {
+    capture.value = meta;
+    return {
+      info: mock(),
+      error: mock(),
+      warn: mock(),
+      debug: mock(),
+    };
+  });
+  const baseContext = createMockRpcContext(overrides);
+  // Replace the logger so child() captures the bound metadata.
+  baseContext.logger = {
+    info: mock(),
+    error: mock(),
+    warn: mock(),
+    debug: mock(),
+    child: childMock,
+  };
+  return { context: baseContext, capture, childMock };
+}
+
+const UUID_V4_REGEX =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+describe("correlationMiddleware", () => {
+  it("generates a UUID v4 when no x-correlation-id header is present", async () => {
+    const { context, capture } = buildContextWithCapture();
+    const router = buildRouterCapturingChildMeta(capture);
+
+    await call(router.echo, {}, { context });
+
+    expect(typeof capture.value?.correlationId).toBe("string");
+    expect(capture.value?.correlationId).toMatch(UUID_V4_REGEX);
+  });
+
+  it("uses the incoming x-correlation-id header when present", async () => {
+    const incoming = "11111111-2222-4333-8444-555555555555";
+    const { context, capture } = buildContextWithCapture({
+      requestHeaders: new Headers({ [CORRELATION_ID_HEADER]: incoming }),
+    });
+    const router = buildRouterCapturingChildMeta(capture);
+
+    await call(router.echo, {}, { context });
+
+    expect(capture.value?.correlationId).toBe(incoming);
+  });
+
+  it("ignores an empty x-correlation-id header and generates a fresh ID", async () => {
+    const { context, capture } = buildContextWithCapture({
+      requestHeaders: new Headers({ [CORRELATION_ID_HEADER]: "" }),
+    });
+    const router = buildRouterCapturingChildMeta(capture);
+
+    await call(router.echo, {}, { context });
+
+    expect(capture.value?.correlationId).toMatch(UUID_V4_REGEX);
+  });
+
+  it("echoes the correlation ID on responseHeaders when available", async () => {
+    const responseHeaders = new Headers();
+    const { context, capture } = buildContextWithCapture({
+      responseHeaders,
+    });
+    const router = buildRouterCapturingChildMeta(capture);
+
+    await call(router.echo, {}, { context });
+
+    const echoed = responseHeaders.get(CORRELATION_ID_HEADER);
+    expect(echoed).not.toBeNull();
+    expect(echoed).toBe(capture.value?.correlationId as string);
+  });
+
+  it("binds pluginId from context.pluginMetadata onto the child logger", async () => {
+    const { context, capture } = buildContextWithCapture({
+      pluginMetadata: { pluginId: "fancy-plugin" },
+    });
+    const router = buildRouterCapturingChildMeta(capture);
+
+    await call(router.echo, {}, { context });
+
+    expect(capture.value?.pluginId).toBe("fancy-plugin");
+  });
+
+  it("binds userId when the user has an id field", async () => {
+    const { context, capture } = buildContextWithCapture({
+      user: { type: "user", id: "user-abc", accessRules: ["*"] },
+    });
+    const router = buildRouterCapturingChildMeta(capture);
+
+    await call(router.echo, {}, { context });
+
+    expect(capture.value?.userId).toBe("user-abc");
+  });
+
+  it("omits userId when the user is a service (no id field)", async () => {
+    const { context, capture } = buildContextWithCapture({
+      user: { type: "service", pluginId: "internal-svc" },
+    });
+    const router = buildRouterCapturingChildMeta(capture);
+
+    await call(router.echo, {}, { context });
+
+    expect("userId" in (capture.value ?? {})).toBe(false);
+  });
+
+  it("falls back to the base logger when child() is not implemented", async () => {
+    // Reproduce a minimal mock logger without `.child` (e.g. a test mock
+    // that hasn't been updated). The middleware must not throw and the
+    // request must still complete.
+    const context = createMockRpcContext();
+    context.logger = {
+      info: mock(),
+      error: mock(),
+      warn: mock(),
+      debug: mock(),
+      // intentionally no child
+    };
+
+    const os = implement(testContract)
+      .$context<RpcContext>()
+      .use(correlationMiddleware)
+      .use(autoAuthMiddleware);
+    const router = os.router({
+      echo: os.echo.handler(() => ({})),
+    });
+
+    const result = await call(router.echo, {}, { context });
+    expect(result).toEqual({});
+  });
+});

package/src/rpc.ts

@@ -53,6 +53,21 @@ export interface RpcContext {
   cacheManager: CacheManager;
   /** Emit a hook event for cross-plugin communication */
   emitHook: EmitHookFn;
+  /**
+   * Inbound HTTP request headers (read-only view). Populated by the
+   * `/api/*` and `/rest/*` Hono handlers in `core/backend`. Optional
+   * because non-HTTP call sites (S2S clients, tests, scheduled queue
+   * jobs) can construct an `RpcContext` without a backing request.
+   */
+  requestHeaders?: Headers;
+  /**
+   * Mutable response headers. Middleware (e.g. `correlationMiddleware`)
+   * can set headers here, and the Hono handler that drives the oRPC
+   * `RPCHandler` / `OpenAPIHandler` merges them onto the actual
+   * `Response` after the procedure has run. Optional for the same
+   * reason as `requestHeaders`.
+   */
+  responseHeaders?: Headers;
 }
 
 /** Context with authenticated real user */
@@ -461,6 +476,91 @@ export const autoAuthMiddleware = os.middleware(
   },
 );
 
+// =============================================================================
+// CORRELATION ID MIDDLEWARE
+// =============================================================================
+
+/**
+ * Name of the inbound and outbound HTTP header that carries the correlation
+ * ID. Exported so dev tools, integration tests, and front-end fetch wrappers
+ * can refer to the canonical value rather than hard-coding the string.
+ */
+export const CORRELATION_ID_HEADER = "x-correlation-id";
+
+/**
+ * Per-request observability middleware.
+ *
+ * Behaviour:
+ * - Reads `x-correlation-id` from `context.requestHeaders` (populated by the
+ *   `/api/*` and `/rest/*` Hono handlers in `core/backend`).
+ * - Generates a fresh UUID v4 via `crypto.randomUUID()` if absent. This is
+ *   the ONLY generation site for correlation IDs in the platform — handlers
+ *   must NOT mint new IDs on their own.
+ * - Binds `{ correlationId, pluginId, userId? }` onto a child logger via
+ *   `ctx.logger.child(...)` so every subsequent log line in the request
+ *   carries that metadata automatically.
+ * - Writes the ID back to `context.responseHeaders` (if available) so the
+ *   outer Hono handler can echo `x-correlation-id` on the response, letting
+ *   the caller correlate their own client-side trace to the server log.
+ *
+ * Note on the echo: oRPC middleware has no direct access to the outgoing
+ * `Response` object — the framework constructs it from the procedure's
+ * return value AFTER middleware has finished. We use the mutable
+ * `responseHeaders` bag on `RpcContext` as a thin write-through: the Hono
+ * route handler merges those headers onto the `Response` post-handle. When
+ * an `RpcContext` is constructed without `responseHeaders` (S2S clients,
+ * tests), the echo silently no-ops; the ID is still bound to the child
+ * logger so server-side correlation still works.
+ *
+ * Order matters: in plugin routers, `.use(correlationMiddleware)` MUST
+ * appear BEFORE `.use(autoAuthMiddleware)` so that auth failures still log
+ * with the correlation ID attached.
+ *
+ * Usage:
+ *
+ *   const os = implement(myContract)
+ *     .$context<RpcContext>()
+ *     .use(correlationMiddleware)
+ *     .use(autoAuthMiddleware);
+ */
+export const correlationMiddleware = os.middleware(
+  async ({ next, context }) => {
+    const incoming = context.requestHeaders?.get(CORRELATION_ID_HEADER);
+    const correlationId =
+      incoming && incoming.length > 0 ? incoming : crypto.randomUUID();
+
+    context.responseHeaders?.set(CORRELATION_ID_HEADER, correlationId);
+
+    const meta: Record<string, unknown> = {
+      correlationId,
+      pluginId: context.pluginMetadata.pluginId,
+    };
+    if (context.user && "id" in context.user) {
+      meta.userId = context.user.id;
+    }
+
+    // `child` is optional on the Logger interface so minimal test-mock
+    // loggers don't have to implement it. Production Winston loggers
+    // always do; gracefully fall back to the base logger otherwise so
+    // the middleware never breaks a request just because metadata
+    // binding wasn't possible.
+    const boundLogger = context.logger.child
+      ? context.logger.child(meta)
+      : context.logger;
+
+    // Partial-merge style (no `...context` spread): oRPC merges the
+    // returned context fields onto the existing context. Spreading
+    // would widen TypeScript's inferred chain type and surface
+    // TS2883 "inferred type cannot be named" errors in downstream
+    // packages whose routers compose this middleware.
+    return next({
+      context: {
+        logger: boundLogger,
+      },
+    });
+  },
+);
+
 /**
  * Extract a nested value from an object using dot notation.
  * E.g., getNestedValue({ params: { id: "123" } }, "params.id") => "123"

package/src/test-utils.ts

@@ -1,5 +1,6 @@
 import { mock } from "bun:test";
 import { RpcContext, EmitHookFn } from "./rpc";
+import { Logger } from "./types";
 import { SafeDatabase } from "./plugin-system";
 import { HealthCheckRegistry } from "./health-check";
 import { CollectorRegistry } from "./collector-registry";
@@ -9,6 +10,22 @@ import {
   CacheManager,
 } from "@checkstack/cache-api";
 
+/**
+ * Build a mock `Logger` whose `.child(...)` returns another mock logger
+ * (recursively). Matches the structural contract that
+ * `correlationMiddleware` and other binding sites rely on.
+ */
+function createMockLogger(): Logger {
+  const logger: Logger = {
+    info: mock(),
+    error: mock(),
+    warn: mock(),
+    debug: mock(),
+    child: mock(() => createMockLogger()),
+  };
+  return logger;
+}
+
 /**
  * Creates a mocked oRPC context for testing.
  * By default provides an authenticated user with wildcard access.
@@ -19,12 +36,7 @@ export function createMockRpcContext(
   return {
     pluginMetadata: { pluginId: "test-plugin" },
     db: mock() as unknown as SafeDatabase<Record<string, unknown>>,
-    logger: {
-      info: mock(),
-      error: mock(),
-      warn: mock(),
-      debug: mock(),
-    },
+    logger: createMockLogger(),
     fetch: {
       fetch: mock(),
       forPlugin: mock().mockReturnValue({

package/src/types.ts

@@ -1,11 +1,45 @@
 import { ZodSchema } from "zod";
 import { ClientDefinition, InferClient } from "@checkstack/common";
 
+/**
+ * Backend logger interface used everywhere in the platform via `RpcContext.logger`
+ * and the various `coreServices.logger` accessors.
+ *
+ * Each method accepts a free-form trailing argument list (`...args: unknown[]`)
+ * so the long-standing varargs callsites — `logger.error("…", err)` where `err`
+ * is an `Error`, or `logger.info("…", value1, value2)` — keep working unchanged.
+ *
+ * For NEW code, prefer the structured-metadata shape:
+ *
+ *   logger.info("did something", { userId, durationMs });
+ *
+ * Winston's `splat` handling treats a single trailing plain object as
+ * structured metadata (merged into the log entry), and an `Error` instance as
+ * a special-cased error (with stack). Either shape lands in the same vararg
+ * slot here, so this signature covers both without overload churn.
+ *
+ * Auto-injected metadata (when the request flows through
+ * `correlationMiddleware`): `{ correlationId, pluginId, userId? }`. Do NOT
+ * include secrets in the structured-metadata object — it is forwarded
+ * verbatim to the log destination.
+ */
 export interface Logger {
   info(message: string, ...args: unknown[]): void;
   error(message: string, ...args: unknown[]): void;
   warn(message: string, ...args: unknown[]): void;
   debug(message: string, ...args: unknown[]): void;
+  /**
+   * Returns a derived logger with the supplied metadata bound to every
+   * subsequent log entry. Used by `correlationMiddleware` to attach
+   * `{ correlationId, pluginId, userId? }`, and available to handlers that
+   * want a tighter scope (e.g. `ctx.logger.child({ jobId })`).
+   *
+   * Optional only to keep minimal test-mock logger objects compatible with
+   * this interface — production loggers (Winston via `core/backend`) always
+   * implement it. Call sites that rely on metadata binding should branch
+   * on presence and fall back to the base logger when it is not available.
+   */
+  child?(meta: Record<string, unknown>): Logger;
 }
 
 export interface Fetch {