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

package/src/doctor/hub-version-fetch.ts

@@ -0,0 +1,43 @@
+/**
+ * Reading the hub's `GET /_api/version` for `hub-doctor`, with a timeout so a
+ * hung or unreachable hub fails a game's CI quickly instead of stalling it.
+ */
+import { HubVersion } from '@diffenderfer-games/hub-contract';
+
+/** How long the doctor waits for the hub by default, ms. */
+export const DEFAULT_HUB_TIMEOUT_MS = 10_000;
+
+/** The hub could not be asked: down, slow, or answering with an error. */
+export interface HubUnreachable {
+  /** The URL that was asked. */
+  readonly unreachableUrl: string;
+  /** Why, for the message (`timed out after 10000 ms`, `HTTP 502`, a network error). */
+  readonly reason: string;
+}
+
+/** Whether a version lookup failed. */
+export function isHubUnreachable(lookup: HubVersion | null | HubUnreachable): lookup is HubUnreachable {
+  return lookup !== null && 'unreachableUrl' in lookup;
+}
+
+/**
+ * The hub's version: `null` for a hub from before versioning (404), a
+ * {@link HubUnreachable} when it can't be read within `timeoutMs`.
+ */
+export async function fetchHubVersion(hubUrl: string, timeoutMs: number = DEFAULT_HUB_TIMEOUT_MS): Promise<HubVersion | null | HubUnreachable> {
+  const url = new URL('/_api/version', hubUrl).toString();
+  try {
+    const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+    if (response.status === 404) {
+      return null;
+    }
+    if (!response.ok) {
+      return { unreachableUrl: url, reason: `HTTP ${String(response.status)}` };
+    }
+    return HubVersion.parse(await response.json());
+  } catch (failure) {
+    const isTimeout = failure instanceof Error && (failure.name === 'TimeoutError' || failure.name === 'AbortError');
+    const reason = isTimeout ? `timed out after ${String(timeoutMs)} ms` : failure instanceof Error ? failure.message : String(failure);
+    return { unreachableUrl: url, reason };
+  }
+}

package/src/doctor/tsconfig.json

@@ -1,12 +1,12 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "types": [
-      "node"
-    ]
-  },
-  "include": [
-    "."
-  ],
-  "exclude": []
-}
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "types": [
+      "node"
+    ]
+  },
+  "include": [
+    "."
+  ],
+  "exclude": []
+}

package/src/globals.ts

