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

package/src/core/connection.ts

@@ -1,299 +1,299 @@
-/**
- * The machinery under every `Hub` call: reaching the REST API, falling back
- * to the offline cache, queueing writes made offline and replaying them,
- * buffering analytics, warming the cache for every game, and reporting
- * online/offline/sync status (to `onStatus` listeners and as `hub:*` window
- * events, which the injected menu listens for).
- */
-import { HubError } from './errors';
-import { LocalStore } from './offline/local-store';
-import type { QueueOp, QueueOpInput } from './offline/queue';
-import { absoluteApiBase, detectApiBase, detectSlug, emitWindowEvent, isBrowserPage } from './page';
-import { createRestClient, type RestClient } from './rest/rest-client';
-import type { HubOptions, HubStatus, SnapshotResponse } from './types';
-
-/** How long `prefetchAll()` waits between snapshots unless forced. */
-const PREFETCH_INTERVAL_MS = 30_000;
-
-/** A queued write the hub refused during a sync: dropped, with the hub's message. */
-export interface SyncConflict {
-  /** The refused op. */
-  readonly op: QueueOp;
-  /** The hub's message. */
-  readonly error?: string;
-}
-
-/** What one `sync()` did. */
-export interface SyncResult {
-  /** Queued writes the hub accepted. */
-  readonly flushed: number;
-  /** Queued writes the hub refused (and that were dropped). */
-  readonly conflicts: SyncConflict[];
-}
-
-/** Whether a failure means "the hub can't be reached" (rather than a refusal). */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: whatever a call threw
-function isTransportFailure(failure: unknown): boolean {
-  return failure instanceof HubError && failure.isOffline;
-}
-
-/** The game slug's path field, or a {@link HubError} when the slug is unknown. */
-export interface GameFields {
-  /** The game's slug. */
-  readonly slug: string;
-}
-
-/** The connection, offline cache and sync machinery shared by every `Hub` method. */
-export class HubConnection {
-  /** This client's game slug (`null` when it could not be determined). */
-  readonly slug: string | null;
-  /** The absolute API base, e.g. `https://diffenderfer.games/_api`. */
-  readonly apiBase: string;
-  /** Typed REST calls to {@link apiBase}. */
-  protected readonly rest: RestClient;
-  /** This game's offline cache, queue and event buffer. */
-  protected readonly store: LocalStore;
-  private readonly offlineMode: NonNullable<HubOptions['offline']>;
-  private isReachable = true;
-  private isSyncing = false;
-  private lastPrefetchAt = 0;
-  private readonly statusListeners = new Set<(status: HubStatus) => void>();
-
-  /** A connection for `options` (slug and API base default to the page's). */
-  constructor(options: HubOptions = {}) {
-    this.slug = options.slug ?? detectSlug();
-    this.apiBase = options.apiBase === undefined ? detectApiBase() : absoluteApiBase(options.apiBase);
-    this.offlineMode = options.offline ?? 'auto';
-    this.rest = createRestClient({
-      apiBase: this.apiBase,
-      fetch: options.fetch ?? globalThis.fetch.bind(globalThis),
-      onReachable: () => {
-        this.setReachable(true);
-      },
-    });
-    this.store = new LocalStore(this.slug ?? 'app');
-    if (typeof navigator !== 'undefined' && 'onLine' in navigator) {
-      this.isReachable = navigator.onLine;
-    }
-    if (isBrowserPage()) {
-      window.addEventListener('online', () => {
-        this.setReachable(true);
-      });
-      window.addEventListener('offline', () => {
-        this.setReachable(false);
-      });
-    }
-  }
-
-  /** `true` when calls are being served from the offline cache rather than the hub. */
-  get isOffline(): boolean {
-    return this.offlineMode === 'always' || (this.offlineMode === 'auto' && !this.isReachable);
-  }
-
-  /** `true` while the hub is reachable. */
-  get isOnline(): boolean {
-    return this.isReachable;
-  }
-
-  /** Queued writes plus buffered analytics events waiting to sync. */
-  pending(): number {
-    return this.store.queueLength() + this.store.getEvents().length;
-  }
-
-  /** Subscribe to connection and sync status changes; returns the unsubscribe function. */
-  onStatus(listener: (status: HubStatus) => void): () => void {
-    this.statusListeners.add(listener);
-    return () => {
-      this.statusListeners.delete(listener);
-    };
-  }
-
-  /** Tell `onStatus` listeners and the page (`hub:status`) the current status. */
-  protected notifyStatus(): void {
-    const status: HubStatus = { online: this.isReachable, offline: this.isOffline, pending: this.pending() };
-    for (const listener of this.statusListeners) {
-      try {
-        listener(status);
-      } catch {
-        // A listener's failure must not stop the others.
-      }
-    }
-    emitWindowEvent('hub:status', status);
-  }
-
-  /** Record reachability; coming back online syncs the queue and re-warms the cache. */
-  protected setReachable(isReachableNow: boolean): void {
-    if (isReachableNow === this.isReachable) {
-      return;
-    }
-    this.isReachable = isReachableNow;
-    emitWindowEvent(isReachableNow ? 'hub:online' : 'hub:offline', { pending: this.pending() });
-    this.notifyStatus();
-    if (isReachableNow) {
-      void this.sync();
-      void this.prefetchAll().catch(() => undefined);
-    }
-  }
-
-  /** `{ slug }` for this game's endpoints; throws when the slug is unknown. */
-  protected gameFields(): GameFields {
-    if (this.slug === null) {
-      throw new HubError('Hub: could not determine the game slug.');
-    }
-    return { slug: this.slug };
-  }
-
-  /**
-   * Run the network call, falling back to the offline answer when the hub
-   * can't be reached (per the offline mode). Real API errors (with an HTTP
-   * status) always reach the caller.
-   */
-  protected async withFallback<Reply>(networkCall: () => Promise<Reply>, offlineAnswer: () => Reply): Promise<Reply> {
-    if (this.isOffline) {
-      return offlineAnswer();
-    }
-    try {
-      return await networkCall();
-    } catch (failure) {
-      if (!isTransportFailure(failure) || this.offlineMode === 'never') {
-        throw failure;
-      }
-      this.setReachable(false);
-      return offlineAnswer();
-    }
-  }
-
-  /** Send one queued write. */
-  private async sendOp(op: QueueOpInput): Promise<void> {
-    const game = this.gameFields();
-    switch (op.kind) {
-      case 'putSave':
-        await this.rest.call('writeSave', { ...game, slot: op.slot, data: op.data, label: op.label });
-        return;
-      case 'deleteSave':
-        await this.rest.call('deleteSave', { ...game, slot: op.slot });
-        return;
-      case 'setStat':
-        await this.rest.call('updateGameStat', { ...game, key: op.key, value: op.value, mode: 'set' });
-        return;
-      case 'maxStat':
-        await this.rest.call('updateGameStat', { ...game, key: op.key, value: op.value, mode: 'max' });
-        return;
-      case 'incrStat':
-        await this.rest.call('updateGameStat', { ...game, key: op.key, value: op.amount, mode: 'incr' });
-        return;
-      case 'submitScore':
-        await this.rest.call('submitScore', { ...game, key: op.key, score: op.score, ...op.opts });
-        return;
-      case 'setProfile':
-        await this.rest.call('setGameProfile', { ...game, ...op.patch });
-        return;
-    }
-  }
-
-  /**
-   * Apply a write to the offline cache at once, then send it now (online
-   * with an empty queue) or queue it behind the others. Resolves with the
-   * local answer; a real API error on the direct path reaches the caller and
-   * is not queued.
-   */
-  protected async mutateQueued<Reply>(input: QueueOpInput, localAnswer: () => Reply): Promise<Reply> {
-    const answer = localAnswer();
-    if (this.isOffline || this.store.queueLength() > 0) {
-      this.store.enqueue(input);
-      this.notifyStatus();
-      if (!this.isOffline) {
-        void this.sync();
-      }
-      return answer;
-    }
-    try {
-      await this.sendOp(input);
-      return answer;
-    } catch (failure) {
-      if (!isTransportFailure(failure)) {
-        throw failure;
-      }
-      this.setReachable(false);
-      this.store.enqueue(input);
-      this.notifyStatus();
-      return answer;
-    }
-  }
-
-  /**
-   * Replay the queue, then the buffered events, in order. Stops at the first
-   * transport failure (offline again: the rest stays queued); a write the hub
-   * refuses is dropped and reported as a conflict.
-   */
-  async sync(): Promise<SyncResult> {
-    if (this.isSyncing || this.isOffline || this.slug === null) {
-      return { flushed: 0, conflicts: [] };
-    }
-    this.isSyncing = true;
-    let flushed = 0;
-    const conflicts: SyncConflict[] = [];
-    try {
-      let queue = this.store.getQueue();
-      for (let op = queue[0]; op !== undefined; op = queue[0]) {
-        try {
-          await this.sendOp(op);
-          flushed += 1;
-        } catch (failure) {
-          if (isTransportFailure(failure)) {
-            break;
-          }
-          conflicts.push({ op, error: failure instanceof Error ? failure.message : String(failure) });
-        }
-        queue = queue.slice(1);
-        this.store.setQueue(queue);
-      }
-      await this.flushEvents();
-    } finally {
-      this.isSyncing = false;
-    }
-    emitWindowEvent('hub:sync', { pending: this.pending(), flushed, conflicts });
-    this.notifyStatus();
-    return { flushed, conflicts };
-  }
-
-  /** Send the buffered analytics events; a refused one is dropped (telemetry never blocks). */
-  private async flushEvents(): Promise<void> {
-    let events = this.store.getEvents();
-    for (let event = events[0]; event !== undefined; event = events[0]) {
-      try {
-        await this.rest.call('recordGameEvent', { ...this.gameFields(), type: event.type });
-      } catch (failure) {
-        if (isTransportFailure(failure)) {
-          return;
-        }
-      }
-      events = events.slice(1);
-      this.store.setEvents(events);
-    }
-  }
-
-  /**
-   * Warm the offline cache for every game the player has touched, in one
-   * request, so going offline later still shows complete progress.
-   * Throttled to once per 30 s unless `isForced`; `null` when offline or throttled.
-   */
-  async prefetchAll(isForced = false): Promise<SnapshotResponse | null> {
-    if (this.isOffline || (!isForced && Date.now() - this.lastPrefetchAt < PREFETCH_INTERVAL_MS)) {
-      return null;
-    }
-    let snapshot: SnapshotResponse;
-    try {
-      snapshot = await this.rest.call('getMyOfflineSnapshot');
-    } catch (failure) {
-      if (isTransportFailure(failure)) {
-        return null;
-      }
-      throw failure;
-    }
-    this.lastPrefetchAt = Date.now();
-    this.store.hydrate(snapshot);
-    emitWindowEvent('hub:prefetch', { games: Object.keys(snapshot.games).length });
-    return snapshot;
-  }
-}
+/**
+ * The machinery under every `Hub` call: reaching the REST API, falling back
+ * to the offline cache, queueing writes made offline and replaying them,
+ * buffering analytics, warming the cache for every game, and reporting
+ * online/offline/sync status (to `onStatus` listeners and as `hub:*` window
+ * events, which the injected menu listens for).
+ */
+import { HubError } from './errors';
+import { LocalStore } from './offline/local-store';
+import type { QueueOp, QueueOpInput } from './offline/queue';
+import { absoluteApiBase, detectApiBase, detectSlug, emitWindowEvent, isBrowserPage } from './page';
+import { createRestClient, type RestClient } from './rest/rest-client';
+import type { HubOptions, HubStatus, SnapshotResponse } from './types';
+
+/** How long `prefetchAll()` waits between snapshots unless forced. */
+const PREFETCH_INTERVAL_MS = 30_000;
+
+/** A queued write the hub refused during a sync: dropped, with the hub's message. */
+export interface SyncConflict {
+  /** The refused op. */
+  readonly op: QueueOp;
+  /** The hub's message. */
+  readonly error?: string;
+}
+
+/** What one `sync()` did. */
+export interface SyncResult {
+  /** Queued writes the hub accepted. */
+  readonly flushed: number;
+  /** Queued writes the hub refused (and that were dropped). */
+  readonly conflicts: SyncConflict[];
+}
+
+/** Whether a failure means "the hub can't be reached" (rather than a refusal). */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: whatever a call threw
+function isTransportFailure(failure: unknown): boolean {
+  return failure instanceof HubError && failure.isOffline;
+}
+
+/** The game slug's path field, or a {@link HubError} when the slug is unknown. */
+export interface GameFields {
+  /** The game's slug. */
+  readonly slug: string;
+}
+
+/** The connection, offline cache and sync machinery shared by every `Hub` method. */
+export class HubConnection {
+  /** This client's game slug (`null` when it could not be determined). */
+  readonly slug: string | null;
+  /** The absolute API base, e.g. `https://diffenderfer.games/_api`. */
+  readonly apiBase: string;
+  /** Typed REST calls to {@link apiBase}. */
+  protected readonly rest: RestClient;
+  /** This game's offline cache, queue and event buffer. */
+  protected readonly store: LocalStore;
+  private readonly offlineMode: NonNullable<HubOptions['offline']>;
+  private isReachable = true;
+  private isSyncing = false;
+  private lastPrefetchAt = 0;
+  private readonly statusListeners = new Set<(status: HubStatus) => void>();
+
+  /** A connection for `options` (slug and API base default to the page's). */
+  constructor(options: HubOptions = {}) {
+    this.slug = options.slug ?? detectSlug();
+    this.apiBase = options.apiBase === undefined ? detectApiBase() : absoluteApiBase(options.apiBase);
+    this.offlineMode = options.offline ?? 'auto';
+    this.rest = createRestClient({
+      apiBase: this.apiBase,
+      fetch: options.fetch ?? globalThis.fetch.bind(globalThis),
+      onReachable: () => {
+        this.setReachable(true);
+      },
+    });
+    this.store = new LocalStore(this.slug ?? 'app');
+    if (typeof navigator !== 'undefined' && 'onLine' in navigator) {
+      this.isReachable = navigator.onLine;
+    }
+    if (isBrowserPage()) {
+      window.addEventListener('online', () => {
+        this.setReachable(true);
+      });
+      window.addEventListener('offline', () => {
+        this.setReachable(false);
+      });
+    }
+  }
+
+  /** `true` when calls are being served from the offline cache rather than the hub. */
+  get isOffline(): boolean {
+    return this.offlineMode === 'always' || (this.offlineMode === 'auto' && !this.isReachable);
+  }
+
+  /** `true` while the hub is reachable. */
+  get isOnline(): boolean {
+    return this.isReachable;
+  }
+
+  /** Queued writes plus buffered analytics events waiting to sync. */
+  pending(): number {
+    return this.store.queueLength() + this.store.getEvents().length;
+  }
+
+  /** Subscribe to connection and sync status changes; returns the unsubscribe function. */
+  onStatus(listener: (status: HubStatus) => void): () => void {
+    this.statusListeners.add(listener);
+    return () => {
+      this.statusListeners.delete(listener);
+    };
+  }
+
+  /** Tell `onStatus` listeners and the page (`hub:status`) the current status. */
+  protected notifyStatus(): void {
+    const status: HubStatus = { online: this.isReachable, offline: this.isOffline, pending: this.pending() };
+    for (const listener of this.statusListeners) {
+      try {
+        listener(status);
+      } catch {
+        // A listener's failure must not stop the others.
+      }
+    }
+    emitWindowEvent('hub:status', status);
+  }
+
+  /** Record reachability; coming back online syncs the queue and re-warms the cache. */
+  protected setReachable(isReachableNow: boolean): void {
+    if (isReachableNow === this.isReachable) {
+      return;
+    }
+    this.isReachable = isReachableNow;
+    emitWindowEvent(isReachableNow ? 'hub:online' : 'hub:offline', { pending: this.pending() });
+    this.notifyStatus();
+    if (isReachableNow) {
+      void this.sync();
+      void this.prefetchAll().catch(() => undefined);
+    }
+  }
+
+  /** `{ slug }` for this game's endpoints; throws when the slug is unknown. */
+  protected gameFields(): GameFields {
+    if (this.slug === null) {
+      throw new HubError('Hub: could not determine the game slug.');
+    }
+    return { slug: this.slug };
+  }
+
+  /**
+   * Run the network call, falling back to the offline answer when the hub
+   * can't be reached (per the offline mode). Real API errors (with an HTTP
+   * status) always reach the caller.
+   */
+  protected async withFallback<Reply>(networkCall: () => Promise<Reply>, offlineAnswer: () => Reply): Promise<Reply> {
+    if (this.isOffline) {
+      return offlineAnswer();
+    }
+    try {
+      return await networkCall();
+    } catch (failure) {
+      if (!isTransportFailure(failure) || this.offlineMode === 'never') {
+        throw failure;
+      }
+      this.setReachable(false);
+      return offlineAnswer();
+    }
+  }
+
+  /** Send one queued write. */
+  private async sendOp(op: QueueOpInput): Promise<void> {
+    const game = this.gameFields();
+    switch (op.kind) {
+      case 'putSave':
+        await this.rest.call('writeSave', { ...game, slot: op.slot, data: op.data, label: op.label });
+        return;
+      case 'deleteSave':
+        await this.rest.call('deleteSave', { ...game, slot: op.slot });
+        return;
+      case 'setStat':
+        await this.rest.call('updateGameStat', { ...game, key: op.key, value: op.value, mode: 'set' });
+        return;
+      case 'maxStat':
+        await this.rest.call('updateGameStat', { ...game, key: op.key, value: op.value, mode: 'max' });
+        return;
+      case 'incrStat':
+        await this.rest.call('updateGameStat', { ...game, key: op.key, value: op.amount, mode: 'incr' });
+        return;
+      case 'submitScore':
+        await this.rest.call('submitScore', { ...game, key: op.key, score: op.score, ...op.opts });
+        return;
+      case 'setProfile':
+        await this.rest.call('setGameProfile', { ...game, ...op.patch });
+        return;
+    }
+  }
+
+  /**
+   * Apply a write to the offline cache at once, then send it now (online
+   * with an empty queue) or queue it behind the others. Resolves with the
+   * local answer; a real API error on the direct path reaches the caller and
+   * is not queued.
+   */
+  protected async mutateQueued<Reply>(input: QueueOpInput, localAnswer: () => Reply): Promise<Reply> {
+    const answer = localAnswer();
+    if (this.isOffline || this.store.queueLength() > 0) {
+      this.store.enqueue(input);
+      this.notifyStatus();
+      if (!this.isOffline) {
+        void this.sync();
+      }
+      return answer;
+    }
+    try {
+      await this.sendOp(input);
+      return answer;
+    } catch (failure) {
+      if (!isTransportFailure(failure)) {
+        throw failure;
+      }
+      this.setReachable(false);
+      this.store.enqueue(input);
+      this.notifyStatus();
+      return answer;
+    }
+  }
+
+  /**
+   * Replay the queue, then the buffered events, in order. Stops at the first
+   * transport failure (offline again: the rest stays queued); a write the hub
+   * refuses is dropped and reported as a conflict.
+   */
+  async sync(): Promise<SyncResult> {
+    if (this.isSyncing || this.isOffline || this.slug === null) {
+      return { flushed: 0, conflicts: [] };
+    }
+    this.isSyncing = true;
+    let flushed = 0;
+    const conflicts: SyncConflict[] = [];
+    try {
+      let queue = this.store.getQueue();
+      for (let op = queue[0]; op !== undefined; op = queue[0]) {
+        try {
+          await this.sendOp(op);
+          flushed += 1;
+        } catch (failure) {
+          if (isTransportFailure(failure)) {
+            break;
+          }
+          conflicts.push({ op, error: failure instanceof Error ? failure.message : String(failure) });
+        }
+        queue = queue.slice(1);
+        this.store.setQueue(queue);
+      }
+      await this.flushEvents();
+    } finally {
+      this.isSyncing = false;
+    }
+    emitWindowEvent('hub:sync', { pending: this.pending(), flushed, conflicts });
+    this.notifyStatus();
+    return { flushed, conflicts };
+  }
+
+  /** Send the buffered analytics events; a refused one is dropped (telemetry never blocks). */
+  private async flushEvents(): Promise<void> {
+    let events = this.store.getEvents();
+    for (let event = events[0]; event !== undefined; event = events[0]) {
+      try {
+        await this.rest.call('recordGameEvent', { ...this.gameFields(), type: event.type });
+      } catch (failure) {
+        if (isTransportFailure(failure)) {
+          return;
+        }
+      }
+      events = events.slice(1);
+      this.store.setEvents(events);
+    }
+  }
+
+  /**
+   * Warm the offline cache for every game the player has touched, in one
+   * request, so going offline later still shows complete progress.
+   * Throttled to once per 30 s unless `isForced`; `null` when offline or throttled.
+   */
+  async prefetchAll(isForced = false): Promise<SnapshotResponse | null> {
+    if (this.isOffline || (!isForced && Date.now() - this.lastPrefetchAt < PREFETCH_INTERVAL_MS)) {
+      return null;
+    }
+    let snapshot: SnapshotResponse;
+    try {
+      snapshot = await this.rest.call('getMyOfflineSnapshot');
+    } catch (failure) {
+      if (isTransportFailure(failure)) {
+        return null;
+      }
+      throw failure;
+    }
+    this.lastPrefetchAt = Date.now();
+    this.store.hydrate(snapshot);
+    emitWindowEvent('hub:prefetch', { games: Object.keys(snapshot.games).length });
+    return snapshot;
+  }
+}