@beignet/devtools 0.0.1

package/src/index.ts

@@ -0,0 +1,136 @@
+/**
+ * @beignet/devtools
+ *
+ * Development-time devtools for the Beignet server.
+ * Provides an in-memory event buffer and HTTP handlers to expose
+ * framework activity (requests, use cases, errors, events, jobs, schedules, providers).
+ *
+ * This package is intended for development and debugging only.
+ * It should not be used in production environments.
+ *
+ * @example
+ * ```ts
+ * import { createDevtoolsProvider } from "@beignet/devtools";
+ * import { createServer } from "@beignet/core/server";
+ *
+ * const server = await createServer({
+ *   ports,
+ *   providers: [createDevtoolsProvider(), ...otherProviders],
+ * });
+ *
+ * // In your code, log events:
+ * ctx.ports.devtools?.log({
+ *   id: crypto.randomUUID(),
+ *   type: "request",
+ *   timestamp: new Date().toISOString(),
+ *   method: "GET",
+ *   path: "/api/users",
+ * });
+ * ```
+ */
+
+import type { ProviderInstrumentationPort } from "@beignet/core/providers";
+import type {
+  DevtoolsEvent,
+  DevtoolsEventInput,
+  DevtoolsListener,
+} from "./events";
+import type { DevtoolsWatcher, DevtoolsWatcherName } from "./watchers";
+
+/**
+ * Filter options for querying devtools events.
+ */
+export interface DevtoolsFilter {
+  /**
+   * Filter by event type.
+   */
+  type?: DevtoolsEvent["type"];
+
+  /**
+   * Filter by request correlation ID.
+   */
+  requestId?: string;
+
+  /**
+   * Filter by W3C trace ID.
+   */
+  traceId?: string;
+
+  /**
+   * Limit the number of results returned (default: 200).
+   */
+  limit?: number;
+}
+
+/**
+ * Port interface for devtools.
+ *
+ * Apps and server internals can log framework events here during development.
+ * The events are stored in an in-memory buffer and can be retrieved via HTTP handlers.
+ */
+export interface DevtoolsPort
+  extends ProviderInstrumentationPort<
+    DevtoolsEventInput,
+    DevtoolsWatcherName,
+    DevtoolsEvent
+  > {
+  /**
+   * Log a devtools event into the in-memory buffer.
+   *
+   * @param event - The event to log
+   */
+  log(event: DevtoolsEvent): void;
+
+  /**
+   * Record an event and fill common fields such as id and timestamp.
+   *
+   * @param event - The event payload to record
+   * @returns The normalized event that was stored
+   */
+  record(event: DevtoolsEventInput): DevtoolsEvent;
+
+  /**
+   * Subscribe to event buffer changes. Used by the live SSE endpoint.
+   *
+   * @param listener - Called when an event is recorded or the buffer is cleared
+   * @returns Cleanup function that removes the listener
+   */
+  subscribe(listener: DevtoolsListener): () => void;
+
+  /**
+   * Retrieve recent events with optional filtering.
+   *
+   * @param filter - Optional filter to apply (type, requestId, limit)
+   * @returns Array of matching events
+   */
+  getEvents(filter?: DevtoolsFilter): DevtoolsEvent[];
+
+  /**
+   * Clear all buffered events (dev-only).
+   */
+  clear(): void | Promise<void>;
+
+  /**
+   * Return the watcher configuration installed for this devtools instance.
+   */
+  getWatchers(): DevtoolsWatcher[];
+
+  /**
+   * Check whether a watcher is enabled.
+   */
+  isWatcherEnabled(name: DevtoolsWatcherName): boolean;
+}
+
+// Re-export everything
+export * from "./access";
+export * from "./audit";
+export * from "./events";
+export * from "./instrumentation";
+export * from "./persistence";
+export * from "./provider";
+export * from "./provider-instrumentation";
+export * from "./redaction";
+export * from "./routes";
+export * from "./trace-context";
+export * from "./ui";
+export * from "./watchers";

package/src/instrumentation.ts

