@tsplc/debug 0.2.17 → 0.2.18

package/src/telemetry.ts

@@ -1,4 +1,8 @@
-import type { TelemetryBatch, TelemetryRecord, TelemetryReply } from "@tsplc/server/telemetry";
+import type {
+	TelemetryBatch,
+	TelemetryRecord,
+	TelemetryReply,
+} from "@tsplc/server/telemetry";
 import { recordedAt } from "@tsplc/server/telemetry-log";
 import type { Session } from "./api.ts";
 import type { DebugManifest } from "./manifest.ts";
@@ -8,11 +12,11 @@ const clockWindowMs = 60_000;
 
 /** A record with the batch it came in, numbered in its task's sequence, at its time on the server's clock. */
 export interface ReceivedRecord {
-  build: string;
-  task: string;
-  sequence: number;
-  at: string;
-  record: TelemetryRecord;
+	build: string;
+	task: string;
+	sequence: number;
+	at: string;
+	record: TelemetryRecord;
 }
 
 /**
@@ -20,91 +24,101 @@ export interface ReceivedRecord {
  * once, keeps the tasks' scan rates, and estimates the PLC's clock against the server's.
  */
 export const createTelemetryFollower = (manifest: DebugManifest) => {
-  const intervals = new Map(manifest.tasks.map(({ name, intervalMs }) => [name, intervalMs]));
-  const tasks = new Map<string, Session["tasks"][number]>(
-    manifest.tasks.map(({ name }) => [
-      name,
-      { name, scan: null, scansPerSecond: null, dropped: 0 },
-    ]),
-  );
-  const rates = new Map<string, { scan: number; now: number }>();
-  let estimates: { offsetMs: number; intervalMs: number; at: number }[] = [];
-  let newest = 0;
-  let build: string | null = null;
+	const intervals = new Map(
+		manifest.tasks.map(({ name, intervalMs }) => [name, intervalMs]),
+	);
+	const tasks = new Map<string, Session["tasks"][number]>(
+		manifest.tasks.map(({ name }) => [
+			name,
+			{ name, scan: null, scansPerSecond: null, dropped: 0 },
+		]),
+	);
+	const rates = new Map<string, { scan: number; now: number }>();
+	let estimates: { offsetMs: number; intervalMs: number; at: number }[] = [];
+	let newest = 0;
+	let build: string | null = null;
 
-  /**
-   * A batch's `now` was read before it was sent, so `now − receivedAt` falls short of the true
-   * offset by its transit time: the largest recent estimate is the closest, and their spread,
-   * plus a scan, bounds how far off it may be.
-   */
-  const clock = (): Session["clock"] => {
-    if (!estimates.length) return null;
-    const offsets = estimates.map(({ offsetMs }) => offsetMs);
-    const best = estimates.reduce((best, estimate) =>
-      estimate.offsetMs > best.offsetMs ? estimate : best,
-    );
-    return {
-      offsetMs: best.offsetMs,
-      uncertaintyMs: best.offsetMs - Math.min(...offsets) + best.intervalMs,
-    };
-  };
+	/**
+	 * A batch's `now` was read before it was sent, so `now − receivedAt` falls short of the true
+	 * offset by its transit time: the largest recent estimate is the closest, and their spread,
+	 * plus a scan, bounds how far off it may be.
+	 */
+	const clock = (): Session["clock"] => {
+		if (!estimates.length) {
+			return null;
+		}
+		const offsets = estimates.map(({ offsetMs }) => offsetMs);
+		const best = estimates.reduce((best, estimate) =>
+			estimate.offsetMs > best.offsetMs ? estimate : best,
+		);
+		return {
+			offsetMs: best.offsetMs,
+			uncertaintyMs: best.offsetMs - Math.min(...offsets) + best.intervalMs,
+		};
+	};
 
-  const observe = (batch: TelemetryBatch, receivedAt: number) => {
-    const rate = rates.get(batch.task);
-    // A restarted PLC counts scans and time from zero again.
-    const restarted = rate !== undefined && batch.now < rate.now;
-    if (restarted) estimates = [];
-    estimates = estimates.filter(({ at }) => receivedAt - at < clockWindowMs);
-    estimates.push({
-      offsetMs: batch.now - receivedAt,
-      intervalMs: intervals.get(batch.task) ?? 0,
-      at: receivedAt,
-    });
-    const stats = {
-      name: batch.task,
-      scansPerSecond: tasks.get(batch.task)?.scansPerSecond ?? null,
-      scan: batch.scan,
-      dropped: batch.dropped,
-    };
-    if (!rate || restarted) rates.set(batch.task, { scan: batch.scan, now: batch.now });
-    else if (batch.now - rate.now >= 1000) {
-      stats.scansPerSecond = ((batch.scan - rate.scan) * 1000) / (batch.now - rate.now);
-      rates.set(batch.task, { scan: batch.scan, now: batch.now });
-    }
-    tasks.set(batch.task, stats);
-  };
+	const observe = (batch: TelemetryBatch, receivedAt: number) => {
+		const rate = rates.get(batch.task);
+		// A restarted PLC counts scans and time from zero again.
+		const restarted = rate !== undefined && batch.now < rate.now;
+		if (restarted) {
+			estimates = [];
+		}
+		estimates = estimates.filter(({ at }) => receivedAt - at < clockWindowMs);
+		estimates.push({
+			offsetMs: batch.now - receivedAt,
+			intervalMs: intervals.get(batch.task) ?? 0,
+			at: receivedAt,
+		});
+		const stats = {
+			name: batch.task,
+			scansPerSecond: tasks.get(batch.task)?.scansPerSecond ?? null,
+			scan: batch.scan,
+			dropped: batch.dropped,
+		};
+		if (!rate || restarted) {
+			rates.set(batch.task, { scan: batch.scan, now: batch.now });
+		} else if (batch.now - rate.now >= 1000) {
+			stats.scansPerSecond =
+				((batch.scan - rate.scan) * 1000) / (batch.now - rate.now);
+			rates.set(batch.task, { scan: batch.scan, now: batch.now });
+		}
+		tasks.set(batch.task, stats);
+	};
 
-  return {
-    /** Where the next pull starts. */
-    since: () => newest,
-    /** Takes a reply to `GET /tsplc/telemetry?since=<since()>`; a restarted server starts over. */
-    accept: (reply: TelemetryReply): ReceivedRecord[] => {
-      if (reply.latest < newest) {
-        newest = 0;
-        return [];
-      }
-      const received: ReceivedRecord[] = [];
-      for (const batch of reply.batches) {
-        if (batch.seq <= newest) continue;
-        newest = batch.seq;
-        build = batch.build;
-        const receivedAt = new Date(batch.receivedAt);
-        observe(batch, receivedAt.getTime());
-        batch.records.forEach((record, index) =>
-          received.push({
-            build: batch.build,
-            task: batch.task,
-            sequence: batch.first + index,
-            at: recordedAt(batch, record, receivedAt).toISOString(),
-            record,
-          }),
-        );
-      }
-      return received;
-    },
-    /** The build the newest batch came from. */
-    build: () => build,
-    clock,
-    tasks: () => [...tasks.values()].map((task) => ({ ...task })),
-  };
+	return {
+		/** Where the next pull starts. */
+		since: () => newest,
+		/** Takes a reply to `GET /tsplc/telemetry?since=<since()>`; a restarted server starts over. */
+		accept: (reply: TelemetryReply): ReceivedRecord[] => {
+			if (reply.latest < newest) {
+				newest = 0;
+				return [];
+			}
+			const received: ReceivedRecord[] = [];
+			for (const batch of reply.batches) {
+				if (batch.seq <= newest) {
+					continue;
+				}
+				newest = batch.seq;
+				build = batch.build;
+				const receivedAt = new Date(batch.receivedAt);
+				observe(batch, receivedAt.getTime());
+				batch.records.forEach((record, index) =>
+					received.push({
+						build: batch.build,
+						task: batch.task,
+						sequence: batch.first + index,
+						at: recordedAt(batch, record, receivedAt).toISOString(),
+						record,
+					}),
+				);
+			}
+			return received;
+		},
+		/** The build the newest batch came from. */
+		build: () => build,
+		clock,
+		tasks: () => [...tasks.values()].map((task) => ({ ...task })),
+	};
 };

