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

package/src/core/errors.ts

@@ -1,147 +1,160 @@
-/**
- * The errors every hub call throws: {@link HubError} and its two kinds,
- * {@link OfflineError} and {@link ContentRejectedError}. The fields come from
- * the contract's error body (`{ error, code, reason, hint, retryAfterMs, until }`).
- */
-import type { ErrorCode, RejectReason } from '@diffenderfer-games/hub-contract';
-import { isRecord, optionalNumber, optionalString } from './storage/json-guards';
-
-/**
- * The code a client gives a call the hub does not have yet (a newer client on
- * an older hub, plan §4.3.3). Deploy the hub first, or use an older client.
- */
-export const UNSUPPORTED_BY_HUB = 'unsupported_by_hub';
-
-/** The code the social runtime gives a call it could not send (no connection). */
-export const OFFLINE_CODE = 'offline';
-
-/**
- * A machine-readable error code: one of the contract's public codes
- * (`content_rejected`, `rate_limited`, `suspended`, `claim_required`, ...),
- * {@link UNSUPPORTED_BY_HUB}, or a code a newer hub added.
- */
-export type HubErrorCode = ErrorCode | typeof UNSUPPORTED_BY_HUB | typeof OFFLINE_CODE | (string & Record<never, never>);
-
-/** The machine-readable extras the hub attaches to an error body. */
-export interface HubErrorDetails {
-  /** A stable error code, for code to branch on. */
-  readonly code?: HubErrorCode | undefined;
-  /** Why content was refused (`link`, `language`, `muted`, `chat_off`, ...). */
-  readonly reason?: RejectReason | (string & Record<never, never>) | undefined;
-  /** A kid-friendly sentence to show the player. */
-  readonly hint?: string | undefined;
-  /** How long to wait before retrying, in ms (rate limits, mutes). */
-  readonly retryAfterMs?: number | undefined;
-  /** When a suspension or mute ends (epoch ms). */
-  readonly until?: number | undefined;
-}
-
-/**
- * Thrown by every hub call that fails. `status` is the HTTP status when the
- * hub answered (401 = not signed in, 404 = unknown game or board, 413 = too
- * large), or `undefined` for a transport failure (offline, no host). Social
- * and multiplayer errors also carry {@link HubErrorDetails}.
- */
-export class HubError extends Error {
-  /** The HTTP status, or `undefined` when the hub could not be reached. */
-  readonly status: number | undefined;
-  /** A stable error code (see {@link HubErrorCode}). */
-  readonly code: HubErrorCode | undefined;
-  /** Why content was refused. */
-  readonly reason: string | undefined;
-  /** A kid-friendly sentence to show the player. */
-  readonly hint: string | undefined;
-  /** How long to wait before retrying, in ms. */
-  readonly retryAfterMs: number | undefined;
-  /** When a suspension or mute ends (epoch ms). */
-  readonly until: number | undefined;
-
-  /** An error with a player-safe `message`, the HTTP `status` (if any) and the body's extras. */
-  constructor(message: string, status?: number, details: HubErrorDetails = {}) {
-    super(message);
-    this.name = 'HubError';
-    this.status = status;
-    this.code = details.code;
-    this.reason = details.reason;
-    this.hint = details.hint;
-    this.retryAfterMs = details.retryAfterMs;
-    this.until = details.until;
-  }
-
-  /** `true` when the failure was a network or transport error, not an HTTP status. */
-  get isOffline(): boolean {
-    return this.status === undefined;
-  }
-}
-
-/** Thrown when an action that genuinely needs the hub is attempted offline. */
-export class OfflineError extends HubError {
-  /** An offline error; the default message is "This needs a connection.". */
-  constructor(message = 'This needs a connection.') {
-    super(message);
-    this.name = 'OfflineError';
-  }
-}
-
-/**
- * Text was refused by the safety filter (HTTP 422, or a socket ack with
- * `code: 'content_rejected'`). Keep the player's draft and show `hint`; when
- * `reason` is `muted` or `rate_limited`, `retryAfterMs` says how long to wait.
- */
-export class ContentRejectedError extends HubError {
-  /** A content reject with the hub's message, status and extras. */
-  constructor(message: string, status: number | undefined, details: HubErrorDetails) {
-    super(message, status, details);
-    this.name = 'ContentRejectedError';
-  }
-}
-
-/** An error body's fields, read without trusting its shape. */
-export interface ErrorBodyFields extends HubErrorDetails {
-  /** The player-safe sentence, when the body had one. */
-  readonly error?: string | undefined;
-}
-
-/** Read the fields this client understands from an error body (or any thrown object). */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: an error body from the hub or an error from another bundle, read field by field
-export function readErrorFields(body: unknown): ErrorBodyFields {
-  if (!isRecord(body)) {
-    return {};
-  }
-  return {
-    error: optionalString(body.error),
-    code: optionalString(body.code),
-    reason: optionalString(body.reason),
-    hint: optionalString(body.hint),
-    retryAfterMs: optionalNumber(body.retryAfterMs),
-    until: optionalNumber(body.until),
-  };
-}
-
-/** The right error class for a failure: a 422 or `content_rejected` is a {@link ContentRejectedError}. */
-export function errorFor(message: string, status: number | undefined, details: HubErrorDetails): HubError {
-  return status === 422 || details.code === 'content_rejected'
-    ? new ContentRejectedError(message, status, details)
-    : new HubError(message, status, details);
-}
-
-/**
- * Re-create an error from another bundle (the social runtime, or another
- * client copy on the page) as this bundle's class, so `instanceof` works in
- * games.
- */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: whatever another bundle threw
-export function toHubError(thrown: unknown): HubError {
-  if (thrown instanceof HubError) {
-    return thrown;
-  }
-  if (!isRecord(thrown)) {
-    return new HubError(String(thrown));
-  }
-  const fields = readErrorFields(thrown);
-  const message = optionalString(thrown.message) ?? 'Request failed';
-  if (fields.code === OFFLINE_CODE) {
-    return new OfflineError(message);
-  }
-  return errorFor(message, optionalNumber(thrown.status), fields);
-}
+/**
+ * The errors every hub call throws: {@link HubError} and its two kinds,
+ * {@link OfflineError} and {@link ContentRejectedError}. The fields come from
+ * the contract's error body (`{ error, code, reason, hint, retryAfterMs, until }`).
+ */
+import type { ErrorCode, RejectReason } from '@diffenderfer-games/hub-contract';
+import { isRecord, optionalNumber, optionalString } from './storage/json-guards';
+
+/**
+ * The code a client gives a call the hub does not have yet (a newer client on
+ * an older hub, plan §4.3.3). Deploy the hub first, or use an older client.
+ */
+export const UNSUPPORTED_BY_HUB = 'unsupported_by_hub';
+
+/** The code the social runtime gives a call it could not send (no connection). */
+export const OFFLINE_CODE = 'offline';
+
+/**
+ * The code `getSave` rejects with when the hub can't be reached and this
+ * device has no copy of the slot it can trust (a fresh device or cleared
+ * browser): the slot may well hold a save, so it is not reported empty.
+ */
+export const SAVE_UNKNOWN_CODE = 'save_unknown';
+
+/**
+ * A machine-readable error code: one of the contract's public codes
+ * (`content_rejected`, `rate_limited`, `suspended`, `claim_required`, ...),
+ * {@link UNSUPPORTED_BY_HUB}, or a code a newer hub added.
+ */
+export type HubErrorCode = ErrorCode | typeof UNSUPPORTED_BY_HUB | typeof OFFLINE_CODE | typeof SAVE_UNKNOWN_CODE | (string & Record<never, never>);
+
+/** The machine-readable extras the hub attaches to an error body. */
+export interface HubErrorDetails {
+  /** A stable error code, for code to branch on. */
+  readonly code?: HubErrorCode | undefined;
+  /** Why content was refused (`link`, `language`, `muted`, `chat_off`, ...). */
+  readonly reason?: RejectReason | (string & Record<never, never>) | undefined;
+  /** A kid-friendly sentence to show the player. */
+  readonly hint?: string | undefined;
+  /** How long to wait before retrying, in ms (rate limits, mutes). */
+  readonly retryAfterMs?: number | undefined;
+  /** When a suspension or mute ends (epoch ms). */
+  readonly until?: number | undefined;
+  /** An online game's rules refused a move (`illegal`): the rules' own short code. */
+  readonly rule?: string | undefined;
+}
+
+/**
+ * Thrown by every hub call that fails. `status` is the HTTP status when the
+ * hub answered (401 = not signed in, 404 = unknown game or board, 413 = too
+ * large), or `undefined` for a transport failure (offline, no host). Social
+ * and multiplayer errors also carry {@link HubErrorDetails}.
+ */
+export class HubError extends Error {
+  /** The HTTP status, or `undefined` when the hub could not be reached. */
+  readonly status: number | undefined;
+  /** A stable error code (see {@link HubErrorCode}). */
+  readonly code: HubErrorCode | undefined;
+  /** Why content was refused. */
+  readonly reason: string | undefined;
+  /** A kid-friendly sentence to show the player. */
+  readonly hint: string | undefined;
+  /** How long to wait before retrying, in ms. */
+  readonly retryAfterMs: number | undefined;
+  /** When a suspension or mute ends (epoch ms). */
+  readonly until: number | undefined;
+  /** An online game's rules refused a move (`code` is `illegal`): the rules' own short code, such as `cell_taken`. */
+  readonly rule: string | undefined;
+
+  /** An error with a player-safe `message`, the HTTP `status` (if any) and the body's extras. */
+  constructor(message: string, status?: number, details: HubErrorDetails = {}) {
+    super(message);
+    this.name = 'HubError';
+    this.status = status;
+    this.code = details.code;
+    this.reason = details.reason;
+    this.hint = details.hint;
+    this.retryAfterMs = details.retryAfterMs;
+    this.until = details.until;
+    this.rule = details.rule;
+  }
+
+  /** `true` when the failure was a network or transport error, not an HTTP status. */
+  get isOffline(): boolean {
+    return this.status === undefined;
+  }
+}
+
+/** Thrown when an action that genuinely needs the hub is attempted offline. */
+export class OfflineError extends HubError {
+  /** An offline error; the default message is "This needs a connection.". */
+  constructor(message = 'This needs a connection.') {
+    super(message);
+    this.name = 'OfflineError';
+  }
+}
+
+/**
+ * Text was refused by the safety filter (HTTP 422, or a socket ack with
+ * `code: 'content_rejected'`). Keep the player's draft and show `hint`; when
+ * `reason` is `muted` or `rate_limited`, `retryAfterMs` says how long to wait.
+ */
+export class ContentRejectedError extends HubError {
+  /** A content reject with the hub's message, status and extras. */
+  constructor(message: string, status: number | undefined, details: HubErrorDetails) {
+    super(message, status, details);
+    this.name = 'ContentRejectedError';
+  }
+}
+
+/** An error body's fields, read without trusting its shape. */
+export interface ErrorBodyFields extends HubErrorDetails {
+  /** The player-safe sentence, when the body had one. */
+  readonly error?: string | undefined;
+}
+
+/** Read the fields this client understands from an error body (or any thrown object). */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: an error body from the hub or an error from another bundle, read field by field
+export function readErrorFields(body: unknown): ErrorBodyFields {
+  if (!isRecord(body)) {
+    return {};
+  }
+  return {
+    error: optionalString(body.error),
+    code: optionalString(body.code),
+    reason: optionalString(body.reason),
+    hint: optionalString(body.hint),
+    retryAfterMs: optionalNumber(body.retryAfterMs),
+    until: optionalNumber(body.until),
+    rule: optionalString(body.rule),
+  };
+}
+
+/** The right error class for a failure: a 422 or `content_rejected` is a {@link ContentRejectedError}. */
+export function errorFor(message: string, status: number | undefined, details: HubErrorDetails): HubError {
+  return (status === 422 && details.code !== 'illegal') || details.code === 'content_rejected'
+    ? new ContentRejectedError(message, status, details)
+    : new HubError(message, status, details);
+}
+
+/**
+ * Re-create an error from another bundle (the social runtime, or another
+ * client copy on the page) as this bundle's class, so `instanceof` works in
+ * games.
+ */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: whatever another bundle threw
+export function toHubError(thrown: unknown): HubError {
+  if (thrown instanceof HubError) {
+    return thrown;
+  }
+  if (!isRecord(thrown)) {
+    return new HubError(String(thrown));
+  }
+  const fields = readErrorFields(thrown);
+  const message = optionalString(thrown.message) ?? 'Request failed';
+  if (fields.code === OFFLINE_CODE) {
+    return new OfflineError(message);
+  }
+  return errorFor(message, optionalNumber(thrown.status), fields);
+}

