@indiegems/gem-web-sdk 16.0.1 → 16.2.0

package/docs/saving-player-progress.md

@@ -150,6 +150,163 @@ silently. Use `putBytes` and `getBytes`, and name the content type you are actua
 `saves` exactly like the player's, scoped to that character — the same declared slots, separate
 stored saves. Most browser games have no characters and can ignore this.
 
+## Handling the common cases
+
+The one failure that does real harm is a game that could not load the player's save, started
+from defaults, and then saved — over the player's real progress. Everything in this section is
+about never doing that, and about not hammering the platform while you avoid it.
+
+### Load before you save
+
+**Load a slot with `get` (or `getBytes`) before you first write it.** The SDK remembers, per
+slot, the version that load found, and sends it with every write. The platform then refuses any
+write that would replace a save you have not seen: one another device or tab wrote since your
+load. Each successful write updates the version, so you never pass it yourself.
+
+What the SDK knows about a slot decides what a write to it does:
+
+| The slot's last load or write here | What a write sends                       | It is refused when                    |
+| ---------------------------------- | ---------------------------------------- | ------------------------------------- |
+| found a save, or wrote one         | that save's version                      | the stored save is a different one    |
+| found no save, or deleted it       | "only if there is still no save"         | a save has appeared since             |
+| **failed**                         | nothing — the SDK refuses it before that | always, until a load succeeds         |
+| never happened in this session     | no condition, as before                  | never; a write here replaces anything |
+
+`describe` and `list` do not count as a load: they read records, not your progress.
+
+### When the load fails
+
+A failed load (a `rate_limited` answer, a timeout, the player offline) means you do not know
+what is stored. **Never write defaults over an unknown save.** Instead:
+
+- keep the game playable, but do not save, and say so if the player would expect it to;
+- retry the load later, with a backoff, and resume saving once one succeeds;
+- if the player chooses to start over, write with `overwrite: true` — the only way past it.
+
+A write to a slot whose last load failed is refused with `GemSaveError` reason `load_failed`
+before anything is sent. It is your safety net, not the plan: check the load's result instead.
+
+```js
+let canSave = false;
+let state = defaults();
+
+async function load() {
+  try {
+    const saved = await gem.me.saves.get('campaign', { timeoutMs: 5000 });
+    if (saved) state = saved;
+    canSave = true; // a null means a new player, and saving is safe
+  } catch {
+    setTimeout(load, 30_000); // play on, unsaved, and try again later
+  }
+}
+```
+
+A load that fails after an earlier one succeeded keeps the earlier version: you still hold that
+copy, and a write conditioned on it is as safe as it was.
+
+### Don't let the boot read hold the game
+
+Give the boot read a short `timeoutMs`, a few seconds, and if it fails start the game anyway in
+the unsaved state above, rather than holding the loading screen. A load that meets a rate limit
+whose wait will not fit in that `timeoutMs` does not sleep through it: it rejects at once as
+`rate_limited` (below), so the loading screen is not held either way.
+
+### When a save conflicts
+
+A write refused because the stored save changed rejects as `GemSaveError` reason
+`save_conflict`. Nothing was written. Resending the same write fails the same way, so:
+
+1. load the slot again (`get`), which learns the new version;
+2. decide what to write: merge the two, keep the stored one, or ask the player which to keep;
+3. write the result, which now replaces the version you just loaded.
+
+To keep this device's progress after asking the player, write with `overwrite: true`.
+
+### Save on events, and debounce
+
+Save when something worth keeping happens — a level cleared, a purchase, a run ended — never on
+a frame timer or on every change. When changes come fast, wait until they stop for a few
+seconds, then write once.
+
+**The SDK keeps one write per slot in flight, and spaces them.** A `put` made while another to
+the same slot is in flight waits for it, and a later `put` replaces the one waiting: the newest
+value is the one sent, and every call it replaced resolves with the same record. Writes to one
+slot go out at least five seconds apart; a write made sooner waits its turn, though never past
+half its own `timeoutMs`. This is a floor under your game, not a debounce: it keeps a runaway save
+loop to a few writes a minute, but your own debounce is still what decides how often you save.
+
+A replaced call keeps its own options. Its `signal` and `timeoutMs` still reject that call alone,
+without cancelling the newer write; the write that goes out runs on the newest call's. Its
+`teardown` and `overwrite` still apply to that write: an autosave that lands behind your teardown
+flush does not make it wait out the spacing, and one that lands behind a confirmed "new game"
+still overwrites. A call that gives up first takes its `teardown` and `overwrite` with it. So
+does a call replaced after the signed-in player changed: it is refused as `save_conflict`, so one
+player's "new game" never overwrites the next player's save.
+
+**Do not re-save immediately because the state changed while a write was in flight.** That loop
+writes back to back, defeats any debounce, and spends the rate limit every other player behind
+the same network address shares. The spacing above limits the damage; it does not make the loop
+right. Wait out the debounce again.
+
+```js
+let dirty = false;
+let writing = null;
+let timer = null;
+
+function changed() {
+  dirty = true;
+  clearTimeout(timer);
+  timer = setTimeout(flush, 5000);
+}
+
+async function flush() {
+  if (writing || !dirty || !canSave) return;
+  dirty = false;
+  writing = gem.me.saves.put('campaign', state).catch(onSaveError);
+  await writing;
+  writing = null;
+  if (dirty) changed(); // wait the debounce again, never write at once
+}
+```
+
+### On a 429, back off
+
+A save or load refused for the rate rejects as `GemApiError` reason `rate_limited`, with
+`retryAfterSeconds` when the platform named a wait. **That is the one shape, whichever leg was
+refused**: the platform's checks, the upload or download of the bytes, or a wait the platform
+asked for that your call's `timeoutMs` will not cover, which rejects at once instead of
+sleeping. So one test covers every save loop:
+
+```js
+function onSaveError(err) {
+  if (err instanceof GemApiError && err.reason === 'rate_limited') {
+    holdSavesFor(err.retryAfterSeconds ?? 60); // keep the state dirty
+  }
+}
+```
+
+**Never retry at once.** Hold every write for at least `retryAfterSeconds` (a minute if it is
+absent), keep the state dirty, and write once when the wait is over. A rate-limited load is the
+"load fails" case above.
+
+The SDK holds too. After a `rate_limited` answer on any leg, it sends no write for the wait the
+answer named: a write made meanwhile waits for it, or, when the wait outlasts its `timeoutMs`,
+rejects at once as `rate_limited` without being sent.
+
+In earlier releases of this SDK, the same refusal could also arrive as a `save_timeout` from a call whose `timeoutMs`
+ran out while it waited out a rate limit, or as an `upload_failed` whose message named a 429. A
+game that matched on either can drop it.
+
+### Saving on teardown
+
+`onWillTerminate` gives you `graceMs`, and Back, a closed tab or a reload give you nothing. Keep
+your last save recent, and in the callback flush only what changed, with a `timeoutMs` inside the
+grace and `teardown: true` — see [Saving against a deadline](#saving-against-a-deadline).
+`teardown` sends the write without waiting for the spacing between writes; it still waits for a
+write already in flight to that slot, and still honours a rate-limit hold, rejecting at once as
+`rate_limited` when the hold outlasts the grace. Skip the flush when the slot cannot be saved (its
+load failed) or your own rate-limit hold is active.
+
 ## Showcase slots: a little progress your friends can read
 
 Everything above is the player's own document, read back by the same player. A **showcase
@@ -285,7 +442,10 @@ const gem = createGem({
     // The parent told you how long it will wait. Spend a little less than that,
     // so a failure still has somewhere to be handled.
     gem.me.saves
-      .put('campaign', state, { timeoutMs: Math.max(1000, notice.graceMs - 500) })
+      .put('campaign', state, {
+        timeoutMs: Math.max(1000, notice.graceMs - 500),
+        teardown: true, // skip the spacing between writes; see "Saving on teardown"
+      })
       .catch(report);
   },
 });