@@ -1,110 +1,115 @@
-/**
- * Page-wide singletons across client versions (plan §4.4). One page often
- * runs two client builds: the game's bundled copy and the host's injected
- * `/_hub/hub.js`. The input system, daily challenges and the realtime API
- * must exist once per page, so each is registered here with the version that
- * created it and a small `api` number that changes only when the
- * cross-bundle shape does.
- *
- * - Same `api`: the first creator wins and everyone shares it.
- * - Different `api`: the caller decides who owns the page (see
- *   {@link claimSingleton}'s `onMismatch`); the mismatch is logged once with the fix.
- * - The v1 names (`window.__HUB_INPUT__`, `__HUB_DAILY__`, `__HUB_RT__`) stay as
- *   aliases while vendored v1 copies are still around.
- */
-
-/** A page-wide singleton's name. */
-export type SingletonName = 'input' | 'daily' | 'rt';
-
-/** One registered singleton. */
-export interface SingletonRecord {
-  /** The client version that created it. */
-  readonly version: string;
-  /** Its cross-bundle shape number. */
-  readonly api: number;
-  /** The instance itself; another bundle's object, so callers check it before use. */
-  // eslint-disable-next-line no-restricted-syntax -- trust boundary: the instance may come from another bundle on the page
-  readonly instance: unknown;
-}
-
-/** The registry on `window.__DG__`. */
-export type DgGlobals = { [K in SingletonName]?: SingletonRecord };
-
-/** The v1 window names, kept as aliases. */
-export const LEGACY_GLOBAL_NAMES = { input: '__HUB_INPUT__', daily: '__HUB_DAILY__', rt: '__HUB_RT__' } as const satisfies Record<SingletonName, string>;
-
-declare global {
-  interface Window {
-    __DG__?: DgGlobals;
-    // eslint-disable-next-line no-restricted-syntax -- trust boundary: set by any bundle on the page, including v1 copies
-    __HUB_INPUT__?: unknown;
-    // eslint-disable-next-line no-restricted-syntax -- trust boundary: set by any bundle on the page, including v1 copies
-    __HUB_DAILY__?: unknown;
-    // eslint-disable-next-line no-restricted-syntax -- trust boundary: set by any bundle on the page, including v1 copies
-    __HUB_RT__?: unknown;
-  }
-}
-
-/** How to claim a singleton. */
-export interface SingletonClaim<T> {
-  readonly name: SingletonName;
-  /** This bundle's client version. */
-  readonly version: string;
-  /** This bundle's shape number for the singleton. */
-  readonly api: number;
-  /** Make the instance when nobody has yet. */
-  readonly create: () => T;
-  /** Whether a registered instance is usable as `T` (it may come from another bundle). */
-  // eslint-disable-next-line no-restricted-syntax -- trust boundary: checks another bundle's object
-  readonly isInstance: (candidate: unknown) => candidate is T;
-  /**
-   * The registered one has a different `api`: return `true` to replace it
-   * with this bundle's instance, `false` to keep it (then `create` makes a
-   * private instance for this bundle only). Default: keep it.
-   */
-  readonly onMismatch?: (registered: SingletonRecord) => boolean;
-}
-
-const warnedMismatches = new Set<SingletonName>();
-
-/** The page registry, created on first use (`undefined` outside a browser). */
-function registryOf(page: Window | undefined): DgGlobals | undefined {
-  if (page === undefined) {
-    return undefined;
-  }
-  page.__DG__ ??= {};
-  return page.__DG__;
-}
-
-/** Register (or join) a page-wide singleton and return the instance this bundle should use. */
-export function claimSingleton<T>(claim: SingletonClaim<T>): T {
-  const page = typeof window === 'undefined' ? undefined : window;
-  const registry = registryOf(page);
-  if (page === undefined || registry === undefined) {
-    return claim.create();
-  }
-  const registered = registry[claim.name];
-  if (registered !== undefined && claim.isInstance(registered.instance)) {
-    if (registered.api === claim.api) {
-      return registered.instance;
-    }
-    if (!warnedMismatches.has(claim.name)) {
-      warnedMismatches.add(claim.name);
-      // eslint-disable-next-line no-console -- the plan's one-time warning to the game developer, with the fix
-      console.warn(`[hub] two clients on this page disagree on "${claim.name}" (v${registered.version} api ${String(registered.api)}, v${claim.version} api ${String(claim.api)}). Fix: npm update @diffenderfer-games/hub`);
-    }
-    if (claim.onMismatch?.(registered) !== true) {
-      return claim.create();
-    }
-  } else {
-    const legacy = page[LEGACY_GLOBAL_NAMES[claim.name]];
-    if (registered === undefined && claim.isInstance(legacy)) {
-      // A v1 vendored copy got there first: share it, as v1 bundles did.
-      return legacy;
-    }
-  }
-  const instance = claim.create();
-  registry[claim.name] = { version: claim.version, api: claim.api, instance };
-  page[LEGACY_GLOBAL_NAMES[claim.name]] = instance;
-  return instance;
-}
+/**
+ * Page-wide singletons across client versions (plan §4.4). One page often
+ * runs two client builds: the game's bundled copy and the host's injected
+ * `/_hub/hub.js`. The input system, daily challenges and the realtime API
+ * must exist once per page, so each is registered here with the version that
+ * created it and a small `api` number that changes only when the
+ * cross-bundle shape does.
+ *
+ * - Same `api`: the first creator wins and everyone shares it.
+ * - Different `api`: the caller decides who owns the page (see
+ *   {@link claimSingleton}'s `onMismatch`); the mismatch is logged once with the fix.
+ * - The v1 names (`window.__HUB_INPUT__`, `__HUB_DAILY__`, `__HUB_RT__`) stay as
+ *   aliases while vendored v1 copies are still around.
+ */
+
+/** A page-wide singleton's name. */
+export type SingletonName = 'input' | 'daily' | 'rt';
+
+/** One registered singleton. */
+export interface SingletonRecord {
+  /** The client version that created it. */
+  readonly version: string;
+  /** Its cross-bundle shape number. */
+  readonly api: number;
+  /** The instance itself; another bundle's object, so callers check it before use. */
+  // eslint-disable-next-line no-restricted-syntax -- trust boundary: the instance may come from another bundle on the page
+  readonly instance: unknown;
+}
+
+/** The registry on `window.__DG__`. */
+export type DgGlobals = { [K in SingletonName]?: SingletonRecord };
+
+/** The version recorded for a singleton adopted from a v1 (vendored) client, which predates the registry. */
+export const V1_CLIENT_VERSION = 'v1';
+
+/** The v1 window names, kept as aliases. */
+export const LEGACY_GLOBAL_NAMES = { input: '__HUB_INPUT__', daily: '__HUB_DAILY__', rt: '__HUB_RT__' } as const satisfies Record<SingletonName, string>;
+
+declare global {
+  interface Window {
+    __DG__?: DgGlobals;
+    // eslint-disable-next-line no-restricted-syntax -- trust boundary: set by any bundle on the page, including v1 copies
+    __HUB_INPUT__?: unknown;
+    // eslint-disable-next-line no-restricted-syntax -- trust boundary: set by any bundle on the page, including v1 copies
+    __HUB_DAILY__?: unknown;
+    // eslint-disable-next-line no-restricted-syntax -- trust boundary: set by any bundle on the page, including v1 copies
+    __HUB_RT__?: unknown;
+  }
+}
+
+/** How to claim a singleton. */
+export interface SingletonClaim<T> {
+  readonly name: SingletonName;
+  /** This bundle's client version. */
+  readonly version: string;
+  /** This bundle's shape number for the singleton. */
+  readonly api: number;
+  /** Make the instance when nobody has yet. */
+  readonly create: () => T;
+  /** Whether a registered instance is usable as `T` (it may come from another bundle). */
+  // eslint-disable-next-line no-restricted-syntax -- trust boundary: checks another bundle's object
+  readonly isInstance: (candidate: unknown) => candidate is T;
+  /**
+   * The registered one has a different `api`: return `true` to replace it
+   * with this bundle's instance, `false` to keep it (then `create` makes a
+   * private instance for this bundle only). Default: keep it.
+   */
+  readonly onMismatch?: (registered: SingletonRecord) => boolean;
+}
+
+const warnedMismatches = new Set<SingletonName>();
+
+/** The page registry, created on first use (`undefined` outside a browser). */
+function registryOf(page: Window | undefined): DgGlobals | undefined {
+  if (page === undefined) {
+    return undefined;
+  }
+  page.__DG__ ??= {};
+  return page.__DG__;
+}
+
+/** Register (or join) a page-wide singleton and return the instance this bundle should use. */
+export function claimSingleton<T>(claim: SingletonClaim<T>): T {
+  const page = typeof window === 'undefined' ? undefined : window;
+  const registry = registryOf(page);
+  if (page === undefined || registry === undefined) {
+    return claim.create();
+  }
+  const registered = registry[claim.name];
+  if (registered !== undefined && claim.isInstance(registered.instance)) {
+    if (registered.api === claim.api) {
+      return registered.instance;
+    }
+    if (!warnedMismatches.has(claim.name)) {
+      warnedMismatches.add(claim.name);
+      // eslint-disable-next-line no-console -- the plan's one-time warning to the game developer, with the fix
+      console.warn(`[hub] two clients on this page disagree on "${claim.name}" (v${registered.version} api ${String(registered.api)}, v${claim.version} api ${String(claim.api)}). Fix: npm update @diffenderfer-games/hub`);
+    }
+    if (claim.onMismatch?.(registered) !== true) {
+      return claim.create();
+    }
+  } else {
+    const legacy = page[LEGACY_GLOBAL_NAMES[claim.name]];
+    if (registered === undefined && claim.isInstance(legacy)) {
+      // A v1 vendored copy got there first: share it, as v1 bundles did, and
+      // record it so later bundles (and diagnostics) see which client owns it.
+      registry[claim.name] = { version: V1_CLIENT_VERSION, api: claim.api, instance: legacy };
+      return legacy;
+    }
+  }
+  const instance = claim.create();
+  registry[claim.name] = { version: claim.version, api: claim.api, instance };
+  page[LEGACY_GLOBAL_NAMES[claim.name]] = instance;
+  return instance;
+}

