@zerotal/devtools 1.6.3 → 1.7.2

package/src/client/tabs/request.ts

@@ -0,0 +1,75 @@
+/**
+ * Both halves of the exchange: what came in, what went out, and what the session
+ * was holding while it happened.
+ *
+ * Headers are an allowlist, not 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. `devtools.headers` opens up the
+ * ones you are actually debugging.
+ *
+ * The session shows **key names only**. "Is the CSRF token there, did the flash
+ * survive the redirect, is the user id set" are all answered by the keys, and the
+ * values are the request's real state.
+ */
+import { copyBtn, esc } from "../ui/format.ts";
+import type { TabView } from "./types.ts";
+
+function kvTable(pairs: Record<string, string>): string {
+  const rows = Object.entries(pairs)
+    .map(([k, v]) => `<tr><td>${esc(k)}</td><td>${esc(v)}</td></tr>`)
+    .join("");
+  return `<table class="kv">${rows || `<tr><td colspan="2" class="dim" style="padding:6px 12px">None</td></tr>`}</table>`;
+}
+
+/** The whole block as `name: value` lines, which is what you paste into a curl. */
+function asText(pairs: Record<string, string>): string {
+  return Object.entries(pairs)
+    .map(([k, v]) => `${k}: ${v}`)
+    .join("\n");
+}
+
+function section(title: string, pairs: Record<string, string>): string {
+  return (
+    `<div class="sec"><div class="stitle">${esc(title)} (${Object.keys(pairs).length})` +
+    copyBtn(asText(pairs), `Copy ${title.toLowerCase()}`) +
+    `</div>${kvTable(pairs)}</div>`
+  );
+}
+
+export const requestTab: TabView = {
+  id: "request",
+  label: "Request",
+  scope: "request",
+
+  render(host, { trace }) {
+    const t = trace!;
+    const params = t.queryParams ?? {};
+    const headers = t.headers ?? {};
+    const responseHeaders = t.responseHeaders ?? {};
+    const session = t.session ?? [];
+
+    // No status line here. This view was once a tab of its own and had to say
+    // which request it was describing; it is now a section of that request, and
+    // whatever opened it — the row in the list, the header in Live — has already
+    // said the method, the path and the status directly above. Repeating them
+    // read as a second heading competing with the real one.
+
+    const sessionKeys = session.length
+      ? `<div class="chips">` +
+        session.map((k) => `<span class="chip">${esc(k)}</span>`).join("") +
+        `</div>`
+      : `<p class="dim" style="padding:2px 0 4px">` +
+        `No session on this request — or no session middleware installed</p>`;
+
+    host.innerHTML =
+      section("Query Params", params) +
+      section("Request Headers", headers) +
+      section("Response Headers", responseHeaders) +
+      `<div class="sec"><div class="stitle">Session keys (${session.length})` +
+      copyBtn(session.join("\n"), "Copy keys") +
+      `</div>${sessionKeys}` +
+      `<p class="dim" style="font-size:10px;margin-top:6px">` +
+      `Names only — the values are this request's real state, and a trace is kept for a day.` +
+      `</p></div>`;
+  },
+};

package/src/client/tabs/sections.ts