@@ -293,9 +453,11 @@ const gem = createGem({
 
 `timeoutMs` is on `put`, `putBytes`, `get` and `getBytes`; it covers every hop together, and it
 is a ceiling rather than a target — it does not make a save faster, it decides when to stop
-waiting for one. A save that misses it rejects as `GemSaveError` with reason `save_timeout`,
+waiting for one. It counts from the call, so a write waiting for the one before it on the same
+slot spends it waiting. A save that misses it rejects as `GemSaveError` with reason `save_timeout`,
 naming the budget you gave it rather than the default, so a log tells you which of the two you
-were running under.
+were running under. A rate limit whose wait it will not cover is not a miss: that rejects at once
+as `rate_limited`.
 
 **The save that fits a teardown window is a small one.** Nothing here turns three round trips
 into fewer, so the durable answer is not to be holding a megabyte of unsaved progress when the
@@ -310,7 +472,7 @@ clock starts — save on the events that matter, and let the teardown flush be a
 | `precondition_failed` | something else saved this slot while yours was in flight                                                         | re-read, rebuild, save again — **never** retry the same payload                              |
 | `too_large`           | the payload is over the slot's ceiling, or this player's or this game's save storage is full — `code` says which | **do not retry.** Store less or raise `max_size_bytes`; or delete a save, or tell the player |
 | `forbidden`           | the player's session ended while the save was in flight                                                          | a fresh session, not a retry                                                                 |
-| `rate_limited`        | too many save calls from this network address                                                                    | back off by what it tells you; then save less often                                          |
+| `rate_limited`        | too many save calls from this network address, refused on any leg of the save or load                            | back off by what it tells you; then save less often                                          |
 | `GemSaveError`        | the payload could not be pushed to or pulled from storage                                                        | see below                                                                                    |
 
 **`too_large` is the one to get right.** It used to reach game code labelled as a retryable
@@ -323,7 +485,11 @@ loop to enter.
 **`GemSaveError` is the half that does not go through the API.** Your payload travels to and
 from storage over a short-lived signed link, so a failure there is not an API error and cannot
 be classified as one. It carries `reason`: `upload_failed`, `download_failed`, `save_timeout`,
-or `save_malformed` for a payload that is not what it claims.
+or `save_malformed` for a payload that is not what it claims. Two more refuse a write to keep
+the player's progress safe, and neither is worth retrying as it stands: `save_conflict`, the
+stored save changed since you loaded it, and `load_failed`, the slot's last load failed. See
+[Handling the common cases](#handling-the-common-cases). A rate limit on the storage leg is not a
+`GemSaveError`: it is `GemApiError` reason `rate_limited`, like every other leg's.
 
 **If you see `upload_failed` on every save, from every player, in a browser** — that is not a
 transient fault and no amount of retrying moves it. Two causes have that shape, both platform

package/docs/server-bundles.md

@@ -80,8 +80,8 @@ To check the download yourself: the package npm serves is, byte for byte, the fi
 also publishes on its download host, with the hash beside it:
 
 ```bash
-curl -fsSL -O https://downloads.gemarcade.com/sdk/v16.0.1/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v16.0.1/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v16.2.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v16.2.0/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiegems/gem-web-sdk",
-  "version": "16.0.1",
+  "version": "16.2.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",

package/schema/bridge.v1.json

@@ -4470,6 +4470,11 @@
           "maxLength": 32,
           "optional": true,
           "$comment": "The game's own name for the screen it is leaving - 'world-1-3', 'results'. UNTRUSTED TEXT. Shown ONLY in a development host's log, so a reviewer can map moments to screens. NEVER FORWARDED TO THE PLATFORM, NEVER STORED, NEVER RENDERED TO A PLAYER AND NEVER SENT TO AN AD NETWORK: a game-authored string that fits this grammar fits a dashless UUID too. The SDK sends only `^[a-z0-9_-]{1,32}$`; codegen emits type and length only, so the charset is the sender's to keep and the receiver's to re-check."
+        },
+        "wall": {
+          "kind": "boolean",
+          "optional": true,
+          "$comment": "`true` - THE GAME ACCEPTS THAT THE PLATFORM MAY SHOW ITS APP WALL AT THIS BREAK: a panel that may leave the player no way on in this browser, so a game sets it only at a break where its progress is already saved and stopping there is acceptable. Absent or `false` is an ordinary break, exactly as before this field existed; the SDK sends it only as `true`. AN ACCEPTANCE, NOT AN ASK: the parent's arbiter still decides, under its own mode, whether anything is shown, and usually nothing is. It only ever widens what the platform may do over THIS game, so a frame that lies about it costs only itself, and it is never a reason to show anything to anyone else. An N-1 parent ignores it as an unknown field and treats the break as ordinary."
         }
       },
       "rateLimit": {