@tsplc/debug 0.0.0-stage → 0.2.17

package/src/http.ts

@@ -0,0 +1,155 @@
+import { readFile } from "node:fs/promises";
+import { z } from "zod";
+import type { Interest, Sample } from "./api.ts";
+import { DebugError, type Debugger, type StreamMessage } from "./debugger.ts";
+import { debugManifest } from "./manifest.ts";
+import { loadUi } from "./ui/index.ts";
+import { watchGroupsSchema } from "./watch.ts";
+
+/** Comments keep proxies and Bun's idle timeout from closing a quiet stream. */
+const heartbeatMs = 5000;
+const encoder = new TextEncoder();
+
+const json = (body: unknown, status = 200) =>
+  Response.json(body, { status, headers: { "Cache-Control": "no-store" } });
+
+const list = (value: string | null) =>
+  (value ?? "")
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+
+export const loadManifest = async (file: string) =>
+  debugManifest.parse(JSON.parse(await readFile(file, "utf8")));
+
+/** What a stream's page shows, from its query. */
+const interest = (search: URLSearchParams): Interest => {
+  const jobs = list(search.get("jobs")).map(Number);
+  if (!jobs.every(Number.isInteger)) throw new DebugError("jobs must be job ids", 400);
+  return {
+    watch: list(search.get("watch")),
+    jobs,
+    health: list(search.get("health")),
+    devices: list(search.get("devices")),
+  };
+};
+
+/** Every stream event, plus samples of the watched paths and states of the shown jobs and devices. */
+const stream = (debug: Debugger, { watch, ...shown }: Interest) => {
+  // Refuse a watch that matches too much before the stream starts.
+  debug.paths.expand(watch);
+  let stop = () => {};
+  return new Response(
+    new ReadableStream<Uint8Array>({
+      start: (controller) => {
+        let open = true;
+        const write = (text: string) => {
+          if (open) controller.enqueue(encoder.encode(text));
+        };
+        const send = ({ event, data }: StreamMessage) =>
+          write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+        send({ event: "session", data: debug.session() });
+        const latest = new Map<string, { sample: Sample; sentAt: number }>();
+        const sendSample = (sample: Sample) => {
+          latest.set(sample.path, { sample, sentAt: Date.now() });
+          send({ event: "sample", data: sample });
+        };
+        const unsubscribe = debug.subscribe(send);
+        const unwatch = debug.watch(watch, sendSample);
+        const unshow = debug.show(shown);
+        const heartbeat = setInterval(() => write(": keepalive\n\n"), heartbeatMs);
+        // Over OPC UA, samples come only on change. While the session holds, an unchanged value
+        // is still current, so it is sent again each interval; clients mark samples stale by their age.
+        const { intervalMs } = debug.session().reading;
+        const refresh = setInterval(() => {
+          if (debug.session().connection.state !== "connected") return;
+          const now = Date.now();
+          for (const { sample, sentAt } of latest.values())
+            if (now - sentAt >= intervalMs)
+              sendSample({ ...sample, receivedAt: new Date(now).toISOString() });
+        }, intervalMs);
+        stop = () => {
+          open = false;
+          clearInterval(heartbeat);
+          clearInterval(refresh);
+          unsubscribe();
+          unwatch();
+          unshow();
+        };
+      },
+      cancel: () => stop(),
+    }),
+    { headers: { "Content-Type": "text/event-stream", "Cache-Control": "no-store" } },
+  );
+};
+
+/**
+ * The debugger's routes (docs/design/debugging.md), with `route` the request's path below where
+ * the host mounts them. There is no route that writes to the controller; hosts authenticate.
+ */
+export const createDebugHandler =
+  (debug: Debugger, log: (message: string) => void) =>
+  async (request: Request, route: string): Promise<Response> => {
+    const { searchParams } = new URL(request.url);
+    const key = `${request.method} ${route}`;
+    try {
+      switch (key) {
+        case "GET /":
+          return new Response((await loadUi()).html, {
+            headers: { "Content-Type": "text/html; charset=utf-8" },
+          });
+        case "GET /ui.js":
+          return new Response((await loadUi()).script, {
+            headers: { "Content-Type": "text/javascript; charset=utf-8" },
+          });
+        case "GET /api/session":
+          return json(debug.session());
+        case "GET /api/manifest":
+          return json(debug.manifest);
+        case "GET /api/stream":
+          return stream(debug, interest(searchParams));
+        case "GET /api/values":
+          return json(await debug.values(list(searchParams.get("paths"))));
+        case "GET /api/jobs":
+          return json(debug.jobs());
+        case "GET /api/hardware":
+          return json(debug.hardware());
+        case "GET /api/timeline":
+          return json(debug.timeline(searchParams.get("since") ?? undefined));
+        case "GET /api/watch":
+          return json(debug.watchGroups());
+        case "PUT /api/watch":
+          return json(await debug.saveWatchGroups(watchGroupsSchema.parse(await request.json())));
+      }
+      return json({ error: `No route ${key}` }, 404);
+    } catch (error) {
+      if (error instanceof DebugError) return json({ error: error.message }, error.status);
+      // RangeError: a watch matches too many values; SyntaxError: a body isn't JSON.
+      if (error instanceof RangeError || error instanceof SyntaxError)
+        return json({ error: error.message }, 400);
+      if (error instanceof z.ZodError) return json({ error: z.prettifyError(error) }, 400);
+      log(`${key} failed: ${error instanceof Error ? error.stack : String(error)}`);
+      return json({ error: "The debugger failed; see its log" }, 500);
+    }
+  };
+
+/**
+ * Serves the debugger on 127.0.0.1 without a token. Requests that name another host are refused,
+ * so no website can reach it by rebinding a domain name to 127.0.0.1.
+ */
+export const serveDebugger = (
+  debug: Debugger,
+  options: { port: number; log: (message: string) => void },
+) => {
+  const handle = createDebugHandler(debug, options.log);
+  return Bun.serve({
+    hostname: "127.0.0.1",
+    port: options.port,
+    fetch: (request) => {
+      const host = request.headers.get("host")?.replace(/:\d+$/, "");
+      if (host !== "127.0.0.1" && host !== "localhost")
+        return json({ error: "Use http://127.0.0.1 or http://localhost" }, 403);
+      return handle(request, new URL(request.url).pathname);
+    },
+  });
+};

