@substrio/cli 0.0.0-stage → 0.1.0

package/src/commands/bundle.mjs

@@ -0,0 +1,369 @@
+/**
+ * Substrio CLI: move an app between servers as one bundle.
+ *
+ *   substrio pull (--for PROFILE | --seal-to PUBKEY) [--out FILE]
+ *       Stream the app's export to FILE, sealed whole to one server's key
+ *       (--for: that profile's server, or --seal-to): only that server can
+ *       read any of it, so one of the two is required.
+ *   substrio push-bundle FILE --to PROFILE [--slug S] [--replace] [--save-profile NAME]
+ *       Stream FILE into the server of PROFILE as an app.
+ *   substrio move --to PROFILE [--slug S] [--replace] [--save-profile NAME]
+ *       Pipe the app's export, sealed to PROFILE's server, straight into that
+ *       server's import: one stream, no temp file.
+ *
+ * The destination takes its system key from the saved profile, never from the
+ * command line. The new app's key is saved (0600) to profile NAME only with
+ * --save-profile, and is never printed.
+ */
+
+import { createHash } from 'node:crypto';
+import {
+  createReadStream,
+  createWriteStream,
+  statSync,
+  unlinkSync,
+} from 'node:fs';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+
+import { SubstrioAPI } from '../api.mjs';
+import { addressOf, failover, liveMove, LiveMoveError } from '../live-move.mjs';
+import { listProfiles, readProfile, writeProfile } from '../config.mjs';
+import { ErrorCode, fail } from '../cli.mjs';
+import { invokeOperation } from './op.mjs';
+
+const C = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[91m',
+  green: '\x1b[92m',
+  yellow: '\x1b[93m',
+};
+
+export const BUNDLE_TYPE = 'application/vnd.substrio.bundle';
+
+const USAGE = {
+  pull: 'substrio pull (--for PROFILE | --seal-to PUBKEY) [--out FILE]',
+  'push-bundle':
+    'substrio push-bundle FILE --to PROFILE [--slug S] [--replace] [--save-profile NAME]',
+  move: 'substrio move --to PROFILE [--slug S] [--replace] [--save-profile NAME] | substrio move --live --to PROFILE | substrio move --failover --to PROFILE',
+};
+
+// The flags each command takes: true for one with a value, false for a switch.
+const FLAGS = {
+  pull: { '--out': true, '--seal-to': true, '--for': true },
+  'push-bundle': {
+    '--to': true,
+    '--slug': true,
+    '--replace': false,
+    '--save-profile': true,
+  },
+  move: {
+    '--to': true,
+    '--slug': true,
+    '--replace': false,
+    '--save-profile': true,
+    '--live': false,
+    '--failover': false,
+  },
+};
+
+
+/**
+ * The options of `command` from its arguments: {out, sealTo, for, to, slug,
+ * replace, saveProfile, file}. Throws on an unknown flag, a missing value, or
+ * a combination the command does not take. Pure.
+ */
+export function parseBundleArgs(command, args) {
+  const known = FLAGS[command];
+  if (!known) throw new Error(`Unknown bundle command: ${command}`);
+  const opts = { replace: false };
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg.startsWith('--')) {
+      positional.push(arg);
+      continue;
+    }
+    if (!(arg in known))
+      throw new Error(`${command} takes no ${arg}. Usage: ${USAGE[command]}`);
+    const name = arg.slice(2).replace(/-(\w)/g, (_, c) => c.toUpperCase());
+    if (!known[arg]) {
+      opts[name] = true;
+      continue;
+    }
+    const value = args[++i];
+    if (value === undefined || value.startsWith('--'))
+      throw new Error(`${arg} needs a value`);
+    opts[name] = value;
+  }
+  if (command === 'push-bundle') {
+    if (positional.length !== 1)
+      throw new Error(`Name one bundle file. Usage: ${USAGE[command]}`);
+    opts.file = positional[0];
+  } else if (positional.length) {
+    throw new Error(
+      `Unexpected argument ${positional[0]}. Usage: ${USAGE[command]}`
+    );
+  }
+  if (command === 'move' && opts.live && opts.failover)
+    throw new Error('Pass --live or --failover, not both');
+  if (command === 'move' && (opts.live || opts.failover) && (opts.slug || opts.replace || opts.saveProfile))
+    throw new Error(`A live move keeps the app's slug and its keys: --${opts.live ? 'live' : 'failover'} takes --to only`);
+  if (command === 'pull' && opts.sealTo && opts.for)
+    throw new Error('Pass --seal-to or --for, not both');
+  if (command === 'pull' && !opts.sealTo && !opts.for)
+    throw new Error(
+      `A bundle is sealed to the server that imports it: pass --for PROFILE or --seal-to PUBKEY. Usage: ${USAGE[command]}`
+    );
+  if (command !== 'pull' && !opts.to)
+    throw new Error(`--to PROFILE is required. Usage: ${USAGE[command]}`);
+  return opts;
+}
+
+// A saved profile with a URL and a key, or a failure naming what is missing.
+function destination(name) {
+  const profile = readProfile(name);
+  if (!profile)
+    fail(
+      `No saved profile "${name}"`,
+      'Save one with: substrio login --profile NAME'
+    );
+  if (!profile.url || !profile.master_key)
+    fail(`Profile "${name}" needs a url and a key`);
+  return profile;
+}
+
+// The API of a destination: its system key, and no app named.
+const destinationApi = (profile) =>
+  new SubstrioAPI({ url: profile.url, master_key: profile.master_key, tenant: null });
+
+// The seal key a server publishes for bundles sent to it (app.seal_key.get).
+async function sealKey(api) {
+  const data = await invokeOperation(api, 'app.seal_key.get', {});
+  if (!data?.public_key)
+    fail(`${api.url} published no seal key`, null, ErrorCode.UNKNOWN);
+  return data.public_key;
+}
+
+// The source's export (app.export) as a response whose body is still unread.
+const openExport = (config, sealTo) =>
+  invokeOperation(new SubstrioAPI(config), 'app.export', { seal_to: sealTo }, { stream: true });
+
+// Streams `body` (a web ReadableStream) into the destination's import
+// (app.import) and returns the parsed result.
+const sendImport = (api, opts, body) =>
+  invokeOperation(
+    api,
+    'app.import',
+    { ...(opts.slug ? { slug: opts.slug } : {}), ...(opts.replace ? { replace: true } : {}) },
+    {
+      body,
+      headers: { 'Content-Type': BUNDLE_TYPE },
+      hint: (result) =>
+        result.status === 409 ? 'The app has data there; pass --replace to overwrite it.' : null,
+    }
+  );
+
+const list = (items) => (items?.length ? items.join(', ') : 'none');
+
+// The import result, without its key; the key goes to a profile when asked.
+function report(result, profile, opts) {
+  const { key, ...shown } = result;
+  const verb = shown.created ? 'created' : 'replaced';
+  console.log(
+    `${C.green}✓${C.reset} App ${C.bold}${shown.app}${C.reset} ${verb} on ${profile.url}`
+  );
+  console.log(
+    `  versions ${shown.versions}, live ${shown.live ?? 'none'}, blobs ${shown.blobs}, database ${shown.database_bytes} bytes`
+  );
+  console.log(`  secrets: ${list(shown.secrets)}`);
+  const missing = shown.secrets_missing || [];
+  const tint = missing.length ? C.yellow : '';
+  console.log(
+    `${tint}  secrets_missing: ${list(missing)}${tint ? C.reset : ''}`
+  );
+  console.log(`  sandboxes: ${list(shown.sandboxes)}`);
+  if (shown.sandboxes_failed?.length)
+    console.log(
+      `${C.yellow}  sandboxes_failed: ${list(shown.sandboxes_failed)}${C.reset}`
+    );
+  if (opts.saveProfile && key) {
+    writeProfile(opts.saveProfile, profile.url, key);
+    console.log(
+      `  The app's key is saved to profile ${C.bold}${opts.saveProfile}${C.reset}.`
+    );
+    console.log(
+      `${C.dim}  In the app's substrio.toml: tenant = "${shown.app}", profile = "${opts.saveProfile}".${C.reset}`
+    );
+  } else if (key) {
+    console.log(
+      `${C.dim}  The app's new key was not saved (pass --save-profile NAME to keep it).${C.reset}`
+    );
+  }
+}
+
+// A new profile name must not overwrite a saved one; checked before any byte moves.
+function checkSaveProfile(opts) {
+  if (
+    opts.saveProfile &&
+    listProfiles().some((p) => p.name === opts.saveProfile)
+  ) {
+    fail(
+      `A profile named "${opts.saveProfile}" already exists; pass --save-profile with another name.`
+    );
+  }
+}
+
+function parseOrFail(command, args) {
+  try {
+    return parseBundleArgs(command, args);
+  } catch (err) {
+    fail(err);
+  }
+}
+
+/** substrio pull: the app's export, streamed to a file with its size and SHA-256. */
+export async function cmdPull(config, args) {
+  const opts = parseOrFail('pull', args);
+  const sealTo = opts.sealTo || (await sealKey(destinationApi(destination(opts.for))));
+  const out = opts.out || `${config.tenant || 'default'}.substrio-bundle`;
+  const exported = await openExport(config, sealTo);
+  const hash = createHash('sha256');
+  let bytes = 0;
+  const count = new Transform({
+    transform(chunk, _enc, done) {
+      hash.update(chunk);
+      bytes += chunk.length;
+      done(null, chunk);
+    },
+  });
+  try {
+    await pipeline(
+      Readable.fromWeb(exported.body),
+      count,
+      createWriteStream(out, { mode: 0o600 })
+    );
+  } catch (err) {
+    try {
+      unlinkSync(out);
+    } catch {
+      /* nothing was written */
+    }
+    fail(`Export stream failed: ${err.message}`, null, ErrorCode.UNKNOWN);
+  }
+  console.log(`${C.green}✓${C.reset} Wrote ${bytes} bytes to ${out}`);
+  console.log(`  sha256 ${hash.digest('hex')}`);
+}
+
+/** substrio push-bundle: a bundle file, streamed into the destination's import. */
+export async function cmdPushBundle(args) {
+  const opts = parseOrFail('push-bundle', args);
+  const profile = destination(opts.to);
+  checkSaveProfile(opts);
+  try {
+    statSync(opts.file);
+  } catch {
+    fail(`No such file: ${opts.file}`, null, ErrorCode.FILE_NOT_FOUND);
+  }
+  const result = await sendImport(
+    destinationApi(profile),
+    opts,
+    Readable.toWeb(createReadStream(opts.file))
+  );
+  report(result, profile, opts);
+}
+
+/** substrio move: the export, sealed to the destination, piped into its import. */
+export async function cmdMove(config, args) {
+  const opts = parseOrFail('move', args);
+  if (opts.live) return cmdLiveMove(config, opts);
+  if (opts.failover) return cmdFailover(config, opts);
+  const profile = destination(opts.to);
+  checkSaveProfile(opts);
+  const api = destinationApi(profile);
+  const exported = await openExport(config, await sealKey(api));
+  const result = await sendImport(api, opts, exported.body);
+  report(result, profile, opts);
+}
+
+// One server of a live move, from a profile: its master key on every call, the app named per call.
+function moveServer(url, masterKey) {
+  const api = new SubstrioAPI({ url, master_key: masterKey, tenant: null });
+  return {
+    address: addressOf(url),
+    url,
+    call: async (method, path, body, tenant) => {
+      const res = await api.raw(method, path, body, tenant ? { 'X-Substrio-Tenant': tenant } : {});
+      // Read as bytes first (MOVE-SITE forwards a site file through this `call`; decoding it as
+      // UTF-8 text before that would corrupt one that is not valid UTF-8).
+      const bytes = Buffer.from(await res.arrayBuffer());
+      const text = bytes.toString('utf8');
+      let json;
+      try {
+        json = JSON.parse(text);
+      } catch {
+        json = undefined;
+      }
+      return { status: res.status, json, text, bytes };
+    },
+  };
+}
+
+/**
+ * substrio move --live: the app moves to PROFILE's server while it keeps taking writes
+ * (live-move.mjs). Both profiles hold their server's master key; the slug stays the same.
+ */
+async function cmdLiveMove(config, opts) {
+  const profile = destination(opts.to);
+  const slug = config.tenant;
+  if (!slug) fail('Name the app to move: its profile has no tenant');
+  const step = (event, detail) =>
+    console.log(
+      event === 'flipped'
+        ? `flipped: ${profile.url} takes writes (fence ${detail.fenceMs.toFixed(1)} ms)`
+        : event === 'sessions_end'
+          ? `sessions_end: ${profile.url} signs sessions with its own key; every session on ${config.url} ends`
+          : event,
+    );
+  let result;
+  try {
+    result = await liveMove(slug, moveServer(config.url, config.master_key), moveServer(profile.url, profile.master_key), {
+      onEvent: step,
+    });
+  } catch (err) {
+    fail(err instanceof LiveMoveError ? err.message : String(err?.message ?? err));
+  }
+  console.log(`${slug} lives on ${profile.url}; ${config.url} keeps it as a read-only replica`);
+  console.log(
+    result.site
+      ? `site: release ${result.site.release}, ${result.site.files} file(s), ${result.site.bytes} byte(s)`
+      : 'site: none',
+  );
+}
+
+/**
+ * substrio move --failover: PROFILE's server, a replica of the app, takes its writes because the
+ * current profile's server no longer answers (live-move.mjs failover). A server that does answer
+ * is moved live instead, losing nothing.
+ */
+async function cmdFailover(config, opts) {
+  const profile = destination(opts.to);
+  const slug = config.tenant;
+  if (!slug) fail('Name the app to fail over: its profile has no tenant');
+  let out;
+  try {
+    out = await failover(slug, moveServer(config.url, config.master_key), moveServer(profile.url, profile.master_key), {
+      onEvent: (event) => console.log(event),
+    });
+  } catch (err) {
+    fail(err instanceof LiveMoveError ? err.message : String(err?.message ?? err));
+  }
+  if (out.mode === 'move') {
+    console.log(`${config.url} answered, so ${slug} was moved live (fence ${out.fenceMs.toFixed(1)} ms): nothing lost`);
+    return;
+  }
+  console.log(`${slug} takes writes on ${profile.url}, holding ${config.url}'s writes up to entry ${out.held}`);
+  console.log(`${config.url} did not answer and is NOT fenced: set ${slug} read-only there before it serves again; writes it acknowledged after entry ${out.held} reach ${profile.url} only if it comes back linked`);
+}

