@diffenderfer-games/hub 2.0.0-next.0 → 2.0.0-next.10

package/src/core/offline/queue.ts

@@ -1,171 +1,126 @@
-/**
- * The offline mutation queue. Writes apply to the local cache at once and
- * queue a durable op; when the hub is reachable again the queue replays in
- * order. Ops collapse as they are queued (a save's last write wins, `incr`s
- * add up, `max`es keep the largest, a board keeps its best, profile patches
- * merge), so the backlog stays small.
- *
- * The op shapes are the v1 client's, unchanged: a page upgraded from a
- * vendored copy replays the queue that copy left in `localStorage`.
- */
-import type { Json } from '@diffenderfer-games/hub-contract';
-import type { SortDir } from '@diffenderfer-games/hub-contract';
-import { isJson, isNullableString, isRecord, optionalNumber, optionalString, type UncheckedRecord } from '../storage/json-guards';
-
-/** A score submission's options as queued (the metadata already JSON). */
-export interface QueuedScoreOptions {
-  /** The board's title; only used when the board key is first created. */
-  readonly title?: string;
-  /** The sort direction; only used on board creation. Default `desc`. */
-  readonly sort?: SortDir;
-  /** Any JSON stored with the entry (a character, a run seed). */
-  readonly meta?: Json;
-}
-
-/** A profile change: either part may be left out. */
-export interface ProfilePatch {
-  /** Shown to other players; `null` clears it. */
-  displayName?: string | null;
-  /** The game's own profile data. */
-  data?: Json;
-}
-
-/** A queued op's id and when it was queued. */
-interface QueueStamp {
-  /** Unique within this page: `<epoch ms>-<sequence>`. */
-  readonly id: string;
-  /** When it was queued (epoch ms). */
-  readonly ts: number;
-}
-
-/** A queued write, before it is stamped. */
-export type QueueOpInput =
-  | { readonly kind: 'putSave'; readonly slot: string; readonly data: Json; readonly label: string | null }
-  | { readonly kind: 'deleteSave'; readonly slot: string }
-  | { readonly kind: 'setStat'; readonly key: string; readonly value: number }
-  | { readonly kind: 'maxStat'; readonly key: string; readonly value: number }
-  | { readonly kind: 'incrStat'; readonly key: string; readonly amount: number }
-  | { readonly kind: 'submitScore'; readonly key: string; readonly score: number; readonly opts: QueuedScoreOptions }
-  | { readonly kind: 'setProfile'; readonly patch: ProfilePatch };
-
-/** A queued write, as stored under `hub:<slug>:queue`. */
-export type QueueOp = QueueOpInput & QueueStamp;
-
-/** The score options in a stored op, or `undefined` when they are malformed. */
-function readScoreOptions(stored: UncheckedRecord): QueuedScoreOptions | undefined {
-  const title = optionalString(stored.title);
-  const sort = stored.sort === 'asc' || stored.sort === 'desc' ? stored.sort : undefined;
-  if (stored.meta !== undefined && !isJson(stored.meta)) {
-    return undefined;
-  }
-  return { ...(title === undefined ? {} : { title }), ...(sort === undefined ? {} : { sort }), ...(stored.meta === undefined ? {} : { meta: stored.meta }) };
-}
-
-/** The profile patch in a stored op, or `undefined` when it is malformed. */
-function readProfilePatch(stored: UncheckedRecord): ProfilePatch | undefined {
-  if ((stored.displayName !== undefined && !isNullableString(stored.displayName)) || (stored.data !== undefined && !isJson(stored.data))) {
-    return undefined;
-  }
-  const patch: ProfilePatch = {};
-  if (stored.displayName !== undefined) {
-    patch.displayName = stored.displayName;
-  }
-  if (stored.data !== undefined) {
-    patch.data = stored.data;
-  }
-  return patch;
-}
-
-/** One stored op's write, or `undefined` when it is not a known, well-formed op. */
-function readOpInput(stored: UncheckedRecord): QueueOpInput | undefined {
-  const slot = optionalString(stored.slot);
-  const key = optionalString(stored.key);
-  const statValue = optionalNumber(stored.value);
-  switch (stored.kind) {
-    case 'putSave':
-      return slot !== undefined && isJson(stored.data) && isNullableString(stored.label) ? { kind: 'putSave', slot, data: stored.data, label: stored.label } : undefined;
-    case 'deleteSave':
-      return slot === undefined ? undefined : { kind: 'deleteSave', slot };
-    case 'setStat':
-    case 'maxStat':
-      return key !== undefined && statValue !== undefined ? { kind: stored.kind, key, value: statValue } : undefined;
-    case 'incrStat': {
-      const amount = optionalNumber(stored.amount);
-      return key !== undefined && amount !== undefined ? { kind: 'incrStat', key, amount } : undefined;
-    }
-    case 'submitScore': {
-      const score = optionalNumber(stored.score);
-      const opts = isRecord(stored.opts) ? readScoreOptions(stored.opts) : undefined;
-      return key !== undefined && score !== undefined && opts !== undefined ? { kind: 'submitScore', key, score, opts } : undefined;
-    }
-    case 'setProfile': {
-      const patch = isRecord(stored.patch) ? readProfilePatch(stored.patch) : undefined;
-      return patch === undefined ? undefined : { kind: 'setProfile', patch };
-    }
-    default:
-      return undefined;
-  }
-}
-
-/** The well-formed ops of a stored queue, in order; anything malformed is dropped. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: a queue read back from localStorage (possibly written by a v1 client)
-export function readQueue(stored: unknown): QueueOp[] {
-  if (!Array.isArray(stored)) {
-    return [];
-  }
-  return stored.flatMap((entry): QueueOp[] => {
-    if (!isRecord(entry)) {
-      return [];
-    }
-    const input = readOpInput(entry);
-    const id = optionalString(entry.id);
-    const ts = optionalNumber(entry.ts);
-    return input === undefined || id === undefined || ts === undefined ? [] : [{ ...input, id, ts }];
-  });
-}
-
-/** The better of two scores on a board sorted `sort` (`desc` by default). */
-export function betterScore(first: number, second: number, sort: SortDir | undefined): number {
-  return sort === 'asc' ? Math.min(first, second) : Math.max(first, second);
-}
-
-/** The op that `queued` becomes when `incoming` collapses into it, or `undefined` when they don't collapse. */
-function collapsedOp(queued: QueueOp, incoming: QueueOp): QueueOp | undefined {
-  if (queued.kind === 'incrStat' && incoming.kind === 'incrStat' && queued.key === incoming.key) {
-    return { ...queued, amount: queued.amount + incoming.amount };
-  }
-  if (queued.kind === 'maxStat' && incoming.kind === 'maxStat' && queued.key === incoming.key) {
-    return { ...queued, value: Math.max(queued.value, incoming.value) };
-  }
-  if (queued.kind === 'setStat' && incoming.kind === 'setStat' && queued.key === incoming.key) {
-    return { ...queued, value: incoming.value };
-  }
-  if (queued.kind === 'submitScore' && incoming.kind === 'submitScore' && queued.key === incoming.key) {
-    return { ...queued, score: betterScore(queued.score, incoming.score, incoming.opts.sort), opts: incoming.opts };
-  }
-  if (queued.kind === 'setProfile' && incoming.kind === 'setProfile') {
-    return { ...queued, patch: { ...queued.patch, ...incoming.patch } };
-  }
-  return undefined;
-}
-
-/** Whether an op writes save slot `slot`. */
-function writesSlot(op: QueueOp, slot: string): boolean {
-  return (op.kind === 'putSave' || op.kind === 'deleteSave') && op.slot === slot;
-}
-
-/**
- * The queue with `incoming` added: a save or delete replaces any queued
- * write to the same slot (and goes last); a compatible op merges into the
- * first queued one in place; anything else is appended.
- */
-export function enqueueOp(queue: readonly QueueOp[], incoming: QueueOp): QueueOp[] {
-  if (incoming.kind === 'putSave' || incoming.kind === 'deleteSave') {
-    return [...queue.filter((op) => !writesSlot(op, incoming.slot)), incoming];
-  }
-  const mergeAt = queue.findIndex((op) => collapsedOp(op, incoming) !== undefined);
-  if (mergeAt < 0) {
-    return [...queue, incoming];
-  }
-  return queue.map((op, i) => (i === mergeAt ? (collapsedOp(op, incoming) ?? op) : op));
-}
+/**
+ * The v1 client's offline queue (`hub:<slug>:queue`): its op shapes and the
+ * reader for what a vendored v1 copy left in `localStorage`. This client
+ * queues into the outbox instead (`outbox.ts`) and moves any v1 ops there on
+ * start (`hub-kinds/legacy-ops.ts`), so nothing a v1 copy queued is lost.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import type { SortDir } from '@diffenderfer-games/hub-contract';
+import { isJson, isNullableString, isRecord, optionalNumber, optionalString, type UncheckedRecord } from '../storage/json-guards';
+
+/** A score submission's options as queued (the metadata already JSON). */
+export interface QueuedScoreOptions {
+  /** The board's title; only used when the board key is first created. */
+  readonly title?: string;
+  /** The sort direction; only used on board creation. Default `desc`. */
+  readonly sort?: SortDir;
+  /** Any JSON stored with the entry (a character, a run seed). */
+  readonly meta?: Json;
+}
+
+/** A profile change: either part may be left out. */
+export interface ProfilePatch {
+  /** Shown to other players; `null` clears it. */
+  displayName?: string | null;
+  /** The game's own profile data. */
+  data?: Json;
+}
+
+/** A queued op's id and when it was queued. */
+interface QueueStamp {
+  /** Unique within this page: `<epoch ms>-<sequence>`. */
+  readonly id: string;
+  /** When it was queued (epoch ms). */
+  readonly ts: number;
+}
+
+/** A queued write, before it is stamped. */
+export type QueueOpInput =
+  | { readonly kind: 'putSave'; readonly slot: string; readonly data: Json; readonly label: string | null }
+  | { readonly kind: 'deleteSave'; readonly slot: string }
+  | { readonly kind: 'setStat'; readonly key: string; readonly value: number }
+  | { readonly kind: 'maxStat'; readonly key: string; readonly value: number }
+  | { readonly kind: 'incrStat'; readonly key: string; readonly amount: number }
+  | { readonly kind: 'submitScore'; readonly key: string; readonly score: number; readonly opts: QueuedScoreOptions }
+  | { readonly kind: 'setProfile'; readonly patch: ProfilePatch };
+
+/** A queued write, as stored under `hub:<slug>:queue`. */
+export type QueueOp = QueueOpInput & QueueStamp;
+
+/** The score options in a stored op, or `undefined` when they are malformed. */
+function readScoreOptions(stored: UncheckedRecord): QueuedScoreOptions | undefined {
+  const title = optionalString(stored.title);
+  const sort = stored.sort === 'asc' || stored.sort === 'desc' ? stored.sort : undefined;
+  if (stored.meta !== undefined && !isJson(stored.meta)) {
+    return undefined;
+  }
+  return { ...(title === undefined ? {} : { title }), ...(sort === undefined ? {} : { sort }), ...(stored.meta === undefined ? {} : { meta: stored.meta }) };
+}
+
+/** The profile patch in a stored op, or `undefined` when it is malformed. */
+function readProfilePatch(stored: UncheckedRecord): ProfilePatch | undefined {
+  if ((stored.displayName !== undefined && !isNullableString(stored.displayName)) || (stored.data !== undefined && !isJson(stored.data))) {
+    return undefined;
+  }
+  const patch: ProfilePatch = {};
+  if (stored.displayName !== undefined) {
+    patch.displayName = stored.displayName;
+  }
+  if (stored.data !== undefined) {
+    patch.data = stored.data;
+  }
+  return patch;
+}
+
+/** One stored op's write, or `undefined` when it is not a known, well-formed op. */
+function readOpInput(stored: UncheckedRecord): QueueOpInput | undefined {
+  const slot = optionalString(stored.slot);
+  const key = optionalString(stored.key);
+  const statValue = optionalNumber(stored.value);
+  switch (stored.kind) {
+    case 'putSave':
+      return slot !== undefined && isJson(stored.data) && isNullableString(stored.label) ? { kind: 'putSave', slot, data: stored.data, label: stored.label } : undefined;
+    case 'deleteSave':
+      return slot === undefined ? undefined : { kind: 'deleteSave', slot };
+    case 'setStat':
+    case 'maxStat':
+      return key !== undefined && statValue !== undefined ? { kind: stored.kind, key, value: statValue } : undefined;
+    case 'incrStat': {
+      const amount = optionalNumber(stored.amount);
+      return key !== undefined && amount !== undefined ? { kind: 'incrStat', key, amount } : undefined;
+    }
+    case 'submitScore': {
+      const score = optionalNumber(stored.score);
+      const opts = isRecord(stored.opts) ? readScoreOptions(stored.opts) : undefined;
+      return key !== undefined && score !== undefined && opts !== undefined ? { kind: 'submitScore', key, score, opts } : undefined;
+    }
+    case 'setProfile': {
+      const patch = isRecord(stored.patch) ? readProfilePatch(stored.patch) : undefined;
+      return patch === undefined ? undefined : { kind: 'setProfile', patch };
+    }
+    default:
+      return undefined;
+  }
+}
+
+/** The well-formed ops of a stored queue, in order; anything malformed is dropped. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a queue read back from localStorage (possibly written by a v1 client)
+export function readQueue(stored: unknown): QueueOp[] {
+  if (!Array.isArray(stored)) {
+    return [];
+  }
+  return stored.flatMap((entry): QueueOp[] => {
+    if (!isRecord(entry)) {
+      return [];
+    }
+    const input = readOpInput(entry);
+    const id = optionalString(entry.id);
+    const ts = optionalNumber(entry.ts);
+    return input === undefined || id === undefined || ts === undefined ? [] : [{ ...input, id, ts }];
+  });
+}
+
+/** The better of two scores on a board sorted `sort` (`desc` by default). */
+export function betterScore(first: number, second: number, sort: SortDir | undefined): number {
+  return sort === 'asc' ? Math.min(first, second) : Math.max(first, second);
+}

