@tsplc/debug 0.2.17 → 0.2.19

package/src/api.ts

@@ -1,3 +1,4 @@
+import type { ServiceCall } from "@tsplc/server";
 import type { AppRecord } from "@tsplc/server/telemetry";
 import type { DebugManifest, SourceRange } from "./manifest.ts";
 
@@ -11,60 +12,62 @@ export type Quality = "good" | "uncertain" | "bad" | "unavailable";
 
 /** One value as read. Values of different paths may come from different scans. */
 export interface Sample {
-  path: string;
-  value: unknown;
-  quality: Quality;
-  status: string;
-  /** When the debugger host received it; the controller reports no time of its own. */
-  receivedAt: string;
+	path: string;
+	value: unknown;
+	quality: Quality;
+	status: string;
+	/** When the debugger host received it; the controller reports no time of its own. */
+	receivedAt: string;
 }
 
 /** `unavailable`: nothing to read through, such as no engineering login open. */
-export type ConnectionState = "connecting" | "connected" | "lost" | "failed" | "unavailable";
+export type ConnectionState =
+	"connecting" | "connected" | "lost" | "failed" | "unavailable";
 
 export interface Session {
-  build: { manifest: string | null; controller: string | null; matches: boolean };
-  connection: { state: ConnectionState; since: string; endpoint: string; error?: string };
-  /** How live values are read, such as "engineering login", and how often. */
-  reading: { method: string; intervalMs: number };
-  /** From the tasks' telemetry batches; `dropped` counts records overwritten before they were sent. */
-  tasks: { name: string; scan: number | null; scansPerSecond: number | null; dropped: number }[];
-  /** PLC clock minus the app server's clock, estimated from telemetry batches. */
-  clock: { offsetMs: number; uncertaintyMs: number } | null;
-  release?: { id: string; deployedAt: string; operation: string };
-  /** The project directory on the host, when served by `tsplc debug`. */
-  projectRoot?: string;
+	build: {
+		manifest: string | null;
+		controller: string | null;
+		matches: boolean;
+	};
+	connection: {
+		state: ConnectionState;
+		since: string;
+		endpoint: string;
+		error?: string;
+	};
+	/** How live values are read, such as "engineering login", and how often. */
+	reading: { method: string; intervalMs: number };
+	/** From the tasks' telemetry batches; `dropped` counts records overwritten before they were sent. */
+	tasks: {
+		name: string;
+		scan: number | null;
+		scansPerSecond: number | null;
+		dropped: number;
+	}[];
+	/** PLC clock minus the app server's clock, estimated from telemetry batches. */
+	clock: { offsetMs: number; uncertaintyMs: number } | null;
+	release?: { id: string; deployedAt: string; operation: string };
+	/** The project directory on the host, when served by `tsplc debug`. */
+	projectRoot?: string;
 }
 
 /** A trace record, decoded through the manifest's event sites. */
 export interface TraceEvent {
-  sequence: number;
-  task: string;
-  scan: number;
-  plcTime: number;
-  site: number;
-  value: unknown;
-  /** The site's guard operands, in the site's order. */
-  operands: { text: string; path?: string; stable: boolean; value: unknown }[];
+	sequence: number;
+	task: string;
+	scan: number;
+	plcTime: number;
+	site: number;
+	value: unknown;
+	/** The site's guard operands, in the site's order. */
+	operands: { text: string; path?: string; stable: boolean; value: unknown }[];
 }
 
 export type { AppRecord };
 
