@tsplc/debug 0.2.17 → 0.2.18

package/src/login.ts

@@ -1,117 +1,35 @@
 import { setTimeout as delay } from "node:timers/promises";
-import type { Connection, TargetAdapter, TargetRead, TargetSample } from "./adapter.ts";
+import type {
+	Connection,
+	TargetAdapter,
+	TargetRead,
+	TargetSample,
+} from "./adapter.ts";
+import { errorMessage } from "./errors.ts";
+import { parseLoginValue } from "./login-value.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";
-  }
+	constructor(
+		message: string,
+		options?: ErrorOptions & { state?: "connecting" | "unavailable" },
+	) {
+		super(message, options);
+		this.state = options?.state ?? "unavailable";
+	}
 
-  readonly state: "connecting" | "unavailable";
+	readonly state: "connecting" | "unavailable";
 }
 
-export const noLogin = "Live values need an engineering login: run `tsplc login`.";
+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;
-};
+const typeName = (type: DebugType) =>
+	type.kind === "scalar" ? type.iec : type.kind;
 
 /**
  * Reads through an engineering login that answers `read(expressions)` with CODESYS's own text
@@ -123,162 +41,224 @@ export const parseLoginValue = (type: DebugType, text: string): unknown => {
  * 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;
+	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 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]!, errorMessage(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);
+		}
+	};
 
-  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);
-  };
+	/** The login's text for each expression, or why it can't read; keeps `connection` current. */
+	const readTexts = async (
+		expressions: string[],
+	): Promise<{ texts: Record<string, string> } | { error: string }> => {
+		const overdue = setTimeout(
+			() => setConnection("lost", "The engineering login stopped answering"),
+			3 * samplingMs,
+		);
+		try {
+			const texts = expressions.length ? await readText(expressions) : {};
+			setConnection("connected");
+			return { texts };
+		} catch (error) {
+			setConnection(
+				error instanceof LoginUnavailable ? error.state : "lost",
+				errorMessage(error),
+			);
+			return { error: errorMessage(error) };
+		} finally {
+			clearTimeout(overdue);
+		}
+	};
 
-  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))),
-      };
-    }
-  };
+	/** A target's value from the login's text, or bad with the reason it has none. */
+	const parsedSample = (
+		{ target, type }: TargetRead,
+		text: string | undefined,
+		receivedAt: string,
+	): TargetSample => {
+		const value = text === undefined ? undefined : parseLoginValue(type, text);
+		if (value !== undefined) {
+			return { value, quality: "good", status: "Good", receivedAt };
+		}
+		const reason =
+			text === undefined
+				? "Not returned by the login"
+				: `Not a ${typeName(type)}`;
+		return {
+			value: text ?? null,
+			quality: "bad",
+			status: rejected.get(target) ?? reason,
+			receivedAt,
+		};
+	};
 
-  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 result = await readTexts(
+			unique
+				.map(({ target }) => target)
+				.filter((target) => !rejected.has(target)),
+		);
+		const receivedAt = new Date().toISOString();
+		if ("error" in result) {
+			return new Map<string, TargetSample>(
+				unique.map(({ target }) => [
+					target,
+					{
+						value: null,
+						quality: "unavailable",
+						status: result.error,
+						receivedAt,
+					},
+				]),
+			);
+		}
+		return new Map(
+			unique.map((read) => [
+				read.target,
+				parsedSample(read, result.texts[read.target], receivedAt),
+			]),
+		);
+	};
 
-  /** 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;
-  };
+	/** Until the next poll: the rest of the interval, as long again after an overrun, longer without a login. */
+	const pauseAfter = (tookMs: number) => {
+		if (connection.state !== "connected" && connection.state !== "connecting") {
+			return retryMs;
+		}
+		return tookMs > samplingMs ? tookMs : samplingMs - tookMs;
+	};
 
-  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();
+	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)!);
+						}
+					}
+				}
+			}
+			await delay(pauseAfter(Date.now() - started), 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;
-    },
-  };
+	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;
+		},
+	};
 };