@somewhatintelligent/kit 0.0.1-beta.1783705886.297c5be

package/src/log/__tests__/instrumented.test.ts

@@ -0,0 +1,319 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { requireRequestLog } from "../index";
+import { instrumented, logged } from "../instrumented";
+
+interface FakeMeta {
+  requestId: string;
+  actor: { kind: "user" | "service" | "anonymous"; userId?: string; serviceName?: string };
+  callerApp?: string;
+}
+
+function actorId(actor: FakeMeta["actor"]): string | null {
+  if (actor.kind === "user") return actor.userId ?? null;
+  if (actor.kind === "service") return actor.serviceName ?? null;
+  return null;
+}
+
+const baseMeta: FakeMeta = {
+  requestId: "req_01",
+  actor: { kind: "user", userId: "user_01" },
+  callerApp: "test_caller",
+};
+
+let logSpy: ReturnType<typeof vi.spyOn>;
+let errorSpy: ReturnType<typeof vi.spyOn>;
+
+beforeEach(() => {
+  logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+  errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+});
+
+afterEach(() => {
+  logSpy.mockRestore();
+  errorSpy.mockRestore();
+});
+
+function makeConfig() {
+  return {
+    service: "fake_service",
+    resolveContext: ({ args }: { methodName: string; args: unknown[]; instance: unknown }) => {
+      const meta = args[1] as FakeMeta;
+      return {
+        requestId: meta.requestId,
+        actorKind: meta.actor.kind,
+        actorId: actorId(meta.actor),
+        callerApp: meta.callerApp,
+      };
+    },
+    deriveOutcome: (ret: unknown) => {
+      const r = ret as { ok: boolean; error?: string };
+      return r.ok ? "ok" : r.error;
+    },
+  };
+}
+
+describe("@instrumented class decorator", () => {
+  test("wraps every async method on the prototype", async () => {
+    @instrumented(makeConfig())
+    class Service {
+      async doThing(input: { id: string }, _meta: FakeMeta) {
+        return { ok: true, value: input.id };
+      }
+      async otherThing(_input: object, _meta: FakeMeta) {
+        return { ok: true, value: "other" };
+      }
+    }
+
+    const svc = new Service();
+    await svc.doThing({ id: "x" }, baseMeta);
+    await svc.otherThing({}, baseMeta);
+
+    expect(logSpy).toHaveBeenCalledTimes(2);
+    expect(logSpy.mock.calls[0]![0]).toMatchObject({
+      service: "fake_service",
+      event: "rpc",
+      operation: "fake_service.doThing",
+      outcome: "ok",
+      request_id: "req_01",
+      actor_kind: "user",
+      actor_id: "user_01",
+      caller_app: "test_caller",
+    });
+    expect(logSpy.mock.calls[1]![0]).toMatchObject({
+      operation: "fake_service.otherThing",
+    });
+  });
+
+  test("derives outcome from return value via deriveOutcome", async () => {
+    @instrumented(makeConfig())
+    class Service {
+      async failing(_i: object, _m: FakeMeta) {
+        return { ok: false, error: "not_found" };
+      }
+    }
+
+    await new Service().failing({}, baseMeta);
+    expect(logSpy).toHaveBeenCalledTimes(1);
+    expect(logSpy.mock.calls[0]![0]).toMatchObject({ outcome: "not_found" });
+  });
+
+  test("emits internal_error + rethrows on throw", async () => {
+    @instrumented(makeConfig())
+    class Service {
+      async kaboom(_i: object, _m: FakeMeta): Promise<{ ok: boolean }> {
+        throw new Error("boom");
+      }
+    }
+
+    await expect(new Service().kaboom({}, baseMeta)).rejects.toThrow("boom");
+    expect(errorSpy).toHaveBeenCalledTimes(1);
+    expect(errorSpy.mock.calls[0]![0]).toMatchObject({
+      outcome: "internal_error",
+      error_message: "boom",
+      operation: "fake_service.kaboom",
+    });
+  });
+
+  test("ALS scope is open inside method body — requireRequestLog().add works", async () => {
+    @instrumented(makeConfig())
+    class Service {
+      async doThing(input: { id: string }, _meta: FakeMeta) {
+        requireRequestLog().add({ resource_id: input.id, custom: "field" });
+        return { ok: true };
+      }
+    }
+
+    await new Service().doThing({ id: "res_01" }, baseMeta);
+    expect(logSpy.mock.calls[0]![0]).toMatchObject({
+      resource_id: "res_01",
+      custom: "field",
+    });
+  });
+
+  test("@logged.skip excludes method from instrumentation", async () => {
+    @instrumented(makeConfig())
+    class Service {
+      async tracked(_i: object, _m: FakeMeta) {
+        return { ok: true };
+      }
+
+      // oxlint-disable-next-line typescript/unbound-method -- decorator reference, not a call
+      @logged.skip
+      async healthCheck() {
+        return { status: "healthy" };
+      }
+    }
+
+    const svc = new Service();
+    await svc.tracked({}, baseMeta);
+    await svc.healthCheck();
+
+    // Only the tracked() call emits.
+    expect(logSpy).toHaveBeenCalledTimes(1);
+    expect(logSpy.mock.calls[0]![0]).toMatchObject({ operation: "fake_service.tracked" });
+  });
+
+  test("operation override via resolveContext is respected", async () => {
+    @instrumented({
+      service: "fake_service",
+      resolveContext: ({ methodName, args }) => {
+        const meta = args[1] as FakeMeta;
+        return {
+          operation: `custom.${methodName}.override`,
+          requestId: meta.requestId,
+          actorKind: meta.actor.kind,
+          actorId: actorId(meta.actor),
+          callerApp: meta.callerApp,
+        };
+      },
+    })
+    class Service {
+      async someOp(_i: object, _m: FakeMeta) {
+        return { ok: true };
+      }
+    }
+
+    await new Service().someOp({}, baseMeta);
+    expect(logSpy.mock.calls[0]![0]).toMatchObject({
+      operation: "custom.someOp.override",
+    });
+  });
+
+  test("preserves return value through wrapper", async () => {
+    @instrumented(makeConfig())
+    class Service {
+      async doThing(_i: object, _m: FakeMeta) {
+        return { ok: true, value: 42 };
+      }
+    }
+
+    const result = await new Service().doThing({}, baseMeta);
+    expect(result).toEqual({ ok: true, value: 42 });
+  });
+
+  test("works on classes that extend a base class (own-method only)", async () => {
+    class Base {
+      async baseMethod() {
+        return { ok: true };
+      }
+    }
+
+    @instrumented(makeConfig())
+    class Derived extends Base {
+      async ownMethod(_i: object, _m: FakeMeta) {
+        return { ok: true, value: "own" };
+      }
+    }
+
+    const d = new Derived();
+    await d.ownMethod({}, baseMeta);
+    await d.baseMethod();
+
+    // Only ownMethod is wrapped; Base.baseMethod is on Base.prototype, not Derived.prototype.
+    expect(logSpy).toHaveBeenCalledTimes(1);
+    expect(logSpy.mock.calls[0]![0]).toMatchObject({ operation: "fake_service.ownMethod" });
+  });
+
+  test("multiple instances share wrapped prototype methods", async () => {
+    @instrumented(makeConfig())
+    class Service {
+      async doThing(_i: object, _m: FakeMeta) {
+        return { ok: true };
+      }
+    }
+
+    const a = new Service();
+    const b = new Service();
+    await a.doThing({}, baseMeta);
+    await b.doThing({}, baseMeta);
+    expect(logSpy).toHaveBeenCalledTimes(2);
+  });
+
+  test("onError converts throws to a returned value (Result-style APIs)", async () => {
+    @instrumented({
+      ...makeConfig(),
+      onError: (e: unknown) => ({
+        ok: false,
+        error: "internal_error",
+        message: e instanceof Error ? e.message : String(e),
+      }),
+    })
+    class Service {
+      async kaboom(_i: object, _m: FakeMeta): Promise<{ ok: boolean }> {
+        throw new Error("boom");
+      }
+    }
+
+    const result = await new Service().kaboom({}, baseMeta);
+    // Throw was converted, NOT propagated.
+    expect(result).toEqual({ ok: false, error: "internal_error", message: "boom" });
+    // Line still emitted at error level with internal_error outcome.
+    expect(errorSpy).toHaveBeenCalledTimes(1);
+    expect(errorSpy.mock.calls[0]![0]).toMatchObject({
+      outcome: "internal_error",
+      error_message: "boom",
+    });
+  });
+
+  test("onError unset → throws still propagate (default behavior preserved)", async () => {
+    @instrumented(makeConfig())
+    class Service {
+      async kaboom(_i: object, _m: FakeMeta): Promise<{ ok: boolean }> {
+        throw new Error("rethrown");
+      }
+    }
+    await expect(new Service().kaboom({}, baseMeta)).rejects.toThrow("rethrown");
+  });
+
+  // A resolveContext failure runs BEFORE the main scope opens. It must NOT slip
+  // the net as a silent `outcome:exception` with empty logs (the roadie
+  // caller_app-misconfig hole) — it has to emit an actionable canonical line.
+  test("resolveContext throw emits a canonical error line + honors onError", async () => {
+    @instrumented({
+      service: "fake_service",
+      resolveContext: () => {
+        throw new Error("ROADIE binding missing props.callerApp");
+      },
+      onError: (e: unknown) => ({
+        ok: false,
+        error: "internal_error",
+        message: e instanceof Error ? e.message : String(e),
+      }),
+    })
+    class Service {
+      async doThing(_i: object, _m: FakeMeta): Promise<{ ok: boolean }> {
+        return { ok: true };
+      }
+    }
+
+    const result = await new Service().doThing({}, baseMeta);
+    // Converted via onError, not a raw throw.
+    expect(result).toMatchObject({ ok: false, error: "internal_error" });
+    // ...and the failure is LOGGED with a phase marker + message, not silent.
+    expect(errorSpy).toHaveBeenCalledTimes(1);
+    expect(errorSpy.mock.calls[0]![0]).toMatchObject({
+      service: "fake_service",
+      operation: "fake_service.doThing",
+      outcome: "internal_error",
+      error_phase: "resolve_context",
+      error_message: "ROADIE binding missing props.callerApp",
+    });
+  });
+
+  test("resolveContext throw with no onError still emits a line, then rethrows", async () => {
+    @instrumented({
+      service: "fake_service",
+      resolveContext: () => {
+        throw new Error("no ctx");
+      },
+    })
+    class Service {
+      async doThing(_i: object, _m: FakeMeta): Promise<{ ok: boolean }> {
+        return { ok: true };
+      }
+    }
+    await expect(new Service().doThing({}, baseMeta)).rejects.toThrow("no ctx");
+    expect(errorSpy).toHaveBeenCalledTimes(1);
+    expect(errorSpy.mock.calls[0]![0]).toMatchObject({ error_phase: "resolve_context" });
+  });
+});