package/src/core/game-data.ts

@@ -1,38 +1,40 @@
-/**
- * A game's own JSON (save payloads, profile data, score metadata) is typed by
- * the game: `hub.putSave<MySave>(...)`, `hub.getSave<MySave>(...)`. The hub
- * stores it as opaque JSON, so neither the contract nor this client can check
- * it against `MySave`: the game vouches for its own type, exactly as with the
- * v1 client. These two functions are the only places that hand-over happens.
- */
-import type { Json } from '@diffenderfer-games/hub-contract';
-
-/** Anything a game may store as JSON: an object (interfaces included), an array, text, a number, a boolean or `null`. */
-export type GamePayload = object | string | number | boolean | null;
-
-/** Always true: a game's payload is sent as JSON (`JSON.stringify` drops what JSON can't hold). */
-function isSentAsJson(_payload: GamePayload): _payload is GamePayload & Json {
-  return true;
-}
-
-/** Always true: JSON the game stored is read back as the game's type. */
-function isGameOwnData<TData>(_stored: Json): _stored is Json & TData {
-  return true;
-}
-
-/** A game's payload as the JSON the hub stores. */
-export function toStoredJson(payload: GamePayload): Json {
-  if (isSentAsJson(payload)) {
-    return payload;
-  }
-  throw new TypeError('unreachable: every payload is sent as JSON');
-}
-
-/** JSON the game stored, typed as the game's own type. */
-// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters -- the caller names the game's own type; the game vouches for it (see above)
-export function toGameData<TData>(stored: Json): TData {
-  if (isGameOwnData<TData>(stored)) {
-    return stored;
-  }
-  throw new TypeError('unreachable: stored game data is the game\'s own');
-}
+/**
+ * A game's own JSON (save payloads, profile data, score metadata) is typed by
+ * the game: `hub.putSave<MySave>(...)`, `hub.getSave<MySave>(...)`. The hub
+ * stores it as opaque JSON, so neither the contract nor this client can check
+ * it against `MySave`: the game vouches for its own type, exactly as with the
+ * v1 client. These two functions are the only places that hand-over happens.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import { isJson, parseJsonText } from './storage/json-guards';
+
+/** Anything a game may store as JSON: an object (interfaces included), an array, text, a number, a boolean or `null`. */
+export type GamePayload = object | string | number | boolean | null;
+
+/** Always true: JSON the game stored is read back as the game's type. */
+function isGameOwnData<TData>(_stored: Json): _stored is Json & TData {
+  return true;
+}
+
+/**
+ * A game's payload as the JSON the hub stores: a copy of exactly what
+ * `JSON.stringify` sends, so an optional field left `undefined` is simply
+ * absent (as on the wire) and the outbox's payload checks accept it, and a
+ * later change to the game's object can't alter a queued write.
+ */
+export function toStoredJson(payload: GamePayload): Json {
+  const stored = parseJsonText(JSON.stringify(payload));
+  if (isJson(stored)) {
+    return stored;
+  }
+  throw new TypeError('This value cannot be stored as JSON.');
+}
+
+/** JSON the game stored, typed as the game's own type. */
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters -- the caller names the game's own type; the game vouches for it (see above)
+export function toGameData<TData>(stored: Json): TData {
+  if (isGameOwnData<TData>(stored)) {
+    return stored;
+  }
+  throw new TypeError('unreachable: stored game data is the game\'s own');
+}