@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/worker/identity.ts

@@ -0,0 +1,183 @@
+// The worker's uplink identity, as three files under WORKER_DIR.
+//
+//   identity.key   32 raw bytes, mode 600, generated once and never rewritten.
+//                  It never leaves the box: a rebuilt box is a new worker.
+//   home.pub       the pinned Home static key, encoded. Whatever the worker
+//                  ends up trusting is written here, so the next boot needs no
+//                  token and no mounted etc tree.
+//   enrolled.json  `{workerId, slug}`, written when Home answers `enroll`.
+//
+// The pin is what the security of the uplink rests on
+// (`todo/ideas/uplink.md` § What it guarantees), so it is resolved from one
+// of three named sources and logged once, never guessed.
+
+import { dirname, join } from "@std/path";
+import { z } from "zod";
+import { log } from "@local/logger";
+import { generateKeypair, KEY_LENGTH, type Keypair, keypairFromPrivateKey } from "@yourrealm/noise";
+import { decodePublicKey, encodePublicKey } from "../worker-protocol/uplink/identity.ts";
+
+const IDENTITY_FILE = "identity.key";
+const HOME_KEY_FILE = "home.pub";
+const ENROLLMENT_FILE = "enrolled.json";
+
+/** Home writes its public key here on boot; a co-located worker mounts the tree. */
+const ETC_HOME_KEY = "home/uplink.pub";
+
+/** How often the wait below re-checks for the file Home is about to write. */
+const PIN_POLL_MS = 2000;
+
+/** What Home hands back once it holds a row for this worker's key. */
+export interface Enrollment {
+  workerId: string;
+  slug: string;
+}
+
+const enrollmentSchema = z.object({
+  workerId: z.string().min(1),
+  slug: z.string().min(1),
+});
+
+/**
+ * This worker's static keypair, generated on first boot.
+ *
+ * `mode` only applies on creation, so the file is chmod'd on every boot: a key
+ * that became group-readable (a restored backup, a hand-edit) is tightened
+ * rather than trusted.
+ */
+export async function loadIdentity(workerDir: string): Promise<Keypair> {
+  const path = join(workerDir, IDENTITY_FILE);
+  const existing = await readFileOrNull(path);
+  if (existing !== null) {
+    if (existing.length !== KEY_LENGTH) {
+      throw new Error(`${path} holds ${existing.length} bytes, not a ${KEY_LENGTH}-byte key`);
+    }
+    await Deno.chmod(path, 0o600);
+    return keypairFromPrivateKey(existing);
+  }
+
+  await Deno.mkdir(workerDir, { recursive: true, mode: 0o700 });
+  const keypair = generateKeypair();
+  await Deno.writeFile(path, keypair.privateKey, { mode: 0o600 });
+  await Deno.chmod(path, 0o600);
+  log(`Generated this worker's uplink identity: ${encodePublicKey(keypair.publicKey)}`);
+  return keypair;
+}
+
+/** The enrollment from a previous boot, or null on a worker that never enrolled. */
+export async function readEnrollment(workerDir: string): Promise<Enrollment | null> {
+  const path = join(workerDir, ENROLLMENT_FILE);
+  const raw = await readTextOrNull(path);
+  if (raw === null) return null;
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    log.warn(`${path} is not JSON; treating this worker as unenrolled`);
+    return null;
+  }
+  const parsed = enrollmentSchema.safeParse(value);
+  if (!parsed.success) {
+    log.warn(`${path} is not an enrollment record; treating this worker as unenrolled`);
+    return null;
+  }
+  return parsed.data;
+}
+
+export async function writeEnrollment(workerDir: string, enrollment: Enrollment): Promise<void> {
+  await Deno.mkdir(workerDir, { recursive: true, mode: 0o700 });
+  await Deno.writeTextFile(join(workerDir, ENROLLMENT_FILE), `${JSON.stringify(enrollment)}\n`, {
+    mode: 0o600,
+  });
+}
+
+interface PinOptions {
+  workerDir: string;
+  /** `REALM_ETC_DIR`; the third source lives under it. */
+  etcDir: string;
+  /** The key half of `REALM_TOKEN`, when the token carried one. */
+  tokenKey?: Uint8Array | null;
+  /** Test seam for the wait below. */
+  pollIntervalMs?: number;
+}
+
+/**
+ * Home's static key, from the first source that has one:
+ *
+ *   1. the key half of `REALM_TOKEN` — the operator pasted it themselves;
+ *   2. `home.pub` — what a previous boot resolved and kept;
+ *   3. `${etcDir}/home/uplink.pub` — what Home writes on its own box.
+ *
+ * A bare-OTP token on a fresh co-located box has neither 2 nor 3 yet, because
+ * Home boots seconds ahead of the worker. That is a wait, not a failure: the
+ * worker polls for the file rather than dialling something it cannot verify.
+ * Whatever is resolved is persisted as `home.pub`.
+ */
+export async function resolveHomePublicKey(opts: PinOptions): Promise<Uint8Array> {
+  const homePubPath = join(opts.workerDir, HOME_KEY_FILE);
+  const etcPath = join(opts.etcDir, ETC_HOME_KEY);
+
+  if (opts.tokenKey != null) {
+    await persistHomeKey(homePubPath, opts.tokenKey);
+    return pinned(opts.tokenKey, "REALM_TOKEN");
+  }
+
+  const kept = await readPublicKeyFile(homePubPath);
+  if (kept !== null) return pinned(kept, homePubPath);
+
+  const fromEtc = await readPublicKeyFile(etcPath);
+  if (fromEtc !== null) {
+    await persistHomeKey(homePubPath, fromEtc);
+    return pinned(fromEtc, etcPath);
+  }
+
+  log(`Home's uplink key is not on this box yet; waiting for ${etcPath}`);
+  const interval = opts.pollIntervalMs ?? PIN_POLL_MS;
+  for (;;) {
+    await new Promise((resolve) => setTimeout(resolve, interval));
+    const appeared = await readPublicKeyFile(etcPath);
+    if (appeared === null) continue;
+    await persistHomeKey(homePubPath, appeared);
+    return pinned(appeared, etcPath);
+  }
+}
+
+function pinned(key: Uint8Array, source: string): Uint8Array {
+  log(`Pinned Home's uplink key ${encodePublicKey(key)} from ${source}`);
+  return key;
+}
+
+async function persistHomeKey(path: string, key: Uint8Array): Promise<void> {
+  await Deno.mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  await Deno.writeTextFile(path, `${encodePublicKey(key)}\n`, { mode: 0o600 });
+}
+
+/** A file holding one encoded public key, or null when it is absent or junk. */
+async function readPublicKeyFile(path: string): Promise<Uint8Array | null> {
+  const raw = await readTextOrNull(path);
+  if (raw === null) return null;
+  const key = decodePublicKey(raw.trim());
+  if (key === null) {
+    log.warn(`${path} does not hold an uplink public key; ignoring it`);
+    return null;
+  }
+  return key;
+}
+
+async function readFileOrNull(path: string): Promise<Uint8Array | null> {
+  try {
+    return await Deno.readFile(path);
+  } catch (err) {
+    if (err instanceof Deno.errors.NotFound) return null;
+    throw err;
+  }
+}
+
+async function readTextOrNull(path: string): Promise<string | null> {
+  try {
+    return await Deno.readTextFile(path);
+  } catch (err) {
+    if (err instanceof Deno.errors.NotFound) return null;
+    throw err;
+  }
+}

