@jr2/orchestrator 0.6.0 → 0.7.0

package/src/run-list.ts

@@ -0,0 +1,191 @@
+// The run listing (ADR-0009): what `GET /runs` reads of its query, the summary of one run, and the
+// cursor of a page. The live runs come from the host's registry and the ended runs from the store's
+// listing columns (`SnapshotStore.ended`); `RunHost.history` joins the two halves in one order,
+// newest start first, so a page is the same whichever half its runs are in.
+
+import type { RunStarter } from "./callers.ts";
+import { periodMs } from "./duration.ts";
+import type { DispatchedBy } from "./registration.ts";
+
+/**
+ * One run as `GET /runs` lists it (ADR-0009): a summary, not the whole `RunStatus`. `status` is
+ * `active` for a live run, else the store's word for how it ended. `reason` says why, where the
+ * Machine did not: the host's reason (`drifted`, `lost`, ADR-0030), the Failure's reason
+ * (`failed`, ADR-0073) or the fault (`error`). `endedAt` is the terminal write of an ended run.
+ * `openGates` counts the Gates open now, so it is 0 for an ended run. `placing` names the child
+ * paths of the Workspaces that wait for capacity (ADR-0064), and `dispatchedBy` the run that
+ * started this one (ADR-0071).
+ */
+export type RunSummary = {
+  runId: string;
+  workflow: string;
+  status: ShownStatus;
+  reason?: string;
+  startedBy?: RunStarter;
+  startedAt: string;
+  endedAt?: string;
+  assembly?: string;
+  openGates: number;
+  placing?: string[];
+  dispatchedBy?: DispatchedBy;
+  /** The space guard deleted the run's kept conversations (ADR-0065); the row stays. */
+  swept?: "conversation swept: no space";
+};
+
+/** A page of the listing: the runs, and the cursor of the next page when there is one. */
+export type RunPage = { runs: RunSummary[]; next?: string };
+
+/** How a run ended, as the store writes it (ADR-0065, ADR-0025, ADR-0030, ADR-0073, ADR-0074). */
+export type EndedStatus = "done" | "failed" | "error" | "cancelled" | "lost" | "drifted";
+
+/** The statuses of an ended run, as the store writes them. xstate's `stopped` is not one: it is
+ * mechanism, and a cancel ends the run `cancelled` (ADR-0025). */
+export const ENDED_STATUSES: readonly EndedStatus[] = ["done", "failed", "error", "cancelled", "lost", "drifted"];
+
+/** The status of a live run: the Machine's own word. */
+export const LIVE_STATUS = "active";
+
+/** A run status as jr2 shows it, on every route and feed: {@link LIVE_STATUS} while the run is
+ * live, else how it ended. The store's own `live` and xstate's `stopped` are never shown. */
+export type ShownStatus = typeof LIVE_STATUS | EndedStatus;
+
+/** A word that the store wrote for an ended run. */
+export function isEndedStatus(word: string): word is EndedStatus {
+  return (ENDED_STATUSES as readonly string[]).includes(word);
+}
+
+/**
+ * The shown status of a store row: `live` shows as {@link LIVE_STATUS}, and an ended word as
+ * itself. jr2 writes no other word. A row with another word is a defect in the store, so it shows
+ * as `error`: it is not live, and nothing can say how it ended.
+ */
+export function shownOfRow(word: string): ShownStatus {
+  if (word === "live") return LIVE_STATUS;
+  return isEndedStatus(word) ? word : "error";
+}
+
+/** How many runs a page holds when the query names no `limit`, and the most it can name. */
+export const RUNS_PAGE_DEFAULT = 50;
+export const RUNS_PAGE_MAX = 500;
+
+/** The query of `GET /runs`, read. `ended` is the ended statuses to list, or `undefined` for none. */
+export type RunListQuery = {
+  live: boolean;
+  ended?: readonly EndedStatus[];
+  workflow?: string;
+  since?: string;
+  after?: { startedAt: string; runId: string };
+  limit: number;
+};
+
+/** An ISO-8601 date, or a date and time with an optional zone. */
+const ISO_TIME = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/;
+
+/**
+ * Read the query of `GET /runs`, or the refusal's text. `status` is `live` (the default), `ended`,
+ * `all`, or a comma list of statuses and the two words; `since` is a duration back from `now`
+ * (`"2h"`, `"7d"`) or an ISO-8601 time; `cursor` is a page's `next`; `limit` is 1 to
+ * {@link RUNS_PAGE_MAX}.
+ */
+export function parseRunListQuery(
+  q: { status?: string; workflow?: string; since?: string; cursor?: string; limit?: string },
+  now: number,
+): RunListQuery | { error: string } {
+  let live = false;
+  const ended = new Set<EndedStatus>();
+  for (const word of (q.status ?? "live").split(",").map((w) => w.trim())) {
+    if (word === "live" || word === LIVE_STATUS) live = true;
+    else if (word === "ended") for (const s of ENDED_STATUSES) ended.add(s);
+    else if (word === "all") {
+      live = true;
+      for (const s of ENDED_STATUSES) ended.add(s);
+    } else if (isEndedStatus(word)) ended.add(word);
+    else {
+      return {
+        error: `status "${word}" is not one jr2 lists — use live, ended, all, or a comma list of ${[LIVE_STATUS, ...ENDED_STATUSES].join(", ")}`,
+      };
+    }
+  }
+  let since: string | undefined;
+  if (q.since !== undefined) {
+    const back = periodMs(q.since);
+    // Only an ISO-8601 shape reaches `Date.parse`: it reads other text leniently, so `7` would be
+    // a time in 2001 and list the whole history.
+    const at = back !== undefined ? now - back : ISO_TIME.test(q.since) ? Date.parse(q.since) : Number.NaN;
+    if (!Number.isFinite(at)) {
+      return { error: `since "${q.since}" is not a duration (such as 2h or 7d) or an ISO-8601 time` };
+    }
+    // A duration longer than the clock goes back lists every run, as the sweep's `Math.max(0, …)`:
+    // a time before 1970 is outside what `Date` can print at its far end.
+    since = new Date(Math.max(at, 0)).toISOString();
+  }
+  let after: RunListQuery["after"];
+  if (q.cursor !== undefined) {
+    after = decodeCursor(q.cursor);
+    if (!after) return { error: "cursor is not one that GET /runs gave — use the next of the page before" };
+  }
+  let limit = RUNS_PAGE_DEFAULT;
+  if (q.limit !== undefined) {
+    limit = Number(q.limit);
+    if (!Number.isInteger(limit) || limit < 1 || limit > RUNS_PAGE_MAX) {
+      return { error: `limit is a whole number from 1 to ${RUNS_PAGE_MAX}` };
+    }
+  }
+  return {
+    live,
+    ...(ended.size ? { ended: [...ended] } : {}),
+    ...(q.workflow !== undefined && q.workflow !== "" ? { workflow: q.workflow } : {}),
+    ...(since !== undefined ? { since } : {}),
+    ...(after ? { after } : {}),
+    limit,
+  };
+}
+
+/** The cursor after `run`: its start and its id, which order the listing. Opaque to a reader. */
+export function encodeCursor(run: { startedAt: string; runId: string }): string {
+  return Buffer.from(JSON.stringify([run.startedAt, run.runId])).toString("base64url");
+}
+
+/** A cursor read back, or undefined when it is not one that {@link encodeCursor} made. */
+export function decodeCursor(cursor: string): { startedAt: string; runId: string } | undefined {
+  try {
+    const value = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8")) as unknown;
+    if (!Array.isArray(value) || value.length !== 2) return undefined;
+    const [startedAt, runId] = value as unknown[];
+    if (typeof startedAt !== "string" || typeof runId !== "string") return undefined;
+    if (!Number.isFinite(Date.parse(startedAt))) return undefined;
+    return { startedAt, runId };
+  } catch {
+    return undefined;
+  }
+}
+
+/** The listing's order: the newest start first, then the larger run id. */
+export function newestFirst(a: RunSummary, b: RunSummary): number {
+  if (a.startedAt !== b.startedAt) return a.startedAt < b.startedAt ? 1 : -1;
+  return a.runId < b.runId ? 1 : a.runId > b.runId ? -1 : 0;
+}
+
+/** Whether `run` comes after the cursor `after` in the order. */
+export function isAfter(
+  run: { startedAt: string; runId: string },
+  after: { startedAt: string; runId: string },
+): boolean {
+  return run.startedAt < after.startedAt || (run.startedAt === after.startedAt && run.runId < after.runId);
+}
+
+/** The child paths of every Workspace in `placing` (ADR-0064), at any depth, off the state values
+ * alone. The root in `placing` is the empty path. */
+export function placingOf(value: unknown, children: readonly PlacingChild[]): string[] {
+  return [...(value === "placing" ? [""] : []), ...placingIn(children, [])];
+}
+
+/** The part of a `RunChild` that {@link placingOf} reads. */
+export type PlacingChild = { id: string; value: unknown; children: readonly PlacingChild[] };
+
+function placingIn(children: readonly PlacingChild[], path: string[]): string[] {
+  return children.flatMap((child) => {
+    const here = [...path, child.id];
+    return [...(child.value === "placing" ? [here.join("/")] : []), ...placingIn(child.children, here)];
+  });
+}

