@tsplc/debug 0.0.0-stage → 0.2.17

package/src/ui/recent.ts

@@ -0,0 +1,322 @@
+import type { AppRecord, TimelineEntry, TraceEvent } from "../api.ts";
+import type { DebugEventSite, DebugManifest } from "../manifest.ts";
+import { type View, empty, h, pathLink, recordSourceLink, sourceLink } from "./dom.ts";
+import { formatClock, formatDuration, formatProperties, formatValue } from "./format.ts";
+import { requestJobLink, requestStatus } from "./jobs.ts";
+import type { Store } from "./store.ts";
+
+type Source = TimelineEntry["source"];
+/** App records are filtered by their own kind. */
+type Kind = AppRecord["kind"] | Exclude<TimelineEntry["kind"], "app">;
+
+const SOURCES: Source[] = ["plc", "server", "agent", "debugger"];
+const KINDS: Kind[] = [
+  "event",
+  "log",
+  "exception",
+  "trace",
+  "request",
+  "deploy",
+  "audit",
+  "connection",
+];
+const PAGE = 300;
+const RENDER_INTERVAL_MS = 300;
+
+const hiddenSources = new Set<Source>();
+const hiddenKinds = new Set<Kind>();
+
+const kindOf = (entry: TimelineEntry): Kind =>
+  entry.kind === "app" ? entry.record.kind : entry.kind;
+
+const sitesByManifest = new WeakMap<DebugManifest, Map<number, DebugEventSite>>();
+const siteOf = (manifest: DebugManifest, id: number) => {
+  let sites = sitesByManifest.get(manifest);
+  if (!sites) {
+    sites = new Map(manifest.events.map((site) => [site.id, site]));
+    sitesByManifest.set(manifest, sites);
+  }
+  return sites.get(id);
+};
+
+/** A traced write, worded as what was observed: the value, the scan, and the guards captured with it. */
+const traceBody = (store: Store, trace: TraceEvent) => {
+  const site = siteOf(store.manifest, trace.site);
+  if (!site)
+    return [
+      h(
+        "div",
+        {},
+        `Site ${trace.site} is not in this build's manifest; value ${JSON.stringify(trace.value)} in scan ${trace.scan}.`,
+      ),
+    ];
+  return [
+    h(
+      "div",
+      {},
+      h("span", { class: "tag" }, site.kind),
+      " ",
+      pathLink(site.path),
+      " was ",
+      h("b", { class: "val" }, formatValue(store.manifest, site.type, trace.value)),
+      ` in scan ${trace.scan}`,
+      h("span", { class: "dim" }, ` · ${trace.task}`),
+    ),
+    h("div", {}, h("code", {}, site.text), " ", sourceLink(store, site.range)),
+    trace.operands.length > 0 &&
+      h(
+        "div",
+        { class: "chips" },
+        h("span", { class: "dim" }, "guards in that scan "),
+        ...trace.operands.map((operand, index) => {
+          const declared = site.operands[index];
+          const value = declared
+            ? formatValue(store.manifest, declared.type, operand.value)
+            : JSON.stringify(operand.value);
+          return h(
+            "span",
+            {
+              class: `chip${operand.stable ? "" : " unstable"}`,
+              title: operand.stable
+                ? `${operand.text}, captured at the write`
+                : `${operand.text}, captured at the write; code between the guard and the write can change it, so the guard may have seen another value`,
+            },
+            declared
+              ? sourceLink(store, declared.range, operand.text)
+              : h("code", {}, operand.text),
+            " = ",
+            operand.path ? pathLink(operand.path, value) : h("span", { class: "val" }, value),
+            operand.stable ? "" : h("span", { class: "dim" }, " ~"),
+          );
+        }),
+      ),
+  ];
+};
+
+/** What the program reported: `bin scanned · barcode=CON-MD3… scanner=3 · route-lookup.ts:120`. */
+const appBody = (store: Store, task: string, record: AppRecord) => {
+  const properties = Object.keys(record.properties).length
+    ? h(
+        "span",
+        { class: "mono", title: JSON.stringify(record.properties, null, 1) },
+        ` · ${formatProperties(record.properties)}`,
+      )
+    : "";
+  const origin = [
+    " · ",
+    recordSourceLink(store, record.source),
+    h("span", { class: "dim" }, ` · ${task}`),
+  ];
+  switch (record.kind) {
+    case "event":
+      return [h("div", {}, h("b", {}, record.event), properties, ...origin)];
+    case "log":
+      return [
+        h(
+          "div",
+          {},
+          h("span", { class: `tag lvl-${record.level}` }, record.level),
+          " ",
+          record.message,
+          properties,
+          ...origin,
+        ),
+      ];
+    case "exception":
+      return [
+        h(
+          "div",
+          {},
+          h("b", { class: "err" }, record.name ?? `error ${record.code}`),
+          " · ",
+          record.handled
+            ? h("span", { class: "dim" }, "handled")
+            : h("b", { class: "err" }, "unhandled"),
+          record.function ? h("span", { class: "mono" }, ` · ${record.function}`) : "",
+          record.instance ? h("span", {}, " on ", pathLink(record.instance)) : "",
+          properties,
+          ...origin,
+        ),
+      ];
+  }
+};
+
+const byWhom = (entry: { user?: string; host?: string }) =>
+  entry.user || entry.host
+    ? h(
+        "span",
+        { class: "dim" },
+        ` by ${entry.user ?? "unknown user"}${entry.host ? ` on ${entry.host}` : ""}`,
+      )
+    : "";
+
+const entryBody = (store: Store, entry: TimelineEntry) => {
+  switch (entry.kind) {
+    case "app":
+      return appBody(store, entry.task, entry.record);
+    case "trace":
+      return traceBody(store, entry.trace);
+    case "request": {
+      const { request } = entry;
+      return [
+        h(
+          "div",
+          {},
+          h("b", { class: "mono" }, request.service),
+          " ",
+          requestStatus(request),
+          request.durationMs === undefined ? "" : ` in ${formatDuration(request.durationMs)}`,
+          request.job === undefined
+            ? ""
+            : h("span", {}, " · from ", requestJobLink(store, request.job, request.sequence)),
+          request.error ? h("div", { class: "err" }, request.error) : "",
+        ),
+      ];
+    }
+    case "deploy":
+      return [
+        h(
+          "div",
+          {},
+          `Release ${entry.release} · ${entry.operation}`,
+          entry.build ? h("span", { class: "mono dim" }, ` build ${entry.build}`) : "",
+          byWhom(entry),
+        ),
+      ];
+    case "audit":
+      return [
+        h(
+          "div",
+          {},
+          h("b", { class: "mono" }, `tsplc ${entry.command}`),
+          byWhom(entry),
+          entry.error ? h("span", { class: "err" }, ` · ${entry.error}`) : "",
+        ),
+        h(
+          "div",
+          { class: "chips" },
+          ...Object.entries(entry.values).map(([path, value]) =>
+            h(
+              "span",
+              { class: "chip" },
+              pathLink(path),
+              value === "" ? " unforced" : ` = ${value}`,
+              entry.previous?.[path] === undefined
+                ? ""
+                : h("span", { class: "dim" }, ` (was ${entry.previous[path]})`),
+            ),
+          ),
+        ),
+      ];
+    case "connection":
+      return [
+        h(
+          "div",
+          {},
+          `Reading values: ${entry.state}`,
+          entry.error ? h("span", { class: "err" }, ` · ${entry.error}`) : "",
+        ),
+      ];
+  }
+};
+
+export const recentEntry = (store: Store, entry: TimelineEntry) =>
+  h(
+    "div",
+    { class: `entry k-${kindOf(entry)}` },
+    h(
+      "span",
+      { class: "when mono" },
+      formatClock(entry.at),
+      entry.approximate
+        ? h(
+            "span",
+            {
+              class: "approx",
+              title:
+                "Placed through another clock, so its order against other sources is approximate",
+            },
+            "≈",
+          )
+        : "",
+    ),
+    h("span", { class: `source src-${entry.source}` }, entry.source),
+    h("div", { class: "body" }, ...entryBody(store, entry)),
+  );
+
+const clockNote = (store: Store) => {
+  const clock = store.session.clock;
+  return `PLC records are placed on the app server's clock from their age when it received them${
+    clock ? `, within ±${clock.uncertaintyMs.toFixed(1)} ms` : ""
+  }, so their order against other sources is approximate (≈).`;
+};
+
+export const recentView = (store: Store): View => {
+  let shown = PAGE;
+  let renderTimer: ReturnType<typeof setTimeout> | undefined;
+  const list = h("div", { class: "entries" });
+  const more = h("button", { onclick: () => ((shown += PAGE), render()) }, `Show ${PAGE} older`);
+  const note = h("p", { class: "hint" });
+
+  const toggles = <T extends string>(values: T[], hidden: Set<T>) =>
+    values.map((value) => {
+      const input = h("input", { type: "checkbox", checked: !hidden.has(value) });
+      input.addEventListener("change", () => {
+        if (input.checked) hidden.delete(value);
+        else hidden.add(value);
+        render();
+      });
+      return h("label", { class: "check" }, input, value);
+    });
+
+  const render = () => {
+    clearTimeout(renderTimer);
+    renderTimer = undefined;
+    note.textContent = clockNote(store);
+    const visible = store.timeline.filter(
+      (entry) => !hiddenSources.has(entry.source) && !hiddenKinds.has(kindOf(entry)),
+    );
+    list.replaceChildren(
+      ...(visible.length
+        ? visible
+            .slice(-shown)
+            .reverse()
+            .map((entry) => recentEntry(store, entry))
+        : [empty("Nothing in the recent window matches these filters.")]),
+    );
+    more.hidden = visible.length <= shown;
+  };
+
+  render();
+  store.show();
+  return {
+    element: h(
+      "div",
+      { class: "page recent" },
+      h("h1", {}, "Recent"),
+      h(
+        "p",
+        { class: "hint" },
+        "The app server's recent window: what the program reported, its traced writes when the trace is on, and the requests it made, with the agent's deployments and audited commands. History lives in the app's telemetry sink, such as PostHog.",
+      ),
+      h(
+        "div",
+        { class: "toolbar" },
+        h("span", { class: "dim" }, "Source"),
+        ...toggles(SOURCES, hiddenSources),
+        h("span", { class: "dim sep" }, "Kind"),
+        ...toggles(KINDS, hiddenKinds),
+      ),
+      note,
+      list,
+      more,
+    ),
+    update(topics) {
+      if (!topics.has("timeline") && !topics.has("session")) return;
+      renderTimer ??= setTimeout(render, RENDER_INTERVAL_MS);
+    },
+    dispose() {
+      clearTimeout(renderTimer);
+    },
+  };
+};