package/src/commands/count.mjs

@@ -0,0 +1,39 @@
+/**
+ * Substrio CLI: `substrio data count COLLECTION [where.FIELD=VALUE ...] [--data '{"where":{...}}']`.
+ *
+ * The same where filter `substrio data query` takes. The server's query.count answers by GET, whose query string
+ * has no `where`, so a filtered count runs as data.query with `count: true` (the server returns the count and
+ * no documents); an unfiltered one stays query.count. One owner of that choice: countPlan.
+ */
+
+import { parseOpArgs } from '../ops.mjs';
+import { runOperation } from './op.mjs';
+
+/** The operation of a count that has a filter, and the input it adds. */
+export const FILTERED_COUNT = Object.freeze({ operation: 'data.query', defaults: Object.freeze({ count: true }) });
+/** The operation of a count without one. */
+export const PLAIN_COUNT = Object.freeze({ operation: 'query.count', defaults: Object.freeze({}) });
+
+/** The input field that filters. */
+const FILTER_FIELD = 'where';
+
+/**
+ * Which operation counts for these arguments (pure): FILTERED_COUNT when the input they make holds a `where`,
+ * else PLAIN_COUNT. Arguments that do not parse are the operation's own error to report.
+ */
+export function countPlan(args) {
+    let input;
+    try {
+        ({ input } = parseOpArgs(args));
+    } catch {
+        return PLAIN_COUNT;
+    }
+    const filtered = input !== null && typeof input === 'object' && !Array.isArray(input) && Object.hasOwn(input, FILTER_FIELD);
+    return filtered ? FILTERED_COUNT : PLAIN_COUNT;
+}
+
+/** Runs the count a group command resolved ({positional, rest}). */
+export function cmdCount(api, resolved) {
+    const plan = countPlan(resolved.rest);
+    return runOperation(api, plan.operation, resolved.rest, { positional: resolved.positional, defaults: { ...plan.defaults } });
+}