@beignet/core 0.0.3 → 0.0.5

package/src/server/request-context.ts

@@ -0,0 +1,116 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { ActivityActor, ActivityTenant } from "../ports/audit.js";
+
+/**
+ * Ambient correlation values for the request currently being handled.
+ *
+ * The server enters this context before user hooks run so instrumentation
+ * sinks can correlate events recorded anywhere in the request lifecycle.
+ * Identity values (`actor`, `tenant`) are refreshed by the server whenever
+ * hooks finalize a new context, so wrappers such as `createAmbientAuditLog`
+ * observe the elevated identity at record time.
+ */
+export interface ActiveRequestContext {
+  requestId?: string;
+  traceId?: string;
+  spanId?: string;
+  parentSpanId?: string;
+  traceparent?: string;
+  /**
+   * Actor for the current request or service execution, when known.
+   */
+  actor?: ActivityActor;
+  /**
+   * Tenant scope for the current request or service execution, when known.
+   */
+  tenant?: ActivityTenant;
+}
+
+const activeRequestContext = new AsyncLocalStorage<
+  ActiveRequestContext | undefined
+>();
+
+/**
+ * Enter the ambient request context for the current async execution.
+ */
+export function enterActiveRequestContext(context: ActiveRequestContext): void {
+  activeRequestContext.enterWith(context);
+}
+
+/**
+ * Clear the ambient request context for the current async execution.
+ */
+export function clearActiveRequestContext(): void {
+  activeRequestContext.enterWith(undefined);
+}
+
+/**
+ * Read the ambient request context, when one is active.
+ */
+export function getActiveRequestContext(): ActiveRequestContext | undefined {
+  return activeRequestContext.getStore();
+}
+
+/**
+ * Read a normalized actor from an app context object, when present.
+ */
+export function readContextActor(ctx: unknown): ActivityActor | undefined {
+  if (!ctx || typeof ctx !== "object") return undefined;
+  const actor = (ctx as { actor?: unknown }).actor;
+  if (!actor || typeof actor !== "object") return undefined;
+  return typeof (actor as { type?: unknown }).type === "string"
+    ? (actor as ActivityActor)
+    : undefined;
+}
+
+/**
+ * Read a normalized tenant from an app context object, when present.
+ */
+export function readContextTenant(ctx: unknown): ActivityTenant | undefined {
+  if (!ctx || typeof ctx !== "object") return undefined;
+  const tenant = (ctx as { tenant?: unknown }).tenant;
+  if (!tenant || typeof tenant !== "object") return undefined;
+  return typeof (tenant as { id?: unknown }).id === "string"
+    ? (tenant as ActivityTenant)
+    : undefined;
+}
+
+/**
+ * Update identity fields on the active ambient request context in place.
+ *
+ * The server calls this after hooks finalize a new request context so the
+ * elevated actor/tenant become visible to ambient consumers, including async
+ * frames that captured the context object before the update. No-op when no
+ * ambient context is active.
+ */
+export function setActiveRequestIdentity(identity: {
+  actor?: ActivityActor;
+  tenant?: ActivityTenant;
+}): void {
+  const context = activeRequestContext.getStore();
+  if (!context) return;
+  if (identity.actor) context.actor = identity.actor;
+  if (identity.tenant) context.tenant = identity.tenant;
+}
+
+/**
+ * Fill missing correlation fields on an event from the ambient request
+ * context.
+ */
+export function inheritActiveRequestContext<
+  Event extends {
+    requestId?: string;
+    traceId?: string;
+    traceparent?: string;
+  },
+>(event: Event): Event {
+  const context = getActiveRequestContext();
+  if (!context) return event;
+
+  return {
+    ...event,
+    requestId: event.requestId ?? context.requestId,
+    traceId: event.traceId ?? context.traceId,
+    traceparent: event.traceparent ?? context.traceparent,
+  };
+}

package/src/server/server-context.ts

@@ -0,0 +1,44 @@
+import type { AnyPorts } from "../ports/index.js";
+import type { ServerContextConfig } from "./context.js";
+
+/**
+ * Declare a server context blueprint once and share it between the runtime
+ * server and tests.
+ *
+ * The helper preserves the blueprint exactly as written — `request`,
+ * `service`, and `gate` keep their inferred types — so apps can keep the
+ * blueprint in a canonical `server/context.ts` file and pass the same value to
+ * `createServer(...)` (through an adapter such as `createNextServer` or
+ * `createFetchServer`) and to `createTestApp(...)`.
+ *
+ * @example
+ * ```ts
+ * // server/context.ts
+ * export const appContext = defineServerContext<AppContext, AppPorts>()({
+ *   gate: (ports) => ports.gate,
+ *   request: async ({ req, ports, requestId, trace }) => ({
+ *     actor: await resolveActor(req),
+ *     auth: null,
+ *     requestId,
+ *     ...trace,
+ *     ports,
+ *   }),
+ *   service: ({ ports, requestId, trace }) => ({
+ *     actor: createServiceActor("app-service"),
+ *     auth: null,
+ *     requestId,
+ *     ...trace,
+ *     ports,
+ *   }),
+ * });
+ * ```
+ *
+ * @returns A function that collects and returns the typed context blueprint.
+ */
+export function defineServerContext<Ctx, Ports extends AnyPorts = AnyPorts>(): <
+  ServiceInput = void,
+>(
+  blueprint: ServerContextConfig<Ctx, Ports, ServiceInput>,
+) => ServerContextConfig<Ctx, Ports, ServiceInput> {
+  return (blueprint) => blueprint;
+}