@substrio/cli 0.0.0-stage → 0.1.0

package/src/jsonfile.mjs

@@ -0,0 +1,22 @@
+/**
+ * Substrio CLI: a JSON file a project names (rules_file, mcp_file, a collection's
+ * file), read once and checked: it must exist and be JSON. The one owner of
+ * those two refusals, so every command words them alike.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+
+import { CliError, ErrorCode } from './cli.mjs';
+
+/**
+ * The parsed JSON of the file at `abs`; `what` names the kind of file ("rules_file")
+ * and `shown` the path the project knows it by. Throws a CliError otherwise.
+ */
+export function readJsonFile(abs, what, shown) {
+    if (!existsSync(abs)) throw new CliError(`${what} ${shown} does not exist`, { code: ErrorCode.FILE_NOT_FOUND });
+    try {
+        return JSON.parse(readFileSync(abs, 'utf-8'));
+    } catch (err) {
+        throw new CliError(`${what} ${shown} is not valid JSON: ${err.message}`, { code: ErrorCode.INVALID_ARGUMENT });
+    }
+}

package/src/live-move.mjs

@@ -0,0 +1,267 @@
+/**
+ * The live move of an app between two servers (NIGHT-MIGRATE): the one owner of the algorithm,
+ * used by `substrio move --live` and by tests/integration/tenant_live_move.test.mjs.
+ *
+ * Made of what the platform has, in this order:
+ *   1. link: the destination holds the app read-only (a replica applies what its primary
+ *      accepted and refuses local writes) and joins the source over SubstrioLink with the
+ *      source's relay token and certificate pin (link_info), never its master key: it copies a
+ *      snapshot, then follows the source's oplog from the point the copy began. The app's key
+ *      ring is copied from the source to the destination (key_ring/set_key_ring) before the
+ *      catch-up below, so the app's own key already works there the moment the flip happens;
+ *      each server signs sessions with its own key, so when link_info's session_key_fingerprint
+ *      differs between the two, every session ends (reported, never a refusal: MOVE-KEYS);
+ *   2. catch-up: the destination's in-order position for the source (its version_vector entry)
+ *      reaches the source's head as read once, so the fence that follows is short;
+ *   3. fence: the source goes read-only; a client's write there is refused with 423
+ *      TENANT_READ_ONLY and is retried where the app lives next;
+ *   4. drain: the destination's position reaches the source's head, read again until it stands
+ *      still (a write that passed the gate just before the fence takes its number after it);
+ *   5. flip: the destination takes writes. The source stays linked as a read-only replica, so a
+ *      move back needs no new link; when the destination's URL is known, the source is marked
+ *      moved there and answers every request but a platform key's with 308 to it (MOVE-ROUTING).
+ * A drain or a flip that fails rolls back: the source takes writes again and the destination
+ * stays read-only, so the app is never without a primary and never has two.
+ *
+ * Every call needs each server's master key (the sync control route is master only).
+ *
+ * failover() promotes a replica when its primary no longer answers: the same status reads and
+ * the same flip, with no fence on a source that cannot be reached (see there).
+ */
+
+export class LiveMoveError extends Error {
+  /** @param {string} message @param {{ rolledBack?: boolean }} [detail] */
+  constructor(message, { rolledBack = false } = {}) {
+    super(message);
+    this.name = 'LiveMoveError';
+    this.rolledBack = rolledBack;
+  }
+}
+
+/**
+ * One server of a move.
+ * @typedef {object} MoveServer
+ * @property {string} address  host:port the other server reaches it on (SubstrioLink)
+ * @property {string} [url]  the URL clients reach it on: when the destination has one, the source is
+ *   marked moved there after the flip
+ * @property {(method: string, path: string, body?: any, tenant?: string | null) =>
+ *   Promise<{ status: number, json?: any, text?: string, bytes?: Buffer }>} call
+ *   an authenticated request with this server's master key; `tenant` names the app in
+ *   X-Substrio-Tenant, null for a platform call. `bytes`, when the implementation gives it, is
+ *   the body exactly as received (MOVE-SITE reads a site file through it; `text` alone would
+ *   corrupt one that is not valid UTF-8).
+ */
+
+/**
+ * @typedef {object} LiveMoveOptions
+ * @property {boolean} [link=true]  false when `to` already follows `from` (a move back)
+ * @property {number} [timeoutMs=60000]  for the copy's catch-up and for the drain, each
+ * @property {(event: string, detail: object) => void} [onEvent]  'linked', 'sessions_end', 'caught_up', 'fenced', 'drained', 'flipped'
+ */
+
+/**
+ * Moves app `slug` from `from` to `to` while it is written. Resolves to
+ * { fenceMs, head, sessionsEnd, site }: the time from the source refusing writes to the
+ * destination taking them, the source's last entry the destination holds, whether the two
+ * servers sign sessions differently (every session ended; always false on a move back,
+ * `link: false`), and the site pushed to the destination (MOVE-SITE; null when the app has none).
+ * @param {string} slug
+ * @param {MoveServer} from
+ * @param {MoveServer} to
+ * @param {LiveMoveOptions} [options]
+ */
+export async function liveMove(slug, from, to, { link = true, timeoutMs = 60000, onEvent = () => {} } = {}) {
+  const { sync, status, readonly, take, mark, siteExport, pushSite } = calls(slug);
+
+  let sessionsEnd = false;
+  if (link) {
+    const made = await to.call('POST', '/v1/_tenants', { slug }, null);
+    if (made.status >= 300 && made.status !== 409)
+      throw new LiveMoveError(`making ${slug} on ${to.address}: ${made.status} ${made.text ?? ''}`.trim());
+    await readonly(to, true);
+    await sync(from, { action: 'set_node_config', advertise_address: from.address });
+    await sync(to, { action: 'set_node_config', advertise_address: to.address });
+    const info = await sync(from, { action: 'link_info' });
+    const destInfo = await sync(to, { action: 'link_info' });
+    await sync(to, { action: 'connect_peer', address: from.address, token: info.relay_token, pin: info.pin });
+    // Each server signs sessions with its own generated key: unless the two match, a session
+    // from the source is unreadable on the destination the moment it takes writes.
+    sessionsEnd = info.session_key_fingerprint !== destInfo.session_key_fingerprint;
+    onEvent('linked', {});
+  }
+
+  // The app's key ring, copied before the catch-up so the destination already checks exactly
+  // the keys the source does the moment the flip happens. Run on a move back too (link=false):
+  // a rotation may have happened since the ring was last copied there.
+  const ring = await sync(from, { action: 'key_ring' });
+  await sync(to, { action: 'set_key_ring', ring: ring.ring });
+  if (sessionsEnd) onEvent('sessions_end', {});
+
+  // MOVE-SITE: the source's site, carried before the flip (never replicated by the oplog/
+  // snapshot copy above). Read and pushed here, before catch-up, so a large site's transfer
+  // overlaps it rather than extending the fence.
+  let release = await siteExport(from);
+  let site = await pushSite(from, to, release);
+
+  // The source's node id, as the destination's version vector names it (8 hex digits).
+  const origin = ((await status(from)).node_id >>> 0).toString(16).padStart(8, '0');
+
+  const head = async () => BigInt((await status(from)).sync_stats.origin_seq);
+  // MOVE-IS-MESH: one call the destination answers the moment it holds the source's history to
+  // `target` and copies nothing (a snapshot, or the pull chains after it, holds nothing yet,
+  // whatever its version vector says), parked on its version vector: no status polling.
+  // `linked`: also until the source is a linked peer of the destination.
+  // The call itself is bounded too: a destination that stops answering (frozen, cut off) is a timeout here,
+  // which rolls the move back, never a wait without end.
+  const reach = async (target, what, linked = false) => {
+    const call = sync(to, { action: 'await_caught_up', origin, seq: Number(target), timeout_ms: timeoutMs, ...(linked ? { linked } : {}) });
+    let timer;
+    const silent = new Promise((done) => (timer = setTimeout(() => done(null), timeoutMs + 2000)));
+    const r = await Promise.race([call, silent]).finally(() => clearTimeout(timer));
+    if (r === null) {
+      call.catch(() => {});  // answered or refused later: nobody waits for it any more
+      throw new LiveMoveError(`timed out waiting for ${what}: ${to.address} did not answer`);
+    }
+    if (!r.held) throw new LiveMoveError(`timed out waiting for ${what}: ${r.at} of ${target}`);
+  };
+
+  // The link first: connect_peer returns before the connection is made (a TLS handshake across a WAN outlasts a
+  // whole drain), and until the source records, its head names nothing (0, or only the marker it takes when
+  // recording starts, which the destination reaches only by copying). The source turns recording on when it
+  // registers the destination, before it answers the link's auth, so a linked source records: one parked call.
+  await reach(0n, `${to.address} to link to ${from.address}`, true);
+  await reach(await head(), 'the copy to catch up');
+  onEvent('caught_up', {});
+
+  const fenceStart = process.hrtime.bigint();
+  await readonly(from, true);
+  onEvent('fenced', {});
+  let last = -1n;
+  try {
+    for (let now = await head(); now !== last; now = await head()) {
+      last = now;
+      await reach(now, `the drain to ${now}`);
+    }
+    onEvent('drained', { head: last });
+    // MOVE-SITE: a deploy to the source during the move (rare: the fence holds every other
+    // write) lands between the first export and here. The release id is the check; re-pushing
+    // only on a change keeps the common path at one export and one push.
+    const after = await siteExport(from);
+    if (after?.id !== release?.id) site = await pushSite(from, to, after);
+    await take(to);
+  } catch (err) {
+    // The app keeps exactly one primary: the source takes writes again.
+    const back = await from.call('PATCH', `/v1/_tenants/${encodeURIComponent(slug)}`, { readonly: false }, null);
+    throw new LiveMoveError(`${err.message}; rolled back: ${from.address} takes writes again (${back.status})`, {
+      rolledBack: back.status < 300,
+    });
+  }
+  const fenceMs = Number(process.hrtime.bigint() - fenceStart) / 1e6;
+  onEvent('flipped', { fenceMs });
+  // After the flip, never inside the rollback: the app has its one primary whatever this answers.
+  if (to.url) {
+    try {
+      await mark(from, to.url);
+    } catch (err) {
+      throw new LiveMoveError(`${to.address} takes writes; marking ${from.address} moved failed: ${err.message}`);
+    }
+  }
+  return { fenceMs, head: last, sessionsEnd, site };
+}
+
+/**
+ * Promotes `to`, a replica of `slug` that follows `from`, when `from` no longer answers.
+ * A source that answers within `probeMs` is not failed over: the call is a planned move instead
+ * (liveMove with the link already up), which loses nothing. Otherwise `to` must hold `from` as a
+ * peer (matched by address, or by `origin`, its node id in 8 hex digits) and must not be copying
+ * (a replica mid-copy lacks what the copy has not brought); then it takes writes.
+ * The source cannot be fenced: whatever it acknowledged past `held` (its last entry `to` holds in
+ * order) is on it alone, and it must be set read-only before it serves the app again; if it comes
+ * back still linked, those writes reach `to` over the link like any other.
+ * Resolves to { mode: 'move', fenceMs, head } or { mode: 'failover', held, peer }.
+ * @param {string} slug
+ * @param {MoveServer} from
+ * @param {MoveServer} to
+ * @param {LiveMoveOptions & { probeMs?: number, origin?: string }} [options]
+ */
+export async function failover(slug, from, to, { probeMs = 2000, origin, ...moveOptions } = {}) {
+  if (await answers(from, slug, probeMs)) {
+    return { mode: 'move', ...(await liveMove(slug, from, to, { ...moveOptions, link: false })) };
+  }
+  const { status, take } = calls(slug);
+  const s = await status(to);
+  const peer = (s.peers ?? []).find((p) => (origin ? p.node_id === origin : p.address === from.address));
+  if (!peer) throw new LiveMoveError(`${to.address} does not follow ${from.address} for ${slug}: it holds no copy to promote`);
+  if (s.catching_up) {
+    throw new LiveMoveError(`${to.address} is still copying ${slug} from ${from.address}: promoting it would lose what the copy has not brought`);
+  }
+  const held = BigInt(s.version_vector?.[peer.node_id] ?? 0);
+  await take(to);
+  (moveOptions.onEvent ?? (() => {}))('promoted', { held });
+  return { mode: 'failover', held, peer };
+}
+
+// The calls of one move or failover of `slug`: every refusal a LiveMoveError naming the server.
+function calls(slug) {
+  const must = async (server, method, path, body, tenant, what) => {
+    const r = await server.call(method, path, body, tenant);
+    if (r.status >= 300) throw new LiveMoveError(`${what} on ${server.address}: ${r.status} ${r.text ?? ''}`.trim());
+    return r.json;
+  };
+  const tenant = (server, body, what) => must(server, 'PATCH', `/v1/_tenants/${encodeURIComponent(slug)}`, body, null, what);
+  const sync = (server, body) => must(server, 'POST', '/v1/_sync', body, slug, body.action);
+  // MOVE-SITE: `server`'s active site release, in site.release.create's own manifest shape
+  // ({id, files: [{path, hash, size}]}), or null when the app has none. Reads the stored
+  // manifest only (substrio_site.cpp's SiteStore::active_release): no file's bytes.
+  const siteExport = async (server) => (await sync(server, { action: 'site_export' })).release;
+  // MOVE-SITE: pushes `release` (siteExport's shape) from `from` to `to` through the same op
+  // `substrio site deploy` uses (site.release.create, then site.blob.upload for each blob `to`
+  // lacks, then site.release.activate). A blob's bytes are read from `from` once, by the path
+  // its release names (its own static route: no second reader of a site file), and sent on;
+  // null `release`: nothing to push. Resolves to { release, files, bytes } for the report, or
+  // null.
+  const pushSite = async (from, to, release) => {
+    if (!release) return null;
+    const created = await must(to, 'POST', '/v1/_site/releases', { files: release.files }, slug, 'site.release.create');
+    for (const hash of created.missing) {
+      const file = release.files.find((f) => f.hash === hash);
+      const path = `/_/${file.path.split('/').map(encodeURIComponent).join('/')}`;
+      const read = await from.call('GET', path, undefined, slug);
+      if (read.status >= 300) throw new LiveMoveError(`reading ${file.path} on ${from.address}: ${read.status} ${read.text ?? ''}`.trim());
+      const bytes = read.bytes ?? Buffer.from(read.text ?? '', 'utf8');
+      await must(to, 'PUT', `/v1/_site/blobs/${hash}`, bytes, slug, `uploading ${file.path}`);
+    }
+    const activated = await must(to, 'POST', `/v1/_site/releases/${created.release.id}/activate`, {}, slug, 'site.release.activate');
+    return { release: activated.active, files: release.files.length, bytes: release.files.reduce((sum, f) => sum + f.size, 0) };
+  };
+  return {
+    sync,
+    status: (server) => must(server, 'GET', '/v1/_sync', undefined, slug, 'sync status'),
+    readonly: (server, value) => tenant(server, { readonly: value }, `readonly ${value}`),
+    // The server becomes the app's primary: it takes writes and is no longer marked moved.
+    take: (server) => tenant(server, { readonly: false, moved_to: null }, 'readonly false'),
+    // The old primary names where the app lives now (MOVE-ROUTING).
+    mark: (server, url) => tenant(server, { moved_to: url }, `moved_to ${url}`),
+    siteExport,
+    pushSite,
+  };
+}
+
+// Whether `server` answers a sync status read for `slug` within `ms` (a refused connection, an
+// error answer and silence are all "no").
+async function answers(server, slug, ms) {
+  let timer;
+  const silence = new Promise((done) => (timer = setTimeout(() => done(false), ms)));
+  const reply = server.call('GET', '/v1/_sync', undefined, slug).then((r) => r.status < 300, () => false);
+  try {
+    return await Promise.race([reply, silence]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** host:port of a server URL, with the scheme's port when the URL names none. */
+export function addressOf(url) {
+  const u = new URL(url);
+  return `${u.hostname}:${u.port || (u.protocol === 'https:' ? 443 : 80)}`;
+}

package/src/local/args.mjs

@@ -0,0 +1,58 @@
+/**
+ * Substrio CLI: the flags of `substrio dev` and `substrio test`, parsed once against a
+ * closed table. A flag the command does not take, or a value flag with no
+ * value, is a typed usage error; nothing is guessed.
+ */
+
+import { CliError, ErrorCode } from '../cli.mjs';
+
+/** How a flag takes its value. */
+export const FlagKind = Object.freeze({
+    SWITCH: 'switch', // present or not
+    VALUE: 'value',   // the next argument, or `--flag=value`
+});
+
+/**
+ * @param {string[]} args
+ * @param {Record<string, string>} table flag name -> FlagKind
+ * @returns {{flags: Map<string, string|true>, positional: string[]}}
+ */
+export function parseFlags(args, table) {
+    const flags = new Map();
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (!arg.startsWith('--')) {
+            positional.push(arg);
+            continue;
+        }
+        const equals = arg.indexOf('=');
+        const name = equals < 0 ? arg : arg.slice(0, equals);
+        const kind = table[name];
+        if (kind === undefined) {
+            throw new CliError(`Unknown flag ${name}`, { code: ErrorCode.INVALID_ARGUMENT, hint: `It takes ${Object.keys(table).join(', ')}` });
+        }
+        if (kind === FlagKind.SWITCH) {
+            if (equals >= 0) throw new CliError(`${name} takes no value`, { code: ErrorCode.INVALID_ARGUMENT });
+            flags.set(name, true);
+            continue;
+        }
+        const value = equals >= 0 ? arg.slice(equals + 1) : args[++i];
+        if (value === undefined || value === '') {
+            throw new CliError(`${name} needs a value`, { code: ErrorCode.INVALID_ARGUMENT });
+        }
+        flags.set(name, value);
+    }
+    return { flags, positional };
+}
+
+/** A whole number flag in [low, high], or `fallback` when absent. */
+export function wholeNumber(flags, name, low, high, fallback) {
+    const text = flags.get(name);
+    if (text === undefined) return fallback;
+    const value = Number(text);
+    if (!Number.isInteger(value) || value < low || value > high) {
+        throw new CliError(`${name} must be a whole number from ${low} to ${high}`, { code: ErrorCode.INVALID_ARGUMENT });
+    }
+    return value;
+}