pi-open-deskos 0.2.1 → 0.4.0

package/src/config.ts

@@ -1,6 +1,9 @@
 import { createHash } from "node:crypto";
+import { isIP } from "node:net";
+import { readFileSync } from "node:fs";
 import os from "node:os";
-import { type DeskLinkConfig } from "./types.ts";
+import path from "node:path";
+import { type OdkLinkConfig } from "./types.ts";
 
 /** A reporting machine identity stable across restarts of the same machine. */
 export function defaultMachineName(hostname = os.hostname()): string {
@@ -9,28 +12,41 @@ export function defaultMachineName(hostname = os.hostname()): string {
 }
 
 function readPort(raw: string): number | null {
-  const port = Number.parseInt(raw, 10);
+  if (!/^\d+$/.test(raw)) return null;
+  const port = Number(raw);
   return Number.isInteger(port) && port > 0 && port <= 65535 ? port : null;
 }
 
+function readEndpoint(address: string): { host: string; port: number } | null {
+  const separator = address.lastIndexOf(":");
+  if (separator <= 0) return null;
+  let host = address.slice(0, separator).trim();
+  const port = readPort(address.slice(separator + 1).trim());
+  if (host.startsWith("[")) {
+    if (!host.endsWith("]")) return null;
+    host = host.slice(1, -1);
+    if (isIP(host) !== 6) return null;
+  } else if (host.includes(":")) {
+    if (isIP(host) !== 6) return null;
+  }
+  if (!host || /[\s/\\[\]?#@]/.test(host) || port === null) return null;
+  return { host, port };
+}
+
 /**
- * Read the Desk Link configuration. An unconfigured machine reports nothing:
+ * Read the Open DeskOS Link configuration. An unconfigured machine reports nothing:
  * a missing address or token is silent, never a partially configured link.
  */
-export function readDeskLinkConfig(env: NodeJS.ProcessEnv = process.env): DeskLinkConfig | null {
-  const address = (env.ODK_DESK_LINK_ADDRESS ?? "").trim();
-  const token = (env.ODK_DESK_LINK_TOKEN ?? "").trim();
+export function readOdkLinkConfig(env: NodeJS.ProcessEnv = process.env): OdkLinkConfig | null {
+  const address = (env.ODK_LINK_ADDRESS ?? "").trim();
+  const token = (env.ODK_LINK_TOKEN ?? "").trim();
   if (address.length === 0 || token.length === 0) return null;
-  const separator = address.lastIndexOf(":");
-  if (separator <= 0) return null;
-  const host = address.slice(0, separator).trim();
-  const port = readPort(address.slice(separator + 1).trim());
-  if (host.length === 0 || port === null) return null;
-  const controlToken = (env.ODK_DESK_LINK_CONTROL_TOKEN ?? "").trim();
+  const endpoint = readEndpoint(address);
+  if (endpoint === null) return null;
+  const controlToken = (env.ODK_LINK_CONTROL_TOKEN ?? "").trim();
   return {
-    machine: (env.ODK_DESK_LINK_MACHINE ?? "").trim() || defaultMachineName(),
-    host,
-    port,
+    machine: (env.ODK_LINK_MACHINE ?? "").trim() || defaultMachineName(),
+    ...endpoint,
     token,
     ...(controlToken.length > 0 ? { controlToken } : {}),
   };
@@ -40,3 +56,107 @@ export function readDeskLinkConfig(env: NodeJS.ProcessEnv = process.env): DeskLi
 export function tokenDigest(token: string): string {
   return createHash("sha256").update(token).digest("hex").slice(0, 8);
 }
+
+/** Where a machine that reports to more than one desk states them. */
+export const DEFAULT_DESKS_FILE = path.join(os.homedir(), ".config", "odk", "desks.json");
+
+export interface OdkLinkConfigSet {
+  configs: OdkLinkConfig[];
+  /** Entries a desks file stated that this machine will not use, with the reason. */
+  refusals: string[];
+  source: "desks-file" | "environment" | "none";
+}
+
+/** One entry of a desks file, or the reason it is not usable. */
+function configFromEntry(entry: unknown, machine: string): OdkLinkConfig | string {
+  if (entry === null || typeof entry !== "object") return "an entry is not an object";
+  const record = entry as Record<string, unknown>;
+  const address = typeof record.address === "string" ? record.address.trim() : "";
+  const token = typeof record.token === "string" ? record.token.trim() : "";
+  if (address.length === 0) return "an entry states no address";
+  if (token.length === 0) return `the entry for ${address} states no token`;
+  const endpoint = readEndpoint(address);
+  if (endpoint === null) return `${address} is not host:port`;
+  const controlToken = typeof record.controlToken === "string" ? record.controlToken.trim() : "";
+  const entryMachine = typeof record.machine === "string" && record.machine.trim().length > 0 ? record.machine.trim() : machine;
+  return {
+    machine: entryMachine,
+    ...endpoint,
+    token,
+    ...(controlToken.length > 0 ? { controlToken } : {}),
+  };
+}
+
+function entriesFrom(text: string): unknown[] | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (Array.isArray(parsed)) return parsed;
+  const stated = (parsed as { desks?: unknown } | null)?.desks;
+  return Array.isArray(stated) ? stated : null;
+}
+
+/**
+ * Every desk this machine reports to.
+ *
+ * One disk file is the source of truth when there is one, because a machine that
+ * reports to several desks needs a token per desk and an environment variable
+ * cannot state that unambiguously. The single-desk environment form keeps
+ * working for a machine that reports to one. An operator who names a file and
+ * then has it not used is told, because silence there would look like a link
+ * that simply never connects.
+ */
+export function readOdkLinkConfigs(
+  env: NodeJS.ProcessEnv = process.env,
+  options: { readFile?: (file: string) => string } = {},
+): OdkLinkConfigSet {
+  const readFile = options.readFile ?? ((file: string) => readFileSync(file, "utf8"));
+  const explicit = (env.ODK_LINK_DESKS_FILE ?? "").trim();
+  const machine = (env.ODK_LINK_MACHINE ?? "").trim() || defaultMachineName();
+  const file = explicit.length > 0 ? explicit : DEFAULT_DESKS_FILE;
+  const refusals: string[] = [];
+
+  let text: string | null = null;
+  try {
+    text = readFile(file);
+  } catch (error) {
+    const code = (error as { code?: string } | null)?.code;
+    if (code !== "ENOENT" || explicit.length > 0) {
+      refusals.push(`refusing ${file}: it could not be read${code === undefined ? "" : ` (${code})`}`);
+      return { configs: [], refusals, source: "desks-file" };
+    }
+  }
+
+  if (text !== null) {
+    const entries = entriesFrom(text);
+    if (entries === null) {
+      refusals.push(`refusing ${file}: it states no list of desks`);
+      return { configs: [], refusals, source: "desks-file" };
+    }
+    const configs: OdkLinkConfig[] = [];
+    const seen = new Set<string>();
+    for (const entry of entries) {
+      const result = configFromEntry(entry, machine);
+      if (typeof result === "string") {
+        refusals.push(`refusing ${file}: ${result}`);
+        continue;
+      }
+      const endpoint = `${result.host}:${result.port}`;
+      if (seen.has(endpoint)) {
+        refusals.push(`${endpoint} is listed more than once in ${file}; the first entry is used`);
+        continue;
+      }
+      seen.add(endpoint);
+      configs.push(result);
+    }
+    return { configs, refusals, source: "desks-file" };
+  }
+
+  const single = readOdkLinkConfig(env);
+  return single === null
+    ? { configs: [], refusals, source: "none" }
+    : { configs: [single], refusals, source: "environment" };
+}

package/src/console-client.ts

@@ -1,16 +1,16 @@
 import { createHmac, randomUUID } from "node:crypto";
-import { DESK_LINK_CONTROL_PROTOCOL, type ControlTransport } from "./control-transport.ts";
-import type { DeskLinkConfig, HistoryPage, HostedPiSession, PositionedSessionEvent } from "./types.ts";
+import { ODK_LINK_CONTROL_PROTOCOL, type ControlTransport } from "./control-transport.ts";
+import type { OdkLinkConfig, HistoryPage, HostedPiSession, PositionedSessionEvent } from "./types.ts";
 
 const CONTROL_TIMEOUT_MS = 5000;
-const CONTROL_DOMAIN = "open-deskos-control-v2";
+const CONTROL_DOMAIN = "odk-control-v2";
 const MAX_ATTACH_BUFFER_EVENTS = 2048;
 const MAX_ATTACH_BUFFER_BYTES = 1024 * 1024;
 
 interface ConsoleClientOptions {
-  config: DeskLinkConfig;
+  config: OdkLinkConfig;
   consoleSessionId: string;
-  createTransport: (config: DeskLinkConfig) => ControlTransport;
+  createTransport: (config: OdkLinkConfig) => ControlTransport;
   timeoutMs?: number;
 }
 
@@ -47,8 +47,8 @@ function reasonFrom(record: Record<string, unknown>, fallback = "control request
 
 function versionError(record: Record<string, unknown>): Error {
   const received = String(record.received ?? record.v ?? "unknown");
-  const accepted = Array.isArray(record.accepted) ? record.accepted.join(", ") : String(DESK_LINK_CONTROL_PROTOCOL);
-  return new Error(`Desk Link control protocol version ${received} refused; accepted ${accepted}`);
+  const accepted = Array.isArray(record.accepted) ? record.accepted.join(", ") : String(ODK_LINK_CONTROL_PROTOCOL);
+  return new Error(`Open DeskOS Link control protocol version ${received} refused; accepted ${accepted}`);
 }
 
 function unwrapReply(record: Record<string, unknown>): Record<string, unknown> {
@@ -57,7 +57,7 @@ function unwrapReply(record: Record<string, unknown>): Record<string, unknown> {
 }
 
 export function controlTranscript(machine: string, sessionId: string, nonce: string): string {
-  return `${CONTROL_DOMAIN}\n${DESK_LINK_CONTROL_PROTOCOL}\n${nonce}\n${machine}\n${sessionId}`;
+  return `${CONTROL_DOMAIN}\n${ODK_LINK_CONTROL_PROTOCOL}\n${nonce}\n${machine}\n${sessionId}`;
 }
 
 export function createControlProof(controlCredential: string, machine: string, sessionId: string, nonce: string): string {
@@ -86,15 +86,17 @@ class ControlConnection {
   readonly #transport: ControlTransport;
   readonly #pending = new Map<string, PendingRequest>();
   readonly #onUnsolicited: (record: Record<string, unknown>) => void;
+  readonly #onClosed: (error: Error) => void;
   #ready: Promise<void>;
   #readyResolve!: () => void;
   #readyReject!: (error: Error) => void;
   #closed = false;
   #transportClosed = false;
 
-  constructor(options: ConsoleClientOptions, onUnsolicited: (record: Record<string, unknown>) => void = () => {}) {
+  constructor(options: ConsoleClientOptions, onUnsolicited: (record: Record<string, unknown>) => void = () => {}, onClosed: (error: Error) => void = () => {}) {
     this.#options = options;
     this.#onUnsolicited = onUnsolicited;
+    this.#onClosed = onClosed;
     this.#ready = new Promise<void>((resolve, reject) => {
       this.#readyResolve = resolve;
       this.#readyReject = reject;
@@ -104,7 +106,7 @@ class ControlConnection {
     readyTimer.unref?.();
     this.#ready.then(() => clearTimeout(readyTimer), () => clearTimeout(readyTimer));
     this.#transport.onOpen(() => this.#transport.send({
-      v: DESK_LINK_CONTROL_PROTOCOL,
+      v: ODK_LINK_CONTROL_PROTOCOL,
       type: "control-hello",
       token: options.config.token,
       machine: options.config.machine,
@@ -129,7 +131,16 @@ class ControlConnection {
       timer.unref?.();
       this.#pending.set(requestId, { resolve, reject, timer, mutationId, sessionId, project });
     });
-    this.#transport.send({ v: DESK_LINK_CONTROL_PROTOCOL, type, requestId, ...fields });
+    try {
+      this.#transport.send({ ...fields, v: ODK_LINK_CONTROL_PROTOCOL, type, requestId });
+    } catch (error) {
+      const pending = this.#pending.get(requestId);
+      if (pending) {
+        clearTimeout(pending.timer);
+        this.#pending.delete(requestId);
+        pending.reject(new ControlRequestError(error instanceof Error ? error.message : "control write failed", { requestId, mutationId, sessionId, project }));
+      }
+    }
     return response;
   }
 
@@ -138,9 +149,10 @@ class ControlConnection {
   }
 
   #receive(value: unknown): void {
+    if (this.#closed) return;
     const record = asRecord(value);
     if (!record) return;
-    if (record.type === "version-mismatch" || (record.v !== undefined && record.v !== DESK_LINK_CONTROL_PROTOCOL)) {
+    if (record.type === "version-mismatch" || (record.v !== undefined && record.v !== ODK_LINK_CONTROL_PROTOCOL)) {
       this.#fail(versionError(record), true);
       return;
     }
@@ -149,7 +161,7 @@ class ControlConnection {
       const algorithm = record.algorithm;
       const credential = this.#options.config.controlToken ?? "";
       if (!nonce || (algorithm !== undefined && algorithm !== "hmac-sha256")) {
-        this.#fail(new Error("invalid Desk Link control challenge"), true);
+        this.#fail(new Error("invalid Open DeskOS Link control challenge"), true);
         return;
       }
       if (!credential) {
@@ -157,7 +169,7 @@ class ControlConnection {
         return;
       }
       this.#transport.send({
-        v: DESK_LINK_CONTROL_PROTOCOL,
+        v: ODK_LINK_CONTROL_PROTOCOL,
         type: "control-proof",
         proof: createControlProof(credential, this.#options.config.machine, this.#options.consoleSessionId, nonce),
       });
@@ -196,6 +208,7 @@ class ControlConnection {
         pending.reject(new ControlRequestError(error.message, { requestId, mutationId: pending.mutationId, sessionId: pending.sessionId, project: pending.project }));
       }
       this.#pending.clear();
+      this.#onClosed(error);
     }
     if (closeTransport && !this.#transportClosed) {
       this.#transportClosed = true;
@@ -219,6 +232,7 @@ export interface ConsoleAttachment {
 export class DeskConsoleClient {
   readonly #options: ConsoleClientOptions;
   #attachment: ConsoleAttachment | null = null;
+  #attaching: ControlConnection | null = null;
 
   constructor(options: ConsoleClientOptions) {
     this.#options = options;
@@ -246,7 +260,7 @@ export class DeskConsoleClient {
   }
 
   async attach(options: AttachOptions): Promise<ConsoleAttachment> {
-    this.#attachment?.close();
+    this.closeAttachment();
     const attachmentId = randomUUID();
     let lastApplied = options.position ?? 0;
     let streamError: string | undefined;
@@ -314,12 +328,22 @@ export class DeskConsoleClient {
           ...(typeof record.response === "string" ? { response: record.response } : {}),
         });
       }
-    });
-    const attached = await connection.request("attach", {
-      sessionId: options.sessionId,
-      attachmentId,
-      after: options.position ?? null,
-    });
+    }, (error) => { streamError ??= error.message; });
+    this.#attaching = connection;
+    let attached: Record<string, unknown>;
+    try {
+      attached = await connection.request("attach", {
+        sessionId: options.sessionId,
+        attachmentId,
+        after: options.position ?? null,
+      });
+      if (this.#attaching !== connection) throw new Error("control link closed");
+    } catch (error) {
+      connection.close();
+      throw error;
+    } finally {
+      if (this.#attaching === connection) this.#attaching = null;
+    }
     acknowledged = true;
     drainQueued();
     const boundary = asPosition(attached.boundary);
@@ -363,6 +387,8 @@ export class DeskConsoleClient {
 
   closeAttachment(): void {
     this.#attachment?.close();
+    this.#attaching?.close();
+    this.#attaching = null;
   }
 
   async #oneShot(type: string, fields: Record<string, unknown> = {}): Promise<Record<string, unknown>> {