@@ -0,0 +1,115 @@
+/**
+ * A request, drawn as its own small set of tabs.
+ *
+ * Twelve request-scoped tabs in the panel's main strip is twelve headings that
+ * are empty for most requests and answer a question you can only ask about a
+ * request you have already picked. They belong to the request, so they are drawn
+ * inside it — by calling the views themselves, since a `TabView` is already
+ * "draw this trace into this element", which is exactly what a section is.
+ * Nothing here reimplements a view.
+ *
+ * Tabs rather than a stack, because the sections are alternatives: you are
+ * reading the queries *or* the headers *or* the waterfall, and stacking them
+ * makes you scroll past two to reach the third. Only the ones with something to
+ * say appear, so the strip is also the summary — a request with a Queries, a
+ * Logs and an Exception tab has already told you what happened before you click
+ * anything.
+ *
+ * Shared by the request list, where a row opens into its own detail, and by the
+ * Live view, which shows the newest request without your having to open anything.
+ */
+import type { RequestTrace } from "../../RequestTrace.ts";
+import { esc } from "../ui/format.ts";
+import type { TabContext, TabView } from "./types.ts";
+
+/** Whether a view drew anything beyond its own "nothing here" line. */
+export function isEmptyRender(body: HTMLElement): boolean {
+  if (!body.textContent?.trim()) return true;
+  const kids = Array.from(body.children);
+  return kids.length > 0 && kids.every((k) => k.classList.contains("empty"));
+}
+
+interface Drawn {
+  view: TabView;
+  badge: ReturnType<NonNullable<TabView["badge"]>>;
+  body: HTMLElement;
+}
+
+/**
+ * Render every request-scoped view that has something to say about `trace`.
+ *
+ * A view is asked for its count first and skipped when it counts nothing — the
+ * queries view renders a stats strip even for a request that ran none, and a
+ * "Queries 0" heading over it is exactly the empty furniture this replaces. What
+ * survives that is rendered and then dropped anyway if what came back is only the
+ * view's own empty-state line, so a request that sent no mail has no Mail tab
+ * rather than a tab holding the word "none".
+ *
+ * Every surviving body is kept in the DOM and hidden rather than re-rendered on
+ * each switch: they are whole tab renderers, and the flick between two of them
+ * should cost nothing.
+ */
+export function renderSections(hostEl: HTMLElement, trace: RequestTrace, ctx: TabContext): void {
+  hostEl.replaceChildren();
+
+  const drawn: Drawn[] = [];
+  for (const view of ctx.sections ?? []) {
+    const badge = view.badge?.({ trace, store: ctx.store });
+    if (badge && Number(badge.count) === 0) continue;
+
+    const body = document.createElement("div");
+    body.className = "dsec-body";
+    try {
+      view.render(body, { trace, store: ctx.store });
+    } catch {
+      // A view that throws must not take the request it belongs to with it.
+      continue;
+    }
+    if (isEmptyRender(body)) continue;
+    drawn.push({ view, badge, body });
+  }
+
+  if (!drawn.length) {
+    hostEl.innerHTML = `<p class="empty">Nothing else was recorded for this request</p>`;
+    return;
+  }
+
+  const activeId = activeSection(
+    ctx.store.sectionTab,
+    drawn.map((d) => d.view.id),
+  );
+
+  const strip = document.createElement("div");
+  strip.className = "dsecs";
+  strip.innerHTML = drawn
+    .map(({ view, badge }) => {
+      const count = badge
+        ? `<span class="dsec-n${badge.warn ? " warn" : ""}">${esc(String(badge.count))}</span>`
+        : "";
+      return (
+        `<button class="dsect${view.id === activeId ? " on" : ""}" ` +
+        `data-sec="${esc(view.id)}">${esc(view.label)}${count}</button>`
+      );
+    })
+    .join("");
+  hostEl.appendChild(strip);
+
+  for (const { view, body } of drawn) {
+    const pane = document.createElement("div");
+    pane.className = "dsec-pane";
+    if (view.id !== activeId) pane.style.display = "none";
+    pane.appendChild(body);
+    hostEl.appendChild(pane);
+  }
+}
+
+/**
+ * Which section to show: the one you were reading, or the first this request has.
+ *
+ * Falling back rather than clearing the preference — move from a request with
+ * queries to one without and you get its first section, but the one after that
+ * with queries again puts you back where you were.
+ */
+export function activeSection(preferred: string, available: string[]): string {
+  return available.includes(preferred) ? preferred : (available[0] ?? "");
+}

package/src/client/tabs/timeline.ts

