@zerotal/devtools 1.6.2 → 1.7.0

package/src/tracing.ts

@@ -19,10 +19,27 @@
  *
  * Console patching is handled separately via startConsoleCapture() since
  * console.log is a hook (interception) not a broadcast event.
+ *
+ * ## This package's cast boundary
+ *
+ * Listed under `boundaries` in `cast-baseline.json`, so the per-file cast ratchet
+ * does not apply here. That is deliberate and confined to this file, for two
+ * invariants nothing in the type system can express:
+ *
+ * 1. **`HttpContext` is read structurally.** `ctx.session`, `ctx.user` and
+ *    `ctx._routeDef` are contributed by packages devtools does not import — that
+ *    independence is the whole design, and it is why an app without the session
+ *    middleware simply has no `session` to read. Every such read is guarded and
+ *    falls back to empty; a missing property is the ordinary case, not an error.
+ * 2. **`console` is patched by name.** Replacing `console[level]` at runtime is
+ *    interception, not a typed call, so the index has to be untyped.
+ *
+ * Nothing else in `@zerotal/devtools` is exempt. A cast that wants to live
+ * somewhere other than this file is a cast to remove.
  */
 
 import { FrameworkEvents, RequestContext } from "@zerotal/core";
-import type { RequestHandled, RequestFailed } from "@zerotal/core";
+import type { RequestHandled, RequestFailed, OutgoingRequestCompleted } from "@zerotal/core";
 import type { HttpContext } from "@zerotal/core";
 import type {
   QuerySpan,
@@ -31,19 +48,26 @@ import type {
   MailEntry,
   CacheEntry,
   JobEntry,
+  ExceptionInfo,
   RequestTrace,
   TraceChannelDescriptor,
   TraceChannelEntry,
 } from "./RequestTrace.ts";
 import { traceStore } from "./TraceStore.ts";
-import { redactBindings, type RedactionOptions } from "./redaction.ts";
+import { captureCallSite, parseStack } from "./callsite.ts";
+import { redactBindings, redactCacheKey, redactValue, type RedactionOptions } from "./redaction.ts";
 
 // ── Per-context event buffers ─────────────────────────────────────────────────
 // Events are buffered for the full request lifetime (including phases that run
 // before DevtoolsInjectionMiddleware, e.g. AuthMiddleware loading the user).
 // Buffers are GC'd with the HttpContext via WeakMap.
 
-type _BufLog = { level: LogEntry["level"]; args: string[]; absMs: number };
+type _BufLog = {
+  level: LogEntry["level"];
+  args: string[];
+  absMs: number;
+  source?: LogEntry["source"];
+};
 type _BufMail = Omit<MailEntry, "offsetMs"> & { absMs: number };
 type _BufCache = Omit<CacheEntry, "offsetMs"> & { absMs: number };
 type _BufJob = Omit<JobEntry, "offsetMs"> & { absMs: number };
@@ -82,7 +106,7 @@ export function _resetChannels(): void {
   _channels.clear();
 }
 
-// ── Redaction ─────────────────────────────────────────────────────────────────
+// ── Capture settings ──────────────────────────────────────────────────────────
 
 let _redaction: RedactionOptions = {};
 
@@ -91,6 +115,31 @@ export function _setRedaction(options: RedactionOptions): void {
   _redaction = options;
 }
 
+/**
+ * Whether to walk the stack for each query and log line.
+ *
+ * A field rather than a config read per event: this runs on the hot path of a
+ * request running forty queries, and resolving config forty times to answer the
+ * same question would cost more than the walk it is guarding.
+ */
+let _captureSource = true;
+
+/** @internal — set by DevtoolsProvider from the app's `devtools` config. */
+export function _setCaptureSource(enabled: boolean): void {
+  _captureSource = enabled;
+}
+
+/**
+ * Request headers recorded beyond the built-in safe list, lower-cased.
+ * `"*"` records every header the redaction rules do not mask.
+ */
+let _extraHeaders = new Set<string>();
+
+/** @internal — set by DevtoolsProvider from the app's `devtools` config. */
+export function _setHeaderAllowlist(headers: string[]): void {
+  _extraHeaders = new Set(headers.map((h) => h.toLowerCase()));
+}
+
 // ── The sink feature packages contribute to ───────────────────────────────────
 
 /**
@@ -122,15 +171,32 @@ export interface TraceSink {
   bufferJob(ctx: object, j: Omit<JobEntry, "offsetMs">): void;
 }
 
+// Everything below masks on the way *in*. Redacting in a renderer would protect
+// nothing: by the time a panel draws a row, the unredacted copy has already been
+// streamed to the browser and written to `.zerotal/devtools.sqlite`, where it
+// sits for a day. The sink is the last point where "not recorded" is still true.
 export const traceSink: TraceSink = {
   channel(descriptor: TraceChannelDescriptor): void {
     _channels.set(descriptor.id, descriptor);
   },
   record(ctx: object, channel: string, entry: Record<string, unknown>): void {
-    _bufPush(_ctxChannels, ctx, { channel, entry, absMs: Date.now() });
+    _bufPush(_ctxChannels, ctx, {
+      channel,
+      entry: redactValue(entry, _redaction) as Record<string, unknown>,
+      absMs: Date.now(),
+    });
   },
   bufferQuery(ctx: object, q: QuerySpan): void {
-    _bufPush(_ctxQueries, ctx, { ...q, bindings: redactBindings(q.sql, q.bindings, _redaction) });
+    // The call site is captured here rather than at the emit site because here
+    // is the only place that knows whether anyone is recording. `skip` is 0: the
+    // frames above are this method and the ORM's bridge, both of which the
+    // framework filter drops anyway.
+    const source = _captureSource && !q.source ? captureCallSite() : q.source;
+    _bufPush(_ctxQueries, ctx, {
+      ...q,
+      bindings: redactBindings(q.sql, q.bindings, _redaction),
+      ...(source ? { source } : {}),
+    });
   },
   bufferWarning(ctx: object, w: NPlusOneWarning): void {
     _bufPush(_ctxWarnings, ctx, w);
@@ -139,7 +205,7 @@ export const traceSink: TraceSink = {
     _bufPush(_ctxMail, ctx, { ...m, absMs: Date.now() });
   },
   bufferCache(ctx: object, c: Omit<CacheEntry, "offsetMs">): void {
-    _bufPush(_ctxCache, ctx, { ...c, absMs: Date.now() });
+    _bufPush(_ctxCache, ctx, { ...c, key: redactCacheKey(c.key, _redaction), absMs: Date.now() });
   },
   bufferJob(ctx: object, j: Omit<JobEntry, "offsetMs">): void {
     _bufPush(_ctxJobs, ctx, { ...j, absMs: Date.now() });
@@ -158,17 +224,38 @@ function _cleanupBuffers(ctx: object): void {
 
 // ── Trace builder ─────────────────────────────────────────────────────────────
 
+/**
+ * Request headers recorded without being asked.
+ *
+ * An allowlist rather than a denylist because a trace is *persisted*: `cookie`
+ * and `authorization` are the request's credentials, and a header nobody thought
+ * to deny is a header on disk for a day. The cost is that the custom header you
+ * are actually debugging is invisible, which is what `devtools.headers` opens.
+ */
 const SAFE_HEADERS = new Set([
   "accept",
   "content-type",
+  "content-length",
   "user-agent",
   "referer",
+  "origin",
+  "accept-language",
   "x-request-id",
   "x-forwarded-for",
   "x-inertia",
   "x-inertia-version",
+  "x-requested-with",
 ]);
 
+/** Never recorded, whatever the allowlist says — these *are* the credentials. */
+const NEVER_HEADERS = new Set(["cookie", "set-cookie", "authorization", "proxy-authorization"]);
+
+function _recordHeader(name: string): boolean {
+  const key = name.toLowerCase();
+  if (NEVER_HEADERS.has(key)) return false;
+  return SAFE_HEADERS.has(key) || _extraHeaders.has("*") || _extraHeaders.has(key);
+}
+
 const INTERNAL_PREFIXES = ["/__flow/", "/__zerotal/", "/__dev/"];
 
 function _isInternal(path: string): boolean {
@@ -189,7 +276,34 @@ function _offset(absMs: number, startMs: number): number {
   return Math.max(0, absMs - startMs);
 }
 
-function _buildTrace(ctx: HttpContext, startMs: number, durationMs: number): RequestTrace {
+/**
+ * What is in the session — the key names, never the values.
+ *
+ * "Is the CSRF token there, did the flash survive the redirect, is the user id
+ * set" are the session questions a request inspector is asked, and all three are
+ * answered by the keys. The values are the request's real state — the user's id,
+ * the token itself, whatever a form flashed — and this trace is written to disk
+ * for a day.
+ *
+ * Read structurally: devtools imports no feature package, and an app without the
+ * session middleware has no `ctx.session` at all.
+ */
+function _sessionKeys(ctx: HttpContext): string[] {
+  try {
+    const session = (ctx as unknown as Record<string, unknown>)["session"] as
+      { _data?: Record<string, unknown> } | undefined;
+    return session?._data ? Object.keys(session._data).sort() : [];
+  } catch {
+    return [];
+  }
+}
+
+function _buildTrace(
+  ctx: HttpContext,
+  startMs: number,
+  durationMs: number,
+  exception: ExceptionInfo | null,
+): RequestTrace {
   const queryParams: Record<string, string> = {};
   ctx.url.searchParams.forEach((v, k) => {
     queryParams[k] = v;
@@ -197,7 +311,14 @@ function _buildTrace(ctx: HttpContext, startMs: number, durationMs: number): Req
 
   const headers: Record<string, string> = {};
   ctx.request.headers.forEach((v, k) => {
-    if (SAFE_HEADERS.has(k.toLowerCase())) headers[k] = v;
+    if (_recordHeader(k)) headers[k] = v;
+  });
+
+  // The response half of the exchange: its status line and the headers it set.
+  // A request tab that shows only what came in answers half the question.
+  const responseHeaders: Record<string, string> = {};
+  ctx.response?.headers.forEach((v, k) => {
+    if (_recordHeader(k)) responseHeaders[k] = v;
   });
 
   const ctxRecord = ctx as unknown as Record<string, unknown>;
@@ -222,14 +343,18 @@ function _buildTrace(ctx: HttpContext, startMs: number, durationMs: number): Req
     memory: _heapUsed(),
     queryParams,
     headers,
+    responseHeaders,
+    session: _sessionKeys(ctx),
     route: rd ? { pattern: rd.pattern, controller: rd.controller, action: rd.action } : null,
     auth: user ? { id: user["id"], name: user["name"], email: user["email"] } : null,
+    exception,
     queries: _ctxQueries.get(ctx) ?? [],
     warnings: _ctxWarnings.get(ctx) ?? [],
     logs: (_ctxLogs.get(ctx) ?? []).map((l) => ({
       level: l.level,
       args: l.args,
       offsetMs: _offset(l.absMs, startMs),
+      ...(l.source ? { source: l.source } : {}),
     })),
     mail: (_ctxMail.get(ctx) ?? []).map(({ absMs, ...rest }) => ({
       ...rest,
@@ -261,27 +386,71 @@ export function startDevtoolsTracing(): void {
 
   // Both successful and failed requests finalise the trace. Failed requests still
   // carry the rendered error response on ctx, so the trace records the error status
-  // code like any other outcome. Everything else on the trace is buffered by
-  // feature packages through `traceSink`.
+  // code like any other outcome — and now the message with it, which used to be
+  // dropped here, leaving a red 500 in the panel with nothing to read next to it.
+  // Everything else on the trace is buffered by feature packages through `traceSink`.
   _unsubs = [
     FrameworkEvents.on<RequestHandled>("RequestHandled", (e) =>
-      _finaliseTrace(e.ctx as HttpContext, e.startMs, e.durationMs),
-    ),
-    FrameworkEvents.on<RequestFailed>("RequestFailed", (e) =>
-      _finaliseTrace(e.ctx as HttpContext, e.startMs, e.durationMs),
+      _finaliseTrace(e.ctx as HttpContext, e.startMs, e.durationMs, null),
     ),
+    FrameworkEvents.on<RequestFailed>("RequestFailed", (e) => {
+      const frames = parseStack(e.stack);
+      _finaliseTrace(e.ctx as HttpContext, e.startMs, e.durationMs, {
+        message: e.error,
+        status: e.status,
+        ...(e.type ? { type: e.type } : {}),
+        ...(frames.length ? { frames } : {}),
+      });
+    }),
+    // Outgoing calls, recorded here rather than by a bridge in the package that
+    // owns them: the owner is `@zerotal/core`, and core cannot know about the
+    // channel API because devtools is what depends on core. Devtools already
+    // subscribes to core's events, so this costs no new dependency in either
+    // direction.
+    FrameworkEvents.on<OutgoingRequestCompleted>("OutgoingRequestCompleted", (e) => {
+      // The event carries no context — the client does not take one — so the
+      // request is read from the ambient scope it was called in.
+      const ctx = RequestContext.tryGet();
+      if (!ctx) return;
+      traceSink.record(ctx, "http", {
+        method: e.method,
+        url: e.url,
+        host: e.host,
+        status: e.status || "—",
+        durationMs: e.durationMs,
+        failed: !e.ok,
+      });
+    }),
   ];
+
+  // Declared here rather than in a satellite for the same reason. `order` puts
+  // it beside the other per-request feeds rather than at the back of the strip.
+  traceSink.channel({
+    id: "http",
+    label: "Outgoing",
+    badge: "method",
+    title: "url",
+    meta: ["status", "durationMs", "host"],
+    warn: "failed",
+    order: 35,
+    render: "table",
+  });
 }
 
 /** Merge buffered events into a trace and push it to the store (once per request). */
-function _finaliseTrace(ctx: HttpContext, startMs: number, durationMs: number): void {
+function _finaliseTrace(
+  ctx: HttpContext,
+  startMs: number,
+  durationMs: number,
+  exception: ExceptionInfo | null,
+): void {
   // Internal framework paths are noise — skip them
   if (_isInternal(ctx.url.pathname)) {
     _cleanupBuffers(ctx);
     return;
   }
 
-  const trace = _buildTrace(ctx, startMs, durationMs);
+  const trace = _buildTrace(ctx, startMs, durationMs, exception);
   _cleanupBuffers(ctx);
   traceStore().push(trace);
 }
@@ -298,6 +467,28 @@ const LOG_LEVELS = ["log", "debug", "info", "warn", "error"] as const;
 let _origConsole: Partial<Record<string, unknown>> = {};
 let _consoleCaptured = false;
 
+/**
+ * One logged argument, as the line the panel shows.
+ *
+ * Objects are redacted before they are serialised, not after: `console.log(user)`
+ * during a debug session used to write the whole record — password hash included
+ * — to disk for a day. Redacting also makes the value safe to serialise at all,
+ * since the walk replaces cycles; a circular argument used to throw a
+ * `Converting circular structure to JSON` out of this patch and into the caller's
+ * `console.log`.
+ */
+function _formatLogArg(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (value instanceof Error) return `${value.name}: ${value.message}`;
+  const safe = redactValue(value, _redaction);
+  try {
+    return JSON.stringify(safe) ?? String(safe);
+  } catch {
+    // BigInt, a throwing toJSON — the log line is not worth failing the request.
+    return String(safe);
+  }
+}
+
 /** @internal — patch console.* to capture log lines per request context */
 export function startConsoleCapture(): void {
   // Idempotent: a second start() without an intervening stop() would otherwise
@@ -319,16 +510,14 @@ export function startConsoleCapture(): void {
       orig(...args);
       const ctx = RequestContext.tryGet();
       if (!ctx) return;
+      // One frame to skip: this wrapper is standing between the caller and the
+      // stack, and without dropping it every log line would point at devtools.
+      const source = _captureSource ? captureCallSite(1) : null;
       _bufPush(_ctxLogs, ctx, {
         level,
-        args: args.map((a) =>
-          typeof a === "string"
-            ? a
-            : a instanceof Error
-              ? `${a.name}: ${a.message}`
-              : (JSON.stringify(a, null, 0) ?? String(a)),
-        ),
+        args: args.map(_formatLogArg),
         absMs: Date.now(),
+        ...(source ? { source } : {}),
       });
     };
   }