package/src/core/offline/replay-lease.ts

@@ -0,0 +1,87 @@
+/**
+ * One replayer at a time per game, across tabs and across the client copies
+ * on one page: a Web Lock where the browser has them, else a lease in
+ * `localStorage` that its holder renews while it works and that lapses if
+ * the tab dies. A replayer that can't get it simply doesn't run; the holder
+ * replays for everyone.
+ */
+import { isRecord, optionalNumber, optionalString, parseJsonText } from '../storage/json-guards';
+import type { KeyValueStore } from '../storage/key-value';
+
+/** Runs work while holding the lease. */
+export interface ReplayLease {
+  /** Run `work` holding the lease; `false` (without running it) when another replayer holds it. */
+  hold(work: () => Promise<void>): Promise<boolean>;
+}
+
+/** How long a `localStorage` lease lasts without renewal. */
+export const STORAGE_LEASE_MS = 15_000;
+
+/** How often the holder renews it. */
+const RENEW_EVERY_MS = 5_000;
+
+/** A lease on the Web Locks API. */
+function webLockLease(locks: LockManager, name: string): ReplayLease {
+  return {
+    hold: (work) => locks.request(name, { ifAvailable: true }, async (lock) => {
+      if (lock === null) {
+        return false;
+      }
+      await work();
+      return true;
+    }),
+  };
+}
+
+/** The lease's holder and expiry, or `undefined` when there is none. */
+function readLease(text: string | null): { readonly owner: string; readonly until: number } | undefined {
+  const stored = text === null ? undefined : parseJsonText(text);
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  const owner = optionalString(stored.owner);
+  const until = optionalNumber(stored.until);
+  return owner === undefined || until === undefined ? undefined : { owner, until };
+}
+
+/** A lease kept in `store` under `key`, for pages without Web Locks. */
+export function storageLease(store: KeyValueStore, key: string, now: () => number = Date.now): ReplayLease {
+  const owner = `${String(now())}-${Math.random().toString(36).slice(2)}`;
+  const claim = (): boolean => {
+    const current = readLease(store.read(key));
+    if (current !== undefined && current.owner !== owner && current.until > now()) {
+      return false;
+    }
+    store.write(key, JSON.stringify({ owner, until: now() + STORAGE_LEASE_MS }));
+    return readLease(store.read(key))?.owner === owner;
+  };
+  return {
+    async hold(work) {
+      if (!claim()) {
+        return false;
+      }
+      const renewal = setInterval(claim, RENEW_EVERY_MS);
+      try {
+        await work();
+      } finally {
+        clearInterval(renewal);
+        if (readLease(store.read(key))?.owner === owner) {
+          store.remove(key);
+        }
+      }
+      return true;
+    },
+  };
+}
+
+/** The page's Web Locks, when it has them. */
+function pageLocks(): LockManager | undefined {
+  return typeof navigator !== 'undefined' && 'locks' in navigator ? navigator.locks : undefined;
+}
+
+/** The lease for game `slug`'s outbox: a Web Lock when available, else one in `store`. */
+export function createReplayLease(slug: string, store: KeyValueStore): ReplayLease {
+  const name = `hub:${slug}:outbox-lease`;
+  const locks = pageLocks();
+  return locks === undefined ? storageLease(store, name) : webLockLease(locks, name);
+}