package/src/index.ts

@@ -0,0 +1,8 @@
+export type * from "./api.ts";
+export type { Connection, TargetAdapter, TargetRead, TargetSample } from "./adapter.ts";
+export { createDebugger, DebugError, type Debugger, type DebuggerOptions } from "./debugger.ts";
+export { createDebugHandler, loadManifest, serveDebugger } from "./http.ts";
+export { createLoginAdapter, LoginUnavailable, noLogin } from "./login.ts";
+export { createOpcUaAdapter, opcUaConnection } from "./opcua.ts";
+export { createPaths, type PathNode, type Paths, type ResolvedPath } from "./paths.ts";
+export { timelineEntries } from "./timeline.ts";

package/src/jobs.ts

@@ -0,0 +1,115 @@
+import type { TargetRead, TargetSample } from "./adapter.ts";
+import type { JobState, RequestTrace, Session } from "./api.ts";
+import type { DebugJob, DebugType } from "./manifest.ts";
+
+const scalar = (iec: string): DebugType => ({ kind: "scalar", iec });
+
+/** What the trace said of a job: whether it is running, and when it last started. */
+export interface TracedJob {
+  busy: boolean;
+  startedAt?: string;
+}
+
+/** The job's `busy` flag, read while a page shows the job and the trace says nothing of it. */
+export const busyRead = (job: DebugJob): TargetRead => ({
+  target: `${job.target}.busy`,
+  type: scalar("BOOL"),
+});
+
+/** What a busy job shows: where it waits, since when, and its latest request. */
+export const detailReads = (job: DebugJob): TargetRead[] => [
+  { target: `${job.target}.step`, type: scalar("UINT") },
+  { target: `${job.target}.cancelling`, type: scalar("BOOL") },
+  ...(job.startedAt ? [{ target: job.startedAt, type: scalar("UDINT") }] : []),
+  ...job.requests.map(({ sequence }) => ({ target: sequence, type: scalar("UDINT") })),
+];
+
+/**
+ * From the last read, else from the trace; null when neither knows. A read wins: a job's caller
+ * stops running it once it finishes, so the trace can miss the finish.
+ */
+export const busyOf = (
+  job: DebugJob,
+  value: (target: string) => TargetSample | undefined,
+  traced: TracedJob | undefined,
+) => {
+  const read = value(busyRead(job).target);
+  return read?.quality === "good" ? read.value === true : (traced?.busy ?? null);
+};
+
+const numberOf = (sample: TargetSample | undefined) =>
+  sample?.quality === "good" && typeof sample.value === "number" ? sample.value : undefined;
+
+/**
+ * A job as the debugger shows it at host time `now`. Details are shown only while it is busy;
+ * its last start stays, so a later run tells a failure apart from the current state. Without a
+ * clock estimate there is no start time from the PLC's own `startedAt`.
+ */
+export const jobState = (
+  job: DebugJob,
+  inputs: {
+    value: (target: string) => TargetSample | undefined;
+    traced: TracedJob | undefined;
+    failure: JobState["failure"];
+    /** Busy, but its details aren't read for want of room in the poll. */
+    unread: boolean;
+    clock: Session["clock"];
+    now: number;
+    /** The server's trace of a call, which the PLC tags with its job and the call site's count. */
+    request: (call: { job: number; service: string; sequence: number }) => RequestTrace | undefined;
+  },
+): JobState => {
+  const { value, traced, clock, now } = inputs;
+  const busy = busyOf(job, value, traced);
+  const startedPlc = job.startedAt === undefined ? undefined : numberOf(value(job.startedAt));
+  const startedAt =
+    traced?.startedAt ??
+    (clock && startedPlc !== undefined
+      ? new Date(startedPlc - clock.offsetMs).toISOString()
+      : undefined);
+  const base: JobState = {
+    id: job.id,
+    quality: value(busyRead(job).target)?.quality ?? (traced ? "good" : "unavailable"),
+    busy,
+    ...(startedAt && { startedAt }),
+    ...(inputs.failure && { failure: inputs.failure }),
+  };
+  if (!busy) return base;
+  if (inputs.unread) return { ...base, unread: true };
+
+  const step = numberOf(value(`${job.target}.step`));
+  const current = job.steps.find((candidate) => candidate.step === step);
+  // Each call site counts its own requests, so the latest is the one the server saw start last,
+  // or the one counted furthest while the server has yet to report them.
+  const calls = job.requests
+    .map((call) => {
+      const sequence = numberOf(value(call.sequence)) ?? 0;
+      const trace = inputs.request({ job: call.job ?? job.id, service: call.service, sequence });
+      return { service: call.service, sequence, trace };
+    })
+    .filter(({ sequence }) => sequence > 0);
+  const later = (call: (typeof calls)[number], than: (typeof calls)[number]) =>
+    call.trace && than.trace
+      ? call.trace.startedAt > than.trace.startedAt
+      : call.sequence > than.sequence;
+  const latest = calls.reduce<(typeof calls)[number] | undefined>(
+    (latest, call) => (latest && !later(call, latest) ? latest : call),
+    undefined,
+  );
+  const cancelling = value(`${job.target}.cancelling`);
+
+  return {
+    ...base,
+    ...(cancelling?.quality === "good" && { cancelling: cancelling.value === true }),
+    ...(step !== undefined && { step }),
+    ...(current && { current: { kind: current.kind, range: current.range, text: current.text } }),
+    ...(startedAt && { elapsedMs: Math.max(0, now - Date.parse(startedAt)) }),
+    ...(latest && {
+      request: {
+        service: latest.service,
+        sequence: latest.sequence,
+        ...(latest.trace && { trace: latest.trace }),
+      },
+    }),
+  };
+};

