@tinvar/react 0.0.0-stage → 0.4.0

package/src/resume-store.js

@@ -0,0 +1,364 @@
+// Where a resumable upload is remembered across a refresh, a closed tab or
+// a crash (ADR 0143): in IndexedDB, one record per file, keyed by what the
+// upload is for and a fingerprint of the file.
+//
+// A record holds the session the server signed and what the page needs to
+// say "Resume uploading <name> (n% done)" -- the name, the size, how far it
+// had got -- and, where the browser has the File System Access API, the
+// FileSystemFileHandle the file was chosen through, so it can be read again
+// at the cost of a permission prompt. Never the file's bytes.
+//
+// A record is the session's that began it, and outlives neither: when the
+// database opens, every record that has run out goes, whatever its scope,
+// and the store keeps whose records it holds -- the session and user of the
+// router's binding -- so wherever the router finds the session over or
+// another -- a sign-out, a sign-in, a 401 -- every record goes, its file
+// handle with it (purge()).
+//
+// The database is opened only by an upload that reads or writes a record,
+// never by the router: a purge asked for before that is kept, and run when
+// the database first opens, before anything is read from it.
+//
+// Every access is wrapped: a browser with no IndexedDB, a private window
+// that refuses it, a quota that is full or a database that is corrupt all
+// read as "nothing remembered", and the upload starts over. Nothing here
+// ever throws.
+
+const DATABASE = 'tinvar-uploads';
+const STORE = 'resumable';
+const VERSION = 1;
+
+/** The entry that says whose records the store holds (purge()): no record, by its shape. */
+const OWNER = '\u0000owner';
+
+/**
+ * @typedef {{
+ *   id: string,
+ *   scope: string,
+ *   fingerprint: string,
+ *   session: string,
+ *   mode: 'chunks' | 'parts',
+ *   name: string,
+ *   size: number,
+ *   type: string,
+ *   lastModified: number,
+ *   offset: number,
+ *   createdAt: number,
+ *   expiresAt: number,
+ *   handle?: unknown,
+ * }} ResumeRecord
+ *
+ * @typedef {{
+ *   get: (id: string) => Promise<ResumeRecord | null>,
+ *   put: (record: ResumeRecord) => Promise<void>,
+ *   delete: (id: string) => Promise<void>,
+ *   inScope: (scope: string) => Promise<ResumeRecord[]>,
+ *   purge?: (binding: string | null) => Promise<void>,
+ * }} ResumeStore
+ */
+
+/**
+ * The browser's resume store, in IndexedDB; or one that remembers nothing
+ * where IndexedDB cannot be had.
+ *
+ * @returns {ResumeStore}
+ */
+export function indexedDbResumeStore() {
+  /** @type {Promise<IDBDatabase | null> | null} */
+  let opening = null;
+  /**
+   * The purge the router asked for before anything opened the database:
+   * the owner it last named, and whether one asked for between would have
+   * emptied the store whoever that owner is -- a session ended, or another
+   * bound -- since the purges before it were never run.
+   *
+   * @type {{ owner: string | null, force: boolean } | null}
+   */
+  let pending = null;
+  // Opened once, by the first upload that reads or writes a record -- never
+  // by the router, so a page with no upload opens no database -- and swept
+  // of every record that has run out, in any scope: a record is otherwise
+  // read, and deleted, only by the field it is for. Then the purge the
+  // router left, before anything is read.
+  const database = () =>
+    (opening ??= open().then(async (db) => {
+      if (db !== null) {
+        await sweep(db, expired);
+        if (pending !== null) {
+          const { owner, force } = pending;
+          pending = null;
+          await purgeFor(db, owner, force);
+        }
+      }
+      return db;
+    }));
+
+  /**
+   * @template T
+   * @param {IDBTransactionMode} mode
+   * @param {(store: IDBObjectStore) => IDBRequest<T>} work
+   * @returns {Promise<T | null>}
+   */
+  const run = async (mode, work) => {
+    const db = await database();
+    return db === null ? null : request(db, mode, work);
+  };
+
+  return {
+    async get(id) {
+      const found = /** @type {ResumeRecord | undefined | null} */ (await run('readonly', (s) => s.get(id)));
+      if (!isRecord(found)) return null;
+      if (expired(found)) {
+        await run('readwrite', (s) => s.delete(id));
+        return null;
+      }
+      return found;
+    },
+    async put(record) {
+      // A file handle the browser will not clone is left out, not the
+      // record: the upload can still be gone on with, the file chosen again.
+      if ((await run('readwrite', (s) => s.put(record))) === null && record.handle !== undefined) {
+        const { handle: _dropped, ...without } = record;
+        await run('readwrite', (s) => s.put(without));
+      }
+    },
+    async delete(id) {
+      await run('readwrite', (s) => s.delete(id));
+    },
+    async inScope(scope) {
+      const all = /** @type {unknown[] | null} */ (
+        await run('readonly', (s) => s.index('scope').getAll(scope))
+      );
+      const records = (all ?? []).filter(isRecord);
+      for (const record of records.filter(expired)) await run('readwrite', (s) => s.delete(record.id));
+      return records.filter((r) => !expired(r)).sort((a, b) => b.createdAt - a.createdAt);
+    },
+    async purge(binding) {
+      const owner = ownerOf(binding);
+      // Not opened on this page: nothing has read a record, so the purge
+      // waits for the first open (database()), which runs it first.
+      if (opening === null) {
+        pending = { owner, force: pending !== null && (pending.force || pending.owner !== owner) };
+        return;
+      }
+      const db = await database();
+      if (db !== null) await purgeFor(db, owner, false);
+    },
+  };
+}
+
+/**
+ * Empties the store unless its entry already names $owner -- and always
+ * for no owner, or where $force says a purge between would have.
+ *
+ * @param {IDBDatabase} db
+ * @param {string | null} owner
+ * @param {boolean} force
+ */
+async function purgeFor(db, owner, force) {
+  const marker = /** @type {{ owner?: unknown } | undefined | null} */ (
+    await request(db, 'readonly', (s) => s.get(OWNER))
+  );
+  if (!force && owner !== null && marker?.owner === owner) return;
+  // Emptied and marked as the new owner's in one transaction: both, or
+  // neither. Failed, the mark is taken off, so the next purge empties the
+  // store again rather than read it as clean.
+  if (!(await clearFor(db, owner))) await request(db, 'readwrite', (s) => s.delete(OWNER));
+}
+
+/**
+ * @template T
+ * @param {IDBDatabase} db
+ * @param {IDBTransactionMode} mode
+ * @param {(store: IDBObjectStore) => IDBRequest<T>} work
+ * @returns {Promise<T | null>}
+ */
+async function request(db, mode, work) {
+  try {
+    return await new Promise((resolve) => {
+      const pending = work(db.transaction(STORE, mode).objectStore(STORE));
+      pending.onsuccess = () => resolve(pending.result);
+      pending.onerror = () => resolve(null);
+    });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Empties the store and, for an owner, marks it as theirs, in one readwrite
+ * transaction. Whether it committed.
+ *
+ * @param {IDBDatabase} db
+ * @param {string | null} owner
+ * @returns {Promise<boolean>}
+ */
+function clearFor(db, owner) {
+  return new Promise((resolve) => {
+    try {
+      const transaction = db.transaction(STORE, 'readwrite');
+      transaction.oncomplete = () => resolve(true);
+      transaction.onerror = () => resolve(false);
+      transaction.onabort = () => resolve(false);
+      const store = transaction.objectStore(STORE);
+      store.clear();
+      if (owner !== null) store.put({ id: OWNER, owner });
+    } catch {
+      resolve(false);
+    }
+  });
+}
+
+/**
+ * Deletes every record $doomed says, in any scope -- its file handle with it.
+ *
+ * @param {IDBDatabase} db
+ * @param {(record: ResumeRecord) => boolean} doomed
+ */
+async function sweep(db, doomed) {
+  const all = /** @type {unknown[] | null} */ (await request(db, 'readonly', (s) => s.getAll()));
+  for (const record of (all ?? []).filter(isRecord).filter(doomed)) {
+    await request(db, 'readwrite', (s) => s.delete(record.id));
+  }
+}
+
+/**
+ * Whose records the store holds, from the router's binding (bindingOf()):
+ * its session and user hashes -- who is signed in, at which auth epoch --
+ * without the tenant and panel, which a record's own scope keeps apart
+ * already, so two tabs in two panels do not wipe each other's. Null for a
+ * session over. A record's scope cannot be held to the binding itself: a
+ * ticket's hashes are keyed apart from a route token's.
+ *
+ * @param {string | null} binding
+ */
+function ownerOf(binding) {
+  if (binding === null) return null;
+  try {
+    const [session, user] = JSON.parse(binding);
+    return typeof session === 'string' && session !== ''
+      ? JSON.stringify([session, String(user ?? '')])
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Forgets, in the page's resume store, every resumable upload unless the
+ * store's records are already the session and user $binding names -- all
+ * of them for null: what the router calls where it finds the session over
+ * or changed. Never throws.
+ *
+ * @param {string | null} binding
+ * @param {ResumeStore} [store]
+ */
+export function purgeResumeStore(binding, store) {
+  try {
+    void (store ?? defaultResumeStore()).purge?.(binding)?.catch(() => {});
+  } catch {
+    // Nothing remembered can be forgotten either.
+  }
+}
+
+/** @returns {Promise<IDBDatabase | null>} */
+function open() {
+  try {
+    const idb = globalThis.indexedDB;
+    if (!idb || typeof idb.open !== 'function') return Promise.resolve(null);
+    return new Promise((resolve) => {
+      let request;
+      try {
+        request = idb.open(DATABASE, VERSION);
+      } catch {
+        resolve(null);
+        return;
+      }
+      request.onupgradeneeded = () => {
+        try {
+          const store = request.result.createObjectStore(STORE, { keyPath: 'id' });
+          store.createIndex('scope', 'scope', { unique: false });
+        } catch {
+          // A database that cannot be shaped is one that holds nothing.
+        }
+      };
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => resolve(null);
+      request.onblocked = () => resolve(null);
+    });
+  } catch {
+    return Promise.resolve(null);
+  }
+}
+
+/** A store in memory: for a page with no IndexedDB, and for tests. @returns {ResumeStore} */
+export function memoryResumeStore() {
+  /** @type {Map<string, ResumeRecord>} */
+  const records = new Map();
+  /** @type {string | null} */
+  let owner = null;
+  return {
+    async get(id) {
+      const found = records.get(id) ?? null;
+      if (found !== null && expired(found)) {
+        records.delete(id);
+        return null;
+      }
+      return found;
+    },
+    async put(record) {
+      records.set(record.id, record);
+    },
+    async delete(id) {
+      records.delete(id);
+    },
+    async inScope(scope) {
+      return [...records.values()]
+        .filter((r) => r.scope === scope && !expired(r))
+        .sort((a, b) => b.createdAt - a.createdAt);
+    },
+    async purge(binding) {
+      const next = ownerOf(binding);
+      if (next !== null && next === owner) return;
+      records.clear();
+      owner = next;
+    },
+  };
+}
+
+/** @param {ResumeRecord} record */
+function expired(record) {
+  return record.expiresAt * 1000 <= Date.now();
+}
+
+/**
+ * A record as this code wrote it -- anything else in the database, from an
+ * older version or another hand, is passed over.
+ *
+ * @param {unknown} value
+ * @returns {value is ResumeRecord}
+ */
+function isRecord(value) {
+  const r = /** @type {any} */ (value);
+  return (
+    r !== null &&
+    typeof r === 'object' &&
+    typeof r.id === 'string' &&
+    typeof r.scope === 'string' &&
+    typeof r.fingerprint === 'string' &&
+    typeof r.session === 'string' &&
+    (r.mode === 'chunks' || r.mode === 'parts') &&
+    typeof r.name === 'string' &&
+    typeof r.size === 'number' &&
+    typeof r.offset === 'number' &&
+    typeof r.createdAt === 'number' &&
+    typeof r.expiresAt === 'number'
+  );
+}
+
+let shared = /** @type {ResumeStore | null} */ (null);
+
+/** The page's one resume store. @returns {ResumeStore} */
+export function defaultResumeStore() {
+  return (shared ??= indexedDbResumeStore());
+}

package/src/route.d.ts

@@ -0,0 +1,50 @@
+/** Route name => its path segments, `{name}` for a parameter; and its host pattern, for a route on a host of its own. */
+export type RouteTable<M> = {
+  readonly [N in keyof M]:
+    readonly string[] | { readonly segments: readonly string[]; readonly host: string };
+};
+
+/** The host a page is drawn on: its #[Domain] pattern (null for the primary host) and what it took. */
+export interface CurrentHost {
+  pattern: string | null;
+  params: Record<string, string> | readonly never[];
+}
+
+/** What the server routes by host with (ADR 0149): PHP's Domains::forClient(). */
+export interface Hosts {
+  scheme: string;
+  port: string;
+  roots: Record<string, string>;
+  primary: string;
+  current?: CurrentHost;
+}
+
+/** The global the browser keeps the page's hosts in, once read from its metadata. */
+export declare const HOSTS_GLOBAL: '__TINVAR_HOSTS__';
+
+/** The global the renderer keeps the AsyncLocalStorage each render's hosts are read from under. */
+export declare const HOSTS_STORE: '__TINVAR_HOSTS_STORE__';
+
+/** The server's hosts, or undefined where it routes on no host. */
+export declare function hosts(): Hosts | undefined;
+
+/** The origin of a host pattern for these parameters, as PHP's Domains::origin() builds it. */
+export declare function originOf(
+  pattern: string,
+  values: Record<string, unknown>,
+  config: Hosts,
+  name: string,
+): string;
+
+/**
+ * Builds the typed `route()` codegen exports from its table of named routes.
+ * Missing parameters are a type error; at runtime they, an unknown name and
+ * a value PHP's router could not match all throw. Where the server routes by
+ * host, a URL to a page on another host than the one drawn is absolute.
+ */
+export declare function routes<M extends object>(
+  table: RouteTable<M>,
+): <N extends keyof M & string>(name: N, params: M[N]) => string;
+
+/** PHP's Request::isPathSegment(), on a decoded value, and not empty. */
+export declare function isPathSegment(value: string): boolean;

package/src/route.js

@@ -0,0 +1,227 @@
+// Building a URL for a named route, from the table codegen writes.
+//
+// tinvar-spec.md: "Codegen emits a typed `route('racks.show', { rack })`
+// helper for TypeScript." Codegen declared that function and nothing ever
+// defined it, so the first import of it failed the build. The generated
+// module now calls routes() with each named page's path segments, and the
+// URL is built here -- by the same rules PHP's CompiledRoute::url() applies,
+// so a link built in a component is the URL the server would have built.
+//
+// Where the application routes by host (ADR 0149), a page may live on a host
+// of its own: its table entry carries the host pattern -- `admin.{root}`,
+// `{account}.{root}` -- and a URL to a page on another host than the one
+// being drawn is absolute, written with the scheme, port and configured
+// domains the server hands each render and each page (hosts()). A page on
+// the same host -- the same pattern, with the same host parameters -- is a
+// path, as it always was. Which host is being drawn comes with the render
+// and with the page, never from the browser's address bar, so the server
+// render and the browser write the same link and hydration holds. The
+// client router fetches a URL on its own origin as a visit and loads any
+// other as a document, so a link to another host is a full navigation.
+//
+// No React and nothing from Node: server components and the browser both
+// import it.
+
+/** The global the browser keeps the page's hosts in, once read from its metadata. */
+export const HOSTS_GLOBAL = '__TINVAR_HOSTS__';
+
+/**
+ * The global the renderer puts an AsyncLocalStorage under, each render run
+ * inside it with its frame's hosts: one renderer draws pages of several
+ * hosts at once, and each render reads its own. Read through the global,
+ * not imported, as this module imports nothing of Node's.
+ */
+export const HOSTS_STORE = '__TINVAR_HOSTS_STORE__';
+
+/**
+ * @typedef {{ pattern: string | null, params: Record<string, string> }} CurrentHost
+ * @typedef {{ scheme: string, port: string, roots: Record<string, string>, primary: string, current?: CurrentHost }} Hosts
+ */
+
+/**
+ * The server's hosts, where it routes by them, and the host being drawn:
+ * the render's own in the renderer, or read once from the page's metadata
+ * in a browser. Undefined where the application routes on no host.
+ *
+ * @returns {Hosts | undefined}
+ */
+export function hosts() {
+  const g = /** @type {Record<string, any>} */ (globalThis);
+  const stored = typeof g[HOSTS_STORE]?.getStore === 'function' ? g[HOSTS_STORE].getStore() : undefined;
+  if (isHosts(stored)) return stored;
+  const set = g[HOSTS_GLOBAL];
+  if (isHosts(set)) return set;
+
+  const doc = /** @type {{ document?: Document }} */ (globalThis).document;
+  if (typeof doc?.querySelector !== 'function') return undefined;
+  const element = doc.querySelector('script[type="application/json"]#tinvar-page');
+  if (!element) return undefined;
+  try {
+    const page = JSON.parse(element.textContent ?? '');
+    if (isHosts(page?.hosts)) {
+      /** @type {Record<string, unknown>} */ (globalThis)[HOSTS_GLOBAL] = page.hosts;
+      return page.hosts;
+    }
+  } catch {
+    // The document is the app's, and nothing in it is assumed well-formed.
+  }
+  return undefined;
+}
+
+/** @param {unknown} value @returns {value is Hosts} */
+function isHosts(value) {
+  const v = /** @type {any} */ (value);
+  return (
+    typeof v === 'object' &&
+    v !== null &&
+    typeof v.scheme === 'string' &&
+    typeof v.port === 'string' &&
+    typeof v.primary === 'string' &&
+    typeof v.roots === 'object' &&
+    v.roots !== null
+  );
+}
+
+/**
+ * Whether a route on host pattern $host (null: the primary host) is on the
+ * host being drawn: the same pattern, and each of its parameters the value
+ * the current host gave it.
+ *
+ * @param {string | null} host
+ * @param {Record<string, unknown>} values
+ * @param {CurrentHost | undefined} current
+ */
+function onCurrentHost(host, values, current) {
+  if (current === undefined || (current.pattern ?? null) !== host) return false;
+  if (host === null) return true;
+  const params = Array.isArray(current.params) ? {} : (current.params ?? {});
+  const labels = host.split('.');
+  return labels.every((label, index) => {
+    if (index === labels.length - 1 || !(label.startsWith('{') && label.endsWith('}'))) return true;
+    const key = label.slice(1, -1);
+    return Object.hasOwn(params, key) && String(values[key]) === params[key];
+  });
+}
+
+/** A host label, as PHP's HostPattern holds one. */
+const LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+
+/**
+ * The origin of a host pattern for these parameters: PHP's Domains::origin().
+ *
+ * @param {string} pattern
+ * @param {Record<string, unknown>} values
+ * @param {Hosts} config
+ * @param {string} name the route, for the errors
+ */
+export function originOf(pattern, values, config, name) {
+  const labels = pattern.split('.');
+  const out = labels.map((label, index) => {
+    if (!(label.startsWith('{') && label.endsWith('}'))) return label;
+    const key = label.slice(1, -1);
+    if (index === labels.length - 1) {
+      const root = config.roots[key];
+      if (typeof root !== 'string') {
+        throw new Error(
+          `[tinvar] The route '${name}' is on ${pattern}, and the server configures no domain '${key}'.`,
+        );
+      }
+      return root;
+    }
+    if (!Object.hasOwn(values, key) || values[key] === undefined || values[key] === null) {
+      throw new Error(`[tinvar] The route '${name}' needs a '${key}' parameter.`);
+    }
+    const value = String(values[key]);
+    if (!LABEL.test(value)) {
+      throw new Error(
+        `[tinvar] '${value}' cannot be the '${key}' parameter of the route '${name}': it is one host label.`,
+      );
+    }
+    return value;
+  });
+
+  return `${config.scheme}://${out.join('.')}${config.port === '' ? '' : `:${config.port}`}`;
+}
+
+/**
+ * @template {object} M route name => its parameters
+ * @param {{ readonly [N in keyof M]: readonly string[] | { readonly segments: readonly string[], readonly host: string } }} table
+ *        route name => path segments, `{name}` for a parameter, with the host pattern of a route on a host of its own
+ * @returns {<N extends keyof M & string>(name: N, params: M[N]) => string}
+ */
+export function routes(table) {
+  return (name, params) => {
+    if (!Object.hasOwn(table, name)) {
+      throw new Error(`[tinvar] No route is named '${name}'.`);
+    }
+
+    /** @type {Record<string, unknown>} */
+    const values = params ?? {};
+    const entry = table[name];
+    const segments = Array.isArray(entry)
+      ? entry
+      : /** @type {{ segments: readonly string[] }} */ (entry).segments;
+    const out = segments.map((segment) => {
+      if (!(segment.startsWith('{') && segment.endsWith('}'))) return segment;
+
+      const key = segment.slice(1, -1);
+      if (!Object.hasOwn(values, key) || values[key] === undefined || values[key] === null) {
+        throw new Error(`[tinvar] The route '${name}' needs a '${key}' parameter.`);
+      }
+
+      const value = String(values[key]);
+
+      // A parameter is one segment, by PHP's Request::isPathSegment() rule
+      // exactly. A separator, a traversal step, a backslash -- which a
+      // browser reads as a separator -- or a control character would build
+      // a URL the router refuses, or one the browser normalizes onto
+      // another path before it is sent: with the CSRF token on it, for an
+      // endpoint call. Refused here instead.
+      if (!isPathSegment(value)) {
+        throw new Error(`[tinvar] '${value}' cannot be the '${key}' parameter of the route '${name}'.`);
+      }
+
+      return rawUrlEncode(value);
+    });
+
+    const path = out.length === 0 ? '/' : `/${out.join('/')}`;
+    const config = hosts();
+    if (config === undefined) return path;
+
+    const host = Array.isArray(entry) ? null : /** @type {{ host: string }} */ (entry).host;
+    if (onCurrentHost(host, values, config.current)) return path;
+
+    return originOf(host ?? config.primary, values, config, name) + path;
+  };
+}
+
+/**
+ * PHP's Request::isPathSegment(), on a decoded value, and not empty.
+ *
+ * @param {string} value
+ */
+export function isPathSegment(value) {
+  return (
+    value !== '' &&
+    value !== '.' &&
+    value !== '..' &&
+    !value.includes('/') &&
+    !value.includes('\\') &&
+    // eslint-disable-next-line no-control-regex
+    !/[\x00-\x1f\x7f]/.test(value)
+  );
+}
+
+/**
+ * PHP's rawurlencode(): everything but A-Z a-z 0-9 - _ . ~ is escaped.
+ * encodeURIComponent() leaves ! ' ( ) * as they are, which would make the
+ * same link differ by where it was built.
+ *
+ * @param {string} value
+ */
+function rawUrlEncode(value) {
+  return encodeURIComponent(value).replace(
+    /[!'()*]/g,
+    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
+  );
+}