package/src/ui/requests.ts

@@ -0,0 +1,81 @@
+import { type View, empty, h } from "./dom.ts";
+import { formatClock, formatDuration } from "./format.ts";
+import { requestJobLink, requestStatus } from "./jobs.ts";
+import type { Store } from "./store.ts";
+
+const LIMIT = 500;
+
+export const requestsView = (store: Store, params: URLSearchParams): View => {
+  const highlighted = Number(params.get("seq") ?? Number.NaN);
+  const body = h("div");
+  const render = () => {
+    const requests = store.timeline
+      .flatMap((entry) => (entry.kind === "request" ? [entry.request] : []))
+      .sort((a, b) => b.seq - a.seq)
+      .slice(0, LIMIT);
+    body.replaceChildren(
+      requests.length
+        ? h(
+            "table",
+            { class: "grid" },
+            h(
+              "thead",
+              {},
+              h(
+                "tr",
+                {},
+                ...["#", "Started", "Service", "Status", "Duration", "Job", "Error"].map((label) =>
+                  h("th", {}, label),
+                ),
+              ),
+            ),
+            h(
+              "tbody",
+              {},
+              ...requests.map((request) =>
+                h(
+                  "tr",
+                  { class: request.seq === highlighted ? "highlight" : undefined },
+                  h("td", { class: "mono num" }, String(request.seq)),
+                  h("td", { class: "mono" }, formatClock(request.startedAt)),
+                  h("td", { class: "mono" }, request.service),
+                  h("td", {}, requestStatus(request)),
+                  h(
+                    "td",
+                    { class: "mono num" },
+                    request.durationMs === undefined ? "—" : formatDuration(request.durationMs),
+                  ),
+                  h(
+                    "td",
+                    {},
+                    request.job === undefined
+                      ? h("span", { class: "dim" }, "not from a job")
+                      : requestJobLink(store, request.job, request.sequence),
+                  ),
+                  h("td", { class: "err" }, request.error ?? ""),
+                ),
+              ),
+            ),
+          )
+        : empty("No service requests recorded yet."),
+    );
+  };
+  render();
+  store.show();
+  return {
+    element: h(
+      "div",
+      { class: "page" },
+      h("h1", {}, "Requests"),
+      h(
+        "p",
+        { class: "hint" },
+        `Service calls the app server traced, newest first (at most ${LIMIT}).`,
+      ),
+      body,
+    ),
+    update(topics) {
+      if (topics.has("timeline")) render();
+    },
+  };
+};

