@zgeoff/atc 2.12.0 → 2.14.0

package/src/daemon/execution-provider.ts

@@ -12,15 +12,64 @@ export interface ExecutionProvider {
   readonly kind: string;
   readonly capabilities: ExecutionCapabilities;
 
-  // Starts a process in a pseudo-terminal of the given size.
+  // Whether the host is a machine other than the daemon's own. A remote
+  // harness's files, transcripts included, live on that machine, and its
+  // environment holds only what atc sets for it.
+  readonly remote: boolean;
+
+  // Where a remote host keeps atc's files: the folder each session's own
+  // files unpack under, and the atc binary inside the host, null when the
+  // host has none. Absent on the daemon's own machine.
+  readonly guest?: GuestLayout;
+
+  // Readies the host a harness is about to start on: a remote host is
+  // created when missing, woken when asleep, and held awake while its
+  // harnesses run. Rejects with the refusal before any harness starts.
+  readonly prepareHost: (request: HostRequest) => Promise<void>;
+
+  // Starts a process in a pseudo-terminal of the given size, on the host the
+  // spec holds, which a prepare readied first.
   readonly spawnHarness: (spec: HarnessSpec) => HarnessHandle;
 
-  // Unpacks a tar archive into a directory, creating the directory first.
+  // Unpacks a tar archive into a directory on a host, creating the directory
+  // first. The daemon's own machine takes no host.
   // oxlint-disable-next-line prefer-readonly-parameter-types -- archive bytes have no readonly form
-  readonly transferArchive: (archive: Uint8Array, dir: string) => Promise<void>;
+  readonly transferArchive: (archive: Uint8Array, dir: string, host?: string) => Promise<void>;
 
   // Runs a command to completion and returns what it printed.
   readonly runCommand: (spec: CommandSpec) => Promise<CommandResult>;
+
+  // Puts a host to sleep with every harness on it kept inside, so a revive
+  // finds each one as it was. Rejects with `host_leased` when another owner
+  // keeps the host awake, and leaves the host as it was then.
+  readonly suspendHost: (host: string) => Promise<void>;
+
+  // Deletes a host and everything on it, harnesses included. Nothing brings
+  // a destroyed host back.
+  readonly destroyHost: (host: string) => Promise<void>;
+
+  // Stops the provider's own background work when the daemon stops, and
+  // leaves every remote harness running for the next daemon to find.
+  readonly dispose: () => void;
+}
+
+/**
+ * The host a harness is about to start on, and the daemon that holds it:
+ * a remote host is held per daemon, so two daemons never release each
+ * other's hold.
+ */
+export interface HostRequest {
+  readonly host: string;
+  readonly daemonID: string;
+
+  // Whether the harness about to start needs atc inside the host, which a
+  // provider that ships its own binary installs when missing.
+  readonly installATC?: boolean;
+}
+
+export interface GuestLayout {
+  readonly dir: string;
+  readonly atc: string | null;
 }
 
 /**
@@ -63,12 +112,44 @@ export interface ExecutionCapabilities {
 export type ExecutionCapability = keyof ExecutionCapabilities;
 
 export interface HarnessSpec {
+  // The atc session the harness belongs to, and the host it runs on: the
+  // session's own id, or its parent's when the two share a host.
+  readonly session: string;
+  readonly host: string;
   readonly bin: string;
   readonly args: readonly string[];
   readonly cwd: string;
+
+  // The variables atc sets for the harness. A provider for the daemon's
+  // own machine adds the daemon's environment around them; a remote one
+  // passes only these and its own.
   readonly env: Readonly<Record<string, string>>;
+
+  // The variable names the harness goes without even when the daemon's
+  // environment holds them, such as a workspace's credential; none of the
+  // variables atc sets is withheld.
+  readonly withheldEnv?: readonly string[];
   readonly cols: number;
   readonly rows: number;
+
+  // Takes each connection a process of the harness opens to the daemon. A
+  // remote provider relays them from a socket inside the host that serves
+  // this harness alone, and points the harness's ATC_SOCKET at it.
+  readonly onRelay?: (relay: HarnessRelay) => void;
+}
+
+/**
+ * One connection from a process inside a harness's host to the daemon, in
+ * lines: each line the process writes arrives whole, and each line the
+ * daemon writes reaches the process in order.
+ */
+export interface HarnessRelay {
+  readonly onLine: (listener: (line: string) => void) => void;
+  readonly onClose: (listener: () => void) => void;
+
+  // Settles once the relay has room for more.
+  readonly writeLine: (line: string) => Promise<void>;
+  readonly close: () => void;
 }
 
 /**
@@ -78,22 +159,46 @@ export interface HarnessSpec {
 export interface HarnessHandle {
   readonly onData: (listener: (data: string) => void) => HarnessSubscription;
   readonly onExit: (listener: (exit: HarnessExit) => void) => HarnessSubscription;
+
+  // Follows a remote harness's connection: lost and being restored, or
+  // restored. A harness on the daemon's own machine has no connection.
+  readonly onAttachment?: (
+    listener: (attachment: HarnessAttachment) => void,
+  ) => HarnessSubscription;
   readonly write: (data: string) => void;
   readonly resize: (cols: number, rows: number) => void;
   readonly kill: () => void;
+
+  // Stops following the harness and leaves its process running, for a host
+  // that keeps it after the daemon lets go; on a host that cannot keep it,
+  // the process ends as a kill ends it. No listener fires after a detach.
+  readonly detach: () => void;
 }
 
+export type HarnessAttachment = 'attached' | 'reattaching';
+
 interface HarnessSubscription {
   readonly dispose: () => void;
 }
 
-interface HarnessExit {
+export interface HarnessExit {
   readonly exitCode: number;
+
+  // Why the harness stopped: its process exited, its host went to sleep
+  // with the process inside, or the host lost it without an exit, such as
+  // a cold boot. Absent is an exit.
+  readonly reason?: 'exited' | 'suspended' | 'ended';
+
+  // What ended it, for a reason other than an exit.
+  readonly detail?: string;
 }
 
 export interface CommandSpec {
   readonly argv: readonly string[];
   readonly cwd: string;
+
+  // The host the command runs on; the daemon's own machine takes none.
+  readonly host?: string;
 }
 
 export interface CommandResult {

package/src/daemon/hooks.ts

@@ -1,8 +1,7 @@
 import { unlinkSync } from 'node:fs';
 import { socketPath } from '../shared/config';
-import { isRecord } from '../shared/report';
 import type { SessionID } from '../shared/session-id';
-import { toSessionID } from '../shared/to-session-id';
+import { parseHookLine } from './parse-hook-line';
 
 export interface HookEvent {
   atcId: SessionID;
@@ -38,22 +37,11 @@ export function startHookServer(onEvent: (e: HookEvent) => void, path: string =
             continue;
           }
 
-          try {
-            const parsed: unknown = JSON.parse(line);
+          const event = parseHookLine(line);
 
-            if (
-              isRecord(parsed) &&
-              typeof parsed['atcId'] === 'string' &&
-              typeof parsed['event'] === 'string' &&
-              isRecord(parsed['payload'])
-            ) {
-              onEvent({
-                atcId: toSessionID(parsed['atcId']),
-                event: parsed['event'],
-                payload: parsed['payload'],
-              });
-            }
-          } catch {}
+          if (event !== null) {
+            onEvent(event);
+          }
         }
       },
       open(socket) {

package/src/daemon/imp-client-port.ts

@@ -0,0 +1,343 @@
+import { createImpClient, openExecSession, openReverseForward } from '@zgeoff/imp-client';
+import type { ExecOutcome, ImpClient } from '@zgeoff/imp-client';
+import type {
+  ImpCommand,
+  ImpCommandResult,
+  ImpCreateSpec,
+  ImpFeatures,
+  ImpLease,
+  ImpPort,
+  ImpRelayConnection,
+  ImpReverseForward,
+  ImpSessionConnection,
+  ImpSessionHandlers,
+  ImpSessionOutcome,
+  ImpSessionRequest,
+  ImpView,
+} from './imp-port';
+import { ImpPortError } from './imp-port-error';
+
+/**
+ * Where impd listens and the token the daemon calls it with. The token
+ * comes from the daemon's environment, never from a config file.
+ */
+export interface ImpClientPortOptions {
+  readonly url: string;
+  readonly token: string | null;
+}
+
+/**
+ * The imp port over `@zgeoff/imp-client`: RPC calls for imps and leases,
+ * one exec WebSocket per session connection, and one reverse forward per
+ * guest socket. Every refusal impd sends becomes an `ImpPortError` with its
+ * code and data, and a call that never reaches impd carries `UNREACHABLE`.
+ */
+export class ImpClientPort implements ImpPort {
+  private readonly url: string;
+
+  private readonly token: string | null;
+
+  private readonly client: ImpClient;
+
+  constructor(options: ImpClientPortOptions) {
+    this.url = options.url;
+    this.token = options.token;
+
+    this.client = createImpClient({
+      url: options.url,
+      ...(options.token === null ? {} : { token: options.token }),
+    });
+  }
+
+  // An impd from before the flags has neither.
+  readonly readFeatures = async (): Promise<ImpFeatures> => {
+    const info = await this.tryCall(() => this.client.system.info());
+
+    return info.features ?? { sessionOffsets: false, leases: false };
+  };
+
+  readonly readImp = async (name: string): Promise<ImpView | null> => {
+    try {
+      const imp = await this.tryCall(() => this.client.imps.get({ name }));
+
+      return {
+        name: imp.name,
+        state: imp.state,
+        leases: (imp.leases?.leases ?? []).map((lease) => toLease(lease)),
+        otherLeaseCount: imp.leases?.otherCount ?? 0,
+      };
+    } catch (error) {
+      if (error instanceof ImpPortError && error.code === 'NOT_FOUND') {
+        return null;
+      }
+
+      throw error;
+    }
+  };
+
+  readonly createImp = async (spec: ImpCreateSpec): Promise<ImpView> => {
+    const imp = await this.tryCall(() =>
+      this.client.imps.create({
+        name: spec.name,
+        ...(spec.image === undefined ? {} : { image: spec.image }),
+        ...(spec.memoryMib === undefined ? {} : { memoryMib: spec.memoryMib }),
+      }),
+    );
+
+    return { name: imp.name, state: imp.state, leases: [], otherLeaseCount: 0 };
+  };
+
+  readonly acquireLease = async (
+    name: string,
+    label: string,
+    ttlSeconds: number,
+  ): Promise<ImpLease> => {
+    const lease = await this.tryCall(() => this.client.leases.acquire({ name, label, ttlSeconds }));
+
+    return toLease(lease);
+  };
+
+  readonly renewLease = async (
+    name: string,
+    label: string,
+    ttlSeconds: number,
+  ): Promise<ImpLease> => {
+    const lease = await this.tryCall(() => this.client.leases.renew({ name, label, ttlSeconds }));
+
+    return toLease(lease);
+  };
+
+  readonly releaseLease = async (name: string, label: string): Promise<boolean> => {
+    const result = await this.tryCall(() => this.client.leases.release({ name, label }));
+
+    return result.released;
+  };
+
+  readonly suspendImp = async (name: string): Promise<void> => {
+    await this.tryCall(() => this.client.imps.sleep({ name }));
+  };
+
+  readonly destroyImp = async (name: string): Promise<void> => {
+    await this.tryCall(() => this.client.imps.destroy({ name }));
+  };
+
+  // The exec WebSocket answers only after it opens, so nothing reaches the
+  // handlers before this returns.
+  readonly openSession = (
+    request: ImpSessionRequest,
+    handlers: ImpSessionHandlers,
+  ): ImpSessionConnection => {
+    const session = openExecSession({
+      baseUrl: this.url,
+      token: this.token,
+      start:
+        request.kind === 'start'
+          ? {
+              name: request.name,
+              session: request.session,
+              argv: request.argv,
+              tty: true,
+              env: request.env,
+              cwd: request.cwd,
+              cols: request.cols,
+              rows: request.rows,
+              ...(request.resumeFrom === undefined ? {} : { resumeFrom: request.resumeFrom }),
+            }
+          : {
+              name: request.name,
+              session: request.session,
+              cols: request.cols,
+              rows: request.rows,
+              wake: request.wake,
+              ...(request.resumeFrom === undefined ? {} : { resumeFrom: request.resumeFrom }),
+            },
+      onStarted: (started) => {
+        handlers.onStarted({ created: started.created, output: started.output });
+      },
+      onOutput: (_channel, data) => {
+        handlers.onOutput(data);
+      },
+      connect: (url, headers) => new WebSocket(url, { headers }),
+    });
+
+    return {
+      outcome: waitForSessionOutcome(session.outcome),
+      write: (data) => {
+        session.sendStdin(data);
+      },
+      resize: (cols, rows) => {
+        session.resize(cols, rows);
+      },
+      sendSignal: (signal) => {
+        session.sendSignal(signal);
+      },
+      close: () => {
+        session.stop();
+      },
+    };
+  };
+
+  // oxlint-disable-next-line prefer-readonly-parameter-types -- the command's input bytes have no readonly form
+  readonly runCommand = async (name: string, command: ImpCommand): Promise<ImpCommandResult> => {
+    const result = await this.tryCall(() =>
+      this.client.run(name, command.argv, {
+        ...(command.cwd === undefined ? {} : { cwd: command.cwd }),
+        ...(command.stdin === undefined ? {} : { stdin: command.stdin }),
+      }),
+    );
+
+    return { code: result.code, stdout: result.stdout, stderr: result.stderr };
+  };
+
+  readonly openReverseForward = (
+    name: string,
+    guestPath: string,
+    onConnection: (connection: ImpRelayConnection) => void,
+  ): ImpReverseForward => {
+    const forward = openReverseForward({
+      baseUrl: this.url,
+      token: this.token,
+      name,
+      guest: { network: 'unix', path: guestPath },
+      connect: (url, headers) => new WebSocket(url, { headers }),
+      onConnection: (accept) => {
+        onConnection(openRelay(accept));
+      },
+    });
+
+    return {
+      listening: waitForListening(forward.listening),
+      stop: () => {
+        forward.stop();
+      },
+    };
+  };
+
+  // Runs one client call, turning impd's refusals and transport failures
+  // into port errors.
+  private async tryCall<T>(call: () => Promise<T>): Promise<T> {
+    try {
+      return await call();
+    } catch (error) {
+      throw toPortError(error);
+    }
+  }
+}
+
+// A lease as the client returns it.
+interface ClientLease {
+  readonly name: string;
+  readonly owner: Readonly<{ principal: string; display: string; label: string }>;
+  readonly until: Date | null;
+}
+
+// oxlint-disable-next-line prefer-readonly-parameter-types -- a lease's end is a Date
+function toLease(lease: ClientLease): ImpLease {
+  return {
+    name: lease.name,
+    owner: {
+      principal: lease.owner.principal,
+      display: lease.owner.display,
+      label: lease.owner.label,
+    },
+    until: lease.until?.getTime() ?? null,
+  };
+}
+
+function toPortError(error: unknown): ImpPortError {
+  if (error instanceof ImpPortError) {
+    return error;
+  }
+
+  // impd's refusals arrive as errors carrying impd's code and data.
+  if (error instanceof Error && 'code' in error && typeof error.code === 'string') {
+    const data: unknown = 'data' in error ? error.data : undefined;
+
+    return new ImpPortError(error.code, error.message, data);
+  }
+
+  const message = error instanceof Error ? error.message : String(error);
+
+  return new ImpPortError('UNREACHABLE', message);
+}
+
+// oxlint-disable-next-line prefer-readonly-parameter-types -- a promise is a live handle
+async function waitForSessionOutcome(outcome: Promise<ExecOutcome>): Promise<ImpSessionOutcome> {
+  const ended = await outcome;
+
+  if (ended.kind === 'local_error') {
+    return {
+      kind: 'local_error',
+      detail: ended.error instanceof Error ? ended.error.message : String(ended.error),
+    };
+  }
+
+  if (ended.kind === 'unauthorized') {
+    return { kind: 'unauthorized' };
+  }
+
+  return ended;
+}
+
+// oxlint-disable-next-line prefer-readonly-parameter-types -- a promise is a live handle
+async function waitForListening(listening: Promise<unknown>): Promise<void> {
+  await listening;
+}
+
+// How the client hands over a guest connection: the daemon accepts it with
+// its handlers and gets the relay back.
+type RelayAccept = (
+  handlers: Readonly<{
+    // oxlint-disable-next-line prefer-readonly-parameter-types -- relayed bytes have no readonly form
+    onData: (data: Uint8Array) => void;
+    onEof: () => void;
+    onClose: (lost: boolean) => void;
+  }>,
+) => Readonly<{
+  // oxlint-disable-next-line prefer-readonly-parameter-types -- relayed bytes have no readonly form
+  send: (data: Uint8Array) => boolean;
+  waitForRoom: () => Promise<void>;
+  close: () => void;
+}>;
+
+// Takes a guest connection at once, handing its bytes and its close to the
+// listeners the relay's owner adds.
+function openRelay(accept: RelayAccept): ImpRelayConnection {
+  // oxlint-disable-next-line prefer-readonly-parameter-types -- relayed bytes have no readonly form
+  const dataListeners: ((data: Uint8Array) => void)[] = [];
+  const closeListeners: (() => void)[] = [];
+
+  const relay = accept({
+    onData: (data) => {
+      for (const listener of dataListeners) {
+        listener(data);
+      }
+    },
+    onEof: () => {},
+    onClose: () => {
+      for (const listener of closeListeners) {
+        listener();
+      }
+    },
+  });
+
+  return {
+    onData: (listener) => {
+      dataListeners.push(listener);
+    },
+    onClose: (listener) => {
+      closeListeners.push(listener);
+    },
+
+    // A send past the relay's window still queues the bytes, so only the
+    // next write waits; a closed relay takes bytes and drops them.
+    write: async (data) => {
+      if (!relay.send(data)) {
+        await relay.waitForRoom();
+      }
+    },
+    close: () => {
+      relay.close();
+    },
+  };
+}