package/src/sandbox-kube.ts

@@ -45,6 +45,8 @@
 //   volume        runtime     the kit's Harness image, as an `image` volume → /opt/jr2
 //   volume        conversations  an emptyDir → /run/jr2/conversations, the Harness container's alone
 //                             (ADR-0031: a Harness restart inside the pod keeps its conversations)
+//   volume        shell       an emptyDir → /run/jr2/shell, the Harness container's alone: the
+//                             socket of a person's shell (`jr2 workspace shell`, ADR-0076)
 //   initContainer preflight   the USER'S image + that volume → ADR-0037's probe, the thing that
 //                             proves a registry ref, whose first appearance is this provision
 //   container     harness     the Sandbox Image, command overridden, /work + /opt/jr2 mounted
@@ -105,6 +107,8 @@ import {
   CONVERSATIONS_DIR,
   CONVERSATIONS_DIR_ENV,
   CONVERSATIONS_VOLUME,
+  SHELL_DIR,
+  SHELL_VOLUME,
   HELD_MOUNT,
   CA_CONFIGMAP,
   heldManifestKey,
@@ -115,6 +119,15 @@ import {
   PRIORITY_CLASS_SANDBOX,
   REPOS_MOUNT,
   sandboxCustodianConfigMap,
+  ANNOTATION_HOLD,
+  ANNOTATION_KEEPALIVE,
+  ANNOTATION_WORKSPACE_PATH,
+  HOLD_HELD,
+  HOLD_RELEASED,
+  LABEL_SANDBOX_RUN,
+  LABEL_SANDBOX_WORKFLOW,
+  LABEL_SANDBOX_WORKSPACE,
+  workspaceLabel,
 } from "./names.ts";
 import {
   CONFIGMAPS,
@@ -770,6 +783,7 @@ export function kubeSandbox(opts: KubeSandboxOptions = {}): SandboxPort {
       name: string;
       runId: string;
       workflow: string;
+      path: string;
       image?: string;
       user?: string;
       workGroup?: number;
@@ -802,8 +816,16 @@ export function kubeSandbox(opts: KubeSandboxOptions = {}): SandboxPort {
       metadata: {
         name: req.name,
         namespace: ns,
-        // The run↔workspace link `jr2 ls` groups by (ADR-0009/0012) — readable without the host.
-        labels: { "jr2.dev/run": req.runId, "jr2.dev/workflow": req.workflow },
+        // The run↔workspace link the `jr2 workspace` verbs read (ADR-0009/0012), without the host:
+        // the run, the Workflow and a selector form of the path as labels, the exact path as an
+        // annotation. The hold mark is `held` from this first write (ADR-0021); the Lease writes it
+        // again with each renewal, and `released` when it stops for good.
+        labels: {
+          [LABEL_SANDBOX_RUN]: req.runId,
+          [LABEL_SANDBOX_WORKFLOW]: req.workflow,
+          ...(req.path ? { [LABEL_SANDBOX_WORKSPACE]: workspaceLabel(req.path) } : {}),
+        },
+        annotations: { ...(req.path ? { [ANNOTATION_WORKSPACE_PATH]: req.path } : {}), [ANNOTATION_HOLD]: HOLD_HELD },
       },
       spec: {
         // The Sandbox Image, unmodified (ADR-0037) — the user's tools, its own USER and HOME, and
@@ -888,6 +910,9 @@ export function kubeSandbox(opts: KubeSandboxOptions = {}): SandboxPort {
           // that Workspace is `Lost` (ADR-0021) — and mounted below into the Harness container
           // ALONE: the User Container must not read an Agent's history.
           { name: CONVERSATIONS_VOLUME, emptyDir: {} },
+          // The shell socket's folder (ADR-0076): the Harness listens there for `jr2 workspace
+          // shell`, in the Harness container ALONE, where no process that it confines makes a file.
+          { name: SHELL_VOLUME, emptyDir: {} },
           // Only for ADR-0037's fallback seat: uid 1000 on a stranger's base has no home at all.
           ...seat.homeVolume,
           // The Custodian's (its values, leaves and config), and the trust ConfigMap (ADR-0020).
@@ -902,6 +927,7 @@ export function kubeSandbox(opts: KubeSandboxOptions = {}): SandboxPort {
           { name: "work", mountPath: WORK_ROOT },
           RUNTIME_VOLUME_MOUNT,
           { name: CONVERSATIONS_VOLUME, mountPath: CONVERSATIONS_DIR },
+          { name: SHELL_VOLUME, mountPath: SHELL_DIR },
           ...seat.homeMount,
           ...custodian.harnessMounts,
         ],
@@ -1448,13 +1474,35 @@ export function kubeSandbox(opts: KubeSandboxOptions = {}): SandboxPort {
     leaseIntervalMs,
 
     async renew(name) {
-      // A write, and only that (ADR-0021): the stamp the operator's idle GC reads. What the
-      // workspace IS comes from the watch, never from this answer.
+      // A write, and only that (ADR-0021): the stamp the operator's idle GC reads, and the hold
+      // mark, written again so a restored run's Lease marks the Sandbox `held`. What the workspace
+      // IS comes from the watch, never from this answer.
       await kube().patch(SANDBOXES, ns, name, {
-        metadata: { annotations: { "jr2.dev/keepalive": new Date().toISOString() } },
+        metadata: { annotations: { [ANNOTATION_KEEPALIVE]: new Date().toISOString(), [ANNOTATION_HOLD]: HOLD_HELD } },
       });
     },
 
+    async releaseHold(name) {
+      // The Lease stopped for good (ADR-0021): no run holds this Sandbox now, and `jr2 workspace rm`
+      // may remove it. A write, and only that.
+      await kube().patch(SANDBOXES, ns, name, { metadata: { annotations: { [ANNOTATION_HOLD]: HOLD_RELEASED } } });
+    },
+
+    async releaseRun(runId) {
+      // A restore ended this run without hosting it (ADR-0021): no Lease runs, so each of its
+      // Sandboxes gets the mark here. The list is the cluster's, not the watch's cache, which may
+      // not have listed yet at boot.
+      const list = await kube().list<SandboxObject>(SANDBOXES, ns, { labelSelector: `${LABEL_SANDBOX_RUN}=${runId}` });
+      await Promise.all(
+        list.items.flatMap((sb) => {
+          const name = sb.metadata?.name;
+          return name
+            ? [kube().patch(SANDBOXES, ns, name, { metadata: { annotations: { [ANNOTATION_HOLD]: HOLD_RELEASED } } })]
+            : [];
+        }),
+      );
+    },
+
     continuity(name, listener) {
       // The watch's word on this name (ADR-0063): the first list, then every event. A dropped
       // watch says nothing, so this says nothing either — unknown is never loss.