package/src/ui/store.ts

@@ -0,0 +1,227 @@
+import type {
+  DeviceState,
+  Interest,
+  JobState,
+  Sample,
+  Session,
+  StreamEvents,
+  TimelineEntry,
+  WatchGroups,
+} from "../api.ts";
+import type { DebugManifest } from "../manifest.ts";
+import { apiUrl, getJson, putJson } from "./client.ts";
+import { type ValueState, valueState } from "./format.ts";
+import { createPaths, type Paths } from "../paths.ts";
+import { ManifestTree } from "./tree.ts";
+
+export type Topic =
+  "session" | "samples" | "jobs" | "devices" | "timeline" | "watch" | "stream" | "error" | "clock";
+
+/** The browser's EventSource state, apart from the controller connection the host reports. */
+type StreamState = "connecting" | "open" | "reconnecting";
+
+interface LiveSample {
+  sample: Sample | undefined;
+  ageMs: number | undefined;
+  state: ValueState;
+}
+
+const TIMELINE_LIMIT = 5000;
+const REOPEN_DEBOUNCE_MS = 250;
+
+// A restarted PLC numbers its records from the start again, so the time tells them apart.
+const timelineKey = (entry: TimelineEntry) => {
+  switch (entry.kind) {
+    case "app":
+      return `app:${entry.task}:${entry.sequence}:${entry.at}`;
+    case "trace":
+      return `trace:${entry.trace.task}:${entry.trace.sequence}:${entry.at}`;
+    case "request":
+      return `request:${entry.request.seq}`;
+    default:
+      return `${entry.kind}:${entry.source}:${entry.at}`;
+  }
+};
+
+/**
+ * Everything the UI shows, kept current from one EventSource. Changes are batched per animation frame
+ * and handed to `onChange` by topic.
+ */
+export class Store {
+  readonly tree: ManifestTree;
+  readonly paths: Paths;
+  stream: StreamState = "connecting";
+  error: string | undefined;
+  samples = new Map<string, Sample>();
+  jobs = new Map<number, JobState>();
+  devices = new Map<string, DeviceState>();
+  /** Oldest first, by `at`. */
+  timeline: TimelineEntry[] = [];
+  watch: WatchGroups = { groups: {} };
+
+  private readonly timelineByKey = new Map<string, TimelineEntry>();
+  /** Browser clock minus host clock, from the fastest sample delivery seen. */
+  private hostSkewMs = Infinity;
+  private source: EventSource | undefined;
+  private showing: string | undefined;
+  private params: Record<string, string> = {};
+  private reopenTimer: ReturnType<typeof setTimeout> | undefined;
+  private pending = new Set<Topic>();
+
+  constructor(
+    readonly manifest: DebugManifest,
+    public session: Session,
+    private readonly onChange: (topics: Set<Topic>) => void,
+  ) {
+    this.tree = new ManifestTree(manifest);
+    this.paths = createPaths(manifest);
+    setInterval(() => this.notify("clock"), 1000);
+  }
+
+  notify(topic: Topic) {
+    if (this.pending.size === 0) requestAnimationFrame(() => this.flush());
+    this.pending.add(topic);
+  }
+
+  private flush() {
+    const topics = this.pending;
+    this.pending = new Set();
+    this.onChange(topics);
+  }
+
+  reportError(error: unknown) {
+    this.error = error instanceof Error ? error.message : String(error);
+    this.notify("error");
+  }
+
+  /** Host time now, so ages of host timestamps do not depend on the browser's clock. */
+  hostNow() {
+    return Date.now() - (Number.isFinite(this.hostSkewMs) ? this.hostSkewMs : 0);
+  }
+
+  ageOf(iso: string) {
+    return Math.max(0, this.hostNow() - Date.parse(iso));
+  }
+
+  get connected() {
+    return this.stream === "open" && this.session.connection.state === "connected";
+  }
+
+  live(path: string): LiveSample {
+    const sample = this.samples.get(path);
+    if (!sample) return { sample, ageMs: undefined, state: "unavailable" };
+    const ageMs = this.ageOf(sample.receivedAt);
+    const state = valueState(sample.quality, ageMs, {
+      connected: this.connected,
+      intervalMs: this.session.reading.intervalMs,
+    });
+    return { sample, ageMs, state };
+  }
+
+  /**
+   * Streams exactly what the page shows, reopening the stream once it settles: the host reads
+   * only these paths, jobs and devices.
+   */
+  show(interest: Partial<Interest> = {}) {
+    const params = Object.fromEntries(
+      Object.entries(interest).flatMap(([name, values]) => {
+        const list = [...new Set(values.map(String))].sort().join(",");
+        return list ? [[name, list]] : [];
+      }),
+    );
+    const showing = JSON.stringify(Object.entries(params).sort());
+    if (showing === this.showing) return;
+    this.showing = showing;
+    this.params = params;
+    clearTimeout(this.reopenTimer);
+    this.reopenTimer = setTimeout(() => this.open(), this.source ? REOPEN_DEBOUNCE_MS : 0);
+  }
+
+  private open() {
+    this.source?.close();
+    const source = new EventSource(apiUrl("stream", this.params));
+    this.source = source;
+    source.onopen = () => {
+      this.stream = "open";
+      this.notify("stream");
+      void this.resync();
+    };
+    source.onerror = () => {
+      this.stream = "reconnecting";
+      this.notify("stream");
+      // The browser retries on its own unless the host refused the stream outright.
+      if (source.readyState === EventSource.CLOSED && this.source === source)
+        this.reopenTimer = setTimeout(() => this.open(), 3000);
+    };
+    const on = <K extends keyof StreamEvents>(name: K, handle: (data: StreamEvents[K]) => void) =>
+      source.addEventListener(name, (event) => handle(JSON.parse(event.data)));
+    on("session", (session) => {
+      this.session = session;
+      this.notify("session");
+    });
+    on("sample", (sample) => {
+      this.hostSkewMs = Math.min(this.hostSkewMs, Date.now() - Date.parse(sample.receivedAt));
+      this.samples.set(sample.path, sample);
+      this.notify("samples");
+    });
+    on("job", (job) => {
+      this.jobs.set(job.id, job);
+      this.notify("jobs");
+    });
+    on("device", (device) => {
+      this.devices.set(device.id, device);
+      this.notify("devices");
+    });
+    on("timeline", (entry) => this.addTimeline([entry]));
+  }
+
+  /** Catch up on what the stream does not replay: every (re)open may follow a gap. */
+  private async resync() {
+    try {
+      const since = this.timeline.at(-1)?.at;
+      const [session, jobs, devices, timeline, watch] = await Promise.all([
+        getJson("session"),
+        getJson("jobs"),
+        getJson("hardware"),
+        getJson("timeline", since ? { since } : {}),
+        getJson("watch"),
+      ]);
+      this.session = session;
+      this.jobs = new Map(jobs.map((job) => [job.id, job]));
+      this.devices = new Map(devices.map((device) => [device.id, device]));
+      this.watch = watch;
+      this.addTimeline(timeline);
+      for (const topic of ["session", "jobs", "devices", "watch"] as const) this.notify(topic);
+    } catch (error) {
+      this.reportError(error);
+    }
+  }
+
+  private addTimeline(entries: TimelineEntry[]) {
+    for (const entry of entries) {
+      const key = timelineKey(entry);
+      const existing = this.timelineByKey.get(key);
+      this.timelineByKey.set(key, entry);
+      if (existing) {
+        this.timeline[this.timeline.indexOf(existing)] = entry;
+        continue;
+      }
+      const at = Date.parse(entry.at);
+      let index = this.timeline.length;
+      while (index > 0 && Date.parse(this.timeline[index - 1]!.at) > at) index--;
+      this.timeline.splice(index, 0, entry);
+    }
+    for (const dropped of this.timeline.splice(0, this.timeline.length - TIMELINE_LIMIT))
+      this.timelineByKey.delete(timelineKey(dropped));
+    this.notify("timeline");
+  }
+
+  async saveWatch(groups: Record<string, string[]>) {
+    try {
+      this.watch = await putJson("watch", { groups });
+      this.notify("watch");
+    } catch (error) {
+      this.reportError(error);
+    }
+  }
+}