@tsplc/debug 0.0.0-stage → 0.2.16

package/src/timeline.ts

@@ -0,0 +1,78 @@
+import type { AppRecord, ConnectionState, RequestTrace, TimelineEntry, TraceEvent } from "./api.ts";
+
+export type Entry<Kind extends TimelineEntry["kind"]> = Extract<TimelineEntry, { kind: Kind }>;
+type Details<Kind extends TimelineEntry["kind"]> = Omit<
+  Entry<Kind>,
+  "at" | "approximate" | "source" | "kind"
+>;
+
+/**
+ * Timeline entries by source. The PLC's records are placed on the app server's clock from their
+ * age when the server received them, and the server keeps its own clock, so those are
+ * approximate. The agent's entries reach a debugger only when the agent hosts it, on the same clock.
+ */
+export const timelineEntries = {
+  app: (at: string, task: string, sequence: number, record: AppRecord): Entry<"app"> => ({
+    at,
+    approximate: true,
+    source: "plc",
+    kind: "app",
+    task,
+    sequence,
+    record,
+  }),
+  trace: (at: string, trace: TraceEvent): Entry<"trace"> => ({
+    at,
+    approximate: true,
+    source: "plc",
+    kind: "trace",
+    trace,
+  }),
+  request: (request: RequestTrace): Entry<"request"> => ({
+    at: request.startedAt,
+    approximate: true,
+    source: "server",
+    kind: "request",
+    request,
+  }),
+  deploy: (at: string, details: Details<"deploy">): Entry<"deploy"> => ({
+    at,
+    approximate: false,
+    source: "agent",
+    kind: "deploy",
+    ...details,
+  }),
+  audit: (at: string, details: Details<"audit">): Entry<"audit"> => ({
+    at,
+    approximate: false,
+    source: "agent",
+    kind: "audit",
+    ...details,
+  }),
+  connection: (at: string, state: ConnectionState, error?: string): Entry<"connection"> => ({
+    at,
+    approximate: false,
+    source: "debugger",
+    kind: "connection",
+    state,
+    ...(error && { error }),
+  }),
+};
+
+/** Entries from every source in time order, keeping the newest `limit`. */
+export const createTimeline = (limit = 10_000) => {
+  const entries: TimelineEntry[] = [];
+  return {
+    add: (entry: TimelineEntry) => {
+      // Sources arrive late and out of order, so insert after the last entry not later than it.
+      let index = entries.length;
+      while (index > 0 && entry.at < (entries[index - 1]?.at ?? entry.at)) index--;
+      entries.splice(index, 0, entry);
+      if (entries.length > limit) entries.splice(0, entries.length - limit);
+    },
+    /** Entries after `at`, or all of them. */
+    since: (at?: string) => (at ? entries.filter((entry) => entry.at > at) : [...entries]),
+  };
+};
+
+export type Timeline = ReturnType<typeof createTimeline>;

package/src/trace.ts

@@ -0,0 +1,45 @@
+import type { TelemetryRecord } from "@tsplc/server/telemetry";
+import type { TraceEvent } from "./api.ts";
+import type { DebugJob, DebugManifest } from "./manifest.ts";
+import type { Paths } from "./paths.ts";
+
+export type TraceRecord = Extract<TelemetryRecord, { kind: "trace" }>;
+
+/**
+ * Decodes the opt-in trace through the manifest's event sites (docs/design/debugging.md). Only
+ * records of the manifest's own build may be decoded: another build's site ids mean other code.
+ */
+export const createTraceDecoder = (manifest: DebugManifest, paths: Paths) => {
+  const sites = new Map(manifest.events.map((site) => [site.id, site]));
+  const jobs = new Map(manifest.jobs.map((job) => [job.id, job]));
+  const jobSites = new Map(
+    manifest.events.flatMap(({ id, job: jobId, phase }) => {
+      const job = jobId === undefined ? undefined : jobs.get(jobId);
+      return job && phase ? [[id, { job, started: phase === "started" }] as const] : [];
+    }),
+  );
+
+  return {
+    decode: (record: TraceRecord, task: string, sequence: number): TraceEvent | undefined => {
+      const site = sites.get(record.site);
+      if (!site) return undefined;
+      return {
+        sequence,
+        task,
+        scan: record.scan,
+        plcTime: record.time,
+        site: site.id,
+        value: paths.decode(site.type, record.value),
+        operands: site.operands.map(({ text, path, stable, type }, index) => ({
+          text,
+          ...(path && { path }),
+          stable,
+          value: paths.decode(type, record.operands[index]),
+        })),
+      };
+    },
+    /** The job a record starts or finishes, if its site is a job's. */
+    job: (record: TraceRecord): { job: DebugJob; started: boolean } | undefined =>
+      jobSites.get(record.site),
+  };
+};