@@ -0,0 +1,133 @@
+/**
+ * Everything the request did, on one waterfall.
+ *
+ * Every entry already carries an offset from the request start; the waterfall is
+ * what makes "what was waiting on what" legible instead of a column of numbers
+ * you have to order in your head.
+ */
+import { esc, fmt } from "../ui/format.ts";
+import type { ClientMetric } from "../metrics.ts";
+import type { TabView } from "./types.ts";
+
+/**
+ * What the browser measured, above what the server did.
+ *
+ * Kept visibly separate rather than merged into the waterfall: these describe
+ * the *page*, not this request, and drawing them on the same track would claim a
+ * relationship that is not there. Shown anyway, because server duration reported
+ * as if it were the user's experience is the panel's most misleading number.
+ */
+function clientStrip(metrics: ClientMetric[]): string {
+  if (!metrics.length) return "";
+  return (
+    `<div class="stats">` +
+    metrics
+      .map(
+        (m) =>
+          `<div class="stat" title="${esc(m.detail)}">` +
+          `<div class="slbl">${esc(m.label)}</div>` +
+          `<div class="sval">${fmt(m.value)}</div></div>`,
+      )
+      .join("") +
+    `</div>` +
+    `<div class="dim" style="font-size:10px;padding:4px 12px">` +
+    `Measured in the browser, for this page load — not for this request.</div>`
+  );
+}
+
+interface Span {
+  at: number;
+  dur: number;
+  kind: string;
+  text: string;
+}
+
+const KEY: Array<[string, string]> = [
+  ["query", "Queries"],
+  ["cache", "Cache"],
+  ["mail", "Mail"],
+  ["job", "Jobs"],
+  ["chan", "Channels"],
+  ["log", "Logs"],
+  ["warn", "Warnings"],
+];
+
+export const timelineTab: TabView = {
+  id: "timeline",
+  label: "Timeline",
+  scope: "request",
+
+  render(host, { trace, store }) {
+    const t = trace!;
+    const spans: Span[] = [];
+
+    for (const q of t.queries) {
+      spans.push({
+        at: Math.max(0, q.startMs - t.startMs),
+        dur: q.durationMs,
+        kind: "query",
+        text: q.sql,
+      });
+    }
+    for (const c of t.cache ?? []) {
+      spans.push({ at: c.offsetMs, dur: c.durationMs, kind: "cache", text: `${c.op} ${c.key}` });
+    }
+    for (const m of t.mail ?? []) {
+      spans.push({ at: m.offsetMs, dur: m.durationMs, kind: "mail", text: m.subject });
+    }
+    for (const j of t.jobs ?? []) {
+      spans.push({ at: j.offsetMs, dur: j.durationMs, kind: "job", text: j.className });
+    }
+    for (const l of t.logs ?? []) {
+      spans.push({
+        at: l.offsetMs,
+        dur: 0,
+        kind: l.level === "error" || l.level === "warn" ? "warn" : "log",
+        text: l.args.join(" "),
+      });
+    }
+    for (const [id, rows] of Object.entries(t.channels ?? {})) {
+      const desc = store.channels.find((c) => c.id === id);
+      for (const r of rows) {
+        const titleKey = desc?.title ?? desc?.badge;
+        spans.push({
+          at: r.offsetMs,
+          dur: typeof r["durationMs"] === "number" ? (r["durationMs"] as number) : 0,
+          kind: "chan",
+          text: `${desc?.label ?? id}: ${titleKey ? String(r[titleKey] ?? "") : ""}`,
+        });
+      }
+    }
+
+    const client = clientStrip(store.clientMetrics);
+
+    if (!spans.length) {
+      host.innerHTML =
+        client + '<p class="empty">Nothing recorded on the timeline for this request</p>';
+      return;
+    }
+
+    spans.sort((a, b) => a.at - b.at);
+    const total = Math.max(1, t.durationMs);
+
+    host.innerHTML =
+      client +
+      `<div class="tkey">` +
+      KEY.map(([k, lbl]) => `<span><i class="tmark ${k}"></i>${lbl}</span>`).join("") +
+      `</div><div>` +
+      spans
+        .map((s) => {
+          const left = Math.min(99, (s.at / total) * 100);
+          const width = Math.max(0.6, Math.min(100 - left, (s.dur / total) * 100));
+          return (
+            `<div class="trow">` +
+            `<span class="tlbl dim">+${s.at}ms</span>` +
+            `<span class="ttrack"><span class="tmark ${s.kind}" style="left:${left}%;width:${width}%"></span></span>` +
+            `<span class="ttxt dim" title="${esc(s.text)}">${esc(s.text)}</span>` +
+            `</div>`
+          );
+        })
+        .join("") +
+      `</div>`;
+  },
+};

package/src/client/tabs/types.ts