package/src/timeline.ts

@@ -1,9 +1,18 @@
-import type { AppRecord, ConnectionState, RequestTrace, TimelineEntry, TraceEvent } from "./api.ts";
+import type {
+	AppRecord,
+	ConnectionState,
+	RequestTrace,
+	TimelineEntry,
+	TraceEvent,
+} from "./api.ts";
 
-export type Entry<Kind extends TimelineEntry["kind"]> = Extract<TimelineEntry, { kind: Kind }>;
+export type Entry<Kind extends TimelineEntry["kind"]> = Extract<
+	TimelineEntry,
+	{ kind: Kind }
+>;
 type Details<Kind extends TimelineEntry["kind"]> = Omit<
-  Entry<Kind>,
-  "at" | "approximate" | "source" | "kind"
+	Entry<Kind>,
+	"at" | "approximate" | "source" | "kind"
 >;
 
 /**
@@ -12,67 +21,93 @@ type Details<Kind extends TimelineEntry["kind"]> = Omit<
  * 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 }),
-  }),
+	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 }),
+	}),
+};
+
+/**
+ * Adds `entry` to `entries`, which are oldest first. Sources arrive late and out of order, so it
+ * goes after the last entry not later than it.
+ */
+export const insertInTimeOrder = (
+	entries: TimelineEntry[],
+	entry: TimelineEntry,
+) => {
+	for (let index = entries.length; index >= 0; index--) {
+		const before = entries[index - 1];
+		if (before === undefined || before.at <= entry.at) {
+			entries.splice(index, 0, entry);
+			return;
+		}
+	}
 };
 
 /** 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]),
-  };
+	const entries: TimelineEntry[] = [];
+	return {
+		add: (entry: TimelineEntry) => {
+			insertInTimeOrder(entries, 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

@@ -10,36 +10,46 @@ export type TraceRecord = Extract<TelemetryRecord, { kind: "trace" }>;
  * 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] : [];
-    }),
-  );
+	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),
-  };
+	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

@@ -1,41 +1,57 @@
 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;
+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[];
+	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[],
+	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;
+	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

@@ -8,41 +8,48 @@ 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;
+	[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}`
+	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 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,
+	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();
+	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 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);
+	request("PUT", route, undefined, body);