@@ -0,0 +1,451 @@
+import type { AnyPorts } from "@beignet/core/ports";
+import type {
+  HttpContractConfig,
+  HttpRequestLike,
+  HttpResponseLike,
+  ServerHook,
+} from "@beignet/core/server";
+import type { DevtoolsEventInput, DevtoolsRedactor } from "./events";
+import type { DevtoolsPort } from "./index";
+import { createDevtoolsEvent } from "./provider";
+import {
+  createChildDevtoolsTraceContext,
+  createDevtoolsTraceContext,
+  type DevtoolsTraceContext,
+  type DevtoolsTraceContextInput,
+  parseTraceparent,
+} from "./trace-context";
+import type { BuiltInDevtoolsWatcherName } from "./watchers";
+
+type PortsWithDevtools = AnyPorts & {
+  devtools?: DevtoolsPort;
+};
+
+type ContextWithPorts = {
+  requestId?: string;
+  traceId?: string;
+  spanId?: string;
+  parentSpanId?: string;
+  traceparent?: string;
+  ports?: {
+    devtools?: DevtoolsPort;
+  };
+};
+
+export interface DevtoolsHooksOptions<Ctx> {
+  /**
+   * Devtools route prefix. Requests under this path are ignored to avoid
+   * filling the timeline with its own polling traffic.
+   *
+   * @default "/api/devtools"
+   */
+  basePath?: string;
+
+  getRequestId?: (args: {
+    req: HttpRequestLike;
+    ctx?: Ctx;
+    response?: HttpResponseLike;
+  }) => string | undefined;
+
+  /**
+   * Response header used to expose the resolved request ID.
+   *
+   * Pass `false` to avoid writing a header.
+   *
+   * @default "x-request-id"
+   */
+  requestIdHeader?: string | false;
+
+  /**
+   * W3C trace context header used to correlate devtools events with distributed
+   * traces.
+   *
+   * Pass `false` to avoid writing a header.
+   *
+   * @default "traceparent"
+   */
+  traceContextHeader?: string | false;
+
+  getTraceContext?: (args: {
+    req: HttpRequestLike;
+    ctx?: Ctx;
+    response?: HttpResponseLike;
+  }) => DevtoolsTraceContextInput | string | undefined;
+
+  /**
+   * Apply a custom redactor to events produced by these hooks. The default
+   * devtools redactor still runs when events are stored.
+   */
+  redact?: DevtoolsRedactor;
+
+  shouldCapture?: (args: {
+    req: HttpRequestLike;
+    ctx?: Ctx;
+    contract: HttpContractConfig;
+    response: HttpResponseLike;
+    error?: unknown;
+  }) => boolean;
+}
+
+export interface DevtoolsUseCaseRunEvent<Ctx> {
+  name: string;
+  kind: "command" | "query";
+  phase: "start" | "end" | "error";
+  durationMs?: number;
+  error?: unknown;
+  ctx: Ctx;
+}
+
+export interface DevtoolsUseCaseObserverOptions<Ctx> {
+  getDevtools?: (ctx: Ctx) => DevtoolsPort | undefined;
+  getRequestId?: (ctx: Ctx) => string | undefined;
+  logErrorEvents?: boolean;
+  redact?: DevtoolsRedactor;
+}
+
+function getContextRequestId(ctx: unknown): string | undefined {
+  if (!ctx || typeof ctx !== "object") return undefined;
+  const requestId = (ctx as { requestId?: unknown }).requestId;
+  return typeof requestId === "string" ? requestId : undefined;
+}
+
+function getContextDevtools(ctx: unknown): DevtoolsPort | undefined {
+  if (!ctx || typeof ctx !== "object") return undefined;
+  const ports = (ctx as ContextWithPorts).ports;
+  return ports?.devtools;
+}
+
+function getContextTraceContext(
+  ctx: unknown,
+): DevtoolsTraceContextInput | undefined {
+  if (!ctx || typeof ctx !== "object") return undefined;
+  const context = ctx as ContextWithPorts;
+  if (
+    !context.traceId &&
+    !context.spanId &&
+    !context.parentSpanId &&
+    !context.traceparent
+  ) {
+    return undefined;
+  }
+  return {
+    traceId: context.traceId,
+    spanId: context.spanId,
+    parentSpanId: context.parentSpanId,
+    traceparent: context.traceparent,
+  };
+}
+
+function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  if (typeof error === "string") return error;
+  return "Unknown error";
+}
+
+function getErrorStack(error: unknown): string | undefined {
+  return error instanceof Error ? error.stack : undefined;
+}
+
+function createRequestId(): string {
+  if (typeof crypto !== "undefined" && "randomUUID" in crypto) {
+    return crypto.randomUUID();
+  }
+  return `${Date.now()}-${Math.random().toString(16).slice(2)}`;
+}
+
+function getPathname(req: HttpRequestLike): string {
+  try {
+    return new URL(req.url).pathname;
+  } catch {
+    return req.url;
+  }
+}
+
+function isDevtoolsPath(pathname: string, basePath: string): boolean {
+  const normalizedBase = basePath.replace(/\/+$/, "");
+  return (
+    pathname === normalizedBase || pathname.startsWith(`${normalizedBase}/`)
+  );
+}
+
+function isWatcherEnabled(
+  devtools: DevtoolsPort,
+  name: BuiltInDevtoolsWatcherName,
+): boolean {
+  return devtools.isWatcherEnabled(name);
+}
+
+export function createDevtoolsHooks<
+  Ctx,
+  Ports extends PortsWithDevtools = PortsWithDevtools,
+>(options: DevtoolsHooksOptions<Ctx> = {}): ServerHook<Ctx, Ports> {
+  let devtools: DevtoolsPort | undefined;
+  const basePath = options.basePath ?? "/api/devtools";
+  const requestIdHeader = options.requestIdHeader ?? "x-request-id";
+  const traceContextHeader = options.traceContextHeader ?? "traceparent";
+  const generatedRequestIds = new WeakMap<HttpRequestLike, string>();
+  const traceContexts = new WeakMap<HttpRequestLike, DevtoolsTraceContext>();
+
+  const resolveRequestId = (args: {
+    req: HttpRequestLike;
+    ctx?: Ctx;
+    response?: HttpResponseLike;
+  }) => {
+    const headerRequestId =
+      requestIdHeader === false
+        ? undefined
+        : args.req.headers.get(requestIdHeader);
+    const existing =
+      options.getRequestId?.(args) ??
+      getContextRequestId(args.ctx) ??
+      headerRequestId ??
+      generatedRequestIds.get(args.req);
+
+    if (existing) return existing;
+
+    const requestId = createRequestId();
+    generatedRequestIds.set(args.req, requestId);
+    return requestId;
+  };
+
+  const resolveTraceContext = (args: {
+    req: HttpRequestLike;
+    ctx?: Ctx;
+    response?: HttpResponseLike;
+  }) => {
+    const configured = options.getTraceContext?.(args);
+    const configuredContext =
+      typeof configured === "string" ? { traceparent: configured } : configured;
+    const contextTrace = getContextTraceContext(args.ctx);
+    const headerTraceparent =
+      traceContextHeader === false
+        ? undefined
+        : args.req.headers.get(traceContextHeader);
+    const existing = configuredContext ?? contextTrace;
+    const existingTraceparent =
+      existing?.traceparent ?? parseTraceparent(headerTraceparent)?.traceparent;
+
+    if (existing) {
+      const traceContext = createDevtoolsTraceContext({
+        ...existing,
+        traceparent: existingTraceparent,
+      });
+      traceContexts.set(args.req, traceContext);
+      return traceContext;
+    }
+
+    const cached = traceContexts.get(args.req);
+    if (cached) return cached;
+
+    const traceContext = createDevtoolsTraceContext({
+      traceparent: existingTraceparent,
+    });
+    traceContexts.set(args.req, traceContext);
+    return traceContext;
+  };
+
+  const record = (event: DevtoolsEventInput) => {
+    if (!devtools) return;
+    const normalized = createDevtoolsEvent(event);
+    try {
+      devtools.record(options.redact ? options.redact(normalized) : normalized);
+    } catch (error) {
+      devtools.record({
+        type: "error",
+        message: "Devtools hook redactor failed",
+        details: {
+          message: error instanceof Error ? error.message : String(error),
+        },
+      });
+    }
+  };
+
+  return {
+    name: "devtools",
+    onRequest: ({ ports }) => {
+      devtools = ports.devtools;
+      return undefined;
+    },
+    beforeHandle: ({ req, ctx }) => {
+      if (!ctx || typeof ctx !== "object" || Array.isArray(ctx)) {
+        return undefined;
+      }
+
+      const traceContext = resolveTraceContext({ req, ctx });
+      return {
+        ctx: {
+          ...ctx,
+          traceId: traceContext.traceId,
+          spanId: traceContext.spanId,
+          parentSpanId: traceContext.parentSpanId,
+          traceparent: traceContext.traceparent,
+        } as Ctx,
+      };
+    },
+    beforeSend: async ({ req, ctx, response }) => {
+      if (requestIdHeader === false && traceContextHeader === false) {
+        return undefined;
+      }
+
+      const requestId = resolveRequestId({ req, ctx, response });
+      const traceContext = resolveTraceContext({ req, ctx, response });
+      const headers = {
+        ...response.headers,
+        ...(requestIdHeader === false ? {} : { [requestIdHeader]: requestId }),
+        ...(traceContextHeader === false
+          ? {}
+          : { [traceContextHeader]: traceContext.traceparent }),
+      };
+      return {
+        ...response,
+        headers,
+      };
+    },
+    afterSend: async ({ req, ctx, contract, response, error, durationMs }) => {
+      if (!devtools) return;
+
+      const path = getPathname(req);
+      if (isDevtoolsPath(path, basePath)) return;
+
+      const shouldCaptureRequest = isWatcherEnabled(devtools, "requests");
+      const shouldCaptureError =
+        Boolean(error) && isWatcherEnabled(devtools, "errors");
+
+      if (!shouldCaptureRequest && !shouldCaptureError) return;
+
+      if (
+        options.shouldCapture &&
+        !options.shouldCapture({ req, ctx, contract, response, error })
+      ) {
+        return;
+      }
+
+      const requestId = resolveRequestId({ req, ctx, response });
+      const traceContext = resolveTraceContext({ req, ctx, response });
+
+      if (shouldCaptureRequest) {
+        record({
+          type: "request",
+          requestId,
+          traceId: traceContext.traceId,
+          spanId: traceContext.spanId,
+          parentSpanId: traceContext.parentSpanId,
+          traceparent: traceContext.traceparent,
+          method: req.method,
+          path,
+          contractName: contract.name,
+          status: response.status,
+          durationMs,
+          details: {
+            headers: Object.fromEntries(req.headers.entries()),
+          },
+        });
+      }
+
+      if (error && shouldCaptureError) {
+        record({
+          type: "error",
+          requestId,
+          traceId: traceContext.traceId,
+          spanId: traceContext.spanId,
+          parentSpanId: traceContext.parentSpanId,
+          traceparent: traceContext.traceparent,
+          message: getErrorMessage(error),
+          stack: getErrorStack(error),
+          contractName: contract.name,
+        });
+      }
+    },
+  };
+}
+
+export function createDevtoolsUseCaseObserver<Ctx>(
+  options: DevtoolsUseCaseObserverOptions<Ctx> = {},
+): (event: DevtoolsUseCaseRunEvent<Ctx>) => void {
+  const logErrorEvents = options.logErrorEvents ?? true;
+  const activeTraceContexts = new Map<string, DevtoolsTraceContext>();
+
+  return (event) => {
+    const devtools =
+      options.getDevtools?.(event.ctx) ?? getContextDevtools(event.ctx);
+    if (!devtools) return;
+
+    const requestId =
+      options.getRequestId?.(event.ctx) ?? getContextRequestId(event.ctx);
+    const errorMessage =
+      event.phase === "error" ? getErrorMessage(event.error) : undefined;
+    const shouldCaptureUseCase = isWatcherEnabled(devtools, "useCases");
+    const shouldCaptureError =
+      event.phase === "error" &&
+      logErrorEvents &&
+      isWatcherEnabled(devtools, "errors");
+
+    if (!shouldCaptureUseCase && !shouldCaptureError) return;
+
+    const parentTraceContext = getContextTraceContext(event.ctx);
+    const useCaseKey = [
+      requestId ?? "no-request",
+      parentTraceContext?.traceId ?? "no-trace",
+      event.kind,
+      event.name,
+    ].join(":");
+    const traceContext =
+      event.phase === "start"
+        ? createChildDevtoolsTraceContext(parentTraceContext ?? {})
+        : (activeTraceContexts.get(useCaseKey) ??
+          createChildDevtoolsTraceContext(parentTraceContext ?? {}));
+
+    if (event.phase === "start") {
+      activeTraceContexts.set(useCaseKey, traceContext);
+    } else {
+      activeTraceContexts.delete(useCaseKey);
+    }
+
+    const record = (input: DevtoolsEventInput) => {
+      const normalized = createDevtoolsEvent(input);
+      try {
+        devtools.record(
+          options.redact ? options.redact(normalized) : normalized,
+        );
+      } catch (error) {
+        devtools.record({
+          type: "error",
+          message: "Devtools use case redactor failed",
+          details: {
+            message: error instanceof Error ? error.message : String(error),
+          },
+        });
+      }
+    };
+
+    if (shouldCaptureUseCase) {
+      record({
+        type: "usecase",
+        requestId,
+        traceId: traceContext.traceId,
+        spanId: traceContext.spanId,
+        parentSpanId: traceContext.parentSpanId,
+        traceparent: traceContext.traceparent,
+        name: event.name,
+        kind: event.kind,
+        phase: event.phase,
+        durationMs: event.durationMs,
+        error: errorMessage,
+      });
+    }
+
+    if (shouldCaptureError) {
+      record({
+        type: "error",
+        requestId,
+        traceId: traceContext.traceId,
+        spanId: traceContext.spanId,
+        parentSpanId: traceContext.parentSpanId,
+        traceparent: traceContext.traceparent,
+        message: errorMessage ?? "Use case failed",
+        stack: getErrorStack(event.error),
+        useCaseName: event.name,
+      });
+    }
+  };
+}