@@ -0,0 +1,68 @@
+/**
+ * What a tab is.
+ *
+ * Every tab in the panel — built-in, channel, or plugin — is reduced to this, so
+ * the shell has one loop for the tab strip and one call for the content instead
+ * of a switch that grows a case per feature. Adding a tab is adding a file.
+ */
+import type { RequestTrace } from "../../RequestTrace.ts";
+import type { Store } from "../state.ts";
+
+export interface TabContext {
+  /** The pinned or live trace, or null before any traffic. */
+  trace: RequestTrace | null;
+  store: Store;
+  /**
+   * The request-scoped views, for the list to render inside whichever request is
+   * open. Absent in a test that renders one tab on its own.
+   */
+  sections?: TabView[];
+}
+
+/** The count beside a tab's label, and whether it should read as a warning. */
+export interface TabBadge {
+  count: number | string;
+  warn?: boolean;
+}
+
+export interface TabView {
+  id: string;
+  label: string;
+  /**
+   * Whether this describes one request or the session.
+   *
+   * `"request"` is not a tab at all: it is a section of the request you opened
+   * in the list. Twelve of these in the strip is twelve tabs that are empty for
+   * most requests and answer a question you can only ask about a request you
+   * have already picked — so they are rendered inside its row instead, and only
+   * when they have something to say. `"session"` earns a tab, because it keeps
+   * reading while you move between requests: the list itself, and a plugin that
+   * owns live browser state.
+   */
+  scope: "request" | "session";
+  /**
+   * Show the live dot while connected. For the tab whose contents change on
+   * their own rather than only when you pick a different request.
+   */
+  live?: boolean;
+  /**
+   * Redraw whenever anything in the store moved, not only when the selected
+   * trace changed. The default is the cheaper one: a tab that reads one trace is
+   * redrawn when that trace changes and left alone otherwise.
+   */
+  volatile?: boolean;
+  /**
+   * Render even when nothing is selected. Only the request list has anything to
+   * say before the first request arrives.
+   */
+  standsAlone?: boolean;
+  badge?(ctx: TabContext): TabBadge | undefined;
+  render(host: HTMLElement, ctx: TabContext): void;
+  /**
+   * Redraw for a scroll of the content host, without a store change.
+   *
+   * Only a tab that windows its rows needs this — for everything else the
+   * browser scrolls what is already drawn.
+   */
+  onScroll?(host: HTMLElement, ctx: TabContext): void;
+}

package/src/client/transport.ts

@@ -0,0 +1,81 @@
+/**
+ * The wire: one `EventSource` and three JSON endpoints.
+ *
+ * Split out because it is the only part of the panel that talks to the server,
+ * and keeping it apart is what lets every tab be a pure function of the store.
+ * `EventSource` reconnects on its own timer, so there is no retry loop here —
+ * only the connection flag the bar's dot reads.
+ */
+import type { RequestTrace, TraceChannelDescriptor } from "../RequestTrace.ts";
+import type { EditorName } from "../editor.ts";
+import type { Store } from "./state.ts";
+
+/** What the SSE stream sends. */
+type Frame =
+  | {
+      type: "history";
+      data: RequestTrace[];
+      channels?: TraceChannelDescriptor[];
+      capacity?: number;
+      editor?: EditorName | null;
+      editorPathMap?: Record<string, string>;
+    }
+  | { type: "trace"; data: RequestTrace }
+  | { type: "clear" };
+
+export interface Transport {
+  /** Ask the server to drop its history. The `clear` frame comes back over SSE. */
+  clear(): void;
+  /** Close the stream. Called when the panel removes itself from the page. */
+  close(): void;
+}
+
+/**
+ * Connect the store to the stream.
+ *
+ * @param base - The devtools endpoint root, without a trailing slash.
+ * @param store - Mutated as frames arrive; it announces its own changes.
+ */
+export function connect(base: string, store: Store): Transport {
+  const sse = new EventSource(`${base}/sse`);
+
+  sse.onopen = () => {
+    store.connected = true;
+    store.changed();
+  };
+
+  sse.onerror = () => {
+    store.connected = false;
+    store.changed();
+  };
+
+  sse.onmessage = (e: MessageEvent<string>) => {
+    let frame: Frame;
+    try {
+      frame = JSON.parse(e.data) as Frame;
+    } catch {
+      // A truncated frame is the stream's problem, not the panel's; the next one
+      // will be whole.
+      return;
+    }
+    if (frame.type === "history") {
+      store.loadHistory(frame.data, frame.channels ?? [], frame.capacity, {
+        editor: frame.editor ?? null,
+        editorPathMap: frame.editorPathMap ?? {},
+      });
+    } else if (frame.type === "trace") {
+      store.addTrace(frame.data);
+    } else {
+      store.clear();
+    }
+  };
+
+  return {
+    clear() {
+      void fetch(`${base}/api/clear`, { method: "POST" });
+    },
+    close() {
+      sse.close();
+    },
+  };
+}

package/src/client/tree.ts

