@joystack/cli 0.1.44 → 0.1.46

package/lib/freeze.mjs

@@ -1,15 +1,17 @@
-// `joystack dev --no-reload`: the game as it is at startup, for the whole run.
+// A copy of the game as it is at one moment: one version of it, as `joystack
+// dev` serves it (live-versions.mjs).
 //
-// The dev server reads a game's files from disk on every request and rebuilds
-// its room when they change, so switching the watchers off alone does not
-// freeze anything: a page opened after an edit gets the edited files, while the
-// room and the injected entity layout stay as they were, and an edit that adds
-// an entity makes that page fail to boot. Freezing therefore serves, and builds
-// the room from, a copy of the game taken once at startup.
-import { constants, cpSync, existsSync, mkdirSync, readdirSync, rmSync, symlinkSync, unlinkSync } from 'node:fs';
+// Serving the game's own folder cannot give a page one version: the page
+// fetches files for as long as it runs, while the room and the injected entity
+// layout are built once, so an edit lands in some of them and not the others.
+// A copy is served and built from instead, and replaced by a new copy, never
+// edited.
+import { constants, copyFileSync, cpSync, existsSync, linkSync, mkdirSync, readdirSync, rmSync, symlinkSync, unlinkSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
-import { basename, join } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path';
+import { collectGameFiles } from './game-files.mjs';
 import { gameBuild } from './build-id.mjs';
+import { snapshotFiles } from './live-versions.mjs';
 import { STATE_DIR_NAMES, stateDir } from './legacy-names.mjs';
 
 // Left out of the copy: recordings and generated build output (.joystack), which
@@ -27,21 +29,39 @@ export function frozenRoot(gameDir) {
   return join(stateDir(gameDir), 'frozen');
 }
 
+// The files a copy of the game at `dir` is taken from, as path → `mtime:size`.
+//
+// Small files also carry a hash of their content. On Windows a file's
+// modified time moves in steps of about 15 ms, so a rewrite to the same size
+// within one step would otherwise go unseen; large files are left to time and
+// size, since reading them on every poll would cost more than it finds.
+export function frozenFiles(dir) {
+  return snapshotFiles([dir], (name, depth) => depth === 0 && LEFT_OUT.has(name), { hashBelow: 256 * 1024 });
+}
+
 /**
  * Copies the game at `dir` into `.joystack/frozen/<pid>-<random>/<folder name>`.
- * `build` is the game's build at the moment of the copy, the one every session
- * played on the copy is stamped with. `remove()` deletes the copy; it also runs
- * when the process exits normally, and a copy whose process died without
- * running it is swept by the next freeze of the same game.
+ * `build()` is the game's build as the copy has it, the one every session
+ * played on the copy is stamped with; it is worked out the first time it is
+ * asked for. `remove()` deletes the copy; it also runs when the process exits
+ * normally, and a copy whose process died without running it is swept by the
+ * next freeze of the same game.
+ *
+ * `files` is the snapshot the copy is taken from (frozenFiles). With `from`, a
+ * previous copy and its snapshot, a file whose entry is the same in both is
+ * hard-linked to the previous copy's instead of copied, so a copy costs the
+ * files that changed. Copies are never written to after they are made, which
+ * is what makes sharing their files safe; the game's own files are always
+ * copied, never linked, since the game's are edited in place.
  *
  * Symlinks inside the game are copied as what they point to, so a linked
  * folder is frozen with the rest.
  * @param {string} dir
- * @returns {{ dir: string, build: object, remove: () => void }}
+ * @param {{ files?: Map<string, string>, from?: { dir: string, files: Map<string, string> } }} [opts]
+ * @returns {{ dir: string, build: () => object, remove: () => void }}
  */
-export function freezeGame(dir) {
+export function freezeGame(dir, { files = null, from = null } = {}) {
   sweepStale(dir);
-  const build = gameBuild(dir);
   const run = join(frozenRoot(dir), `${process.pid}-${randomBytes(3).toString('hex')}`);
   // The folder name is the game's slug unless package.json names one, so the
   // copy keeps it.
@@ -50,21 +70,54 @@ export function freezeGame(dir) {
   let removed = false;
   const remove = () => {
     if (removed) return;
-    removed = true;
-    process.off('exit', remove);
     // The link first, on its own: on Windows it is a junction, and a recursive
     // delete that followed it would empty the game's real node_modules.
     try { unlinkSync(modulesLink); } catch { /* never made */ }
-    rmSync(run, { recursive: true, force: true });
+    // On Windows a file a process still has open cannot be deleted, and a
+    // stopped room server lets go of its files a moment after it exits. A copy
+    // that still cannot be deleted is tried again when this process exits,
+    // and swept by the next `joystack dev` of the game after that.
+    try {
+      rmSync(run, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+    } catch {
+      return;
+    }
+    removed = true;
+    process.off('exit', remove);
   };
   process.on('exit', remove);
   try {
     mkdirSync(copy, { recursive: true });
-    // Entry by entry, because the copy lives inside the game (under .joystack),
-    // and a copy of a folder into its own subfolder is refused outright.
-    for (const entry of readdirSync(dir)) {
-      if (LEFT_OUT.has(entry)) continue;
-      cpSync(join(dir, entry), join(copy, entry), { recursive: true, dereference: true, mode: constants.COPYFILE_FICLONE });
+    if (files) {
+      const made = new Set();
+      for (const [path, entry] of files) {
+        const rel = relative(dir, path);
+        if (rel.startsWith('..') || isAbsolute(rel)) continue;
+        // The snapshot also names files the copy leaves out: an engine
+        // installed in the game's node_modules is watched along with the game,
+        // and the copy reaches it through the node_modules link made below.
+        if (LEFT_OUT.has(rel.split(sep)[0])) continue;
+        const to = join(copy, rel);
+        const parent = dirname(to);
+        if (!made.has(parent)) {
+          mkdirSync(parent, { recursive: true });
+          made.add(parent);
+        }
+        if (from && from.files.get(path) === entry) {
+          try {
+            linkSync(join(from.dir, rel), to);
+            continue;
+          } catch { /* a disk without hard links, or the previous file is gone: copied below */ }
+        }
+        copyFileSync(path, to, constants.COPYFILE_FICLONE);
+      }
+    } else {
+      // Entry by entry, because the copy lives inside the game (under
+      // .joystack), and a copy of a folder into its own subfolder is refused.
+      for (const entry of readdirSync(dir)) {
+        if (LEFT_OUT.has(entry)) continue;
+        cpSync(join(dir, entry), join(copy, entry), { recursive: true, dereference: true, mode: constants.COPYFILE_FICLONE });
+      }
     }
     const modules = join(dir, 'node_modules');
     if (existsSync(modules)) symlinkSync(modules, modulesLink, process.platform === 'win32' ? 'junction' : 'dir');
@@ -72,7 +125,10 @@ export function freezeGame(dir) {
     remove();
     throw err;
   }
-  return { dir: copy, build, remove };
+  // The id is the copy's files; the commit and whether the files differ from
+  // it are read from the game's folder when the build is first asked for.
+  let build = null;
+  return { dir: copy, build: () => (build ??= gameBuild(dir, { files: collectGameFiles(copy) })), remove };
 }
 
 // Deletes the copies of runs whose process no longer exists: a `joystack dev`

package/lib/inject.mjs

@@ -34,7 +34,7 @@ function jsJson(value) {
 // resolve them to the framework runtime under the (already-mounted) /shared/
 // tree. This set is the import surface (shared/docs/api.md); keep it in sync
 // with V2_BARE_SPECIFIERS in backend/api/src/lib/inject.js.
-const V2_IMPORTS = {
+export const V2_IMPORTS = {
   joystack: '/shared/framework/runtime/joystack.js',
   'joystack/traits': '/shared/framework/runtime/traits.js',
   'joystack/client': '/shared/framework/runtime/client.js',

package/lib/legacy-names.mjs

@@ -93,6 +93,12 @@ export function canonicalSpecifier(specifier) {
   return specifier;
 }
 
+/**
+ * The engine file the root door resolves to in an engine released before the
+ * rename, which has no `shared/framework/runtime/joystack.js`.
+ */
+export const LEGACY_ROOT_DOOR_FILE = `shared/framework/runtime/${OLD}.js`;
+
 /** A browser import map extended with the old name of every joystack door it maps. */
 export function withLegacyDoors(imports) {
   const out = { ...imports };

package/lib/live-versions.mjs

@@ -0,0 +1,212 @@
+// The versions `joystack dev` serves.
+//
+// A version is a copy of the game taken at one moment (freeze.mjs), with the
+// room and the entity layout built from that copy. The page, every file it
+// fetches later and the room all come from one version, so a page never runs
+// against files that changed under it.
+//
+// This module decides when a new version is made and keeps the state every
+// page and the control endpoints report:
+//
+//   state    'ready'     the current version is served
+//            'updating'  a new version is being made; game pages show "Updating…"
+//            'failed'    the last attempt failed; game pages show `error`
+//   auto     whether a version is made as soon as the files settle
+//   pending  whether the files differ from the last version attempted
+//
+// The operating system says when a file in a watched folder changes, and a
+// version is made once no change has arrived for `quietMs`. The events only
+// say when to look: what a version is made from, and whether anything is
+// pending, is always a fresh snapshot of the files. A slower poll covers
+// changes the events miss (a folder the system cannot watch, an engine
+// checkout); a poll counts the files as settled when it finds what the
+// previous poll found.
+import { createHash } from 'node:crypto';
+import { readdirSync, readFileSync, statSync, watch as watchFolder } from 'node:fs';
+import { join } from 'node:path';
+
+// Every file under each root, as path → `mtime:size`, with a hash of the
+// content appended for files smaller than `hashBelow` bytes. `skip(name,
+// depth)` leaves an entry out; depth 0 is a root's own entries.
+export function snapshotFiles(roots, skip = () => false, { hashBelow = 0 } = {}) {
+  const out = new Map();
+  const walk = (dir, depth) => {
+    let names;
+    try {
+      names = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const name of names) {
+      if (skip(name, depth)) continue;
+      const p = join(dir, name);
+      let st;
+      try {
+        st = statSync(p);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) walk(p, depth + 1);
+      else out.set(p, `${st.mtimeMs}:${st.size}${st.size < hashBelow ? `:${contentHash(p)}` : ''}`);
+    }
+  };
+  for (const root of roots) walk(root, 0);
+  return out;
+}
+
+function contentHash(path) {
+  try {
+    return createHash('sha1').update(readFileSync(path)).digest('base64');
+  } catch {
+    return 'unreadable';
+  }
+}
+
+export function sameFiles(a, b) {
+  if (!a || !b || a.size !== b.size) return false;
+  for (const [k, v] of a) if (b.get(k) !== v) return false;
+  return true;
+}
+
+/**
+ * @param {object} o
+ * @param {() => Map} o.snapshot      the files a version is made from, now
+ * @param {(o: { files: Map, previous: object }) => Promise<object>} o.make
+ *        makes a version from the files as they are; `files` is the snapshot
+ *        taken just before, `previous` the version served now
+ * @param {(v: object) => Promise<void>} o.show  makes `v` the served version; throws to fail it
+ * @param {(v: object) => void} o.retire   the previous version, once it is no longer served
+ * @param {object} o.first          the version served at startup, with its `files` snapshot
+ * @param {{ dir: string, ignore?: (rel: string) => boolean }[]} [o.watch]
+ *        folders whose change events start a version; `rel` is the changed
+ *        path within the folder, with `/` separators
+ */
+export function createLiveVersions({ snapshot, make, show, retire, first, auto = true, watch = [], quietMs = 50, intervalMs = 1000, log = () => {}, onStatus = () => {} }) {
+  let current = first;
+  // The files the last attempt was made from, whether it was shown or failed.
+  let attempted = first.files;
+  let last = null;
+  let busy = false;
+  let closed = false;
+  let wanted = false;
+  let quiet = null;
+  let status = { state: 'ready', auto, pending: false, error: null };
+
+  const set = (next) => {
+    const changed = Object.keys(next).some((k) => status[k] !== next[k]);
+    status = { ...status, ...next };
+    if (changed) onStatus(status);
+  };
+
+  async function update() {
+    if (busy) {
+      wanted = true;
+      return;
+    }
+    busy = true;
+    try {
+      do {
+        wanted = false;
+        set({ state: 'updating', error: null });
+        const before = snapshot();
+        let version = null;
+        let error = null;
+        try {
+          version = await make({ files: before, previous: current });
+        } catch (err) {
+          error = err;
+        }
+        if (closed) {
+          version?.remove();
+          return;
+        }
+        // Files that changed while the copy was taken may have been copied
+        // half-written: the attempt does not count, and is made again once
+        // they settle.
+        if (!sameFiles(before, snapshot())) {
+          version?.remove();
+          await new Promise((r) => setTimeout(r, quietMs));
+          wanted = true;
+          continue;
+        }
+        attempted = before;
+        if (version) {
+          version.files = before;
+          try {
+            await show(version);
+          } catch (err) {
+            error = err;
+            version.remove();
+            version = null;
+          }
+        }
+        if (closed) return;
+        if (version) {
+          const previous = current;
+          current = version;
+          retire(previous);
+          set({ state: 'ready', error: null, pending: false });
+          log('→ reloaded: serving the files as they are now');
+        } else {
+          const message = String(error?.message ?? error);
+          set({ state: 'failed', error: message, pending: false });
+          log(`✗ the game does not build — the page shows this until the files change:\n${message}`);
+        }
+      } while (wanted && !closed);
+    } finally {
+      busy = false;
+    }
+    // Changes that arrived while this update ran.
+    check({ settled: true });
+  }
+
+  // Compares the files with the last attempt; `settled` says they have
+  // stopped changing.
+  function check({ settled }) {
+    if (closed || busy) return;
+    const now = snapshot();
+    const stable = settled || sameFiles(now, last);
+    last = now;
+    const pending = !sameFiles(now, attempted);
+    if (pending !== status.pending) set({ pending });
+    if (status.auto && pending && stable) update();
+  }
+
+  const watchers = [];
+  for (const { dir, ignore = () => false } of watch) {
+    try {
+      const w = watchFolder(dir, { recursive: true }, (_, name) => {
+        if (name && ignore(String(name).replace(/\\/g, '/'))) return;
+        clearTimeout(quiet);
+        quiet = setTimeout(() => check({ settled: true }), quietMs);
+      });
+      w.on('error', () => w.close());
+      watchers.push(w);
+    } catch { /* this folder is left to the poll */ }
+  }
+  const timer = setInterval(() => check({ settled: false }), intervalMs);
+  timer.unref();
+
+  return {
+    get status() {
+      return status;
+    },
+    get current() {
+      return current;
+    },
+    // Makes a version of the files as they are now, whatever the mode.
+    reload() {
+      return update();
+    },
+    setAuto(on) {
+      set({ auto: !!on });
+      if (on) check({ settled: true });
+    },
+    close() {
+      closed = true;
+      clearInterval(timer);
+      clearTimeout(quiet);
+      for (const w of watchers) w.close();
+    },
+  };
+}

package/lib/publish-checks.mjs

@@ -0,0 +1,75 @@
+// The checks of a game's code against its engine, run before a publish uploads
+// anything: every `/shared/…` path the game's code names, and every door it
+// imports (`joystack`, `joystack/client`, `three`, …), must exist in the
+// engine the game is pinned to. Without them the published page fails to load
+// a module.
+//
+// The publish server runs the same checks on the single-request route
+// (backend/api/src/routes/publish.js, codeError). The file-by-file route does
+// not read the game's files back, so the CLI runs them here, with the same
+// rules and the same messages.
+
+import { readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { V2_IMPORTS } from './inject.mjs';
+import { LEGACY_ROOT_DOOR_FILE, withLegacyDoors } from './legacy-names.mjs';
+
+const SHARED_REF_RE = /["'(=]\s*\/(shared\/[A-Za-z0-9_@./-]+)/g;
+const CODE_FILE_RE = /\.(js|mjs|html|css)$/i;
+const ROOT_DOOR = 'joystack';
+
+function decodeText(bytes) {
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Throws when the game's code names an engine file or door its engine does not
+ * ship. `files` maps each path to its bytes; `engine` is the installed engine
+ * ({ version, sharedDir }).
+ */
+export function checkGameCode(files, engine) {
+  // The engine's files by exact path, as the platform's release lists them: a
+  // folder, a `..` path or a different letter case is not a file it serves.
+  let entries = [];
+  try {
+    entries = readdirSync(engine.sharedDir, { recursive: true, withFileTypes: true });
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+  const shipped = new Set(
+    entries.filter((e) => e.isFile()).map((e) => `shared/${relative(engine.sharedDir, join(e.parentPath ?? e.path, e.name)).split('\\').join('/')}`),
+  );
+  const ships = (path) => shipped.has(path);
+  const texts = new Map();
+  for (const [path, bytes] of files) texts.set(path, decodeText(bytes));
+
+  for (const [path, text] of texts) {
+    if (text == null || !CODE_FILE_RE.test(path)) continue;
+    for (const m of text.matchAll(SHARED_REF_RE)) {
+      if (!ships(m[1])) throw new Error(`game references /${m[1]}, which engine ${engine.version} does not ship`);
+    }
+  }
+
+  // Whether each door's engine file ships, under the door's current name and
+  // its old one. An engine from before the rename has the root door under its
+  // old file name.
+  const available = {};
+  for (const [door, url] of Object.entries(V2_IMPORTS)) {
+    available[door] = ships(url.replace(/^\//, '')) || (door === ROOT_DOOR && ships(LEGACY_ROOT_DOOR_FILE));
+  }
+  const doors = withLegacyDoors(available);
+  const used = new Set([ROOT_DOOR, `${ROOT_DOOR}/client`]);
+  for (const text of texts.values()) {
+    if (!text) continue;
+    for (const door of Object.keys(doors)) {
+      if (text.includes(`'${door}'`) || text.includes(`"${door}"`)) used.add(door);
+    }
+  }
+  for (const door of used) {
+    if (!doors[door]) throw new Error(`engine ${engine.version} does not ship the \`${door}\` import`);
+  }
+}

package/lib/publish-upload.mjs

@@ -0,0 +1,163 @@
+// The file-by-file publish: ask which files the platform lacks, upload those
+// one per request, then ask it to put the game live.
+//
+//   POST /api/creator/publish/missing      fingerprints, CHECK_BATCH at a time
+//   PUT  /api/creator/publish/file/<sha256> one file each, UPLOAD_CONCURRENCY at once
+//   POST /api/creator/publish/finish       the publish's meta
+//
+// The platform stores files by fingerprint and shares them across every game,
+// so a publish to a new name (a review copy, a lane's copy) uploads only what no
+// earlier publish stored, and a publish cut off halfway resumes where it
+// stopped. Each request is small, so none runs into the platform's
+// per-request limits. A request refused for a passing reason (a rate limit, a
+// network error, the platform busy or restarting) is retried on its own with a
+// growing wait; anything else fails the publish with the platform's message.
+
+// Fingerprints asked about per request. The platform answers up to 250
+// (MAX_CHECK_BATCH in backend/api/src/routes/publish.js), but each request
+// looks them up in storage only six at a time, each lookup a round trip of
+// hundreds of milliseconds from far away; small batches in parallel requests
+// answer a large game in a few seconds.
+export const CHECK_BATCH = 25;
+// Each upload request spends most of its time waiting on round trips between
+// the platform and its database and storage, about 1.4 s from far away, so
+// many overlap. Measured from Mauritius on 120 small files: 29 s at 6 at once,
+// 8 s at 24, 5 s at 48.
+export const UPLOAD_CONCURRENCY = 32;
+// Batches of the "which are missing" question in flight at once.
+export const CHECK_CONCURRENCY = 32;
+const ATTEMPTS = 6;
+const UPLOAD_TIMEOUT_MS = 5 * 60_000;
+const REQUEST_TIMEOUT_MS = 2 * 60_000;
+// The platform answers 503 for a failure that may pass (storage busy, a
+// publish that failed and changed nothing); Cloudflare's edge answers 503 when
+// a request ran out of CPU, and 52x when it could not reach the platform. A 500
+// is retried only when it is the platform's unexpected-error answer: its other
+// 500s name a fault in its own setup, which a retry does not fix. A 502 means
+// a game's server failed to deploy.
+const RETRYABLE = new Set([408, 429, 503, 504, 520, 521, 522, 523, 524]);
+const UNEXPECTED_ERROR = '{"error":"internal error"}';
+
+export class LegacyPlatform extends Error {}
+
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Uploads what the platform lacks and finishes the publish. `files` maps each
+ * path to its bytes, `meta.files` each path to its SHA-256. Returns the
+ * platform's answer ({ slug, title, … }) with `uploaded` and `alreadyStored`
+ * counts. Throws LegacyPlatform when the platform predates these routes.
+ */
+export async function publishFileByFile({ apiBase, token, files, meta, log = console.log, fetchImpl = fetch, sleep = defaultSleep }) {
+  const auth = token ? { Authorization: `Bearer ${token}` } : {};
+
+  // One request, retried while the reason passes. Returns the response of the
+  // first attempt that is not retryable.
+  const request = async (what, url, init, timeoutMs = REQUEST_TIMEOUT_MS) => {
+    for (let attempt = 1; ; attempt++) {
+      let res = null;
+      let error = null;
+      try {
+        res = await fetchImpl(url, { ...init, headers: { ...auth, ...init.headers }, signal: AbortSignal.timeout(timeoutMs) });
+      } catch (err) {
+        error = err;
+      }
+      if (res?.status === 500) {
+        const body = await res.text();
+        if (body.trim() !== UNEXPECTED_ERROR) return new Response(body, { status: 500 });
+        res = new Response(body, { status: 500 });
+      } else if (res && !RETRYABLE.has(res.status)) return res;
+      if (attempt === ATTEMPTS) {
+        if (res) return res;
+        throw new Error(`${what} failed after ${ATTEMPTS} attempts: ${error?.cause?.message ?? error?.message ?? error}`);
+      }
+      const retryAfter = Number(res?.headers.get('retry-after'));
+      const wait = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : 1000 * 2 ** (attempt - 1);
+      if (res?.status === 429) log(`  The platform asked to slow down; continuing in ${Math.round(wait / 1000)} s…`);
+      await res?.body?.cancel().catch(() => {});
+      await sleep(wait);
+    }
+  };
+  const failed = async (what, res) => {
+    const detail = await res.text().catch(() => '');
+    return new Error(`${what} failed (HTTP ${res.status}): ${detail.slice(0, 300)}`);
+  };
+
+  const byHash = new Map();
+  for (const [path, bytes] of files) byHash.set(meta.files[path], bytes);
+  const hashes = [...byHash.keys()];
+
+  const batches = [];
+  for (let i = 0; i < hashes.length; i += CHECK_BATCH) batches.push(hashes.slice(i, i + CHECK_BATCH));
+  const missing = [];
+  const ask = async (batch) => {
+    const res = await request('checking which files the platform has', `${apiBase}/api/creator/publish/missing`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ files: batch }),
+    });
+    if (res.status === 404) throw new LegacyPlatform('the platform has no file-by-file publish');
+    if (!res.ok) throw await failed('publish', res);
+    missing.push(...(await res.json()).missing);
+  };
+  // The first batch alone, so a platform without these routes is found before
+  // anything else is sent.
+  await ask(batches[0]);
+  const rest = batches.slice(1);
+  await Promise.all(Array.from({ length: Math.min(CHECK_CONCURRENCY, rest.length) }, async () => {
+    for (let batch = rest.shift(); batch; batch = rest.shift()) await ask(batch);
+  }));
+
+  const bytesOf = (hash) => byHash.get(hash).byteLength;
+  const total = missing.reduce((n, h) => n + bytesOf(h), 0);
+  const mb = (n) => (n / 1024 / 1024).toFixed(1);
+  log(
+    missing.length
+      ? `Uploading ${missing.length} of ${hashes.length} files (${mb(total)} MB); the platform already has the rest.`
+      : `The platform already has all ${hashes.length} files; nothing to upload.`,
+  );
+
+  let done = 0;
+  let sent = 0;
+  let nextReport = 0.25;
+  const queue = [...missing];
+  let stopped = false;
+  const worker = async () => {
+    for (let hash = queue.shift(); hash && !stopped; hash = queue.shift()) {
+      let res;
+      try {
+        res = await request(
+          'uploading a file',
+          `${apiBase}/api/creator/publish/file/${hash}`,
+          { method: 'PUT', headers: { 'content-type': 'application/octet-stream' }, body: byHash.get(hash) },
+          UPLOAD_TIMEOUT_MS,
+        );
+      } catch (err) {
+        stopped = true;
+        throw err;
+      }
+      if (!res.ok) {
+        stopped = true;
+        const path = Object.keys(meta.files).find((p) => meta.files[p] === hash);
+        throw await failed(`uploading ${path}`, res);
+      }
+      await res.body?.cancel().catch(() => {});
+      done++;
+      sent += bytesOf(hash);
+      // Progress on a long upload, at each quarter.
+      if (missing.length >= 40 && done / missing.length >= nextReport && done < missing.length) {
+        log(`  ${done} of ${missing.length} files uploaded (${mb(sent)} of ${mb(total)} MB)…`);
+        while (done / missing.length >= nextReport) nextReport += 0.25;
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(UPLOAD_CONCURRENCY, missing.length) }, worker));
+
+  const res = await request('publish', `${apiBase}/api/creator/publish/finish`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(meta),
+  });
+  if (!res.ok) throw await failed('publish', res);
+  return { ...(await res.json()), uploaded: missing.length, alreadyStored: hashes.length - missing.length };
+}