package/src/index.ts

@@ -1,50 +1,55 @@
-/**
- * `@diffenderfer-games/hub`: the hub client for games on diffenderfer.games.
- *
- * ```ts
- * import { hub } from '@diffenderfer-games/hub';
- *
- * const { user } = await hub.me();
- * await hub.putSave('auto', { level: 7, gold: 120 });
- * await hub.submitScore('highscore', 9001, { title: 'High Score' });
- * ```
- *
- * In a hosted game the slug and API base are detected from the page; use
- * {@link createHub} for others. Every call rejects with a {@link HubError}
- * when it fails, except the fire-and-forget analytics (`recordPlay`,
- * `heartbeat`, `event`). When the hub can't be reached, reads come from an
- * offline cache and writes are queued until it is back.
- *
- * The page-wide namespaces hang off `hub` as lazy getters (`hub.input`,
- * `hub.daily`, `hub.social`, `hub.mp`, `hub.rooms`, `hub.race`), and each has
- * its own entry (`@diffenderfer-games/hub/input`, ...) for games that want
- * only that part.
- *
- * @packageDocumentation
- */
-export { createHub, Hub, hub } from './core/hub';
-export {
-  ContentRejectedError,
-  HubError,
-  OfflineError,
-  UNSUPPORTED_BY_HUB,
-  type HubErrorCode,
-  type HubErrorDetails,
-} from './core/errors';
-export type { SyncConflict, SyncResult } from './core/connection';
-export type { AuthResponse, ProfileUpdate, StatResult } from './core/hub-progress';
-export type { GrantBundle, TradeBundle, TradeId, TradeListOptions, TradeNoteOptions } from './core/hub-economy';
-export type { HubMenuControl } from './core/menu-control';
-export type { QueueOp, QueueOpInput, QueuedScoreOptions, ProfilePatch } from './core/offline/queue';
-export type { BufferedEvent } from './core/offline/events';
-export type { EndpointFields, EndpointName, EndpointReply } from './core/rest/endpoint-types';
-export { CLIENT_VERSION_HEADER } from './core/rest/rest-client';
-export type { ClientSupport } from './core/version/hub-version';
-export { HUB_CLIENT_VERSION } from './core/version/client-version.gen';
-export type * from './core/types';
-export * from './daily';
-export * from './input';
-export type * from './social';
-export type * from './mp';
-export type * from './race';
-export type * from './rooms';
+/**
+ * `@diffenderfer-games/hub`: the hub client for games on diffenderfer.games.
+ *
+ * ```ts
+ * import { hub } from '@diffenderfer-games/hub';
+ *
+ * const { user } = await hub.me();
+ * await hub.putSave('auto', { level: 7, gold: 120 });
+ * await hub.submitScore('highscore', 9001, { title: 'High Score' });
+ * ```
+ *
+ * In a hosted game the slug and API base are detected from the page; use
+ * {@link createHub} for others. Every call rejects with a {@link HubError}
+ * when it fails, except the fire-and-forget analytics (`recordPlay`,
+ * `heartbeat`, `event`). When the hub can't be reached, reads come from an
+ * offline cache and writes are queued in an outbox until it is back; games
+ * queue their own operations with `hub.offline` (docs: "Offline and replay").
+ *
+ * The page-wide namespaces hang off `hub` as lazy getters (`hub.input`,
+ * `hub.daily`, `hub.social`, `hub.mp`, `hub.rooms`, `hub.race`), and each has
+ * its own entry (`@diffenderfer-games/hub/input`, ...) for games that want
+ * only that part.
+ *
+ * @packageDocumentation
+ */
+export { createHub, Hub, hub } from './core/hub';
+export {
+  ContentRejectedError,
+  HubError,
+  OfflineError,
+  UNSUPPORTED_BY_HUB,
+  type HubErrorCode,
+  type HubErrorDetails,
+} from './core/errors';
+export type { SyncConflict, SyncResult } from './core/connection';
+export type { AuthResponse, ProfileUpdate, StatResult } from './core/hub-progress';
+export type { GrantBundle, TradeBundle, TradeId, TradeListOptions, TradeNoteOptions } from './core/hub-economy';
+export type { HubMenuControl } from './core/menu-control';
+export type { QueueOp, QueueOpInput, QueuedScoreOptions, ProfilePatch } from './core/offline/queue';
+export { OfflineApi } from './core/offline/offline-api';
+export { OUTBOX_FULL_CODE, type OfflineEventDetails, type OfflineEventName, type OfflineListener, type OfflineOp } from './core/offline/outbox';
+export type { OfflineHandler, OfflineKindDefinition, ReplayContext } from './core/offline/outbox-kinds';
+export { OUTBOX_MAX_CHARS, OUTBOX_MAX_ENTRIES } from './core/offline/outbox-store';
+export type { BufferedEvent } from './core/offline/events';
+export type { EndpointFields, EndpointName, EndpointReply } from './core/rest/endpoint-types';
+export { CLIENT_VERSION_HEADER } from './core/rest/rest-client';
+export type { ClientSupport } from './core/version/hub-version';
+export { HUB_CLIENT_VERSION } from './core/version/client-version.gen';
+export type * from './core/types';
+export * from './daily';
+export * from './input';
+export type * from './social';
+export type * from './mp';
+export type * from './race';
+export type * from './rooms';