@indiegems/gem-web-sdk 7.4.0 → 7.4.1

package/docs/async-opponents.md

@@ -0,0 +1,396 @@
+# Async opponents
+
+Not every game needs an opponent, and this is a capability rather than an obligation. But if your
+game has a run, a deck, a build or a lap worth measuring against another player's, the platform
+will hold a durable snapshot of one and hand it to a different player's game hours later, with
+nothing live between them.
+
+An **async opponent** is that snapshot: one record, shaped by you, carrying whatever your game
+needs to rebuild an opponent and play against it. A game whose matches run entirely in the browser
+has no server of its own to hold that state or to arbitrate a live match, and this is the
+competitive mode that needs neither.
+
+**A snapshot is data, and nothing more is implied by it.** The player it came from is not online,
+has not agreed to this particular match, and is not told it happened. Design the screen that way:
+your player is playing a record, not challenging a person.
+
+## 1. Whether you need this
+
+Async opponents are the platform's asynchronous competitive mode — one player's saved state,
+played against by another player later, with nothing live in between.
+
+Reach for it when your game is played alone but wants opposition: a ghost lap, a defending deck, a
+fortress somebody else built, a rival seeded from a real run. It suits a game that runs entirely in
+the browser, because no part of the loop needs a server you operate.
+
+Do not reach for it when the players have to be in the same match at the same time — that is a live
+room, and [`rooms-and-matches.md`](rooms-and-matches.md) is the page for it. Do not reach for it to
+rank players either: standings are [`leaderboards.md`](leaderboards.md), and they are written from
+the server side, by a dedicated-server match or by your game's serverless function, rather than
+from a snapshot.
+
+The whole loop in one sentence: **your game pushes a record after a match, draws a few records at
+the next match's start, and fetches the full data for the one your player picks.**
+
+## 2. The loop, and why it has this shape
+
+The loop is three REST calls, and they do not cost the same. The order below is what keeps the
+expensive one off the path a player is waiting on.
+
+1. **Push a snapshot, after a match ends** — `POST /v1/async-opponents`. Blocks nobody: the match
+   is over and nobody is waiting on it. It makes the play that just happened available to other
+   players' future draws.
+2. **Draw a set, at match start** — `GET /v1/async-opponents`. **This is the gameplay-blocking
+   call**, with a player watching a loading screen while it runs, so it is bounded work that does
+   not grow as the pool does.
+3. **Fetch the one your player picked** — `GET /v1/async-opponents/{opponent_id}`. The only
+   operation that returns `payload`, the dense data your game needs to actually reconstruct that
+   opponent.
+
+**The draw deliberately omits `payload`, and the third call exists because of it.** A draw can
+return twenty-five records and the player plays one; carrying dense data on all twenty-five would
+mean paying twenty-five heavy reads to use a single one. So the batch is scalars and the payload is
+fetched once, for the pick.
+
+Two consequences to design for now rather than later. The by-id fetch is load-bearing — it is not
+an optimisation you can fold away. And **"the opponent I picked is gone" is a routine state rather
+than an edge case**: records expire and slots are recycled in the seconds between a draw and a
+pick, so plan the fallback before you meet it.
+
+## 3. How your game reaches it
+
+Async opponents are REST operations under `/v1/`, and your game calls them directly.
+
+**The browser SDK has no named async-opponent surface.** What it has is the published raw client:
+`gem.client.get`, `gem.client.post` and `gem.client.delete` take any `/v1/` path, sign it with the
+token your frame already holds, and throw a typed `GemApiError` you branch on — so
+`gem.client.get('/v1/async-opponents?…')`, `gem.client.post('/v1/async-opponents', body)` and
+`gem.client.delete('/v1/async-opponents/…')` are the three calls this page is about. That client is
+marked deprecated in favour of the SDK's named surfaces, and it is still the right call here: it is
+the door for the case the named surfaces do not cover, and this is that case.
+
+**That deprecation carries a floor, not a date.** `gem.client` keeps working for the rest of `3.x`,
+and `4.0.0` is the earliest release that may remove it — [the deprecation
+policy](deprecation-policy.md#2-the-rule-for-the-packages-api-surface) is the whole rule: it names
+the soonest a removal could reach you rather than scheduling one. And what closes the gap before
+then is you saying it is there — the notice on `gem.client` asks you to report anything the named
+surfaces do not offer, and this page is one of those things written down. **Reaching for it does
+not decide who signs the write:** `gem.client` signs with the play token your frame already holds,
+so a record the platform has to trust belongs on the server-authored route below rather than on a
+client call.
+
+**A server-authored push is the same route with a different token.** A dedicated-server match's
+bundle holds a game-server token and the same client shape, so a server that has just decided an
+outcome can write the record itself, from values a modified client never touched — see
+[`server-bundles.md`](server-bundles.md) for how a bundle calls the backend. Most of this page
+reads the same from either side; what differs is the write gates in section 4, the withdraw scope
+in section 9, and `exclude_self`, which does nothing for a game server token because it carries no
+`sub`. If the same bundle runs as a browser listen host (`gem.match.serve`), it holds the hosting
+player's play token rather than a game-server token: its pushes are player pushes, gated as in
+section 4, and `exclude_self` applies.
+
+## 4. What you declare, and what it does at runtime
+
+No async-opponent *record* route answers until your game config declares an **async opponent
+type**. A type is a policy: who may write records of it, how many one entity may keep, how long a
+record lives, whether it carries a payload, and what its properties are. The config section is
+`async_opponent_types`, and `gemctl config schema` is the authoritative field list — do not
+re-derive one from this page. What follows is what each declared value does once your game is
+running.
+
+- **`player_writable`** — whether a player's own client may push. It has a cost; see below.
+- **`max_slots_per_entity`** — how many records one entity may hold **at each version**. A cap
+  rather than a quota: once it is full, the next push recycles the oldest.
+- **`ttl_seconds`** — how long a record lives, from the push. Set it against your push cadence; a
+  TTL shorter than the interval at which your players finish matches empties your own pool.
+- **`max_payload_bytes`** — the ceiling on `payload`. **Absent means the type accepts no payload at
+  all**, not that it accepts an unbounded one, and a push supplying one is refused rather than
+  silently truncated.
+- **`versions`** — each declared version carries its own property schema and its own `searchable`
+  list. What versions do to the cap and to a draw is section 5.
+
+**`player_writable` buys you a competitive mode with no server of your own, and it costs
+authority.** With it off, only a game server may push, and every value in the pool was written by
+code a player cannot reach. With it on, a browser game runs the whole loop by itself — and the
+values are self-reported, so a modified client can push a lap nobody drove, and a player's push may
+replace a record a game server wrote for that same entity. **Two gates must both pass for a player
+push: the type declares `player_writable`, and every property that push sets declares
+`client_writable`.** Both default to closed, platform-wide, so a property you never opened is
+refused even on a type you did.
+
+**`searchable` names properties the platform indexes as records are written.** No draw takes a
+property filter today — the draw's parameters are the seven in section 7 and no others — so what
+the declaration builds is the index itself. **Declare it when you first write the version.** The
+index is built from records as they arrive and nothing goes back over the ones already stored, so a
+record written under a version that did not name the property is not in that index and will not be.
+The list sits beside the property map on the version, not on the individual property definition.
+
+**Read the types at runtime rather than hardcoding the schema.**
+`GET /v1/async-opponent-types` returns every type in your game's active config, each with the full
+property schema of every version it declares, which is what lets a config change land without a
+re-ship. It is also the authority: it reads the live config for your channel, so if a copy you are
+holding disagrees with it, the copy is the stale side.
+
+## 5. Versions, and the cap that follows them
+
+Every async opponent type declares versions, and a version is a contract rather than a revision
+marker: each carries its own property schema, so v2 may add, drop or retype a property without
+invalidating the records already written as v1.
+
+Four things follow from that, and the fourth is a trap.
+
+- **The slot cap is per entity, per type, per version.** An entity already at its maximum on v1 can
+  still fill a set on v2, so rolling a version out does not drain the pool your players are still
+  drawing from.
+- **A draw names one type and one version, and never mixes them.** `version` is required on the
+  draw for the reason it is required on the push: it selects the property schema, so it cannot be
+  inferred.
+- **A retired version keeps its schema declared.** Records written under it stay readable until
+  they expire; the version simply stops accepting pushes and draws.
+- **A version your config does not currently accept is one signal covering two different faults.**
+  Never declared, and declared-then-retired, answer a draw identically: `200`, an empty `opponents`
+  array, and `empty_reason: "version_retired"`.
+
+**That last one is where a client hangs.** A build shipping a version number the config never
+declared reads "version retired" as a thin pool, shows an empty state and waits — and waiting
+cannot fix it, because the fault is a constant compiled into the client. Check the version you ship
+against `GET /v1/async-opponent-types` at startup: a version missing from the listing is your bug,
+and a version present and inactive is a rollout.
+
+## 6. Push a snapshot, after the match
+
+A push writes one record for one entity, and it runs after a match has ended, when nothing is
+waiting on it.
+
+`POST /v1/async-opponents` takes `opponent_type`, `version`, `entity_type`, `entity_id` and
+`properties`; `payload` is optional, and permitted only on a type that declares
+`max_payload_bytes`.
+
+```js
+const { playerId } = await gem.awaitIdentity();
+
+const pushed = await gem.client.post('/v1/async-opponents', {
+  opponent_type: 'ghost-lap', // by slug or by UUID
+  version: 3,
+  entity_type: 'player',
+  entity_id: playerId,
+  properties: { track: 'coast', lap_ms: 84210, car: 'roadster' },
+  payload: { inputs: recordedInputs }, // only on a type that declares max_payload_bytes
+});
+// pushed.opponent_id, pushed.expires_at
+```
+
+`properties` are scalars only and are validated against the schema the named version declares: a
+key that version does not declare is a refusal, not an extra field that rides along.
+
+**Keep personal data out of what you push.** Everything in a record is served to other players'
+clients, so `properties` and `payload` are the wrong place for anything about the player that your
+game would not print on their profile.
+
+**`entity_id` names a target, never a credential.** Ownership comes from the token: a player token
+may name only an entity that player owns, and a game server token only an entity in its own game.
+Naming somebody else's entity is refused with the same answer as naming nothing at all — the
+refusal is deliberately useless for testing whether an id is real.
+
+**Every push mints a fresh `opponent_id`, including one that recycles.** Once the entity's slots
+for that type and version are full, the next push evicts the oldest, so an entity's pool is always
+its most recent snapshots and never grows without bound. The `201` carries `opponent_id` and
+`expires_at`; there is no update call and no id worth holding between pushes.
+
+## 7. Draw a set, at match start
+
+A draw is the call your player waits on. It reads records for one type and one version and returns
+a handful of them at random.
+
+`GET /v1/async-opponents` takes seven parameters and no others:
+
+| Parameter | Required | What it does |
+| --- | --- | --- |
+| `opponent_type` | yes | The type, **by slug or by UUID** |
+| `version` | yes | Which declared version to draw from; a draw never mixes versions |
+| `count` | no | How many to return. **Defaults to 5**, minimum 1, maximum 25 |
+| `exclude_self` | no | **Defaults to true.** Resolved from your token; you never name yourself |
+| `exclude_opponent_ids` | no | Ids to leave out, **at most 50 entries** |
+| `game_id` | no | Carried by the token a framed game already holds |
+| `channel` | no | Carried by the token a framed game already holds |
+
+**`exclude_self` resolves to the calling player only.** A player who pushed a record for one of
+their own characters can draw that character back; if that reads wrong in your game, exclude the
+id yourself.
+
+The response is `opponents` and, when the draw came up short, `empty_reason`. **`empty_reason` is
+absent when the draw returned exactly `count` — the key is omitted, not `null`.** There is no value
+meaning "nothing was wrong"; its presence is the whole signal, and section 10 says what each of its
+five values means. A short draw is an ordinary `200` rather than an error: a new game's pool is
+empty by definition, so your match-start screen has to render that as a designed state.
+
+**One response never carries two records from the same entity**, so ten drawn opponents are ten
+different players or characters.
+
+Every drawn record carries `opponent_id`, `opponent_type`, `version`, `entity_type` (`player` or
+`character`), `entity_id`, `properties`, `created_at` and `expires_at` — all of them, always — plus
+the optional player identity fields — `player_id`, `display_name`, `discriminator`, `display_tag`,
+the portrait `avatar_icon_id` and `avatar_icon_url`, and `badges` — which **are absent entirely for
+a `character` entity**. For a player whose identity is withheld from you, `player_id` stays (it is
+the `entity_id` you already hold) and the name, tag and portrait are absent. `created_at` and `expires_at`
+are Unix timestamps in seconds. There is no `payload` here; that is section 8.
+
+**`opponent_type` goes in as a slug or a UUID and comes back as a UUID.** A game that pushes with a
+slug and then matches drawn records against that same slug matches nothing, and nothing raises.
+Compare against the id from the type listing, or do not compare on it at all.
+
+```ts
+// The raw client returns what you type it as, so declare the shape you read.
+// Untyped, `drawn` is `unknown` and every line that touches it fails to compile.
+interface Drawn {
+  opponents: {
+    display_tag?: string | null;
+    properties: Record<string, string | number | boolean>;
+  }[];
+  empty_reason?: string;
+}
+
+const query = new URLSearchParams({ opponent_type: 'ghost-lap', version: '3', count: '10' });
+const drawn = await gem.client.get<Drawn>(`/v1/async-opponents?${query}`);
+
+if (drawn.empty_reason) {
+  // Fewer than `count` came back, and the reason decides what to do — see section 10.
+}
+
+for (const opponent of drawn.opponents) {
+  // `mapIdentity`, imported beside `text`: the identity fields every surface that shows a player
+  // carries, the name and tag as PlayerText.
+  const who = mapIdentity(opponent);
+  const name = who.displayName ? text.toPlain(who.displayName) : 'Anonymous player';
+  const row = document.createElement('li');
+  row.textContent = `${name} — ${opponent.properties.lap_ms} ms`;
+  results.append(row);
+}
+```
+
+**Those strings were typed by another player. Render them through `textContent` or your
+framework's escaping — never `innerHTML`, and never as an image source or a link target, which are
+script-URL sinks.** That covers every value in `properties` on a `player_writable` type, and it
+covers `display_name`, `discriminator` and `display_tag` on every type. The rule runs the other way
+at push time, which is why section 6 says to keep personal data out of what you write: every value
+in a record is served to somebody else's client.
+
+Three controls stand behind that rule, and how far each one reaches is worth knowing, because what
+you are handed is a flat object with nothing wrapping it:
+
+- **A length bound, always.** Every string property on an async opponent type must declare a
+  `max_length` — a config that omits one is refused — so every string you draw is bounded, and the
+  ceiling is tighter on a `player_writable` type, where the value came from another player.
+  `GET /v1/async-opponent-types` publishes the bound each of your versions declares.
+- **A scrub on the way out.** The platform strips invisible and formatting characters from a
+  record's `properties` as it serves them.
+- **The SDK's `PlayerText` binding, which you opt into on this path.** Where the SDK hands you a
+  player's text through one of its named surfaces, it arrives as `PlayerText` rather than `string`,
+  so `el.innerHTML = value` will not compile. **A value you read through `gem.client` is an ordinary
+  JSON string** — so pass each drawn record through `mapIdentity`, which gives you the same
+  identity fields every other surface carries, name and tag wrapped. It covers the identity fields
+  only; nothing stands between a `properties` value and `innerHTML` except the way you render it.
+
+**The draw is uniform over records, not over entities.** `max_slots_per_entity` is a cap and not a
+quota, so an entity holding three records is drawn three times as often as one holding a single
+record — even though no one response carries two records from the same entity. That is fine for
+picking an opponent to play; it is not a fairness guarantee, and nothing in your game should be
+built as though it were.
+
+## 8. Fetch the one your player picked
+
+A drawn record carries no `payload`. Once the player has chosen one, fetch that record by its id:
+this is the only operation that returns it.
+
+`GET /v1/async-opponents/{opponent_id}` returns the same fields the draw returned, plus `payload`:
+
+```js
+const opponent = await gem.client.get(`/v1/async-opponents/${opponentId}`);
+// {
+//   opponent_id, opponent_type, version, entity_type, entity_id,
+//   properties: { track: 'coast', lap_ms: 84210, car: 'roadster' },
+//   display_name, discriminator, display_tag,
+//   created_at, expires_at,
+//   payload: { inputs: [] },
+// }
+```
+
+**`properties` is flat.** The values sit directly on it, with nothing wrapping them and no marker
+saying which of them a player authored — which is why the rule in section 7 is a rule about your
+rendering rather than a field you can test.
+
+**`payload` is returned as stored.** It is scrubbed of invisible characters, it is absent when the
+type declares no `max_payload_bytes` or the push supplied none, and **it is not validated against
+any schema** — the only bounds on it are the type's byte ceiling and a depth cap, which makes it
+the least constrained thing this API hands you. Everything the rule in section 7 says applies to
+what you find inside it, at least as hard as it applies to `properties`.
+
+**A `404` here is routine.** Records expire and slots are recycled between a draw and a pick, so a
+player taking a moment to choose is enough to cause one. Fall back to a fresh draw rather than
+reporting an error — and note that every refusal on this route is that same `404`, so it does not
+tell "expired" apart from "not yours to read".
+
+## 9. Withdraw a record
+
+A record leaves the pool by itself when its TTL expires. Withdrawing is for the player who wants
+out sooner, and for a game server tidying up behind itself.
+
+`DELETE /v1/async-opponents/{opponent_id}` answers `204` on success. A player token may withdraw
+records for entities that player owns, their own characters included — the path names a record, and
+it is the record's entity that gets authorised, so your own player id is never assumed to be it. A
+game server token may withdraw any record in its own game and channel, including ones it did not
+write.
+
+**A `404` means already gone** — expired, recycled, written under another channel, or never yours.
+Treat it as done and do not retry it.
+
+**A drawn `opponent_id` is a handle for reading, never for withdrawing.** This is the mistake the
+shape of the loop invites: a game holding ten ids from a draw calls delete on one to take it out of
+the player's list, and gets `404 async_opponent_not_found` — the same answer a record that expired
+would give, because "a real record for an entity you may not address" is deliberately
+indistinguishable from "gone". It is not the `403`: that refusal is about your credential rather
+than about the record, and section 10 carries both.
+
+## 10. When a draw comes up short, and when a call is refused
+
+**The first five rows are not errors.** A draw that comes back short is an ordinary `200` carrying
+an `empty_reason` — the state a new game's pool is in most of the time — and it is in this table
+because a match-start screen has to handle it beside the refusals, not because it is one.
+
+Everything below them is a refusal, thrown as a typed error, and what you branch on is not the HTTP
+status — one status covers several distinct refusals. **Branch on `err.code` where the platform
+sent one and on `err.reason` otherwise.** These routes do send `code`, which is what makes the
+table below actionable.
+
+| What you get | What happened | What to do |
+| --- | --- | --- |
+| `200` with `empty_reason: "empty_pool"` | No records exist for this type and version at all | Offer single-player; retrying does not create a pool |
+| `200` with `empty_reason: "version_retired"` | The version is not one this type currently accepts — undeclared, or declared and retired | Check the version you ship against the type listing before blaming the pool |
+| `200` with `empty_reason: "all_excluded"` | Records exist and are live; `exclude_self` or your exclusion list removed every one | Clear the exclusions accumulated this session and draw again |
+| `200` with `empty_reason: "all_expired"` | Records exist but every one has expired | Raise `ttl_seconds`, or push more often — your cadence is slower than the type's TTL |
+| `200` with `empty_reason: "pool_exhausted"` | Fewer than `count` survived expiry, exclusions and one-per-entity — **and it is also the answer when the cause cannot be pinned down** | Play the ones you got and draw again shortly; do not read it as a diagnosis |
+| `404 async_opponent_not_found` on a fetch | The record expired, or its slot was recycled since your draw | Fall back to a fresh draw; this is ordinary play, not an error state |
+| `404 async_opponent_not_found` on a withdraw | Already expired, already recycled, written under another channel, or a record for an entity you may not address — a drawn id lands here | Treat it as already gone, and withdraw only ids for entities your player owns |
+| `400 async_opponent_property_invalid` | A property the version's schema does not accept, or the wrong type for one it does | Re-read that version's schema from the type listing; the same push will not start working |
+| `400 async_opponent_payload_too_large` | The payload is over the type's `max_payload_bytes` | Push less, or raise the ceiling on the type |
+| `400 async_opponent_payload_not_permitted` | The type declares no `max_payload_bytes`, so it takes no payload | Drop the payload, or declare a ceiling on the type |
+| `400 too_many_exclusions` | More than 50 entries in `exclude_opponent_ids` | Bound the list you keep — the fifty most recent |
+| `403 async_opponent_type_not_player_writable` | A player token pushed to a type only game servers may write | Push from your server bundle, or open the type |
+| `403 async_opponent_property_not_client_writable` | A player push set a property the version does not declare `client_writable` | Declare the property writable, or leave it for the server half to write |
+| `403 forbidden` on a withdraw | The credential is not a game-scoped writer, decided before any record is read — or the record moved entity under the delete | Withdraw with the token your frame holds, or from your server bundle |
+| `404 async_opponent_type_not_found` | Your active config declares no type with that slug or id | Re-read the type listing; do not retry the call |
+| `404 async_opponent_version_retired` on a push | The version is undeclared or inactive; the draw answers the same input with `empty_reason: "version_retired"` | Ship a version the config declares, and check it at startup rather than at push time |
+| `404 no_config_assigned` | The channel has no assigned config version at all | Promote a config to this channel; a reason to stop asking rather than to retry |
+| `404 not_found` on a push | The `entity_id` is not one this caller may write for — the same answer as an id naming nothing | Push only for entities your player owns |
+| `429 rate_limited` | This address is over the route's per-minute budget | Back off for the wait `err.retryAfterSeconds` names |
+| `429 async_opponent_contended` | This entity's records were being written concurrently; the budget is not the problem | Retry shortly; a second attempt usually lands |
+| `503 service_unavailable` on a push | The limiter refused the push itself, rather than the platform being short of capacity — it says nothing about your record | Retry it; the record was neither written nor rejected |
+
+**`err.retryAfterSeconds` is a whole number of seconds when the server named a wait, and missing
+when it did not** — which means "no estimate", never "do not retry". `err.retryable` is the field
+that answers that.
+
+**A session that cannot be refreshed is not in this table.** The SDK replays a `401` against a
+fresh token and, if that fails too, raises `AuthError` rather than `GemApiError` — a different
+class, and one that carries no `retryable` at all. A `catch` written from this table alone falls
+through it, and at match start that is the gameplay-blocking path.