package/src/worker/index.ts

@@ -0,0 +1,16 @@
+// @yourrealm/sdk/worker — the worker harness.
+//
+// Long-running process that holds one uplink session to Home, pulls state
+// over it, untars + parses, and calls back into a host-supplied apply. Pulls
+// types from @yourrealm/sdk/worker-protocol; the host wires a runtime-specific
+// renderer (e.g. @yourrealm/sdk/runtime/docker/compose) in the onNewState
+// callback at reconcile time.
+
+export {
+  type ReconcileContext,
+  startWorker,
+  type StartWorkerOptions,
+  type WorkerHandle,
+} from "./start-worker.ts";
+export { validateWorkerState } from "./validate.ts";
+export { WorkerOffline } from "./uplink.ts";

package/src/worker/public-ip.ts

@@ -0,0 +1,92 @@
+// The worker's own public address, for Home's `worker.public_ip`.
+//
+// Home sees the address whatever proxies the uplink hands it, which on a
+// co-located box is a container address and behind a CDN is the CDN's; a box
+// reading its own interface behind NAT gets the LAN address. So the worker
+// asks something outside and reports the answer, and Home keeps this one.
+// `domain_claim` probing compares a resolved hostname against it (see
+// `todo/ideas/naming-layer.md`).
+//
+// **The echo URL comes from Home, on the announce, and there is no default.**
+// A realm with no Realm DNS configured gets `null` and this module then never
+// makes a request - a hardcoded default would have every self-hosted worker
+// quietly talking to `yourrealm.eu`. `REALM_PUBLIC_IP_URL` overrides it for an
+// operator running their own echo.
+//
+// It measures the TCP path on purpose: a DNS A record and HTTP-01 both care
+// about that, and on a symmetric NAT a UDP mapping differs from it.
+
+import { z } from "zod";
+import { log } from "@local/logger";
+
+// Matches caddy-dynamicdns's `check_interval` - the same question, asked at the
+// same rate, for the same reason.
+const TTL_MS = 5 * 60_000;
+// A reconcile must never wait on an external service. Short enough to be noise
+// against the tar stream and compose run the pull already costs.
+const TIMEOUT_MS = 2000;
+
+const ipSchema = z.union([z.ipv4(), z.ipv6()]);
+
+let echoUrl: string | null = null;
+let cached: string | null = null;
+let fetchedAt = 0;
+
+/**
+ * Point this module at a source-IP echo, or at nothing. Called with whatever
+ * Home answers the announce with; a `REALM_PUBLIC_IP_URL` override always
+ * wins, so a later announce can't drag an operator's own echo back to the
+ * default.
+ */
+export function setPublicIpEcho(url: string | null): void {
+  const override = Deno.env.get("REALM_PUBLIC_IP_URL");
+  const next = override ?? url;
+  if (next === echoUrl) return;
+  echoUrl = next;
+  // A changed echo invalidates what the old one said. Not a correctness
+  // problem (both report the same box) but it keeps `fetchedAt` honest.
+  cached = null;
+  fetchedAt = 0;
+}
+
+/**
+ * The last known public address, refreshed if it has gone stale. Returns null
+ * when no echo is configured or none has ever answered - callers must treat
+ * that as "unknown", never as "unreachable".
+ *
+ * Awaits the refresh rather than kicking it off in the background: reconciles
+ * are rare and trigger-driven, so a value refreshed after the pull would be
+ * one whole reconcile behind, and on a box whose address just moved that is
+ * exactly when the answer matters. Bounded by TIMEOUT_MS, and a failure keeps
+ * serving the previous value.
+ *
+ * `now` is a seam for the tests, which otherwise cannot reach the staleness
+ * branch without sitting out a five-minute TTL.
+ */
+export async function currentPublicIp(now: number = Date.now()): Promise<string | null> {
+  if (echoUrl === null) return null;
+  if (cached !== null && now - fetchedAt < TTL_MS) return cached;
+
+  try {
+    const res = await fetch(echoUrl, { signal: AbortSignal.timeout(TIMEOUT_MS) });
+    if (!res.ok) {
+      await res.body?.cancel();
+      throw new Error(`echo returned ${res.status}`);
+    }
+    const body = (await res.text()).trim();
+    const parsed = ipSchema.safeParse(body);
+    if (!parsed.success) {
+      // A captive portal or an error page answers 200 with HTML. Storing that
+      // would put junk in `worker.public_ip` and read as a mismatch on
+      // every claim, which is worse than knowing nothing.
+      throw new Error("echo did not answer with an IP address");
+    }
+    cached = parsed.data;
+    fetchedAt = now;
+  } catch (err) {
+    // Keep whatever we had. An address that moved is rare; an echo that
+    // blipped is not, and a null here would blank a good value on Home.
+    log.warn(`Public IP echo failed (${(err as Error).message})`);
+  }
+  return cached;
+}

