@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/worker-protocol/uplink/methods.ts

@@ -0,0 +1,462 @@
+// The RPC catalogue: one schema pair per method in `todo/ideas/uplink.md`
+// § 4 RPC, plus the typed helpers that call and answer them, so neither end
+// ever hand-encodes JSON.
+//
+// Shapes only. Who may call what, and what a caller does while the session is
+// down, are Home's and the worker's decisions — this file has no opinion.
+
+import { z } from "zod";
+import { HEADER_NAME_RE, HEADER_VALUE_RE } from "../../http-header.ts";
+import { WORKER_CAPABILITIES, type WorkerCapability } from "../../permissions.ts";
+import {
+  homeProxyRequestSchema,
+  homeProxyResponseSchema,
+} from "../../runtime/docker/home-proxy-server/protocol.ts";
+import { nodeVersionSchema } from "../node-version.ts";
+import type { SiloOrphan } from "../silo-paths.ts";
+import { UPDATE_ERROR_MAX_CHARS } from "../update-files.ts";
+import { UplinkError, UplinkProtocolError } from "./errors.ts";
+import { decodeUtf8, encodeUtf8 } from "./frame.ts";
+import { jsonResponse, type Rpc, type RpcHandler } from "./rpc.ts";
+
+/** The response header `state.pull` answers a 200 with. */
+export const ETAG_HEADER = "etag";
+
+// --- shared pieces ------------------------------------------------------
+
+const capabilitiesSchema = z.array(
+  z.enum(WORKER_CAPABILITIES as readonly [WorkerCapability, ...WorkerCapability[]]),
+);
+
+// The worker's own view of its public address, from the acme-dns echo. Home
+// cross-checks it against the socket's `X-Forwarded-For` but stores this one
+// (`todo/ideas/uplink.md` § Identity). A junk filter, not a trust boundary.
+const publicIpSchema = z.union([z.ipv4(), z.ipv6()]);
+
+/** What both `enroll` and `hello` hand back once the worker row is known. */
+const workerIdentitySchema = z.object({
+  workerId: z.string().min(1),
+  slug: z.string().min(1),
+  // Null when the realm has no Realm DNS at all, which is what keeps a
+  // self-hosted install from quietly calling yourrealm.eu.
+  publicIpUrl: z.string().nullable(),
+});
+
+const okSchema = z.object({ ok: z.literal(true) });
+
+/**
+ * What the box's `realm-ingress` container is running, or null where there is
+ * no such container.
+ *
+ * Read off the container itself rather than off `etc/ingress/.env`, and the
+ * difference is the whole point: the `.env` says what this box is *configured*
+ * to run, while this says what it *is* running, and the two differ for exactly
+ * as long as an update is in flight or has failed. That gap is what the
+ * `applied` signal exists to see. It is still the pinned `name@sha256:` ref,
+ * because compose interpolates the `.env` pin into the service's `image:` and
+ * the container records that string verbatim.
+ *
+ * The ingress holds no session of its own - it is a proxy, not a node - so this
+ * is the only way its version reaches Home.
+ */
+const ingressVersionSchema = z.object({ imageRef: z.string().min(1) }).nullable();
+
+/**
+ * The platform compose projects a worker will write a `.update` for.
+ *
+ * Two, and neither is `home` or `updater`: Home writes its own box's
+ * `etc/home/.update` directly, and the updater cannot apply an update to
+ * itself. Restricting it here rather than in the worker is what makes a wrong
+ * project a 400 on the wire instead of a path traversal argument.
+ */
+export const UPDATE_PROJECTS = ["worker", "ingress"] as const;
+export type UpdateProject = (typeof UPDATE_PROJECTS)[number];
+
+/** Longest `message` a per-app apply result carries: the tail of compose's stderr. */
+export const APPLY_MESSAGE_MAX_CHARS = 2048;
+/** Longest `error` an `update.status` carries: the file cap, declared beside its reader. */
+export { UPDATE_ERROR_MAX_CHARS };
+
+/**
+ * One app's result from a reconcile. `message` is the tail of compose's stderr
+ * or the spawn error - what the box said, so Home can show it rather than an
+ * "applied" that means only "the etag landed".
+ */
+export const appApplyResultSchema = z.discriminatedUnion("ok", [
+  z.object({ appId: z.string().min(1), ok: z.literal(true) }),
+  z.object({
+    appId: z.string().min(1),
+    ok: z.literal(false),
+    message: z.string().min(1).max(APPLY_MESSAGE_MAX_CHARS),
+  }),
+]);
+export type AppApplyResult = z.infer<typeof appApplyResultSchema>;
+
+/**
+ * What one of the box's updater-driven compose projects is doing. `pending` is
+ * "`etc/<project>/.update` exists"; `error` is the trimmed content of
+ * `etc/<project>/.update.error`, or null when there is none. Independent of
+ * `version.imageRef`: a project can be pending with no error, failed with the
+ * token still present (the updater keeps `.update` as its retry token), or
+ * idle with a stale error file after a hand `rm`.
+ */
+export const updateStatusSchema = z.object({
+  project: z.enum(UPDATE_PROJECTS),
+  pending: z.boolean(),
+  error: z.string().min(1).max(UPDATE_ERROR_MAX_CHARS).nullable(),
+});
+export type UpdateStatus = z.infer<typeof updateStatusSchema>;
+
+// A `[name, value]` list rather than a record, in both directions: the
+// ForwardAuth hop relays request headers wholesale and a response can carry
+// more than one `set-cookie`, which a `Record<string, string>` would lose.
+const headerPairsSchema = z.array(z.tuple([z.string(), z.string()]));
+
+// Mirrors the worker's `/ui-proxy` body. The port bound against the app's own
+// declared ports is the worker's check, not this schema's.
+const uiProxyRequestSchema = z.object({
+  appId: z.string().min(1),
+  service: z.string().min(1),
+  port: z.number().int().positive().max(65535),
+  path: z.string().startsWith("/"),
+  method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]),
+  query: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+  headers: z
+    .record(z.string(), z.string())
+    .refine(
+      (h) => Object.entries(h).every(([k, v]) => HEADER_NAME_RE.test(k) && HEADER_VALUE_RE.test(v)),
+      "invalid header",
+    )
+    .optional(),
+  body: z.unknown().optional(),
+});
+
+// Typed against the interface so the two cannot drift.
+const siloOrphanSchema: z.ZodType<SiloOrphan> = z.object({
+  id: z.string().min(1),
+  mtime: z.string().nullable(),
+  sizeBytes: z.number().nullable(),
+});
+
+// --- the catalogue ------------------------------------------------------
+
+/**
+ * Every method, by name. An entry with a `result` is JSON both ways and goes
+ * through `callJson`/`jsonHandler`; an entry with only `params` is
+ * byte-bodied and has its own helper below.
+ */
+export const methods = {
+  /** Worker → Home, on an unenrolled session. The only method one accepts. */
+  enroll: {
+    params: z.object({
+      otp: z.string().min(1),
+      /** Display name; the installer defaults it to the box's hostname. */
+      name: z.string().trim().max(64).optional(),
+      capabilities: capabilitiesSchema,
+      version: nodeVersionSchema,
+      /** What this box's ingress is running, or null if it has none. */
+      ingress: ingressVersionSchema,
+      publicIp: publicIpSchema.optional(),
+    }),
+    result: workerIdentitySchema,
+  },
+
+  /**
+   * Worker → Home, first call on every connect: the door. 404 means the row is
+   * gone.
+   *
+   * This shape never changes. Every fact about the box goes in `announce`
+   * instead, precisely so that a worker and a Home on different builds can
+   * still open a session - which is the only way Home can tell that box to
+   * update. A `hello` Home could refuse strands the box until an operator
+   * writes the digest into `etc/worker/.update` by hand.
+   *
+   * The answer carries Home's own `protocol`. A worker that reads back a
+   * number other than its own holds the session and waits: it announces
+   * nothing, pulls nothing, and serves only what Home asks of it - `update`,
+   * which is what moves it onto Home's number.
+   */
+  hello: {
+    params: z.object({
+      /**
+       * The catalogue version this worker speaks. Absent means 0: a worker from
+       * before the door existed says nothing here, and 0 is never a version a
+       * door-aware worker announces.
+       *
+       * The default is part of the door's definition rather than a shim to
+       * remove later. The door is frozen, so the rule that reads a silent
+       * worker as 0 is frozen with it.
+       */
+      protocol: z.number().int().nonnegative().default(0),
+      version: nodeVersionSchema,
+    }),
+    result: workerIdentitySchema.extend({ protocol: z.number().int().nonnegative() }),
+  },
+
+  /**
+   * Worker → Home, once per connect, right after a `hello` whose answer carried
+   * a matching `protocol`. Everything the box knows about itself, replacing
+   * whatever Home held for this worker.
+   *
+   * Free to change in a way `hello` is not: a worker only ever sends it to a
+   * Home that agreed on the catalogue version first.
+   */
+  announce: {
+    params: z.object({
+      capabilities: capabilitiesSchema,
+      /** What this box's ingress is running, or null if it has none. */
+      ingress: ingressVersionSchema,
+      /** What this worker is actually running, not what it was last sent. */
+      appliedEtag: z.string().nullable(),
+      /**
+       * The box's whole update picture, replacing whatever Home held for this
+       * worker. A project absent here is unknown on this box (no
+       * `etc/<project>` dir); a worker with no `etc/` at all sends `[]`.
+       */
+      updates: z.array(updateStatusSchema),
+      publicIp: publicIpSchema.optional(),
+    }),
+    result: okSchema,
+  },
+
+  /** Worker → Home. 304 unchanged, 503 pending, 200 the tar.gz as bytes. */
+  "state.pull": {
+    params: z.object({
+      etag: z.string().nullable(),
+      publicIp: publicIpSchema.optional(),
+    }),
+  },
+
+  /**
+   * Worker → Home, after a reconcile lands. `apps` is one entry per app the
+   * worker ran `compose up` for, so the etag says what was pulled and the
+   * entries say what actually came up.
+   */
+  "state.applied": {
+    params: z.object({ etag: z.string().min(1), apps: z.array(appApplyResultSchema) }),
+    result: okSchema,
+  },
+
+  /** Worker → Home, one stream per gated request. The hot path. */
+  verify: {
+    params: z.object({
+      /** The original request's query string, `?` included, or empty. */
+      search: z.string(),
+      headers: headerPairsSchema,
+    }),
+    result: z.object({
+      status: z.number().int(),
+      headers: headerPairsSchema,
+      /** Base64: the relayed body is whatever the gate answered with. */
+      body: z.base64(),
+    }),
+  },
+
+  /** Worker → Home, the `home.apiAccess` broker, with the calling app id. */
+  apiAccess: {
+    params: homeProxyRequestSchema.extend({ appId: z.string().min(1) }),
+    result: homeProxyResponseSchema,
+  },
+
+  /**
+   * Worker → Home, when a project's `.update` / `.update.error` changes on
+   * disk. One row, upserted; `announce.updates` is the whole set.
+   */
+  "update.status": {
+    params: updateStatusSchema,
+    result: okSchema,
+  },
+
+  /** Home → worker. Zero payload; dropped while the session is down. */
+  reconcile: {
+    params: z.object({}),
+    result: okSchema,
+  },
+
+  /** Home → worker. The response status is the proxied one, body the bytes. */
+  uiProxy: {
+    params: uiProxyRequestSchema,
+  },
+
+  /**
+   * Home → worker. The worker writes `etc/<project>/.update`; its sidecar
+   * applies it. One method for both roles the worker can move, because the box
+   * has one sidecar and one etc/ tree - the project names which of them.
+   */
+  update: {
+    params: z.object({
+      imageRef: z.string().min(1),
+      project: z.enum(UPDATE_PROJECTS),
+    }),
+    result: okSchema,
+  },
+
+  /** Home → worker. `live` is every Silo id that still has a row. */
+  siloOrphans: {
+    params: z.object({ live: z.array(z.string()) }),
+    result: z.array(siloOrphanSchema),
+  },
+} as const;
+
+type Methods = typeof methods;
+
+export type MethodName = keyof Methods;
+
+/** The methods that are JSON in both directions. */
+export type JsonMethod = {
+  [M in MethodName]: Methods[M] extends { result: z.ZodType } ? M : never;
+}[MethodName];
+
+export type Params<M extends MethodName> = z.infer<Methods[M]["params"]>;
+export type Result<M extends JsonMethod> = z.infer<Methods[M]["result"]>;
+
+/**
+ * A method answered — or is being answered — with a non-2xx status.
+ *
+ * Both directions on purpose: `callJson` throws it with what the peer said,
+ * and a handler throws it to say what to answer (`hello` → 404 for a worker
+ * whose row is gone). `status` is the contract; `body` is diagnostic.
+ */
+export class MethodError extends UplinkError {
+  readonly method: string;
+  readonly status: number;
+  readonly body: string;
+
+  constructor(method: string, status: number, body: string) {
+    super(`${method} answered ${status}${body === "" ? "" : `: ${body.slice(0, 200)}`}`);
+    this.name = "MethodError";
+    this.method = method;
+    this.status = status;
+    this.body = body;
+  }
+}
+
+// --- calling ------------------------------------------------------------
+
+/** Calls a JSON method and validates the answer against its result schema. */
+export async function callJson<M extends JsonMethod>(
+  rpc: Rpc,
+  method: M,
+  params: Params<M>,
+): Promise<Result<M>> {
+  const spec = methods[method] as { params: z.ZodType; result: z.ZodType };
+  const res = await rpc.call(method, {}, encodeJson(spec.params, params));
+  const text = decodeUtf8(await readAll(res.body));
+  if (res.status < 200 || res.status >= 300) throw new MethodError(method, res.status, text);
+  return parseResult(method, spec.result, text) as Result<M>;
+}
+
+export interface StatePull {
+  /** 200 with a body, 304 unchanged, 503 while the first recompute pends. */
+  status: number;
+  /** Present on a 200; what the next pull sends back as `etag`. */
+  etag?: string;
+  /** The tar.gz, unread. The caller drains or cancels it. */
+  body: ReadableStream<Uint8Array>;
+}
+
+/** `state.pull`, whose 200 body is the per-worker bundle rather than JSON. */
+export async function pullState(rpc: Rpc, params: Params<"state.pull">): Promise<StatePull> {
+  const res = await rpc.call("state.pull", {}, encodeJson(methods["state.pull"].params, params));
+  const etag = res.headers[ETAG_HEADER];
+  return etag === undefined
+    ? { status: res.status, body: res.body }
+    : { status: res.status, etag, body: res.body };
+}
+
+export interface UiProxyResult {
+  /** The status the container answered the worker with. */
+  status: number;
+  headers: Record<string, string>;
+  body: Uint8Array;
+}
+
+/** `uiProxy`, whose response body is bytes the worker relayed verbatim. */
+export async function callUiProxy(rpc: Rpc, payload: Params<"uiProxy">): Promise<UiProxyResult> {
+  const res = await rpc.call("uiProxy", {}, encodeJson(methods.uiProxy.params, payload));
+  return { status: res.status, headers: res.headers, body: await readAll(res.body) };
+}
+
+// --- answering ----------------------------------------------------------
+
+/**
+ * Wraps a handler for one JSON method: the body is parsed against its params
+ * schema (400 on a mismatch) and the return value is answered as JSON. Throw
+ * `MethodError` to answer any other status.
+ */
+export function jsonHandler<M extends JsonMethod>(
+  method: M,
+  fn: (params: Params<M>) => Promise<Result<M>> | Result<M>,
+): RpcHandler {
+  const spec = methods[method] as { params: z.ZodType };
+  return async (req) => {
+    let raw: unknown;
+    try {
+      raw = JSON.parse(decodeUtf8(await readAll(req.body)));
+    } catch {
+      return jsonResponse(400, { error: `${method}: body is not JSON` });
+    }
+    const parsed = spec.params.safeParse(raw);
+    if (!parsed.success) {
+      return jsonResponse(400, { error: `${method}: ${issueText(parsed.error)}` });
+    }
+    try {
+      return jsonResponse(200, await fn(parsed.data as Params<M>));
+    } catch (e) {
+      // Anything else is a bug, and rpc.ts frames it as a 500.
+      if (e instanceof MethodError) return jsonResponse(e.status, { error: e.body });
+      throw e;
+    }
+  };
+}
+
+// --- helpers ------------------------------------------------------------
+
+function encodeJson(schema: z.ZodType, params: unknown): Uint8Array {
+  // Parsed on the way out too: the refinements a type cannot express — a
+  // `path` that is safe, a header value that is printable — are exactly the
+  // ones worth catching before they reach the peer.
+  return encodeUtf8(JSON.stringify(schema.parse(params)));
+}
+
+function parseResult(method: string, schema: z.ZodType, text: string): unknown {
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    throw new UplinkProtocolError(`${method} answered with a body that is not JSON`);
+  }
+  const parsed = schema.safeParse(value);
+  if (!parsed.success) {
+    throw new UplinkProtocolError(
+      `${method} answered an unexpected shape: ${issueText(parsed.error)}`,
+    );
+  }
+  return parsed.data;
+}
+
+function issueText(error: z.ZodError): string {
+  const issue = error.issues[0];
+  if (issue === undefined) return "invalid";
+  const path = issue.path.join(".");
+  return path === "" ? issue.message : `${path}: ${issue.message}`;
+}
+
+async function readAll(body: ReadableStream<Uint8Array>): Promise<Uint8Array> {
+  const reader = body.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  for (;;) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    chunks.push(value);
+    size += value.length;
+  }
+  const out = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return out;
+}