-export interface RequestTrace {
-  /** The server's own sequence number. */
-  seq: number;
-  service: string;
-  /** From `x-tsplc-request: <job id>:<sequence>`. */
-  job?: number;
-  sequence?: number;
-  startedAt: string;
-  durationMs?: number;
-  status: "pending" | "ok" | "error" | "timeout";
-  httpStatus?: number;
-  error?: string;
-  input?: unknown;
-  output?: unknown;
-}
+/** One PLC service call, as the app server traced it. */
+export type RequestTrace = ServiceCall;
 
 /**
  * A job as last seen. `busy` is null until it is known: from the trace's start and finish
@@ -72,81 +75,81 @@ export interface RequestTrace {
  * is busy and shown.
  */
 export interface JobState {
-  id: number;
-  /** Of the `busy` reading; a traced job's is good. */
-  quality: Quality;
-  busy: boolean | null;
-  cancelling?: boolean;
-  step?: number;
-  current?: { kind: string; range: SourceRange; text: string };
-  startedAt?: string;
-  elapsedMs?: number;
-  request?: { service: string; sequence: number; trace?: RequestTrace };
-  /** Busy, but over the number of jobs whose details are read on each poll. */
-  unread?: true;
-  /** The last failure nothing caught, from the program's `exception` records. */
-  failure?: { at: string; code: number; name?: string; source: string };
+	id: number;
+	/** Of the `busy` reading; a traced job's is good. */
+	quality: Quality;
+	busy: boolean | null;
+	cancelling?: boolean;
+	step?: number;
+	current?: { kind: string; range: SourceRange; text: string };
+	startedAt?: string;
+	elapsedMs?: number;
+	request?: { service: string; sequence: number; trace?: RequestTrace };
+	/** Busy, but over the number of jobs whose details are read on each poll. */
+	unread?: true;
+	/** The last failure nothing caught, from the program's `exception` records. */
+	failure?: { at: string; code: number; name?: string; source: string };
 }
 
 export interface DeviceState {
-  id: string;
-  /** "unknown" unless the driver's own state was read. */
-  health: {
-    state: "unknown" | "ok" | "fault" | "stale";
-    value?: number;
-    name?: string;
-    diagnostic?: boolean;
-    message?: string;
-    quality: Quality;
-  };
-  assemblies: {
-    direction: "input" | "output";
-    address?: string;
-    bytes: number[] | null;
-    quality: Quality;
-  }[];
-  /** Channels bound to TypeScript I/O paths, by channel id. */
-  channels: { id: string; path: string; value: unknown; quality: Quality }[];
-  /** The device's hand-configured status symbols, by label. */
-  status: Record<string, { value: unknown; quality: Quality }>;
+	id: string;
+	/** "unknown" unless the driver's own state was read. */
+	health: {
+		state: "unknown" | "ok" | "fault" | "stale";
+		value?: number;
+		name?: string;
+		diagnostic?: boolean;
+		message?: string;
+		quality: Quality;
+	};
+	assemblies: {
+		direction: "input" | "output";
+		address?: string;
+		bytes: number[] | null;
+		quality: Quality;
+	}[];
+	/** Channels bound to TypeScript I/O paths, by channel id. */
+	channels: { id: string; path: string; value: unknown; quality: Quality }[];
+	/** The device's hand-configured status symbols, by label. */
+	status: Record<string, { value: unknown; quality: Quality }>;
 }
 
 /** An entry of the "Recent" view: the server's recent window, merged with the agent's logs. */
 export type TimelineEntry = {
-  at: string;
-  /** Placed through another clock (the PLC's, or the app server's), so its order is approximate. */
-  approximate: boolean;
-  source: "plc" | "server" | "agent" | "debugger";
+	at: string;
+	/** Placed through another clock (the PLC's, or the app server's), so its order is approximate. */
+	approximate: boolean;
+	source: "plc" | "server" | "agent" | "debugger";
 } & (
-  | { kind: "app"; task: string; sequence: number; record: AppRecord }
-  | { kind: "trace"; trace: TraceEvent }
-  | { kind: "request"; request: RequestTrace }
-  | {
-      kind: "deploy";
-      release: string;
-      operation: string;
-      build?: string;
-      user?: string;
-      host?: string;
-    }
-  | {
-      kind: "audit";
-      /** As typed after `tsplc`, such as `force` or `reset cold`. */
-      command: string;
-      /** Expressions written or forced, with their values; unforced expressions map to "". */
-      values: Record<string, string>;
-      /** The values read just before a write or force. */
-      previous?: Record<string, string>;
-      user?: string;
-      host?: string;
-      release?: string;
-      error?: string;
-    }
-  | { kind: "connection"; state: ConnectionState; error?: string }
+	| { kind: "app"; task: string; sequence: number; record: AppRecord }
+	| { kind: "trace"; trace: TraceEvent }
+	| { kind: "request"; request: RequestTrace }
+	| {
+			kind: "deploy";
+			release: string;
+			operation: string;
+			build?: string;
+			user?: string;
+			host?: string;
+	  }
+	| {
+			kind: "audit";
+			/** As typed after `tsplc`, such as `force` or `reset cold`. */
+			command: string;
+			/** Expressions written or forced, with their values; unforced expressions map to "". */
+			values: Record<string, string>;
+			/** The values read just before a write or force. */
+			previous?: Record<string, string>;
+			user?: string;
+			host?: string;
+			release?: string;
+			error?: string;
+	  }
+	| { kind: "connection"; state: ConnectionState; error?: string }
 );
 
 export interface WatchGroups {
-  groups: Record<string, string[]>;
+	groups: Record<string, string[]>;
 }
 
 /**
@@ -154,29 +157,29 @@ export interface WatchGroups {
  * `health` devices, and everything of `devices`. Stream query parameters, comma-separated.
  */
 export interface Interest {
-  watch: string[];
-  jobs: number[];
-  health: string[];
-  devices: string[];
+	watch: string[];
+	jobs: number[];
+	health: string[];
+	devices: string[];
 }
 
 export interface StreamEvents {
-  session: Session;
-  sample: Sample;
-  job: JobState;
-  request: RequestTrace;
-  device: DeviceState;
-  timeline: TimelineEntry;
+	session: Session;
+	sample: Sample;
+	job: JobState;
+	request: RequestTrace;
+	device: DeviceState;
+	timeline: TimelineEntry;
 }
 
 /** Response bodies by route. Errors are `{ error: string }` with a 4xx or 5xx status. */
 export interface ApiResponses {
-  "GET /api/session": Session;
-  "GET /api/manifest": DebugManifest;
-  "GET /api/values": Sample[];
-  "GET /api/jobs": JobState[];
-  "GET /api/hardware": DeviceState[];
-  "GET /api/timeline": TimelineEntry[];
-  "GET /api/watch": WatchGroups;
-  "PUT /api/watch": WatchGroups;
+	"GET /api/session": Session;
+	"GET /api/manifest": DebugManifest;
+	"GET /api/values": Sample[];
+	"GET /api/jobs": JobState[];
+	"GET /api/hardware": DeviceState[];
+	"GET /api/timeline": TimelineEntry[];
+	"GET /api/watch": WatchGroups;
+	"PUT /api/watch": WatchGroups;
 }