package/src/worker/queue.ts

@@ -0,0 +1,54 @@
+import { log } from "@local/logger";
+import { reconcileWorker, type ReconcileDeps } from "./reconcile.ts";
+import type { WorkerState } from "../worker-protocol/index.ts";
+
+interface ReconcileQueue {
+  trigger(): void;
+  /** The etag this worker last applied, or null. Reported on every announce. */
+  appliedEtag(): string | null;
+}
+
+/**
+ * Debounced, serial reconcile queue. `trigger()` is fire-and-forget:
+ * if a reconcile is already running, it sets a flag so the loop
+ * runs again right after. Errors inside reconcile are logged and
+ * swallowed (the next trigger picks up).
+ */
+export function createReconcileQueue(deps: ReconcileDeps): ReconcileQueue {
+  let isRunning = false;
+  let pendingWhileRunning = false;
+  let lastEtag: string | null = null;
+  // Kept so a 304 can re-run the idempotent healers (onUnchanged) against the
+  // state the current etag describes.
+  let lastState: WorkerState | null = null;
+
+  function trigger(): void {
+    if (isRunning) {
+      pendingWhileRunning = true;
+      return;
+    }
+    void run();
+  }
+
+  async function run(): Promise<void> {
+    isRunning = true;
+    try {
+      do {
+        pendingWhileRunning = false;
+        try {
+          log("Reconciling worker...");
+          const result = await reconcileWorker(deps, lastEtag, lastState);
+          lastEtag = result.etag;
+          lastState = result.state ?? lastState;
+          log(`Reconciled worker ${result.etag}`);
+        } catch (err) {
+          log.error("Worker reconcile failed:", { err });
+        }
+      } while (pendingWhileRunning);
+    } finally {
+      isRunning = false;
+    }
+  }
+
+  return { trigger, appliedEtag: () => lastEtag };
+}