package/src/log/__tests__/scheduled.test.ts

@@ -0,0 +1,107 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { requireRequestLog } from "../index";
+import { loggedJob } from "../scheduled";
+
+let logSpy: ReturnType<typeof vi.spyOn>;
+let errorSpy: ReturnType<typeof vi.spyOn>;
+
+beforeEach(() => {
+  logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+  errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+});
+
+afterEach(() => {
+  logSpy.mockRestore();
+  errorSpy.mockRestore();
+});
+
+describe("loggedJob", () => {
+  test("emits event=job with synthesized requestId + service actor", async () => {
+    const job = loggedJob({ service: "roadie", operation: "roadie.job.reap" }, async () => ({
+      reaped: 7,
+    }));
+
+    const result = await job();
+    expect(result).toEqual({ reaped: 7 });
+    expect(logSpy).toHaveBeenCalledTimes(1);
+    const line = logSpy.mock.calls[0]![0] as Record<string, unknown>;
+    expect(line).toMatchObject({
+      service: "roadie",
+      event: "job",
+      operation: "roadie.job.reap",
+      outcome: "ok",
+      actor_kind: "service",
+      actor_id: "roadie",
+    });
+    // Default requestId is crypto.randomUUID — non-empty string.
+    expect(typeof line.request_id).toBe("string");
+    expect((line.request_id as string).length).toBeGreaterThan(8);
+  });
+
+  test("generateRequestId override is used", async () => {
+    let count = 0;
+    const job = loggedJob(
+      {
+        service: "roadie",
+        operation: "roadie.job.x",
+        generateRequestId: () => `custom_${++count}`,
+      },
+      async () => ({ ok: true }),
+    );
+
+    await job();
+    await job();
+    expect(logSpy.mock.calls[0]![0]).toMatchObject({ request_id: "custom_1" });
+    expect(logSpy.mock.calls[1]![0]).toMatchObject({ request_id: "custom_2" });
+  });
+
+  test("requireRequestLog().add inside handler captures domain fields", async () => {
+    const job = loggedJob({ service: "roadie", operation: "roadie.job.reap" }, async () => {
+      requireRequestLog().add({ reaped_count: 12, swept_grants: ["g1", "g2"] });
+    });
+
+    await job();
+    expect(logSpy.mock.calls[0]![0]).toMatchObject({
+      reaped_count: 12,
+      swept_grants: ["g1", "g2"],
+    });
+  });
+
+  test("throw → internal_error at error level + rethrow", async () => {
+    const job = loggedJob({ service: "roadie", operation: "roadie.job.fail" }, async () => {
+      throw new Error("scheduled task crashed");
+    });
+
+    await expect(job()).rejects.toThrow("scheduled task crashed");
+    expect(errorSpy.mock.calls[0]![0]).toMatchObject({
+      outcome: "internal_error",
+      error_message: "scheduled task crashed",
+    });
+  });
+
+  test("passes args through to handler", async () => {
+    const job = loggedJob(
+      { service: "roadie", operation: "roadie.job.passthrough" },
+      async (a: number, b: string) => ({ a, b }),
+    );
+
+    const result = await job(7, "hello");
+    expect(result).toEqual({ a: 7, b: "hello" });
+  });
+
+  test("resolveContext extra fields land on line", async () => {
+    const job = loggedJob(
+      {
+        service: "roadie",
+        operation: "roadie.job.with_caller",
+        resolveContext: () => ({ callerApp: "roadie" }),
+      },
+      async () => undefined,
+    );
+
+    await job();
+    expect(logSpy.mock.calls[0]![0]).toMatchObject({
+      caller_app: "roadie",
+    });
+  });
+});