package/src/login.ts

@@ -0,0 +1,284 @@
+import { setTimeout as delay } from "node:timers/promises";
+import type { Connection, TargetAdapter, TargetRead, TargetSample } from "./adapter.ts";
+import type { DebugType } from "./manifest.ts";
+
+/** Why the login can't read now; `state` is what the debugger shows meanwhile. */
+export class LoginUnavailable extends Error {
+  constructor(message: string, options?: ErrorOptions & { state?: "connecting" | "unavailable" }) {
+    super(message, options);
+    this.state = options?.state ?? "unavailable";
+  }
+
+  readonly state: "connecting" | "unavailable";
+}
+
+export const noLogin = "Live values need an engineering login: run `tsplc login`.";
+
+/** How long to wait between attempts while there is no login to read through. */
+const retryMs = 5000;
+
+const integerTypes = new Set([
+  ...["SINT", "INT", "DINT", "LINT", "USINT", "UINT", "UDINT", "ULINT"],
+  ...["BYTE", "WORD", "DWORD", "LWORD"],
+]);
+const timeUnits: Record<string, number> = {
+  d: 86_400_000,
+  h: 3_600_000,
+  m: 60_000,
+  s: 1000,
+  ms: 1,
+  us: 0.001,
+  ns: 0.000_001,
+};
+
+const typeName = (type: DebugType) => (type.kind === "scalar" ? type.iec : type.kind);
+
+const message = (error: unknown) => (error instanceof Error ? error.message : String(error));
+
+/** `16#FF`, `2#1010`, `-42`, with IEC's digit separators; beyond doubles' exact range, a string. */
+const integer = (text: string) => {
+  const radix = /^(2|8|16)#([0-9a-f_]+)$/i.exec(text);
+  const digits = radix ? radix[2]!.replaceAll("_", "") : text.replaceAll("_", "");
+  if (!radix && !/^[+-]?\d+$/.test(digits)) return undefined;
+  const value = BigInt(radix ? `0${{ 2: "b", 8: "o", 16: "x" }[radix[1]!]}${digits}` : digits);
+  return Number.isSafeInteger(Number(value)) ? Number(value) : String(value);
+};
+
+/** `T#1h2m3s4ms`, `TIME#-1.5s`, `LTIME#5us`, in milliseconds. */
+const duration = (text: string) => {
+  const body = /^L?T(?:IME)?#(-?)(.+)$/i.exec(text);
+  if (!body) return undefined;
+  const parts = [...body[2]!.replaceAll("_", "").matchAll(/(\d+(?:\.\d+)?)(ms|us|ns|d|h|m|s)/gi)];
+  if (parts.map(([part]) => part).join("") !== body[2]!.replaceAll("_", "")) return undefined;
+  const ms = parts.reduce(
+    (total, [, amount, unit]) => total + Number(amount) * timeUnits[unit!.toLowerCase()]!,
+    0,
+  );
+  return body[1] ? -ms : ms;
+};
+
+/** `'it$'s'` or `"wide"`, with IEC's `$` escapes. */
+const quoted = (text: string) => {
+  const body = /^(['"])(.*)\1$/s.exec(text);
+  if (!body) return undefined;
+  return body[2]!.replace(/\$([0-9a-f]{2}|[$'"lnprt])/gi, (_, code: string) => {
+    if (code.length === 2) return String.fromCharCode(parseInt(code, 16));
+    const named: Record<string, string> = { l: "\n", n: "\n", p: "\f", r: "\r", t: "\t" };
+    return named[code.toLowerCase()] ?? code;
+  });
+};
+
+/**
+ * A value as `read_value` returns it, in the form the debugger decodes: BOOL as a boolean,
+ * numbers and TIME (in ms) as numbers, enums as their member's number (or its name when the
+ * manifest doesn't list it), STRING unquoted, and arrays read whole as arrays. Undefined when the
+ * text doesn't fit the type.
+ */
+export const parseLoginValue = (type: DebugType, text: string): unknown => {
+  const trimmed = text.trim();
+  // Typed literals such as `INT#5`; TIME's own `T#` prefix is kept.
+  const untyped = trimmed.replace(/^(?!L?T(?:IME)?#)[a-z_]+#(?=.)/i, "");
+  switch (type.kind) {
+    case "enum": {
+      const number = integer(untyped);
+      if (typeof number === "number") return number;
+      const named = /^(?:\w+\.)*(\w+)(?:\s*\((-?\d+)\))?$/.exec(untyped);
+      if (!named) return undefined;
+      return type.members[named[1]!] ?? (named[2] === undefined ? named[1] : Number(named[2]));
+    }
+    case "array": {
+      const items = /^\[?(.*?)\]?$/s.exec(untyped)![1]!.trim();
+      if (!items) return [];
+      // Only raw assembly bytes are read whole; their elements are scalars named by IEC type.
+      const element = { kind: "scalar", iec: type.element } as const;
+      const values = items.split(/\s*,\s*/).map((item) => parseLoginValue(element, item));
+      return values.length === type.length && values.every((value) => value !== undefined)
+        ? values
+        : undefined;
+    }
+    case "record":
+      return undefined;
+    case "scalar":
+      break;
+  }
+  const iec = type.iec.toUpperCase();
+  if (iec === "BOOL") return { TRUE: true, FALSE: false, 1: true, 0: false }[untyped.toUpperCase()];
+  if (integerTypes.has(iec)) return integer(untyped);
+  if (iec === "REAL" || iec === "LREAL") {
+    const number = Number(untyped);
+    return untyped !== "" && !Number.isNaN(number) ? number : undefined;
+  }
+  if (iec === "TIME" || iec === "LTIME") return duration(trimmed);
+  if (/^W?STRING\b/.test(iec)) return quoted(trimmed) ?? trimmed;
+  return trimmed;
+};
+
+/**
+ * Reads through an engineering login that answers `read(expressions)` with CODESYS's own text
+ * for each value: no publication is needed, and nothing is subscribed. Watched targets are polled
+ * every `samplingMs`, one command per poll, and a poll that overruns delays the next by as long.
+ *
+ * A read fails as a whole when one expression can't be read, so a failing read is retried with
+ * `probe` alone: if that fails too the login is lost; otherwise the read is split until the
+ * expressions that fail are found, and those are reported bad until the next login.
+ */
+export const createLoginAdapter = (options: {
+  read: (expressions: string[]) => Promise<Record<string, string>>;
+  /** A target that always reads, such as the build id. */
+  probe: string;
+  endpoint: string;
+  samplingMs?: number;
+}): TargetAdapter => {
+  const samplingMs = options.samplingMs ?? 1000;
+  let connection: Connection = { state: "connecting", since: new Date().toISOString() };
+  const connectionListeners = new Set<(connection: Connection) => void>();
+  const subscriptions = new Set<{
+    targets: readonly TargetRead[];
+    listener: (target: string, sample: TargetSample) => void;
+    intervalMs: number;
+    due: number;
+  }>();
+  /** Expressions the controller refused, with its reason, until the login is lost. */
+  const rejected = new Map<string, string>();
+  const controller = new AbortController();
+
+  const setConnection = (state: Connection["state"], error?: string) => {
+    if (controller.signal.aborted) return;
+    if (connection.state === state && connection.error === error) return;
+    if (state !== "connected") rejected.clear();
+    connection = { state, since: new Date().toISOString(), ...(error && { error }) };
+    for (const listener of connectionListeners) listener(connection);
+  };
+
+  const split = async (expressions: string[]): Promise<Record<string, string>> => {
+    try {
+      return await options.read(expressions);
+    } catch (error) {
+      if (error instanceof LoginUnavailable) throw error;
+      if (expressions.length === 1) {
+        rejected.set(expressions[0]!, message(error));
+        return {};
+      }
+      const half = Math.ceil(expressions.length / 2);
+      return {
+        ...(await split(expressions.slice(0, half))),
+        ...(await split(expressions.slice(half))),
+      };
+    }
+  };
+
+  const readText = async (expressions: string[]) => {
+    try {
+      return await options.read(expressions);
+    } catch (error) {
+      if (error instanceof LoginUnavailable) throw error;
+      // One expression the controller can't read fails the whole read; a lost login fails the probe too.
+      await options.read([options.probe]);
+      return split(expressions);
+    }
+  };
+
+  /** Never fails: while the login can't read, every target is unavailable. */
+  const read = async (targets: readonly TargetRead[]) => {
+    const unique = [...new Map(targets.map((target) => [target.target, target])).values()];
+    const expressions = unique
+      .map(({ target }) => target)
+      .filter((target) => !rejected.has(target));
+    const samples = new Map<string, TargetSample>();
+    let values: Record<string, string>;
+    const overdue = setTimeout(
+      () => setConnection("lost", "The engineering login stopped answering"),
+      3 * samplingMs,
+    );
+    try {
+      values = expressions.length ? await readText(expressions) : {};
+      setConnection("connected");
+    } catch (error) {
+      setConnection(error instanceof LoginUnavailable ? error.state : "lost", message(error));
+      const receivedAt = new Date().toISOString();
+      for (const { target } of unique)
+        samples.set(target, {
+          value: null,
+          quality: "unavailable",
+          status: message(error),
+          receivedAt,
+        });
+      return samples;
+    } finally {
+      clearTimeout(overdue);
+    }
+    const receivedAt = new Date().toISOString();
+    for (const { target, type } of unique) {
+      const text = values[target];
+      const refused = rejected.get(target);
+      const value = text === undefined ? undefined : parseLoginValue(type, text);
+      samples.set(
+        target,
+        value !== undefined
+          ? { value, quality: "good", status: "Good", receivedAt }
+          : {
+              value: text ?? null,
+              quality: "bad",
+              status:
+                refused ??
+                (text === undefined ? "Not returned by the login" : `Not a ${typeName(type)}`),
+              receivedAt,
+            },
+      );
+    }
+    return samples;
+  };
+
+  const poll = async () => {
+    while (!controller.signal.aborted) {
+      const started = Date.now();
+      // Timers fire a little early or late; a subscription due within half an interval is read now.
+      const due = [...subscriptions].filter(({ due }) => due <= started + samplingMs / 2);
+      if (due.length) {
+        for (const subscription of due) subscription.due = started + subscription.intervalMs;
+        // Closing the debugger must not wait for an engineering worker that stopped answering.
+        const stopped = Promise.withResolvers<void>();
+        const stop = () => stopped.resolve();
+        controller.signal.addEventListener("abort", stop, { once: true });
+        const samples = await Promise.race([
+          read(due.flatMap(({ targets }) => targets)),
+          stopped.promise,
+        ]).finally(() => controller.signal.removeEventListener("abort", stop));
+        if (!samples || controller.signal.aborted) break;
+        for (const subscription of due)
+          if (subscriptions.has(subscription))
+            for (const { target } of subscription.targets)
+              subscription.listener(target, samples.get(target)!);
+      }
+      const took = Date.now() - started;
+      const waiting = connection.state !== "connected" && connection.state !== "connecting";
+      await delay(waiting ? retryMs : took > samplingMs ? took : samplingMs - took, undefined, {
+        signal: controller.signal,
+      }).catch(() => undefined);
+    }
+  };
+  const running = poll();
+
+  return {
+    method: "engineering login",
+    endpoint: options.endpoint,
+    samplingMs,
+    connection: () => connection,
+    onConnection: (listener) => {
+      connectionListeners.add(listener);
+      return () => connectionListeners.delete(listener);
+    },
+    read,
+    subscribe: (targets, listener, intervalMs = samplingMs) => {
+      const subscription = { targets, listener, intervalMs, due: 0 };
+      subscriptions.add(subscription);
+      return () => subscriptions.delete(subscription);
+    },
+    close: async () => {
+      controller.abort();
+      subscriptions.clear();
+      connectionListeners.clear();
+      await running;
+    },
+  };
+};