package/src/worker/reconcile.ts

@@ -0,0 +1,127 @@
+import { log } from "@local/logger";
+import { extractTarToWorkerDir } from "./extract-tar.ts";
+import { validateWorkerState } from "./validate.ts";
+import { currentPublicIp } from "./public-ip.ts";
+import { workerStateSchema, type WorkerState } from "../worker-protocol/index.ts";
+import type { AppApplyResult, Params, StatePull } from "../worker-protocol/uplink/index.ts";
+
+interface ReconcileResult {
+  /** Null until a pull has landed: a worker Home has nothing for yet. */
+  etag: string | null;
+  /** The applied state — parsed on a 200, echoed back from `lastState` on a 304. */
+  state?: WorkerState;
+}
+
+export interface ReconcileDeps {
+  workerDir: string;
+  /** `state.pull` over the live session. */
+  pull: (params: Params<"state.pull">) => Promise<StatePull>;
+  /**
+   * `state.applied`, so Home learns what this worker is running and which of
+   * its apps came up. `apps` is one entry per compose project the callback ran.
+   */
+  applied?: (etag: string, apps: AppApplyResult[]) => Promise<void>;
+  /** Applies the state; resolves with one result per app it brought up. */
+  onNewState: (state: WorkerState) => Promise<AppApplyResult[]>;
+  /**
+   * Fires on a 304 (state unchanged) with the last-known state. Wire the cheap,
+   * idempotent healers here (broker-socket ensure) so anything that can vanish
+   * without a state change — a stray `rm`, a crashed broker — is
+   * rebuilt on any reconcile trigger instead of staying dead until the next
+   * state change. Must be a strict subset of `onNewState`'s side effects.
+   *
+   * Resolves with the results of any app it re-upped, empty when it only
+   * healed. A non-empty answer is reported to Home against the held etag: that
+   * is how an app that failed on the state change and came up on a retry stops
+   * reading as failed.
+   */
+  onUnchanged?: (state: WorkerState) => Promise<AppApplyResult[]>;
+}
+
+/**
+ * Reconcile the whole worker by pulling the per-worker state.json + supporting
+ * files from Home over the uplink and handing the parsed wire state to
+ * `onNewState`. Home serves a content-hash etag; we send it back so unchanged
+ * state collapses to a 304.
+ *
+ * Tar's "only writes paths in the archive" semantics naturally preserves
+ * apps/${appId}/data/ runtime dirs — Home never includes those in the tar.
+ */
+export async function reconcileWorker(
+  deps: ReconcileDeps,
+  lastEtag: string | null,
+  lastState: WorkerState | null,
+): Promise<ReconcileResult> {
+  // Ride the pull rather than the announce: an announce is a boot event, so a
+  // worker whose public address moves would keep reporting the old one until
+  // its container is recreated. Every trigger refreshes it here instead, which
+  // is why there is no heartbeat loop for this. Absent when unknown - Home
+  // reads a missing field as "leave the column alone", never as "clear it".
+  const publicIp = await currentPublicIp();
+  const res = await deps.pull({
+    etag: lastEtag,
+    ...(publicIp === null ? {} : { publicIp }),
+  });
+
+  if (res.status === 304) {
+    await res.body.cancel();
+    log("Skipping reconcile (no changes)");
+    // State is unchanged, but the local brokers it describes may not be — heal
+    // them against the last-known state so a vanished socket doesn't wait for
+    // the next state change to come back.
+    if (lastState && deps.onUnchanged) {
+      const apps = await deps.onUnchanged(lastState);
+      // Only a retry that actually ran something has news; an idle heal sends
+      // nothing, so a 304 costs Home no write.
+      if (apps.length > 0 && lastEtag !== null) await reportApplied(deps, lastEtag, apps);
+    }
+    return { etag: lastEtag, ...(lastState === null ? {} : { state: lastState }) };
+  }
+  if (res.status === 503) {
+    await res.body.cancel();
+    // Home is up but has not computed this worker's state yet. It pushes a
+    // reconcile the moment it has, so there is nothing to retry here.
+    log("Home has no state for this worker yet");
+    return { etag: lastEtag, ...(lastState === null ? {} : { state: lastState }) };
+  }
+  if (res.status !== 200) {
+    await res.body.cancel();
+    throw new Error(`state.pull answered ${res.status}`);
+  }
+  if (res.etag === undefined) {
+    await res.body.cancel();
+    throw new Error("state.pull answered 200 without an etag");
+  }
+
+  await Deno.mkdir(deps.workerDir, { recursive: true, mode: 0o700 });
+  // mkdir's `mode` is ignored when the dir already exists; chmod
+  // every reconcile so a pre-existing 0o755 dir gets tightened.
+  await Deno.chmod(deps.workerDir, 0o700);
+  const { stateJsonString } = await extractTarToWorkerDir(res.body, deps.workerDir);
+
+  if (stateJsonString == null) throw new Error("state.pull answered without a state.json entry");
+
+  const state = workerStateSchema.parse(JSON.parse(stateJsonString));
+  validateWorkerState(state);
+
+  const apps = await deps.onNewState(state);
+  await reportApplied(deps, res.etag, apps);
+
+  return { etag: res.etag, state };
+}
+
+/**
+ * Fire and forget: Home learns what this worker is running, and a failure
+ * here must not turn a landed reconcile into a failed one. The next announce
+ * carries the same etag, and the next trigger re-reports any app still down.
+ */
+async function reportApplied(
+  deps: ReconcileDeps,
+  etag: string,
+  apps: AppApplyResult[],
+): Promise<void> {
+  if (!deps.applied) return;
+  await deps.applied(etag, apps).catch((err: unknown) => {
+    log.warn(`state.applied ${etag} failed (${(err as Error).message})`);
+  });
+}