@@ -0,0 +1,138 @@
+/**
+ * Turning flat records into the nested views the panel draws.
+ *
+ * Two shapings, both pure and both testable without a DOM: dotted prop paths
+ * into a tree, and a set of traces into correlated groups.
+ */
+import type { RequestTrace, TraceChannelDescriptor } from "../RequestTrace.ts";
+
+/** A node of a dotted-path tree: a leaf with attributes, a branch with children, or both. */
+export interface PathTreeNode {
+  children: Map<string, PathTreeNode>;
+  /** The node's own attributes, or null for a branch nothing was recorded against. */
+  attrs: Record<string, unknown> | null;
+}
+
+/**
+ * Split a map of dotted paths into the tree the dots already describe.
+ *
+ * `user.name` and `user.email` are two entries in a flat record and one branch
+ * with two leaves on screen — which is the difference between reading a prop bag
+ * and scanning one. A path can be both: `user` may carry attributes of its own
+ * *and* have children, so a branch keeps its `attrs` rather than being treated as
+ * a container.
+ *
+ * @param paths - Dotted path → that node's attributes.
+ */
+export function buildPathTree(paths: Array<[string, unknown]>): Map<string, PathTreeNode> {
+  const root = new Map<string, PathTreeNode>();
+  for (const [path, attrs] of paths) {
+    let level = root;
+    const parts = path.split(".");
+    parts.forEach((part, i) => {
+      let node = level.get(part);
+      if (!node) {
+        node = { children: new Map(), attrs: null };
+        level.set(part, node);
+      }
+      if (i === parts.length - 1) {
+        node.attrs = attrs && typeof attrs === "object" ? (attrs as Record<string, unknown>) : {};
+      }
+      level = node.children;
+    });
+  }
+  return root;
+}
+
+/**
+ * The value that groups this trace with others, from whichever channel declared
+ * a `traceGroup` field. Null when nothing correlates it.
+ *
+ * One user action can be several requests — a visit, then the deferred-prop loads
+ * it triggers — and listing them as unrelated siblings is how the thing you are
+ * debugging scrolls off the top. Which field says so is the channel's to declare,
+ * so this stays free of any package's vocabulary.
+ *
+ * The id is prefixed with the channel's, so two channels that both correlate
+ * cannot collide on a shared value.
+ */
+export function traceGroupKey(
+  trace: RequestTrace,
+  channels: TraceChannelDescriptor[],
+): string | null {
+  for (const c of channels) {
+    if (!c.traceGroup) continue;
+    const value = trace.channels?.[c.id]?.[0]?.[c.traceGroup];
+    if (value != null && value !== "") return `${c.id}:${String(value)}`;
+  }
+  return null;
+}
+
+/** One line of the All tab: a trace, its index in the full list, and its nesting. */
+export interface TraceRow {
+  trace: RequestTrace;
+  /** Index into the *unfiltered* trace list, so a click still selects the right one. */
+  index: number;
+  /** True for a follow-up shown under its group head. */
+  child: boolean;
+  /** The group this row heads, when it heads one. */
+  groupKey?: string;
+  /** How many follow-ups are folded under this head. */
+  groupSize?: number;
+}
+
+/**
+ * Flatten the filtered traces into the rows the All tab draws, folding correlated
+ * requests under the oldest of each set.
+ *
+ * A group takes the position of its *newest* member, so a batch still receiving
+ * follow-ups stays where you are looking rather than sinking as it grows. The
+ * head is its oldest member — the request that started it — because that is the
+ * one you meant to click.
+ *
+ * Kept separate from the rendering so the All tab's structure can be asserted on
+ * without a DOM, and so virtualisation has a flat array to window over.
+ */
+export function foldTraceRows(
+  matches: Array<{ trace: RequestTrace; index: number }>,
+  channels: TraceChannelDescriptor[],
+  expanded: ReadonlySet<string>,
+): TraceRow[] {
+  const order: string[] = [];
+  const groups = new Map<string, Array<{ trace: RequestTrace; index: number }>>();
+
+  for (const m of matches) {
+    // Uncorrelated traces get a key of their own so they never merge with each
+    // other — the fallback has to be unique, not shared.
+    const key = traceGroupKey(m.trace, channels) ?? `#${m.index}`;
+    let bucket = groups.get(key);
+    if (!bucket) {
+      groups.set(key, (bucket = []));
+      order.push(key);
+    }
+    bucket.push(m);
+  }
+
+  const rows: TraceRow[] = [];
+  for (const key of order) {
+    const members = groups.get(key)!;
+    if (members.length === 1) {
+      rows.push({ trace: members[0]!.trace, index: members[0]!.index, child: false });
+      continue;
+    }
+    // Oldest last, because the list is newest-first.
+    const head = members[members.length - 1]!;
+    const rest = members.slice(0, -1);
+    rows.push({
+      trace: head.trace,
+      index: head.index,
+      child: false,
+      groupKey: key,
+      groupSize: rest.length,
+    });
+    if (expanded.has(key)) {
+      for (const m of rest) rows.push({ trace: m.trace, index: m.index, child: true });
+    }
+  }
+  return rows;
+}