package/src/core/offline/replay-policy.ts

@@ -0,0 +1,52 @@
+/**
+ * What a failed replay does next, and how long it waits:
+ *
+ * - `offline`: the hub (or the network) can't be reached. The op stays at
+ *   the head of the queue and replay waits for the connection.
+ * - `retry`: the hub answered with a passing problem (408, 429, 5xx) or a
+ *   game handler's fetch failed. The op stays at the head and is retried with
+ *   backoff, up to {@link MAX_RETRIES} times, then dropped.
+ * - `drop`: the hub refused it (any other status) or the handler threw
+ *   something else. The op is dropped and reported, and the queue moves on.
+ */
+import { HubError } from '../errors';
+
+/** What to do after a failed replay. */
+export type FailureVerdict = 'offline' | 'retry' | 'drop';
+
+/** The most tries for an op that keeps getting a passing failure. */
+export const MAX_RETRIES = 8;
+
+/** The first retry's delay. */
+const BASE_DELAY_MS = 1000;
+
+/** The longest delay between tries. */
+const MAX_DELAY_MS = 60_000;
+
+/** Statuses that mean "try again later". */
+const PASSING_STATUSES: ReadonlySet<number> = new Set([408, 425, 429]);
+
+/** The verdict for a failure. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: whatever a replay handler threw
+export function verdictFor(failure: unknown): FailureVerdict {
+  if (failure instanceof HubError) {
+    if (failure.status === undefined) {
+      return 'offline';
+    }
+    return failure.status >= 500 || PASSING_STATUSES.has(failure.status) ? 'retry' : 'drop';
+  }
+  // A game handler's own fetch rejects with a TypeError when the network is down.
+  return failure instanceof TypeError ? 'retry' : 'drop';
+}
+
+/** The delay before try `attempts + 1`: doubling from 1 s, capped at 60 s, with jitter so tabs and players spread out. */
+export function backoffMs(attempts: number, random: () => number = Math.random): number {
+  const ceiling = Math.min(MAX_DELAY_MS, BASE_DELAY_MS * 2 ** Math.max(0, attempts - 1));
+  return Math.round(ceiling / 2 + (ceiling / 2) * random());
+}
+
+/** A failure's message, for reports. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: whatever a replay handler threw
+export function failureMessage(failure: unknown): string {
+  return failure instanceof Error ? failure.message : String(failure);
+}

package/src/core/page-account.ts

@@ -0,0 +1,121 @@
+/**
+ * Who the page is signed in as, as the hub tells it, so `hub.userId()` and
+ * `hub.avatar` follow the account without the game calling `hub.me()`:
+ *
+ * - the menu's `hub:account` (every refresh: after it makes a new guest's
+ *   account, after sign-in) and `hub:auth` (the account changed);
+ * - the social runtime's {@link SESSION_EVENT} each time its socket says
+ *   hello (connected, or connected again after a drop);
+ * - this client's own sign-in, sign-up, claim and sign-out.
+ *
+ * One per page: every bundle's copy hears the same window events.
+ */
+import { readField } from '../realtime/cross-bundle';
+import { SESSION_EVENT } from '../realtime/runtime-api';
+import { isBrowserPage } from './page';
+
+/** The window events that say who is signed in (`{ user }`). */
+const ACCOUNT_EVENTS = ['hub:account', 'hub:auth'] as const;
+
+/** The signed-in player as the page heard it. */
+export interface PageUser {
+  readonly id: number;
+  /** Their look code when the source carried it, else `null`. */
+  readonly look: string | null;
+}
+
+/** Where the news came from: an account event, or a socket hello (a time to catch up on what was missed). */
+export type AccountSource = 'account' | 'session';
+
+/** Hears every report of who is signed in. */
+export type AccountListener = (user: PageUser | null, source: AccountSource) => void;
+
+/** The page's account, as last heard. */
+export class PageAccount {
+  /** `undefined` until something said; `null` when signed out. */
+  private heard: PageUser | null | undefined = undefined;
+  private readonly listeners = new Set<AccountListener>();
+  private isListening = false;
+
+  constructor() {
+    this.listen();
+  }
+
+  /** The signed-in player, `null` when signed out, `undefined` before anything said. */
+  get user(): PageUser | null | undefined {
+    this.listen();
+    return this.heard;
+  }
+
+  /** Record who is signed in (this client's own sign-in or sign-out) and tell the listeners. */
+  note(user: PageUser | null, source: AccountSource = 'account'): void {
+    this.heard = user;
+    for (const listener of [...this.listeners]) {
+      listener(user, source);
+    }
+  }
+
+  /** Hear every report; returns the unsubscribe function. */
+  on(listener: AccountListener): () => void {
+    this.listen();
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /** Listen to the window events (at once in a page; made before a window existed, on first use). */
+  private listen(): void {
+    if (this.isListening || !isBrowserPage()) {
+      return;
+    }
+    this.isListening = true;
+    for (const eventName of ACCOUNT_EVENTS) {
+      window.addEventListener(eventName, (event) => { this.onEvent(event, 'account'); });
+    }
+    window.addEventListener(SESSION_EVENT, (event) => { this.onEvent(event, 'session'); });
+  }
+
+  private onEvent(event: Event, source: AccountSource): void {
+    if (!(event instanceof CustomEvent)) {
+      return;
+    }
+    const user = readUser(event.detail);
+    if (user !== undefined) {
+      this.note(user, source);
+    }
+  }
+}
+
+/** A page user from an account the hub sent (`look` when it has one). */
+export function toPageUser(user: { readonly id: number; readonly look?: string | undefined }): PageUser {
+  return { id: user.id, look: lookOrNull(user.look) };
+}
+
+/** A non-empty look code, else `null`. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a field of another bundle's event detail
+function lookOrNull(look: unknown): string | null {
+  return typeof look === 'string' && look !== '' ? look : null;
+}
+
+/** The user in a `{ user }` detail: the user, `null` (signed out), or `undefined` (it doesn't say). */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: another bundle's event detail, read field by field
+function readUser(detail: unknown): PageUser | null | undefined {
+  const user = readField(detail, 'user');
+  if (user === null) {
+    return null;
+  }
+  const id = readField(user, 'id');
+  if (typeof id !== 'number' || !Number.isInteger(id)) {
+    return undefined;
+  }
+  return { id, look: lookOrNull(readField(user, 'look')) };
+}
+
+let pageAccountSingleton: PageAccount | null = null;
+
+/** The page's account tracker (made on first use; the hub client makes it at load). */
+export function pageAccount(): PageAccount {
+  pageAccountSingleton ??= new PageAccount();
+  return pageAccountSingleton;
+}