@crowdedkingdoms/crowdyjs 18.8.0-dev.1 → 18.9.0-dev.1

package/MIGRATION.md

@@ -120,6 +120,80 @@ super-admin's session). There is no SDK replacement.
 `dev`'s SDL after #417 merged (`npm run schema:sync:paths -- --schema <that schema.gql>`, then
 `npm run codegen`).
 
+## 18.9.0: the input log says what it lost, and when to retry
+
+Additive. **Needs the Game API release after v2.40.2** (`InputLogSession.missingRecords` is
+selected on every sessions read; an older Game API refuses the selection). Promote the Game API
+first on each tier.
+
+- **`missingRecords`** on every recorded session: inputs the replication server accepted that
+  never reached the log (an overloaded server or a broker outage). 0 when the recording is
+  complete as far as it is known: a lost end of the recording cannot be counted (its session
+  closes as `unrecorded` instead). Null on one recorded before the count existed. Recording is
+  best-effort, and this is how a gap shows.
+- **Three end reasons** in `endReason`: `logging_off` (replay logging was turned off during the
+  session), `shutdown` (the replication server recording it stopped, a deploy; the client
+  reconnects to another server, where the same session continues and its end is replaced), and
+  `paused` (recording paused because the app's logging setting could not be confirmed; the
+  client sees nothing, and a later record reopens the session). `unrecorded` (no end was
+  recorded; closed an hour after its last input) comes with the same Game API release.
+- **Reads say when to retry.** `messages` throws `INPUT_LOG_TEMPORARILY_UNAVAILABLE` when the log
+  cannot be read right now (it used to answer an empty page, or `INPUT_LOG_UNAVAILABLE`). A server
+  runs one read per user, and two per app and per org, at a time: a read over that share waits
+  for an earlier one within its own few-second deadline, and `INPUT_LOG_RATE_LIMITED` means the
+  wait ran out. Both carry `extensions.retryable`: retry with the same cursor after a short
+  back-off, a bounded number of times. A read whose request is closed stops and frees its
+  share: pass `signal` in the options of `sessions` / `messages` (new) and abort a read nobody
+  will see, say when the user opens another session. An operation may select
+  `inputLogMessages` only once.
+- **A `signal` keeps the request timeout.** A `signal` passed to a request
+  (`client.gql.request(document, variables, { signal })`, and the input log's new option) used
+  to replace the client's timeout, so a request with one could wait for ever, and an abort
+  rejected as `CrowdyTimeoutError`. It now runs alongside the timeout, and aborting rejects with
+  the signal's reason.
+- **A cursor belongs to its session.** `BAD_USER_INPUT` for a malformed cursor or one from another
+  session (until this Game API, a cursor from another session was not detected and the read just
+  returned fewer inputs).
+- **`apps.update(appId, { replayLoggingEnabled: true })`** needs a spendable balance that covers
+  the projected cost of keeping one retention period of the app's recent traffic; the
+  `INPUT_LOG_FUNDS_NEEDED` refusal's `extensions.requiredMicrousd` and `spendableMicrousd` say how
+  much. Recordings already kept go on billing after logging is turned off, until they age out.
+
+Paging a session, the loop that does not stop early:
+
+```ts
+import { CrowdyGraphQLError, decodeBase64 } from '@crowdedkingdoms/crowdyjs';
+
+const RETRY = new Set(['INPUT_LOG_TEMPORARILY_UNAVAILABLE', 'INPUT_LOG_RATE_LIMITED']);
+const MAX_RETRIES = 8; // in a row, about half a minute of back-off; then give up
+const reading = new AbortController(); // abort() when the user moves on
+let after: string | undefined;
+for (let backoffMs = 250, retries = 0; ; ) {
+  let page;
+  try {
+    page = await game.inputLog.messages(appId, gameTokenId, {
+      first: 200,
+      after,
+      signal: reading.signal,
+    });
+  } catch (err) {
+    if (!(err instanceof CrowdyGraphQLError) || !RETRY.has(String(err.code))) throw err;
+    if (++retries > MAX_RETRIES) throw err;
+    await new Promise((r) => setTimeout(r, backoffMs));
+    backoffMs = Math.min(backoffMs * 2, 5_000);
+    continue; // the same cursor: nothing is skipped
+  }
+  backoffMs = 250;
+  retries = 0;
+  for (const { node } of page.edges) handle(node.messageType, decodeBase64(node.body));
+  if (!page.pageInfo.hasNextPage) break;
+  after = page.pageInfo.endCursor ?? after;
+}
+```
+
+Nothing in the SDK changed shape; the regenerated types add `missingRecords` and the refreshed
+descriptions.
+
 ## 18.8.0: builds report the SDK version they compiled against
 
 Additive, with one new floor: **the build documents select `ExecBuild.sdkVersion`, so 18.8.0
@@ -230,16 +304,21 @@ Additive. An app with replay logging on has its client inputs recorded, and `cli
 reads them back on the app-scoped client:
 
 ```ts
-const { edges, pageInfo } = await game.inputLog.sessions(appId, { first: 20 });
+const { edges } = await game.inputLog.sessions(appId, { first: 20 });
+const gameTokenId = edges[0].node.gameTokenId;
 let after: string | undefined;
-do {
-  const page = await game.inputLog.messages(appId, edges[0].node.gameTokenId, { first: 200, after });
+for (;;) {
+  const page = await game.inputLog.messages(appId, gameTokenId, { first: 200, after });
   for (const { node } of page.edges) handle(node.messageType, decodeBase64(node.body));
-  after = page.pageInfo.endCursor ?? undefined;
   if (!page.pageInfo.hasNextPage) break;
-} while (after);
+  after = page.pageInfo.endCursor ?? after;
+}
 ```
 
+(Corrected in 18.9.0: the first version of this example stopped when `endCursor` came back null
+even with `hasNextPage` true, which a v2.39 Game API answers when a read cannot start in time.
+18.9.0's section has the loop with retries.)
+
 A player reads only the sessions and inputs they sent; a holder of `manage_apps` on the app reads
 every session. Keep paging while `hasNextPage` is true: a messages page can be short, or empty,
 when it stopped at the server's time or scan limit. Inputs are kept for the published retention,
@@ -250,8 +329,8 @@ with the same cursor, when the log cannot be read right now.
 `App.replayLoggingEnabled` is selected on every app read and set with `apps.update(appId,
 { replayLoggingEnabled: true })` (`manage_apps`). Turning it on is refused with
 `INPUT_LOG_FUNDS_NEEDED` unless the org's wallet has a spendable balance or the org is exempt from
-billing, because stored input logs are billed (crowdedkingdoms.com/pricing). It needs ck-api with
-the input log (`inputLogSessions`, `inputLogMessages`).
+billing, because stored input logs are billed (crowdedkingdoms.com/pricing). It needs ck-api v2.39.0 or later: every app read selects
+`replayLoggingEnabled`, which an older Game API refuses.
 
 ## 18.5.0: channel messages limited by distance
 

package/README.md

@@ -29,6 +29,16 @@ This README is the `dev` branch's: it documents the release on the `dev` dist-ta
 (`npm view @crowdedkingdoms/crowdyjs dist-tags`), and its links go to the dev docs site. A
 plain `npm install` resolves `latest`, the production release, which has no `client.exec`.
 
+**Server compatibility.** A release selects fields the Game API it was built against has,
+so it needs that Game API or newer; promote the Game API before the SDK on each tier.
+
+| CrowdyJS | Needs the Game API (ck-api) |
+| --- | --- |
+| 18.9.0 | the release after v2.40.2 (`InputLogSession.missingRecords`) |
+| 18.8.0 | v2.40.2 or later (`ExecBuild.sdkVersion`) |
+| 18.7.0 | v2.40.0 or later (`runtimeGate`, channel audio) |
+| 18.6.0 | v2.39.0 or later (every app read selects `replayLoggingEnabled`) |
+
 CrowdyJS targets browsers by default and uses native `fetch`, `WebSocket`,
 `crypto`, `btoa`, and `atob`. Node tools can still use the SDK, but must
 provide browser-compatible globals when opening realtime connections (e.g.

package/dist/client.d.ts

@@ -147,7 +147,8 @@ export declare class GraphQLClient {
      * @param variables - Variables for the operation; omit for operations that
      *   take none.
      * @param options - Optional `signal` to abort the request from your own
-     *   `AbortController` (in addition to the built-in timeout).
+     *   `AbortController` (in addition to the built-in timeout). Aborting it rejects
+     *   with the signal's reason, not a {@link CrowdyTimeoutError}.
      * @returns The operation's `data` payload.
      * @throws {CrowdyHttpError} on a non-2xx HTTP status.
      * @throws {CrowdyGraphQLError} when the response carries a non-empty

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAahD,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAG1D;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;;;;;OAYG;IACH,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzE;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,aAAa;IACxB,yEAAyE;IACzE,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAgB;IAC/C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAe;IAC1C,OAAO,CAAC,iBAAiB,CAAC,CAEM;IAEhC,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;;;;;OAMG;gBACS,MAAM,EAAE,mBAAmB,YAAK,EAAE,OAAO,EAAE,YAAY;IAmBnE;;;;;;;OAOG;IACH,yBAAyB,CACvB,OAAO,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAC5D,IAAI;IAIP;;;;OAIG;IACH,WAAW,IAAI,MAAM;IAIrB;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAInC;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,OAAO,CAAC,OAAO,EAAE,UAAU,EAC/B,QAAQ,EAAE,iBAAiB,CAAC,OAAO,EAAE,UAAU,CAAC,EAChD,SAAS,CAAC,EAAE,UAAU,EACtB,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GACrC,OAAO,CAAC,OAAO,CAAC;IASnB;;;;;;;;;;;;;;;;;;;OAmBG;IACG,KAAK,CAAC,CAAC,GAAG,GAAG,EACjB,KAAK,EAAE,MAAM,EACb,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACvC,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GACrC,OAAO,CAAC,CAAC,CAAC;IA0Cb,0EAA0E;YAC5D,OAAO;CAyEtB;AAED;;;GAGG;AACH,OAAO,EAAE,aAAa,IAAI,gBAAgB,EAAE,CAAC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAahD,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAG1D;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;;;;;OAYG;IACH,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzE;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,aAAa;IACxB,yEAAyE;IACzE,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAgB;IAC/C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAe;IAC1C,OAAO,CAAC,iBAAiB,CAAC,CAEM;IAEhC,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;;;;;OAMG;gBACS,MAAM,EAAE,mBAAmB,YAAK,EAAE,OAAO,EAAE,YAAY;IAmBnE;;;;;;;OAOG;IACH,yBAAyB,CACvB,OAAO,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAC5D,IAAI;IAIP;;;;OAIG;IACH,WAAW,IAAI,MAAM;IAIrB;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAInC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,OAAO,CAAC,OAAO,EAAE,UAAU,EAC/B,QAAQ,EAAE,iBAAiB,CAAC,OAAO,EAAE,UAAU,CAAC,EAChD,SAAS,CAAC,EAAE,UAAU,EACtB,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GACrC,OAAO,CAAC,OAAO,CAAC;IASnB;;;;;;;;;;;;;;;;;;;OAmBG;IACG,KAAK,CAAC,CAAC,GAAG,GAAG,EACjB,KAAK,EAAE,MAAM,EACb,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACvC,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GACrC,OAAO,CAAC,CAAC,CAAC;IA0Cb,0EAA0E;YAC5D,OAAO;CAqFtB;AAED;;;GAGG;AACH,OAAO,EAAE,aAAa,IAAI,gBAAgB,EAAE,CAAC"}

package/dist/client.js

@@ -107,7 +107,8 @@ export class GraphQLClient {
      * @param variables - Variables for the operation; omit for operations that
      *   take none.
      * @param options - Optional `signal` to abort the request from your own
-     *   `AbortController` (in addition to the built-in timeout).
+     *   `AbortController` (in addition to the built-in timeout). Aborting it rejects
+     *   with the signal's reason, not a {@link CrowdyTimeoutError}.
      * @returns The operation's `data` payload.
      * @throws {CrowdyHttpError} on a non-2xx HTTP status.
      * @throws {CrowdyGraphQLError} when the response carries a non-empty
@@ -180,9 +181,20 @@ export class GraphQLClient {
     /** One HTTP round trip. {@link query} wraps this to handle a redirect. */
     async attempt(query, variables, options) {
         const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        let timedOut = false;
+        const timeoutId = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, this.timeout);
+        // The caller's signal is followed as well as the timeout, never instead of it.
+        const caller = options.signal;
+        const followCaller = () => controller.abort(caller?.reason);
+        if (caller?.aborted)
+            followCaller();
+        else
+            caller?.addEventListener('abort', followCaller, { once: true });
         const token = this.session.getToken();
-        const signal = options.signal ?? controller.signal;
+        const signal = controller.signal;
         const lbCookie = this.lbCookieStore?.headerValue();
         try {
             const requestBody = { query, variables };
@@ -227,6 +239,8 @@ export class GraphQLClient {
         }
         catch (error) {
             clearTimeout(timeoutId);
+            if (!timedOut && caller?.aborted)
+                throw caller.reason ?? error;
             if (error instanceof Error && error.name === 'AbortError') {
                 throw new CrowdyTimeoutError(this.timeout);
             }
@@ -239,6 +253,9 @@ export class GraphQLClient {
             this.logger.error?.('GraphQL request failed', error);
             throw new CrowdyNetworkError(error);
         }
+        finally {
+            caller?.removeEventListener('abort', followCaller);
+        }
     }
 }
 /**

package/dist/domains/inputLog.d.ts

@@ -15,6 +15,13 @@ export interface InputLogPageOptions<Filter> {
     /** A previous page's `pageInfo.endCursor`; omit for the first page. */
     after?: string;
     filter?: Filter;
+    /**
+     * Abort the read: the call rejects with the signal's reason, and the server stops a
+     * `messages` read and frees its share at once (the Game API release after v2.40.2), so the
+     * next read, a different session's say, does not wait for it. Abort the one you no longer
+     * need when the user moves on.
+     */
+    signal?: AbortSignal;
 }
 /**
  * The input log: the client inputs the realtime servers recorded for an app with
@@ -28,11 +35,21 @@ export interface InputLogPageOptions<Filter> {
  * **Who sees what.** A player reads only the sessions and inputs they sent. A holder of
  * `manage_apps` on the app reads every session and may filter by `userId`.
  *
- * Inputs are kept for the input log's published retention (crowdedkingdoms.com/pricing)
- * and then deleted, so an old session can still be listed after its inputs are gone.
- * Without input logging on the deployment, both calls throw
- * {@link CrowdyGraphQLError} `INPUT_LOG_UNAVAILABLE`; `messages` also throws it, retryable
- * with the same cursor, when the log cannot be read right now.
+ * Inputs are kept for the input log's published retention (crowdedkingdoms.com/pricing,
+ * up to about an hour longer) and then deleted, so an old session can still be listed
+ * after its inputs are gone. Recording is best-effort: a session's `missingRecords` counts
+ * the inputs that were accepted but never reached the log.
+ *
+ * Without input logging on the deployment, both calls throw {@link CrowdyGraphQLError}
+ * `INPUT_LOG_UNAVAILABLE`. `messages` throws `INPUT_LOG_TEMPORARILY_UNAVAILABLE` when the
+ * log cannot be read right now. A server runs one read per user, and two per app and per
+ * org, at a time: a read over that share waits for an earlier one within its own few-second
+ * deadline, and `INPUT_LOG_RATE_LIMITED` means the wait ran out. Both carry
+ * `extensions.retryable`, so wait a moment and call again with the same cursor; a read
+ * whose request is closed (`opts.signal` aborted) stops and frees its share. An operation may select
+ * `inputLogMessages` only once. The Game API release after v2.40.2 raises those two;
+ * v2.39.0 to v2.40.2 answer `INPUT_LOG_UNAVAILABLE` instead, and an empty page when a read
+ * could not start in time.
  */
 export declare class InputLogAPI {
     private gql;
@@ -44,7 +61,18 @@ export declare class InputLogAPI {
      * @param opts - Paging, and {@link InputLogSessionFilter}: `userId` (another user's
      *   needs `manage_apps`), `from` / `to`, and `messageType` (sessions containing it).
      * @returns One page: `edges[].node` are the sessions, `pageInfo.endCursor` the next
-     *   page's `after`, `totalCount` the matching sessions.
+     *   page's `after`, `totalCount` the matching sessions. A node's `endReason` is how the
+     *   session ended: `expired`, `revoked`, `reconnect` or `released` as the client saw it;
+     *   `logging_off` when the app turned replay logging off during it; `shutdown` when the
+     *   realtime server recording it stopped (the client reconnects to another server, where
+     *   the same session continues and its end is replaced); `paused` when recording paused
+     *   because the app's logging setting could not be confirmed (a later record reopens the
+     *   session); `unrecorded` when no end was recorded and it was closed an hour after its last
+     *   input (all three from the Game API release after v2.40.2); or null while it may still
+     *   run. `missingRecords` counts the session's inputs that were accepted but never recorded,
+     *   by an overloaded server or a broker outage: 0 when the recording is complete as far as
+     *   it is known (a lost end cannot be counted), null on a session recorded before the count
+     *   existed.
      * @throws {CrowdyGraphQLError} `FORBIDDEN` for another user's sessions without
      *   `manage_apps`, or `INPUT_LOG_UNAVAILABLE`.
      */
@@ -57,8 +85,12 @@ export declare class InputLogAPI {
      * input logs are billed on. Spatial inputs also carry their chunk and actor, and
      * channel inputs their channel.
      *
-     * **Keep paging while `pageInfo.hasNextPage` is true.** A page can hold fewer than
-     * `first` inputs, or none, when it reached the server's time or scan limit.
+     * **Keep paging while `pageInfo.hasNextPage` is true**, not while `endCursor` is set: a page
+     * can hold fewer than `first` inputs, or none, when it reached the server's time or scan
+     * limit, and its `endCursor` still moves the next page on. Keep the previous cursor if one
+     * comes back null, and retry `INPUT_LOG_TEMPORARILY_UNAVAILABLE` / `INPUT_LOG_RATE_LIMITED`
+     * with it after a short back-off, a bounded number of times (MIGRATION.md, 18.9.0). Pass
+     * `opts.signal` and abort a read nobody will see.
      *
      * @param appId - Numeric app id.
      * @param gameTokenId - The session: {@link InputLogSessionRecord.gameTokenId}.
@@ -66,8 +98,10 @@ export declare class InputLogAPI {
      *   `messageTypes` (at most 64).
      * @returns One page of inputs.
      * @throws {CrowdyGraphQLError} `NOT_FOUND` for a session that is not yours without
-     *   `manage_apps`, `BAD_USER_INPUT` for a cursor from another session, or
-     *   `INPUT_LOG_UNAVAILABLE`.
+     *   `manage_apps`; `BAD_USER_INPUT` for a malformed cursor, or (from the Game API release
+     *   after v2.40.2, which binds a cursor to its session) one from another session;
+     *   `INPUT_LOG_TEMPORARILY_UNAVAILABLE` or `INPUT_LOG_RATE_LIMITED`, both retryable with the
+     *   same cursor; or `INPUT_LOG_UNAVAILABLE`.
      */
     messages(appId: string, gameTokenId: string, opts?: InputLogPageOptions<InputLogMessageFilter>): Promise<InputLogMessagePage>;
 }

package/dist/domains/inputLog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inputLog.d.ts","sourceRoot":"","sources":["../../src/domains/inputLog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,EAGL,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC3B,MAAM,yBAAyB,CAAC;AAEjC,gDAAgD;AAChD,MAAM,MAAM,mBAAmB,GAAG,qBAAqB,CAAC,kBAAkB,CAAC,CAAC;AAC5E,wEAAwE;AACxE,MAAM,MAAM,qBAAqB,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;AACjF,gDAAgD;AAChD,MAAM,MAAM,mBAAmB,GAAG,qBAAqB,CAAC,kBAAkB,CAAC,CAAC;AAC5E,sEAAsE;AACtE,MAAM,MAAM,qBAAqB,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjF,4FAA4F;AAC5F,MAAM,WAAW,mBAAmB,CAAC,MAAM;IACzC,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,WAAW;IACV,OAAO,CAAC,GAAG;gBAAH,GAAG,EAAE,aAAa;IAEtC;;;;;;;;;;OAUG;IACG,QAAQ,CACZ,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,mBAAmB,CAAC,qBAAqB,CAAM,GACpD,OAAO,CAAC,mBAAmB,CAAC;IAU/B;;;;;;;;;;;;;;;;;;;OAmBG;IACG,QAAQ,CACZ,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE,mBAAmB,CAAC,qBAAqB,CAAM,GACpD,OAAO,CAAC,mBAAmB,CAAC;CAUhC"}
+{"version":3,"file":"inputLog.d.ts","sourceRoot":"","sources":["../../src/domains/inputLog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,EAGL,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC3B,MAAM,yBAAyB,CAAC;AAEjC,gDAAgD;AAChD,MAAM,MAAM,mBAAmB,GAAG,qBAAqB,CAAC,kBAAkB,CAAC,CAAC;AAC5E,wEAAwE;AACxE,MAAM,MAAM,qBAAqB,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;AACjF,gDAAgD;AAChD,MAAM,MAAM,mBAAmB,GAAG,qBAAqB,CAAC,kBAAkB,CAAC,CAAC;AAC5E,sEAAsE;AACtE,MAAM,MAAM,qBAAqB,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjF,4FAA4F;AAC5F,MAAM,WAAW,mBAAmB,CAAC,MAAM;IACzC,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,WAAW;IACV,OAAO,CAAC,GAAG;gBAAH,GAAG,EAAE,aAAa;IAEtC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,QAAQ,CACZ,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,mBAAmB,CAAC,qBAAqB,CAAM,GACpD,OAAO,CAAC,mBAAmB,CAAC;IAS/B;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACG,QAAQ,CACZ,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE,mBAAmB,CAAC,qBAAqB,CAAM,GACpD,OAAO,CAAC,mBAAmB,CAAC;CAQhC"}

package/dist/domains/inputLog.js

@@ -11,11 +11,21 @@ import { InputLogMessagesDocument, InputLogSessionsDocument, } from '../generate
  * **Who sees what.** A player reads only the sessions and inputs they sent. A holder of
  * `manage_apps` on the app reads every session and may filter by `userId`.
  *
- * Inputs are kept for the input log's published retention (crowdedkingdoms.com/pricing)
- * and then deleted, so an old session can still be listed after its inputs are gone.
- * Without input logging on the deployment, both calls throw
- * {@link CrowdyGraphQLError} `INPUT_LOG_UNAVAILABLE`; `messages` also throws it, retryable
- * with the same cursor, when the log cannot be read right now.
+ * Inputs are kept for the input log's published retention (crowdedkingdoms.com/pricing,
+ * up to about an hour longer) and then deleted, so an old session can still be listed
+ * after its inputs are gone. Recording is best-effort: a session's `missingRecords` counts
+ * the inputs that were accepted but never reached the log.
+ *
+ * Without input logging on the deployment, both calls throw {@link CrowdyGraphQLError}
+ * `INPUT_LOG_UNAVAILABLE`. `messages` throws `INPUT_LOG_TEMPORARILY_UNAVAILABLE` when the
+ * log cannot be read right now. A server runs one read per user, and two per app and per
+ * org, at a time: a read over that share waits for an earlier one within its own few-second
+ * deadline, and `INPUT_LOG_RATE_LIMITED` means the wait ran out. Both carry
+ * `extensions.retryable`, so wait a moment and call again with the same cursor; a read
+ * whose request is closed (`opts.signal` aborted) stops and frees its share. An operation may select
+ * `inputLogMessages` only once. The Game API release after v2.40.2 raises those two;
+ * v2.39.0 to v2.40.2 answer `INPUT_LOG_UNAVAILABLE` instead, and an empty page when a read
+ * could not start in time.
  */
 export class InputLogAPI {
     constructor(gql) {
@@ -28,17 +38,23 @@ export class InputLogAPI {
      * @param opts - Paging, and {@link InputLogSessionFilter}: `userId` (another user's
      *   needs `manage_apps`), `from` / `to`, and `messageType` (sessions containing it).
      * @returns One page: `edges[].node` are the sessions, `pageInfo.endCursor` the next
-     *   page's `after`, `totalCount` the matching sessions.
+     *   page's `after`, `totalCount` the matching sessions. A node's `endReason` is how the
+     *   session ended: `expired`, `revoked`, `reconnect` or `released` as the client saw it;
+     *   `logging_off` when the app turned replay logging off during it; `shutdown` when the
+     *   realtime server recording it stopped (the client reconnects to another server, where
+     *   the same session continues and its end is replaced); `paused` when recording paused
+     *   because the app's logging setting could not be confirmed (a later record reopens the
+     *   session); `unrecorded` when no end was recorded and it was closed an hour after its last
+     *   input (all three from the Game API release after v2.40.2); or null while it may still
+     *   run. `missingRecords` counts the session's inputs that were accepted but never recorded,
+     *   by an overloaded server or a broker outage: 0 when the recording is complete as far as
+     *   it is known (a lost end cannot be counted), null on a session recorded before the count
+     *   existed.
      * @throws {CrowdyGraphQLError} `FORBIDDEN` for another user's sessions without
      *   `manage_apps`, or `INPUT_LOG_UNAVAILABLE`.
      */
     async sessions(appId, opts = {}) {
-        const data = await this.gql.request(InputLogSessionsDocument, {
-            appId,
-            first: opts.first,
-            after: opts.after,
-            filter: opts.filter,
-        });
+        const data = await this.gql.request(InputLogSessionsDocument, { appId, first: opts.first, after: opts.after, filter: opts.filter }, { signal: opts.signal });
         return data.inputLogSessions;
     }
     /**
@@ -49,8 +65,12 @@ export class InputLogAPI {
      * input logs are billed on. Spatial inputs also carry their chunk and actor, and
      * channel inputs their channel.
      *
-     * **Keep paging while `pageInfo.hasNextPage` is true.** A page can hold fewer than
-     * `first` inputs, or none, when it reached the server's time or scan limit.
+     * **Keep paging while `pageInfo.hasNextPage` is true**, not while `endCursor` is set: a page
+     * can hold fewer than `first` inputs, or none, when it reached the server's time or scan
+     * limit, and its `endCursor` still moves the next page on. Keep the previous cursor if one
+     * comes back null, and retry `INPUT_LOG_TEMPORARILY_UNAVAILABLE` / `INPUT_LOG_RATE_LIMITED`
+     * with it after a short back-off, a bounded number of times (MIGRATION.md, 18.9.0). Pass
+     * `opts.signal` and abort a read nobody will see.
      *
      * @param appId - Numeric app id.
      * @param gameTokenId - The session: {@link InputLogSessionRecord.gameTokenId}.
@@ -58,17 +78,13 @@ export class InputLogAPI {
      *   `messageTypes` (at most 64).
      * @returns One page of inputs.
      * @throws {CrowdyGraphQLError} `NOT_FOUND` for a session that is not yours without
-     *   `manage_apps`, `BAD_USER_INPUT` for a cursor from another session, or
-     *   `INPUT_LOG_UNAVAILABLE`.
+     *   `manage_apps`; `BAD_USER_INPUT` for a malformed cursor, or (from the Game API release
+     *   after v2.40.2, which binds a cursor to its session) one from another session;
+     *   `INPUT_LOG_TEMPORARILY_UNAVAILABLE` or `INPUT_LOG_RATE_LIMITED`, both retryable with the
+     *   same cursor; or `INPUT_LOG_UNAVAILABLE`.
      */
     async messages(appId, gameTokenId, opts = {}) {
-        const data = await this.gql.request(InputLogMessagesDocument, {
-            appId,
-            gameTokenId,
-            first: opts.first,
-            after: opts.after,
-            filter: opts.filter,
-        });
+        const data = await this.gql.request(InputLogMessagesDocument, { appId, gameTokenId, first: opts.first, after: opts.after, filter: opts.filter }, { signal: opts.signal });
         return data.inputLogMessages;
     }
 }

package/dist/generated/graphql-schema.d.ts

@@ -882,7 +882,7 @@ export type App = {
     orgId: Scalars['BigInt']['output'];
     /** OAuth-style redirect-URI allow-list for the portal handoff. A portal authorization code’s redirect_uri must match one of these by origin; empty disallows browser portal entry to this app. */
     redirectUris: Array<Scalars['String']['output']>;
-    /** Whether replay logging is on: the realtime servers record every client input they accept for this app, searchable with inputLogSessions and readable with inputLogMessages, and billed as stored input logs. False (the default) records nothing ("No replication logging"). Set with updateApp (manage_apps); turning it on needs a funded org wallet or a billing-exempt org. */
+    /** Whether replay logging is on: the realtime servers record every client message they accept for this app, searchable with inputLogSessions and readable with inputLogMessages, and billed as stored input logs. False (the default) records nothing ("No replication logging"). Set with updateApp (manage_apps); turning it on needs a wallet that covers the projected cost of one retention period, or a billing-exempt org. */
     replayLoggingEnabled: Scalars['Boolean']['output'];
     /**
      * Reserved realtime (UDP) capacity in bytes/s for shared apps. Superseded by reservedUdpBytesPerSec.
@@ -1208,7 +1208,7 @@ export type AppUsageProjection = {
     daysElapsed: Scalars['Float']['output'];
     /** Per-app free monthly egress allowance in bytes (5 decimal GB). */
     freeAllowanceBytes: Scalars['String']['output'];
-    /** Stored input logs this calendar month so far, in byte-hours (input_log_storage_byte_hours, which has no free allowance). 0 when replay logging was off all month. */
+    /** Stored input logs this calendar month so far, in byte-hours (input_log_storage_byte_hours, which has no free allowance). Recordings keep accruing after replay logging is turned off, until they age out at the end of the retention; 0 when nothing was held this month. */
     inputLogByteHours: Scalars['String']['output'];
     /** True when projected egress exceeds the free allowance, or null when insufficient data. */
     onTrackToExceed: Maybe<Scalars['Boolean']['output']>;
@@ -1236,7 +1236,7 @@ export type AppUsageSummary = {
     graphqlRecvBytes: Scalars['String']['output'];
     /** Total GraphQL bytes sent (string counter). */
     graphqlSendBytes: Scalars['String']['output'];
-    /** Stored input logs over the window, in byte-hours (string counter): the sum of the hourly samples, which is the quantity input_log_storage_byte_hours bills. Each recorded byte (InputLogMessage.sizeBytes) is held for the input log retention, one byte-hour per hour. 0 when replay logging was off. */
+    /** Stored input logs over the window, in byte-hours (string counter): the sum of the hourly samples, which is the quantity input_log_storage_byte_hours bills. Each recorded byte (InputLogMessage.sizeBytes) is held for the input log retention, one byte-hour per hour, so recordings keep accruing byte-hours after replay logging is turned off, until they age out. 0 when nothing was held during the window. */
     inputLogByteHours: Scalars['String']['output'];
     /** Recorded input-log bytes the app holds now (string counter): the latest hourly sample, the bytes recorded within the trailing retention. 0 when replay logging has never been on. */
     inputLogRetainedBytes: Scalars['String']['output'];
@@ -4403,9 +4403,9 @@ export type InputLogSession = {
     byteCount: Scalars['BigInt']['output'];
     /** The datacenter that recorded the session, when known. */
     datacenter: Maybe<Scalars['String']['output']>;
-    /** How the session ended, as the client saw it: expired, revoked, reconnect or released. Null while it may still be running. */
+    /** How the session ended: expired, revoked, reconnect or released, as the client saw it; logging_off, when the app turned replay logging off while the session was open; shutdown, when the realtime server recording it stopped (a deploy), after which the client reconnects elsewhere; paused, when recording paused because the app's logging setting could not be confirmed, which the client does not see (a later record reopens the session); or unrecorded, when its end was not recorded and it was closed an hour after its last record. Null while it may still be running. */
     endReason: Maybe<Scalars['String']['output']>;
-    /** When the session ended, if its end was recorded; null while it may still be running. */
+    /** When the session ended; null while it may still be running. A session whose end was not recorded is closed at its last record once it has gone an hour without one. Later records reopen a session (endedAt returns to null). */
     endedAt: Maybe<Scalars['DateTime']['output']>;
     /** The game token the session ran on; pass it to inputLogMessages to read the inputs. */
     gameTokenId: Scalars['BigInt']['output'];
@@ -4415,6 +4415,8 @@ export type InputLogSession = {
     messageCount: Scalars['BigInt']['output'];
     /** The client message types the session contains, ascending. */
     messageTypes: Array<Scalars['Int']['output']>;
+    /** Records the realtime servers numbered for this session that never reached the log: recording is best-effort, so an overloaded server or a broker outage can leave gaps, and this is how many. 0 when the recording is complete as far as it is known. A lost end of the recording cannot be counted (its session closes as unrecorded instead). Null for a session recorded before the realtime servers numbered their records. */
+    missingRecords: Maybe<Scalars['BigInt']['output']>;
     /** When the first recorded input arrived. */
     startedAt: Scalars['DateTime']['output'];
     /** The user whose client sent the inputs. */
@@ -4928,7 +4930,7 @@ export type Mutation = {
     updateActor: Actor;
     /** Replaces an actor’s `publicState` and/or `privateState` blobs (fields omitted from `input` are left unchanged). OWNER-EXCLUSIVE: only the actor’s owner may write (throws Unauthorized otherwise). Game-plane: requires an app token for the actor’s app (a session token or another app’s token is answered NotFound). `uuid` is the 32-character ASCII actor id; blobs are base64-encoded binary. */
     updateActorState: Actor;
-    /** Update mutable fields of an existing app (name, description, visibility, status, metadata, wildernessWritesOpen, replayLoggingEnabled); only fields present in the input are changed. Turning replayLoggingEnabled on is refused with INPUT_LOG_FUNDS_NEEDED unless the org's wallet has a spendable balance or the org is billing-exempt. Requires the 'manage_apps' permission on the app (resolved via its org); super admins bypass. Use this to publish (status=LIVE), change visibility, or restore an archived app (status back to DRAFT/LIVE). Throws if the app id does not exist. */
+    /** Update mutable fields of an existing app (name, description, visibility, status, metadata, wildernessWritesOpen, replayLoggingEnabled); only fields present in the input are changed. Turning replayLoggingEnabled on is refused with INPUT_LOG_FUNDS_NEEDED unless the org's wallet can spend at least the projected cost of keeping one retention period of the app's recent traffic (extensions.requiredMicrousd and spendableMicrousd say how much), or the org is billing-exempt; recordings already kept go on billing after it is turned off, until they age out. Requires the 'manage_apps' permission on the app (resolved via its org); super admins bypass. Use this to publish (status=LIVE), change visibility, or restore an archived app (status back to DRAFT/LIVE). Throws if the app id does not exist. */
     updateApp: App;
     /** Updates an avatar’s mutable fields (currently `name`) and returns it. OWNER-EXCLUSIVE: only the avatar’s owner may call this (throws Unauthorized otherwise). Requires a valid game token. To change state blobs use `updateAvatarState`. */
     updateAvatar: Avatar;
@@ -6787,7 +6789,7 @@ export type Query = {
     hostedGamePublishes: Array<HostedGamePublish>;
     /** The LIVE and LISTED hosted third-party games, for the Overworld lobby and the marketplace. PUBLIC. Empty when the tier does not host third-party games. Operators see every game with allHostedGames. */
     hostedGames: Array<HostedGame>;
-    /** The recorded inputs of one session, oldest first, each exactly as the client sent it (without its authentication tail). Read from the input log by the offset ranges its index holds, so inputs past the published retention are gone even while the session is still listed. With 'manage_apps' on the app you may read any session; anyone else may read only their own, and any other session answers NOT_FOUND. Game plane: send the app-scoped token for this app to the app's datacenter. Page with `first` (default 50, max 200) and `after`; a page can hold fewer than `first` inputs when it stopped at its time or scan limit, so keep paging while hasNextPage is true. INPUT_LOG_UNAVAILABLE when input logging is not configured on this deployment, and also, retryable with the same cursor, when the log cannot be read right now. */
+    /** The recorded inputs of one session, oldest first, each exactly as the client sent it (without its authentication tail). Read from the input log by the offset ranges its index holds, so inputs past the published retention are gone even while the session is still listed. With 'manage_apps' on the app you may read any session; anyone else may read only their own, and any other session answers NOT_FOUND. Game plane: send the app-scoped token for this app to the app's datacenter. Page with `first` (default 50, max 200) and `after`, the previous page's endCursor for this same session (a cursor from another session is BAD_USER_INPUT); a page can hold fewer than `first` inputs, or none, when it stopped at its time or scan limit, so keep paging while hasNextPage is true. An operation may select this field only once. A server runs one read per user (two per app and per org) at a time; a read over that share waits for the earlier one within its own few-second deadline, and a read whose request is closed stops. Errors: INPUT_LOG_UNAVAILABLE when input logging is not configured on this deployment, or this server may not read its log (do not retry); INPUT_LOG_RATE_LIMITED (429) when the wait for an earlier read ran out or left too little time to read, and INPUT_LOG_TEMPORARILY_UNAVAILABLE (503) when the log cannot be read just now, both with extensions.retryable: retry shortly with the same cursor. A read whose request closed stops as INPUT_LOG_READ_ABORTED (499), which nobody receives. */
     inputLogMessages: InputLogMessageConnection;
     /** Recorded client sessions of an app with replay logging on (App.replayLoggingEnabled), newest first. With 'manage_apps' on the app you see every session and may filter by userId; anyone else sees only their own, and asking for another user's is FORBIDDEN. Game plane: send the app-scoped token for this app to the app's datacenter. Page with `first` (default 50, max 200) and `after`. INPUT_LOG_UNAVAILABLE when input logging is not configured on this deployment. */
     inputLogSessions: InputLogSessionConnection;
@@ -8630,7 +8632,7 @@ export type UpdateAppInput = {
     metadata?: InputMaybe<Scalars['String']['input']>;
     /** New display name (1-256 chars). Omit to leave unchanged. */
     name?: InputMaybe<Scalars['String']['input']>;
-    /** Turn replay logging on (true) or off (false): record every client input the realtime servers accept for this app, kept for the input log's published retention and billed as stored input logs (input_log_storage_byte_hours, no free allowance). Turning it ON is refused with INPUT_LOG_FUNDS_NEEDED unless the org's wallet has a spendable balance or the org is billing-exempt; turning it off always succeeds. Recording starts and stops within about 15 seconds. Omit to leave unchanged. */
+    /** Turn replay logging on (true) or off (false): record every client message the realtime servers accept for this app (keep-alives included), kept for the input log's published retention and billed as stored input logs (input_log_storage_byte_hours, no free allowance). Turning it ON is refused with INPUT_LOG_FUNDS_NEEDED unless the org's wallet can spend at least the projected cost of keeping one retention period of the app's recent traffic, or the org is billing-exempt; turning it off always succeeds, and what was already recorded goes on billing until it ages out. Recording starts and stops within about 15 seconds. Omit to leave unchanged. */
     replayLoggingEnabled?: InputMaybe<Scalars['Boolean']['input']>;
     /** New lifecycle status; set LIVE to publish, or DRAFT/LIVE to restore an archived app. Omit to leave unchanged. */
     status?: InputMaybe<AppStatus>;