package/src/log/core.ts

@@ -0,0 +1,230 @@
+/**
+ * Canonical log line — one structured JSON line per logical operation.
+ *
+ * The platform's single log shape, used at every boundary: HTTP edges,
+ * service-binding RPC methods, TanStack server-fns, scheduled jobs, and
+ * Better Auth events. Every line carries `{service, event, operation,
+ * outcome, duration_ms, request_id, caller_app, actor_kind, actor_id,
+ * time}` plus per-op domain fields. `request_id` is NEVER minted here —
+ * it always comes from the caller (`cf-request-id` adopted at the entry
+ * Worker, propagated unchanged through every layer).
+ *
+ * Field accrual is propagated via `AsyncLocalStorage` — handlers anywhere
+ * in the async call stack call `getRequestLog()` (or `requireRequestLog()`)
+ * to add domain fields without explicit parameter threading. This is what
+ * makes boundary instrumentation work: framework-level wrappers open the
+ * scope, handler code is plain.
+ *
+ * Logging is intentionally decoupled from `Result<T, E>` envelopes.
+ * Outcome is set explicitly via `log.outcome(code)`; the primitive
+ * defaults to `"ok"` on normal return and `"internal_error"` on throw.
+ * Callers that use Result envelopes wrap this primitive in their own
+ * thin adapter that derives outcome from the result discriminant.
+ *
+ * Sub-modules (`./http`, `./instrumented`, `./scheduled`, `./server-fn`)
+ * import the primitives from this file rather than `./index` so the barrel
+ * stays acyclic.
+ */
+/// <reference types="node" />
+// Namespace import — see kit/request-context for the same rationale. Vite
+// externalizes `node:async_hooks` in the client environment to a Proxy
+// that throws on any property access. A named `{ AsyncLocalStorage }`
+// destructure becomes a module-init `stub["AsyncLocalStorage"]` access in
+// Vite's dev transform and crashes the browser. The namespace binding is
+// inert until `logStorage()` is invoked server-side.
+import * as nodeAsyncHooks from "node:async_hooks";
+import type { AsyncLocalStorage as ALS } from "node:async_hooks";
+import { getActorId, getActorKind, getCallerApp, getRequestId } from "../request-context";
+
+export type Level = "info" | "warn" | "error";
+
+export interface CanonicalLogBuilder {
+  /** Merge fields into the line. Last write wins. Forbidden keys are stripped at emit time. */
+  add(fields: Record<string, unknown>): void;
+  /** Set the outcome code. Defaults to `"ok"` on normal return. Overridden to `"internal_error"` on throw. */
+  outcome(code: string): void;
+}
+
+export interface CanonicalLogContext {
+  /** Component emitting the line — `"roadie"`, `"guestlist"`, `"identity"`, etc. */
+  service: string;
+  /** Event kind — `"rpc" | "http" | "server_fn" | "job" | "auth"`. Free-form to allow new categories. */
+  event: string;
+  /** Abstract operation name — `"roadie.signPart"`, `"identity.server_fn.submit_attempt"`. */
+  operation: string;
+  /**
+   * Request ID. Optional — when omitted, read from the active
+   * `withRequestContext` ALS scope at emit time. Pass explicitly only
+   * when no ALS scope is open (e.g. RPC paths where `meta.requestId` is
+   * authoritative).
+   */
+  requestId?: string;
+  /** Actor identity kind. Optional — read from ALS at emit time when omitted. */
+  actorKind?: string;
+  /** Actor identifier. Optional — read from ALS at emit time when omitted. */
+  actorId?: string | null;
+  /** For RPC events: which app/service called this method. Optional — read from ALS at emit time when omitted. */
+  callerApp?: string;
+  /** Outcome codes that should emit at error level. Defaults: `{"backend_unavailable", "internal_error"}`. */
+  errorOutcomes?: ReadonlySet<string>;
+  /** Field names that must never be emitted. Defaults to a security-baseline set. */
+  forbiddenFields?: ReadonlySet<string>;
+  /** Field-name prefixes whose matches must never be emitted. Defaults: `["R2_", "S3_"]`. */
+  forbiddenPrefixes?: readonly string[];
+}
+
+const DEFAULT_ERROR_OUTCOMES: ReadonlySet<string> = new Set([
+  "backend_unavailable",
+  "internal_error",
+]);
+
+const DEFAULT_FORBIDDEN_FIELDS: ReadonlySet<string> = new Set([
+  "url",
+  "uploadUrl",
+  "body",
+  "requiredHeaders",
+  "permissionScope",
+  "password",
+  "secret",
+  "authorization",
+  "cookie",
+  "S3_ACCESS_KEY_ID",
+  "S3_SECRET_ACCESS_KEY",
+]);
+
+const DEFAULT_FORBIDDEN_PREFIXES: readonly string[] = ["R2_", "S3_"];
+
+let _logStorage: ALS<CanonicalLogBuilder> | undefined;
+function logStorage(): ALS<CanonicalLogBuilder> {
+  return (_logStorage ??= new nodeAsyncHooks.AsyncLocalStorage<CanonicalLogBuilder>());
+}
+
+/**
+ * Read the current canonical log builder from the surrounding async context.
+ * Returns `null` if no `withCanonicalLog` scope is active. Use inside handlers
+ * to accrue domain fields from anywhere in the call stack.
+ */
+export function getRequestLog(): CanonicalLogBuilder | null {
+  return logStorage().getStore() ?? null;
+}
+
+/**
+ * Like `getRequestLog()` but throws if no scope is active. Use when the
+ * call site must be inside a logged boundary (server-fn handler, RPC
+ * method, instrumented job) — failing loudly beats silently dropping
+ * domain fields.
+ */
+export function requireRequestLog(): CanonicalLogBuilder {
+  const log = logStorage().getStore();
+  if (!log) {
+    throw new Error(
+      "requireRequestLog() called outside any withCanonicalLog scope — " +
+        "this code path is not running inside an instrumented boundary",
+    );
+  }
+  return log;
+}
+
+// Removes forbidden fields (per the security baseline) AND `undefined`
+// values. `undefined` would JSON-stringify away in production but pollutes
+// `console.log(line)` output during dev (e.g. `caller_app: undefined` on a
+// leaf service's own events). `null` is preserved — it's a meaningful
+// signal (`actor_id: null` for anonymous, etc.).
+function stripLine(
+  line: Record<string, unknown>,
+  fields: ReadonlySet<string>,
+  prefixes: readonly string[],
+): Record<string, unknown> {
+  for (const key of Object.keys(line)) {
+    if (line[key] === undefined || fields.has(key) || prefixes.some((p) => key.startsWith(p))) {
+      delete line[key];
+    }
+  }
+  return line;
+}
+
+/**
+ * Serialize a thrown value into log-safe `message`/`stack` strings.
+ * `String(x)` on a non-Error object yields `[object Object]` /
+ * `[object Response]` — useless in a canonical line. Thrown `Response`s
+ * (TanStack `redirect()` et al) are named by status; other non-Error
+ * objects are JSON-encoded (truncated) so the line stays actionable.
+ */
+export function describeThrown(e: unknown): { message: string; stack?: string } {
+  if (e instanceof Error) return { message: e.message, stack: e.stack };
+  if (e instanceof Response) return { message: `thrown Response (status ${e.status})` };
+  if (typeof e === "object" && e !== null) {
+    try {
+      return { message: JSON.stringify(e).slice(0, 500) };
+    } catch {
+      return { message: "[unserializable object]" };
+    }
+  }
+  return { message: String(e) };
+}
+
+export async function withCanonicalLog<T>(
+  ctx: CanonicalLogContext,
+  fn: (log: CanonicalLogBuilder) => Promise<T>,
+): Promise<T> {
+  const errorOutcomes = ctx.errorOutcomes ?? DEFAULT_ERROR_OUTCOMES;
+  const forbiddenFields = ctx.forbiddenFields ?? DEFAULT_FORBIDDEN_FIELDS;
+  const forbiddenPrefixes = ctx.forbiddenPrefixes ?? DEFAULT_FORBIDDEN_PREFIXES;
+
+  const start = Date.now();
+  const fields: Record<string, unknown> = {};
+  let outcome = "ok";
+
+  const builder: CanonicalLogBuilder = {
+    add(extra) {
+      Object.assign(fields, extra);
+    },
+    outcome(code) {
+      outcome = code;
+    },
+  };
+
+  const emit = (finalOutcome: string, level: Level) => {
+    // Read correlation fields at EMIT time, not scope-open time. This lets
+    // boundary middleware open a scope with just `{ requestId }` early, then
+    // patch in actor/caller info as handlers resolve them. By the time emit
+    // runs (handler done, scope closing), the ALS reflects the final state.
+    // Explicit ctx values still win — RPC paths pass meta.requestId directly.
+    const line = stripLine(
+      {
+        service: ctx.service,
+        event: ctx.event,
+        operation: ctx.operation,
+        outcome: finalOutcome,
+        request_id: ctx.requestId ?? getRequestId() ?? undefined,
+        caller_app: ctx.callerApp ?? getCallerApp() ?? undefined,
+        actor_kind: ctx.actorKind ?? getActorKind() ?? undefined,
+        actor_id: ctx.actorId ?? getActorId() ?? null,
+        duration_ms: Date.now() - start,
+        time: new Date().toISOString(),
+        ...fields,
+      },
+      forbiddenFields,
+      forbiddenPrefixes,
+    );
+    if (level === "error") console.error(line);
+    else if (level === "warn") console.warn(line);
+    else console.log(line);
+  };
+
+  return logStorage().run(builder, async () => {
+    try {
+      const result = await fn(builder);
+      emit(outcome, errorOutcomes.has(outcome) ? "error" : "info");
+      return result;
+    } catch (e) {
+      // Always attach a traceback so an internal_error line is actionable — a
+      // canonical line that says "something threw" with no stack is the gap we
+      // are closing. Falls back to the serialized value for non-Error throws.
+      const { message, stack } = describeThrown(e);
+      builder.add({ error_message: message, error_stack: stack ?? message });
+      emit("internal_error", "error");
+      throw e;
+    }
+  });
+}