package/src/ui/bits.ts

@@ -0,0 +1,41 @@
+import type { DebugChannel, DebugIo } from "../manifest.ts";
+
+/** An unsigned little-endian field of an assembly, as EtherNet/IP lays them out; null past 32 bits or the end. */
+export const readBits = (bytes: number[], offsetBits: number, bits: number): number | null => {
+  if (bits > 32 || offsetBits + bits > bytes.length * 8) return null;
+  let value = 0;
+  for (let bit = 0; bit < bits; bit++) {
+    const at = offsetBits + bit;
+    if ((bytes[at >> 3]! >> (at & 7)) & 1) value += 2 ** bit;
+  }
+  return value;
+};
+
+interface MappedBit {
+  channel: DebugChannel;
+  paths: string[];
+}
+
+/** What each bit of one assembly carries: the channel covering it and the TypeScript paths mapped to that channel. */
+export const mapBits = (
+  device: string,
+  direction: "input" | "output",
+  bytes: number,
+  channels: DebugChannel[],
+  io: DebugIo[],
+): (MappedBit | undefined)[] => {
+  const bits: (MappedBit | undefined)[] = Array.from({ length: bytes * 8 }, () => undefined);
+  for (const channel of channels) {
+    if (channel.direction !== direction) continue;
+    const paths = io
+      .filter((entry) => entry.device === device && entry.channel === channel.id)
+      .map((entry) => entry.path);
+    for (
+      let bit = channel.offsetBits;
+      bit < channel.offsetBits + channel.bits && bit < bits.length;
+      bit++
+    )
+      bits[bit] = { channel, paths };
+  }
+  return bits;
+};

package/src/ui/client.ts

@@ -0,0 +1,48 @@
+import type { ApiResponses } from "../api.ts";
+
+/**
+ * The debugger API, by relative URL so the UI works under the agent's `/debug` prefix. A `?token=` on the
+ * page is passed on to every call, since EventSource cannot send headers.
+ */
+const token = new URLSearchParams(location.search).get("token");
+
+type Method = "GET" | "PUT";
+type RouteOf<M extends Method> = {
+  [K in keyof ApiResponses]: K extends `${M} /api/${infer Route}` ? Route : never;
+}[keyof ApiResponses];
+type ResponseOf<M extends Method, R extends string> = ApiResponses[Extract<
+  keyof ApiResponses,
+  `${M} /api/${R}`
+>];
+
+export const apiUrl = (route: string, params: Record<string, string> = {}) => {
+  const search = new URLSearchParams(params);
+  if (token) search.set("token", token);
+  const query = search.toString();
+  return `./api/${route}${query ? `?${query}` : ""}`;
+};
+
+const request = async <M extends Method, R extends RouteOf<M>>(
+  method: M,
+  route: R,
+  params?: Record<string, string>,
+  body?: unknown,
+): Promise<ResponseOf<M, R>> => {
+  const response = await fetch(apiUrl(route, params), {
+    method,
+    headers: body === undefined ? undefined : { "Content-Type": "application/json" },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  if (!response.ok) {
+    const detail = response.headers.get("Content-Type")?.includes("json")
+      ? (await response.json()).error
+      : await response.text();
+    throw new Error(`${method} ${route}: ${response.status} ${detail}`);
+  }
+  return response.json();
+};
+
+export const getJson = <R extends RouteOf<"GET">>(route: R, params?: Record<string, string>) =>
+  request("GET", route, params);
+export const putJson = <R extends RouteOf<"PUT">>(route: R, body: unknown) =>
+  request("PUT", route, undefined, body);