@tinvar/react 0.0.0-stage → 0.4.1

package/src/resumable.js

@@ -0,0 +1,822 @@
+// A resumable upload (ADR 0143): a file sent in pieces -- chunks through PHP,
+// or parts straight to the object store -- each one only from where the
+// server says it holds, so a refresh, a closed tab, a crash or a dropped
+// network costs at most the piece that was in flight.
+//
+// The server is the only one who knows how much is in. After every failure
+// the browser asks it (/_upload/session/offset, or the parts the store
+// holds) before sending another byte; nothing is ever sent again from zero
+// while the server holds some of it. A network that drops, or a server that
+// answers 5xx, is tried again on its own, backing off, and at once when the
+// browser says it is online again.
+//
+// What lets the upload go on after the page is gone is a record in
+// IndexedDB (resume-store.js): the session the server signed, and the
+// file's name, size and fingerprint -- never its bytes. Choosing the same
+// file again finds it, by what the upload is for and the fingerprint, so a
+// different file is never appended to an old session.
+
+import { send, watchStall } from './transport.js';
+import { defaultResumeStore } from './resume-store.js';
+
+/** Where a resumable upload begins, under the ticket. */
+export const UPLOAD_SESSION_PATH = '/_upload/session';
+/** Where it is asked how much is in. */
+export const UPLOAD_OFFSET_PATH = '/_upload/session/offset';
+/** Where a chunk is appended, through PHP. */
+export const UPLOAD_CHUNK_PATH = '/_upload/session/chunk';
+/** Where the URLs for the next parts are asked for, for the store. */
+export const UPLOAD_PARTS_PATH = '/_upload/session/parts';
+/** Where an upload sent in parts is completed. */
+export const UPLOAD_SESSION_COMPLETE_PATH = '/_upload/session/complete';
+/** Where an upload is given up. */
+export const UPLOAD_ABORT_PATH = '/_upload/session/abort';
+
+/** Seconds between tries, after a network drop or a 5xx: about two minutes in all, then it is the person's to retry. */
+export const BACKOFF = [1, 2, 4, 8, 15, 30, 30, 30];
+
+/** Milliseconds a piece may send nothing before it is given up as a dropped network, and the server asked where it is. */
+export const STALL_TIMEOUT = 30_000;
+
+/** How much of each end of a file its fingerprint reads. */
+const SAMPLE_BYTES = 65_536;
+
+/**
+ * @typedef {import('./transport.js').Outcome} Outcome
+ * @typedef {import('./transport.js').Progress} Progress
+ * @typedef {import('./resume-store.js').ResumeStore} ResumeStore
+ * @typedef {import('./resume-store.js').ResumeRecord} ResumeRecord
+ * @typedef {'uploading' | 'paused' | 'resuming'} ResumableState
+ *
+ * The session an upload goes on in, and the id of the record that
+ * remembers it (null where nothing is remembered): what giving it up
+ * (abortUpload(), and the record deleted) needs.
+ * @typedef {{ session: string, id: string | null }} ResumableSession
+ *
+ * @typedef {{
+ *   ticket: string,
+ *   file: Blob,
+ *   direct?: boolean,
+ *   signal?: AbortSignal,
+ *   onProgress?: (progress: Progress) => void,
+ *   onState?: (state: ResumableState) => void,
+ *   onSession?: (session: ResumableSession) => void,
+ *   store?: ResumeStore,
+ *   handle?: unknown,
+ *   backoff?: number[],
+ *   stallTimeout?: number,
+ * }} ResumableOptions
+ */
+
+/**
+ * Sends a file as a resumable upload: going on with the session a record
+ * remembers for this very file, where one is and the server still holds it,
+ * or beginning one. Answers as send() does -- the last answer, the
+ * upload's on success -- or `unsupported` where the server takes no
+ * resumable upload of this kind, for the caller to send the file whole.
+ *
+ * `onSession` is told the session once it is known, and remembered, so a
+ * caller that cancels the upload for good can give it up. A cancel alone
+ * keeps it on the server, for a later page to go on with.
+ *
+ * Never throws for an outcome.
+ *
+ * @param {ResumableOptions} options
+ * @returns {Promise<Outcome | { type: 'unsupported' }>}
+ */
+export async function uploadResumable({
+  ticket,
+  file,
+  direct = false,
+  signal,
+  onProgress,
+  onState,
+  onSession,
+  store = defaultResumeStore(),
+  handle,
+  backoff = BACKOFF,
+  stallTimeout = STALL_TIMEOUT,
+}) {
+  const scope = uploadScope(ticket);
+  const fingerprint = scope === null ? null : await fingerprintFile(file);
+  const id = scope === null || fingerprint === null ? null : `${scope}#${fingerprint}`;
+  const report = (/** @type {number} */ loaded) =>
+    onProgress?.({
+      loaded,
+      total: file.size,
+      percentage: file.size > 0 ? Math.min(100, Math.floor((loaded / file.size) * 100)) : undefined,
+    });
+  const forget = async () => {
+    if (id !== null) await quietly(() => store.delete(id));
+  };
+
+  /** @type {{ session: string, mode: 'chunks' | 'parts', offset: number, unit: number } | null} */
+  let current = null;
+  const remembered = id === null ? null : await quietly(() => store.get(id));
+  if (remembered !== null && remembered !== undefined && remembered.size === file.size) {
+    onState?.('resuming');
+    const asked = await retrying(() => askOffset(remembered.session, signal), { signal, onState, backoff });
+    if (asked.type === 'completed') {
+      await forget();
+      report(file.size);
+      return asked.outcome;
+    }
+    if (asked.type === 'open') {
+      current = { session: remembered.session, mode: asked.mode, offset: asked.offset, unit: asked.unit };
+      onSession?.({ session: remembered.session, id });
+    } else if (asked.type === 'gone') {
+      // Run out, abandoned, or another session's or user's: forgotten
+      // without a word, and the file sent as a new upload.
+      await forget();
+    } else {
+      return asked;
+    }
+  }
+
+  if (current === null) {
+    const name = fileName(file);
+    const begun = await send({
+      url: UPLOAD_SESSION_PATH,
+      data: { ticket, size: file.size, name, type: typeof file.type === 'string' ? file.type : '', direct },
+      signal,
+    });
+    if (begun.type === 'http' && begun.status === 404) return { type: 'unsupported' };
+    if (begun.type !== 'success') return begun;
+    const body = begun.body;
+    const unit = body?.mode === 'parts' ? body?.partBytes : body?.chunkBytes;
+    if (
+      typeof body?.session !== 'string' ||
+      (body.mode !== 'chunks' && body.mode !== 'parts') ||
+      typeof unit !== 'number' ||
+      unit < 1 ||
+      typeof body.expiresAt !== 'number'
+    ) {
+      return malformed();
+    }
+    current = { session: body.session, mode: body.mode, offset: 0, unit };
+    if (id !== null && scope !== null && fingerprint !== null) {
+      /** @type {ResumeRecord} */
+      const record = {
+        id,
+        scope,
+        fingerprint,
+        session: body.session,
+        mode: body.mode,
+        name,
+        size: file.size,
+        type: typeof file.type === 'string' ? file.type : '',
+        lastModified: lastModifiedOf(file),
+        offset: 0,
+        createdAt: Date.now(),
+        expiresAt: body.expiresAt,
+        ...(handle === undefined ? {} : { handle }),
+      };
+      await quietly(() => store.put(record));
+    }
+    onSession?.({ session: body.session, id });
+  }
+
+  report(current.offset);
+  const remember = async (/** @type {number} */ offset) => {
+    if (id === null) return;
+    const record = await quietly(() => store.get(id));
+    if (record) await quietly(() => store.put({ ...record, offset }));
+  };
+  const context = { file, signal, onState, backoff, stallTimeout, report, remember, forget };
+
+  return current.mode === 'chunks' ? sendChunks(current, context) : sendParts(current, context);
+}
+
+/**
+ * @typedef {{
+ *   file: Blob,
+ *   signal: AbortSignal | undefined,
+ *   onState: ((state: ResumableState) => void) | undefined,
+ *   backoff: number[],
+ *   stallTimeout: number,
+ *   report: (loaded: number) => void,
+ *   remember: (offset: number) => Promise<void>,
+ *   forget: () => Promise<void>,
+ * }} SendContext
+ */
+
+/**
+ * Chunk after chunk, each at the offset the server holds: a chunk refused
+ * as being for another offset goes on from the one the refusal names; one
+ * that did not arrive is tried again once the server has said how much it
+ * holds. The last chunk's answer is the upload's.
+ *
+ * @param {{ session: string, offset: number, unit: number }} current
+ * @param {SendContext} context
+ * @returns {Promise<Outcome>}
+ */
+async function sendChunks(
+  { session, offset: from, unit },
+  { file, signal, onState, backoff, stallTimeout, report, remember, forget },
+) {
+  let offset = from;
+  let failures = 0;
+  let mismatches = 0;
+
+  for (;;) {
+    if (offset >= file.size && file.size > 0) {
+      // Every byte held, nothing kept: a keep that failed for a reason that
+      // passes gave the session back, and it is completed from what is held.
+      const done = await retrying(
+        () => send({ url: UPLOAD_SESSION_COMPLETE_PATH, data: { session }, signal }),
+        {
+          signal,
+          onState,
+          backoff,
+        },
+      );
+      if (done.type === 'http' && done.status === 409 && ++mismatches <= 3) {
+        const held = Number(done.headers.get('upload-offset'));
+        if (Number.isSafeInteger(held) && held >= 0 && held < file.size) {
+          offset = held;
+          report(offset);
+          continue;
+        }
+      }
+      // As for parts: forgotten once done, or refused for good; a server
+      // that failed for a while keeps the bytes, and the record with them.
+      if (done.type === 'success' || refusedForGood(done)) {
+        await forget();
+      }
+      if (done.type === 'success') report(file.size);
+      return done;
+    }
+    const chunk = file.slice(offset, Math.min(offset + unit, file.size));
+    /** @type {Record<string, string>} */
+    const headers = {
+      'content-type': 'application/offset+octet-stream',
+      'upload-session': session,
+      'upload-offset': String(offset),
+    };
+    const sum = await checksum(chunk);
+    if (sum !== null) headers['upload-checksum'] = sum;
+
+    onState?.('uploading');
+    const at = offset;
+    const sent = await send({
+      url: UPLOAD_CHUNK_PATH,
+      body: chunk,
+      headers,
+      signal,
+      stallTimeout,
+      onUploadProgress: (p) => report(at + p.loaded),
+    });
+
+    if (sent.type === 'success') {
+      if (sent.status === 201) {
+        await forget();
+        report(file.size);
+        return sent;
+      }
+      const held = Number(sent.headers.get('upload-offset') ?? sent.body?.offset);
+      if (!Number.isSafeInteger(held) || held <= offset || held > file.size) return malformed();
+      offset = held;
+      failures = 0;
+      mismatches = 0;
+      report(offset);
+      await remember(offset);
+      continue;
+    }
+
+    if (sent.type === 'http' && sent.status === 409) {
+      // Not where the server is: on from where it says it is.
+      const held = Number(sent.headers.get('upload-offset'));
+      if (!Number.isSafeInteger(held) || held < 0 || held > file.size || ++mismatches > 3) return sent;
+      offset = held;
+      report(offset);
+      continue;
+    }
+
+    if (sent.type === 'http' && sent.status === 460) {
+      // Changed on its way: sent again, as it is.
+      if (++failures > backoff.length) return sent;
+      continue;
+    }
+
+    if (transient(sent)) {
+      if (++failures > backoff.length) return sent;
+      onState?.('paused');
+      if (!(await pause(delayFor(sent, backoff, failures), signal))) return { type: 'cancelled' };
+      onState?.('resuming');
+      const asked = await retrying(() => askOffset(session, signal), { signal, onState, backoff });
+      if (asked.type === 'completed') {
+        await forget();
+        report(file.size);
+        return asked.outcome;
+      }
+      if (asked.type === 'gone') {
+        await forget();
+        return asked.outcome;
+      }
+      if (asked.type !== 'open') return asked;
+      offset = asked.offset;
+      report(offset);
+      continue;
+    }
+
+    if (
+      sent.type === 'cancelled' ||
+      sent.type === 'expired' ||
+      (sent.type === 'http' && sent.status === 401)
+    ) {
+      // Still the server's to go on with, after a refresh or a sign-in.
+      return sent;
+    }
+
+    // Refused for good -- too large, not a type the field takes, or a
+    // session that is gone -- and over on the server too. Anything else (a
+    // keep refused while too many uploads wait, 429 upload_pending) leaves
+    // the bytes held, for the session to go on with later.
+    if (refusedForGood(sent)) await forget();
+    return sent;
+  }
+}
+
+/**
+ * Part after part to the store, from the first the store does not hold as
+ * granted: the server asks the store what it holds each time, and hands out
+ * URLs for the next few. Once it holds them all, the server completes it.
+ *
+ * @param {{ session: string, unit: number }} current
+ * @param {SendContext} context
+ * @returns {Promise<Outcome>}
+ */
+async function sendParts(
+  { session, unit },
+  { file, signal, onState, backoff, stallTimeout, report, remember, forget },
+) {
+  let failures = 0;
+  // What the store held when last asked, and whether every part granted
+  // then was taken: asked again after that, it must hold more.
+  let held = -1;
+  let sentWhole = false;
+
+  for (;;) {
+    const granted = await retrying(() => send({ url: UPLOAD_PARTS_PATH, data: { session }, signal }), {
+      signal,
+      onState,
+      backoff,
+    });
+    if (granted.type !== 'success') {
+      if (
+        granted.type === 'http' &&
+        granted.status >= 400 &&
+        granted.status < 500 &&
+        ![401, 429].includes(granted.status)
+      ) {
+        await forget();
+      }
+      return granted;
+    }
+    const body = granted.body;
+    if (typeof body?.offset !== 'number' || !Array.isArray(body?.parts)) return malformed();
+    report(body.offset);
+    await remember(body.offset);
+
+    if (body.offset > held) {
+      failures = 0;
+    } else if (sentWhole && body.parts.length > 0) {
+      // A store that said it took the parts and does not hold them -- slow
+      // to list them, or losing them -- is waited for, and then given up
+      // on, rather than sent them again without end.
+      if (++failures > backoff.length) return malformed();
+      onState?.('paused');
+      if (!(await pause(delayFor(granted, backoff, failures), signal))) return { type: 'cancelled' };
+      onState?.('resuming');
+    }
+    held = body.offset;
+    sentWhole = false;
+
+    if (body.parts.length === 0) {
+      const done = await retrying(
+        () => send({ url: UPLOAD_SESSION_COMPLETE_PATH, data: { session }, signal }),
+        {
+          signal,
+          onState,
+          backoff,
+        },
+      );
+      if (done.type === 'http' && done.status === 409 && ++failures <= backoff.length) {
+        // A part the store does not hold after all: asked for again, after a
+        // pause, so a store slow to list what it holds is not asked at once.
+        onState?.('paused');
+        if (!(await pause(delayFor(done, backoff, failures), signal))) return { type: 'cancelled' };
+        onState?.('resuming');
+        continue;
+      }
+      // Forgotten once done, or refused for good; a server that failed for
+      // a while, a throttle or a sign-in leaves the parts to complete later.
+      if (done.type === 'success' || refusedForGood(done)) {
+        await forget();
+      }
+      if (done.type === 'success') report(file.size);
+      return done;
+    }
+
+    for (const part of body.parts) {
+      const start = (part.number - 1) * unit;
+      const blob = file.slice(start, start + part.size);
+      if (typeof part.url !== 'string' || blob.size !== part.size) return malformed();
+      onState?.('uploading');
+      const put = await putToStore(
+        part.url,
+        part.headers ?? {},
+        blob,
+        signal,
+        (p) => report(start + p.loaded),
+        stallTimeout,
+      );
+      if (put.type === 'sent') {
+        sentWhole = part === body.parts.at(-1);
+        continue;
+      }
+      if (put.type === 'cancelled') return put;
+      // A URL that ran out is asked for again; a store that did not answer
+      // is waited for. Either way the store is asked what it holds first.
+      if (++failures > backoff.length) return put;
+      if (transient(put)) {
+        onState?.('paused');
+        if (!(await pause(delayFor(put, backoff, failures), signal))) return { type: 'cancelled' };
+        onState?.('resuming');
+      }
+      break;
+    }
+  }
+}
+
+/**
+ * Asks the server how much of an upload it holds.
+ *
+ * @param {string} session
+ * @param {AbortSignal | undefined} signal
+ * @returns {Promise<
+ *   | { type: 'open', mode: 'chunks' | 'parts', offset: number, size: number, unit: number, name: string }
+ *   | { type: 'completed', outcome: Outcome }
+ *   | { type: 'gone', outcome: Outcome }
+ *   | Outcome
+ * >}
+ */
+export async function askOffset(session, signal) {
+  const asked = await send({ url: UPLOAD_OFFSET_PATH, data: { session }, signal });
+  if (asked.type === 'http' && (asked.status === 403 || asked.status === 404 || asked.status === 410)) {
+    return { type: 'gone', outcome: asked };
+  }
+  if (asked.type !== 'success') return asked;
+  const body = asked.body;
+  if (body?.upload && typeof body.upload === 'object') {
+    return { type: 'completed', outcome: { ...asked, status: 201, body: body.upload } };
+  }
+  const unit = body?.mode === 'parts' ? body?.partBytes : body?.chunkBytes;
+  if (
+    (body?.mode !== 'chunks' && body?.mode !== 'parts') ||
+    typeof body.offset !== 'number' ||
+    typeof body.size !== 'number' ||
+    typeof unit !== 'number'
+  ) {
+    return malformed();
+  }
+  return {
+    type: 'open',
+    mode: body.mode,
+    offset: body.offset,
+    size: body.size,
+    unit,
+    name: typeof body.name === 'string' ? body.name : '',
+  };
+}
+
+/** How many times an abort is sent while the server says a completion is running. */
+const ABORT_TRIES = 8;
+
+/**
+ * Gives an upload up on the server -- its bytes removed, its room given
+ * back -- whatever the server answers: a session it no longer holds is
+ * given up already. A 425 says another request is completing the session
+ * and the file may yet be kept, so the abort is sent again after the wait
+ * the server names, a few times; given up then, a file that was kept waits
+ * unclaimed and is pruned. The record that remembers it is not touched
+ * here; the caller deletes it from its resume store.
+ *
+ * @param {string} session
+ */
+export async function abortUpload(session) {
+  for (let attempt = 1; ; attempt++) {
+    const outcome = await send({ url: UPLOAD_ABORT_PATH, data: { session } });
+    if (outcome.type !== 'http' || outcome.status !== 425 || attempt >= ABORT_TRIES) return;
+    if (!(await pause(delayFor(outcome, [2], attempt), undefined))) return;
+  }
+}
+
+/**
+ * What a ticket is for -- its action and parameter, its record, tenant and
+ * panel, and the session and user it was issued to, as the keyed hashes it
+ * carries -- read from it for a key, and trusted for nothing else: the
+ * server holds every use to them. Null for a ticket this cannot read, and
+ * nothing is remembered then.
+ *
+ * Bound to the session and the user so a resume is offered only to whoever
+ * began it: another account signed in on this browser is never shown the
+ * name of the file someone else was sending.
+ *
+ * @param {string} ticket
+ * @returns {string | null}
+ */
+export function uploadScope(ticket) {
+  try {
+    const [version, payload] = String(ticket).split('.');
+    if (version !== 'v1' || !payload) return null;
+    const base64 = payload.replace(/-/g, '+').replace(/_/g, '/');
+    const binary = atob(base64 + '='.repeat((4 - (base64.length % 4)) % 4));
+    const claims = JSON.parse(new TextDecoder().decode(Uint8Array.from(binary, (c) => c.charCodeAt(0))));
+    const scope = ['a', 'f', 'm', 'k', 'y', 'n', 's', 'u'].map((key) => claims?.[key]);
+    return scope.every((part) => typeof part === 'string') ? JSON.stringify(scope) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A file's fingerprint: its name, size and last change, and a digest of its
+ * first and last 64 KiB -- so a different file of the same name and size is
+ * never taken for it. Null where the file cannot be read.
+ *
+ * @param {Blob} file
+ * @returns {Promise<string | null>}
+ */
+export async function fingerprintFile(file) {
+  try {
+    const head = await digest(file.slice(0, SAMPLE_BYTES));
+    const tail = await digest(file.slice(Math.max(0, file.size - SAMPLE_BYTES)));
+    if (head === null || tail === null) return null;
+    return `${fileName(file)}:${file.size}:${lastModifiedOf(file)}:${head}:${tail}`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * PUTs a blob to a URL the server presigned, with the headers it was signed
+ * with, reporting progress. Not through send(): the store is another
+ * origin, and nothing of this one's -- its cookies, its CSRF header -- goes
+ * there. Given up as a network failure once it has sent nothing for
+ * $stallTimeout milliseconds, where that is given.
+ *
+ * @param {string} url
+ * @param {Record<string, string>} headers
+ * @param {Blob} blob
+ * @param {AbortSignal | undefined} signal
+ * @param {((progress: Progress) => void) | undefined} onProgress
+ * @param {number} [stallTimeout]
+ * @returns {Promise<{ type: 'sent' } | Outcome>}
+ */
+export function putToStore(url, headers, blob, signal, onProgress, stallTimeout) {
+  return new Promise((resolve) => {
+    if (signal?.aborted) {
+      resolve({ type: 'cancelled' });
+      return;
+    }
+    const xhr = new XMLHttpRequest();
+    xhr.open('PUT', url);
+    xhr.withCredentials = false;
+    for (const [name, value] of Object.entries(headers)) {
+      if (typeof value === 'string') xhr.setRequestHeader(name, value);
+    }
+    if (onProgress && xhr.upload) {
+      xhr.upload.addEventListener('progress', (event) => {
+        const total = event.lengthComputable ? event.total : undefined;
+        onProgress({
+          loaded: event.loaded,
+          total,
+          percentage: total ? Math.round((event.loaded / total) * 100) : undefined,
+        });
+      });
+    }
+    const stall = watchStall(xhr, stallTimeout);
+    const abort = () => xhr.abort();
+    signal?.addEventListener('abort', abort, { once: true });
+    xhr.addEventListener('load', () => {
+      stall.stop();
+      signal?.removeEventListener('abort', abort);
+      resolve(
+        xhr.status >= 200 && xhr.status < 300
+          ? { type: 'sent' }
+          : {
+              type: 'http',
+              status: xhr.status,
+              body: null,
+              headers: new Headers(),
+              code: null,
+              reference: null,
+              retryAfter: null,
+            },
+      );
+    });
+    xhr.addEventListener('error', () => {
+      stall.stop();
+      signal?.removeEventListener('abort', abort);
+      resolve({ type: 'network', error: new Error('The file did not reach the store.') });
+    });
+    xhr.addEventListener('abort', () => {
+      stall.stop();
+      signal?.removeEventListener('abort', abort);
+      resolve(
+        stall.stalled()
+          ? { type: 'network', error: new Error('The store took nothing for too long.') }
+          : { type: 'cancelled' },
+      );
+    });
+    xhr.send(blob);
+  });
+}
+
+/**
+ * Tries a step again while it fails as a network or a busy server does,
+ * backing off, paused between.
+ *
+ * @template {{ type: string }} T
+ * @param {() => Promise<T>} step
+ * @param {{ signal: AbortSignal | undefined, onState: ((state: ResumableState) => void) | undefined, backoff: number[] }} options
+ * @returns {Promise<T | { type: 'cancelled' }>}
+ */
+async function retrying(step, { signal, onState, backoff }) {
+  for (let attempt = 0; ; attempt++) {
+    const outcome = await step();
+    if (!transient(/** @type {any} */ (outcome)) || attempt >= backoff.length) return outcome;
+    onState?.('paused');
+    if (!(await pause(delayFor(/** @type {any} */ (outcome), backoff, attempt + 1), signal)))
+      return { type: 'cancelled' };
+    onState?.('resuming');
+  }
+}
+
+/**
+ * Whether a failure is one to wait out: no answer at all, a server error --
+ * a malware scan that could not run among them, the session's bytes kept
+ * for the next try -- a throttle, or a 425 while another request completes
+ * the session. Never a refusal.
+ *
+ * @param {Outcome | { type: 'sent' }} outcome
+ */
+function transient(outcome) {
+  if (outcome.type === 'network') return true;
+  if (outcome.type !== 'http') return false;
+  if (outcome.status === 429) return outcome.code !== 'upload_pending';
+  if (outcome.status === 425) return true;
+  if (outcome.code === 'opaque_redirect' || outcome.code === 'malformed') return false;
+  return outcome.status >= 500 || outcome.status === 0;
+}
+
+/**
+ * Whether a refusal ends the upload on the server too -- a session gone, or
+ * one refused for its size, type or content -- so that nothing is left to
+ * go on with. A keep refused for the quota (507) or while too many uploads
+ * wait (429) gives the session back with its bytes (ADR 0143).
+ *
+ * @param {Outcome} outcome
+ */
+function refusedForGood(outcome) {
+  if (outcome.type === 'validation') return true;
+  return outcome.type === 'http' && [403, 404, 410, 413, 415, 422].includes(outcome.status);
+}
+
+/**
+ * @param {Outcome | { type: 'sent' }} outcome
+ * @param {number[]} backoff
+ * @param {number} attempt from 1
+ */
+function delayFor(outcome, backoff, attempt) {
+  const wanted =
+    outcome.type === 'http' && outcome.retryAfter !== null ? Math.min(60, outcome.retryAfter) : null;
+  const base = wanted ?? backoff[Math.min(attempt, backoff.length) - 1] ?? 1;
+  // A little jitter, so the tabs of a whole office back on line at once
+  // do not all come back in the same second.
+  return base * 1000 * (0.8 + Math.random() * 0.4);
+}
+
+/**
+ * Waits $ms, or until the browser says it is online again, or until the
+ * upload is cancelled. While the browser says it is offline, it waits for
+ * that alone.
+ *
+ * @param {number} ms
+ * @param {AbortSignal | undefined} signal
+ * @returns {Promise<boolean>} false when cancelled
+ */
+function pause(ms, signal) {
+  return new Promise((resolve) => {
+    if (signal?.aborted) {
+      resolve(false);
+      return;
+    }
+    const offline = globalThis.navigator?.onLine === false;
+    const timer = offline ? null : setTimeout(() => done(true), ms);
+    const online = () => done(true);
+    const abort = () => done(false);
+    globalThis.addEventListener?.('online', online);
+    signal?.addEventListener('abort', abort, { once: true });
+    /** @param {boolean} value */
+    function done(value) {
+      if (timer !== null) clearTimeout(timer);
+      globalThis.removeEventListener?.('online', online);
+      signal?.removeEventListener('abort', abort);
+      resolve(value);
+    }
+  });
+}
+
+/**
+ * A chunk's SHA-256, as the server checks it (`sha256 <base64>`); null where
+ * the browser has no SubtleCrypto -- outside a secure context -- and the
+ * chunk goes without one.
+ *
+ * @param {Blob} chunk
+ * @returns {Promise<string | null>}
+ */
+async function checksum(chunk) {
+  try {
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle) return null;
+    const hash = new Uint8Array(await subtle.digest('SHA-256', await chunk.arrayBuffer()));
+    let binary = '';
+    for (const byte of hash) binary += String.fromCharCode(byte);
+    return `sha256 ${btoa(binary)}`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A digest of a piece of a file, as hex: SHA-256 where the browser has it,
+ * FNV-1a where it does not -- an identity, not a seal; the server checks
+ * everything that matters.
+ *
+ * @param {Blob} blob
+ * @returns {Promise<string | null>}
+ */
+async function digest(blob) {
+  if (typeof blob.arrayBuffer !== 'function') return null;
+  const bytes = new Uint8Array(await blob.arrayBuffer());
+  const subtle = globalThis.crypto?.subtle;
+  if (subtle) {
+    try {
+      return [...new Uint8Array(await subtle.digest('SHA-256', bytes))]
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+    } catch {
+      // Below.
+    }
+  }
+  let a = 0x811c9dc5;
+  let b = 0x01000193;
+  for (const byte of bytes) {
+    a = Math.imul(a ^ byte, 0x01000193) >>> 0;
+    b = Math.imul(b ^ byte ^ (a & 0xff), 0x01000193) >>> 0;
+  }
+  return `fnv${a.toString(16).padStart(8, '0')}${b.toString(16).padStart(8, '0')}`;
+}
+
+/** @param {Blob} file */
+function fileName(file) {
+  const name = /** @type {any} */ (file).name;
+  return typeof name === 'string' ? name : '';
+}
+
+/** @param {Blob} file */
+function lastModifiedOf(file) {
+  const at = /** @type {any} */ (file).lastModified;
+  return typeof at === 'number' ? at : 0;
+}
+
+/**
+ * Runs a store call, never throwing: what it gives, or null.
+ *
+ * @template T
+ * @param {() => Promise<T>} call
+ * @returns {Promise<T | null>}
+ */
+async function quietly(call) {
+  try {
+    const result = await call();
+    return result === undefined ? /** @type {any} */ (true) : result;
+  } catch {
+    return null;
+  }
+}
+
+/** An answer this code cannot read: a failure, never taken for success. @returns {Outcome} */
+function malformed() {
+  return {
+    type: 'http',
+    status: 0,
+    body: null,
+    headers: new Headers(),
+    code: 'malformed',
+    reference: null,
+    retryAfter: null,
+  };
+}