@indiegems/gem-web-sdk 19.0.2 → 20.1.0

package/schema/bridge.v1.json

@@ -1790,8 +1790,11 @@
         "deliberately: a frame that took its JWKS endpoint from a relayed message",
         "would let the parent choose the keys it verifies peers against.",
         "",
-        "The nine events are the whole vocabulary; an unrecognised p2p_* type is",
-        "a drop at the parent, not a passthrough.",
+        "The nine events are the whole vocabulary of this message; an",
+        "unrecognised p2p_* type is a drop at the parent, not a passthrough. The",
+        "relay drain notice is the one further push the parent relays, and it",
+        "crosses as its own type, gem.relayDraining: this enum is closed, so a",
+        "tenth value would be refused by every frame already shipped.",
         "",
         "PARENT TO FRAME ONLY. gem.signal is the other direction."
       ],
@@ -1824,6 +1827,68 @@
       "rateLimit": { "perMinute": 1800 }
     },
 
+    {
+      "type": "gem.relayDraining",
+      "direction": "parentToFrame",
+      "transport": "port",
+      "$comment": [
+        "A TURN relay this player's P2P match may be using is going away, relayed",
+        "from gem-api's `p2p_relay_draining`. Gated by the `p2pRelayDrain`",
+        "capability; the mapping lives in schema/capabilities.json and nowhere",
+        "else.",
+        "",
+        "A HINT, AND ONE THE FRAME COULD SURVIVE WITHOUT. It tells the frame to",
+        "re-lease and, where its selected candidate pair runs through one of",
+        "these relays, to restart ICE on the connection it already has, so the",
+        "match moves before the relay stops rather than after. The control is",
+        "the relay's own: a draining relay refuses new allocations whatever",
+        "this message says, and a connection on it fails over by the ordinary",
+        "path when it stops. A parent that rewrites this can cost a frame a",
+        "renegotiation; it cannot move a connection anywhere.",
+        "",
+        "ITS OWN TYPE, NOT A TENTH VALUE IN gem.signalEvent'S ENUM: the",
+        "generated validator rejects an unknown enum value, and every frame",
+        "already shipped would answer `invalid_message`. A parent sends this",
+        "only to a frame that advertised the capability and drops it otherwise.",
+        "",
+        "SCOPED BY MATCH, NOT BY GAME. gem-api stamps the push with no game id,",
+        "as it does `p2p_error`, so the parent relays it only for a match this",
+        "player's socket or this frame has already named.",
+        "",
+        "PARENT TO FRAME ONLY. A frame-authored drain notice would let a game",
+        "tell the parent a relay is going away."
+      ],
+      "fields": {
+        "matchId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "The match whose relays are draining. The frame acts only for the live session on this match."
+        },
+        "clusterTargetId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "The cluster the draining relays belong to. It decides nothing on the frame: the re-lease asks the cluster the session already leases from."
+        },
+        "relayIps": {
+          "kind": "array",
+          "maxItems": 16,
+          "items": { "kind": "string", "maxLength": 64 },
+          "$comment": "The draining relays' public addresses — the hosts in the lease's `turn:` URLs, and what a selected candidate pair names. A lease names at most three relays."
+        },
+        "drainingSince": {
+          "kind": "string",
+          "maxLength": 40,
+          "$comment": "RFC 3339. When the relays began draining."
+        },
+        "deadline": {
+          "kind": "string",
+          "maxLength": 40,
+          "$comment": "RFC 3339. When the relays stop relaying. A link still on one by then is dropped and re-dialled; one this side cannot parse is read as the drain ceiling, thirty minutes."
+        }
+      },
+      "rateLimit": { "perMinute": 60 }
+    },
+
     {
       "type": "gem.dedicatedEvent",
       "direction": "parentToFrame",
@@ -3819,11 +3884,11 @@
         "  balance a player paid for is the rest of this list, and these four are",
         "  the ones the old argument stood in for:",
         "",
-        "    - THE CONFIRMATION IS THE PARENT'S, and it costs a gesture. The sheet is",
-        "      drawn in the parent's own chrome from platform records, and only on",
-        "      user activation (below).",
-        "    - A DISMISSAL BACKS OFF, and the confirm control is quiet after paint",
-        "      (both below; the arcade holds the quiet period for 400 ms).",
+        "    - THE CONFIRMATION IS THE PARENT'S. The sheet is drawn in the",
+        "      parent's own chrome from platform records, and only the player's own",
+        "      press on its confirm control spends.",
+        "    - THE CONFIRM CONTROL IS QUIET AFTER PAINT (below; the arcade holds",
+        "      the quiet period for 400 ms).",
         "    - A SHORTFALL IS NEVER A SALE. `insufficient_funds` gets no top-up, no",
         "      upsell and no way into a store from THIS sheet. A game MAY open the",
         "      arcade's store for one of the store's own SKUs -",
@@ -3842,18 +3907,14 @@
         "  price, quantity and total distinctly so a 10x multiplier is never hidden",
         "  behind one figure.",
         "",
-        "  ONLY ON USER ACTIVATION. Render nothing, and answer `declined` with",
-        "  reason `busy`, unless `navigator.userActivation.isActive` is true when",
-        "  the ask arrives. A click or key press in the game frame activates the",
-        "  parent page too, so a Buy button works and a timer does not. It is the",
-        "  browser's own signal, so keyboard and assistive-technology activation",
-        "  count. This is the control that makes `cancelled` (gem.purchaseResult)",
-        "  safe to disclose: a prompt costs a real player's gesture.",
-        "",
-        "  BACK OFF AFTER A CANCEL. After a `cancelled`, answer further asks from",
-        "  that game `declined` / `busy` without rendering, for an interval that",
-        "  grows with each consecutive cancel. Without it, 'ask, learn cancelled,",
-        "  ask again' is a re-prompt loop a game can write in three lines.",
+        "  NO PRESS, AND NO BACK-OFF (owner decision).",
+        "  Arcade games are developed in-house and trusted, and a limit between",
+        "  a player and a purchase refused players who wanted to buy. So the",
+        "  parent renders the sheet for an ask from a timer or after an await as",
+        "  for one from a click - `navigator.userActivation` is not read - and a",
+        "  sheet the player closed never makes the next ask wait: it is answered",
+        "  `cancelled`, and the game's next ask opens a sheet. The sheet itself",
+        "  is the confirmation; a game cannot press it.",
         "",
         "  ONE PROMPT AT A TIME, and not instantly actionable. A gem.requestPurchase",
         "  arriving while a prompt is open is answered `declined` / `busy` without",
@@ -3960,9 +4021,9 @@
         "EVERY OBLIGATION ON `gem.requestPurchase` APPLIES HERE, UNCHANGED:",
         "payable currencies only, resolved exactly; price it yourself from",
         "platform records, under the player's session (the offer's price in",
-        "`currencySlug`); the confirmation is the parent's own sheet, on user",
-        "activation only; back off after a cancel; one prompt at a time, quiet",
-        "after paint; one purchase per ask; meter it in money, server-side;",
+        "`currencySlug`); the confirmation is the parent's own sheet, with no",
+        "press required and no back-off; one prompt at a time, quiet after",
+        "paint; one purchase per ask; meter it in money, server-side;",
         "treat every field as untrusted text. A shortfall is never a sale.",
         "",
         "AND THREE OF ITS OWN:",
@@ -4056,13 +4117,14 @@
         "a game nothing it cannot already read.",
         "",
         "THE ONE ADDED DISCLOSURE IS `cancelled`: what the player chose in",
-        "platform UI. It is behavioural data, and it is what makes an instant",
-        "re-prompt loop cheap - ask, learn 'cancelled', ask again. It ships with",
-        "two parent-side controls, stated as obligations on gem.requestPurchase:",
-        "ONLY ON USER ACTIVATION (no prompt without a real gesture) and BACK OFF",
-        "AFTER A CANCEL (further asks answered `busy`, unrendered, for a growing",
-        "interval). A parent that cannot enforce both must not send `cancelled`;",
-        "it sends `error` in its place.",
+        "platform UI. It first shipped behind two parent-side controls - user",
+        "activation, and a back-off after a cancel - against a game that asks,",
+        "learns 'cancelled' and asks again. Both were removed by owner decision:",
+        "Arcade games are developed in-house and trusted,",
+        "and the back-off refused players who wanted to buy. A parent sends",
+        "`cancelled` when the player dismissed a sheet they could afford, and",
+        "answers the game's next ask on its merits. A parent older than that",
+        "decision may send `error` in its place; read both as 'not bought'.",
         "",
         "EVERY OUTCOME RESOLVES. Only a protocol failure rejects. A player tapping",
         "Cancel is an ordinary thing that happens in every shop, and rejecting there",
@@ -4098,7 +4160,7 @@
         "outcome": {
           "kind": "enum",
           "values": ["ok", "declined", "unavailable"],
-          "$comment": "THREE VALUES, AND THAT IS THE COMPLETE VOCABULARY OF WHAT TO DO. The WHY is `reason`, a bounded string, so the explanations can grow without this enum growing - which matters because `check-schema-freeze` treats a new enum value as breaking (an N-1 receiver refuses it, and a refused `declined` becomes a two-minute timeout and an `unavailable`). A game branches its money logic on this field and on a re-read of inventory, never on `reason`. THE TIMING CHANNEL: a refusal the parent reaches without rendering anything is separable from a human Cancel by latency. That used to be the gap the no-reason rule left open; with `reason` sent, it tells a game nothing `reason` and `gem.platform.currencies.get()` do not already say. What still matters is how fast a game can ask, and user activation plus the cancel back-off bound that at human speed."
+          "$comment": "THREE VALUES, AND THAT IS THE COMPLETE VOCABULARY OF WHAT TO DO. The WHY is `reason`, a bounded string, so the explanations can grow without this enum growing - which matters because `check-schema-freeze` treats a new enum value as breaking (an N-1 receiver refuses it, and a refused `declined` becomes a two-minute timeout and an `unavailable`). A game branches its money logic on this field and on a re-read of inventory, never on `reason`. THE TIMING CHANNEL: a refusal the parent reaches without rendering anything is separable from a human Cancel by latency. That used to be the gap the no-reason rule left open; with `reason` sent, it tells a game nothing `reason` and `gem.platform.currencies.get()` do not already say. What still matters is how fast a game can ask: games are trusted, so nothing paces a game's asks beyond one prompt at a time and the rate limit."
         },
         "reason": {
           "kind": "string",
@@ -4138,9 +4200,8 @@
             "  the target is not in the purchase catalog,  declined     not_purchasable",
             "    or is not purchasable",
             "  the target has no price in that currency    declined     no_price_in_currency",
-            "  a sheet is already open, a purchase is in   declined     busy",
-            "    flight, a cancel back-off is running, or",
-            "    the ask arrived without user activation",
+            "  a sheet is already open, or a purchase is   declined     busy",
+            "    in flight",
             "  the player dismissed a sheet they could     declined     cancelled",
             "    afford",
             "  a shortfall shown on the sheet, or gem-api  declined     insufficient_funds",
@@ -5013,8 +5074,9 @@
         "`appLinks` capability. Answered by `gem.openAppResult`.",
         "",
         "AN ACTING MESSAGE. It leaves the game, so the parent holds it to the",
-        "rules every acting message shares (gem.requestOpenGame and",
-        "gem.requestStorePurchase state them too):",
+        "rules every acting message shares (gem.requestOpenGame states them",
+        "too; a purchase - gem.requestStorePurchase, gem.requestPurchase -",
+        "shares all of them but the press):",
         "",
         "  A PERSON MUST HAVE PRESSED. Read `navigator.userActivation.isActive`",
         "  synchronously on receipt, before any `await`, or accept a controller",
@@ -5507,10 +5569,12 @@
         "listing, takes money only on the payment provider's page or the",
         "operating system's purchase sheet, and tells the game the outcome.",
         "",
-        "AN ACTING MESSAGE, under every rule gem.requestOpenApp states: a press",
-        "the parent can see (a missing `userActivation` API fails closed), one",
-        "acting message at a time across all of them, both checked before",
-        "`skuId` is resolved, and the answer bound to this frame session. And:",
+        "AN ACTING MESSAGE: one acting message at a time across all of them,",
+        "checked before `skuId` is resolved, and the answer bound to this frame",
+        "session. UNLIKE gem.requestOpenApp AND gem.requestOpenGame IT NEEDS NO",
+        "PRESS (owner decision): a purchase asked from a",
+        "timer or after an await opens its checkout as one asked from a click",
+        "does, because the checkout is the confirmation. And:",
         "",
         "  ONLY A SKU IT WOULD LIST. `skuId` must be one gem.storeOffersResult",
         "  would list to this player right now; anything else is `unavailable`",
@@ -5528,14 +5592,13 @@
         "  bought again yet, the parent says when, in its own chrome, and",
         "  answers `declined` / `cancelled` - the answer a closed checkout gets,",
         "  so the cooldown, which would reveal a recent purchase, never crosses",
-        "  the bridge. It starts no back-off: the player turned nothing down.",
+        "  the bridge.",
         "",
-        "  BACK OFF AFTER A DISMISSAL. `cancelled` is disclosed, so after the",
-        "  player closes a checkout a game started, further asks from that game",
-        "  are `declined` / `busy`, unrendered, for an interval that grows with",
-        "  each dismissal (the Arcade: 30 s, 2 min, 10 min, then the rest of the",
-        "  session). Only the player closing it starts the back-off: a failed",
-        "  payment, `error` and `ok` / `pending` do not.",
+        "  NO BACK-OFF (owner decision). A player who",
+        "  closed a checkout and asks again gets the checkout again, however many",
+        "  times; a player who paid and buys the same SKU again gets a new",
+        "  checkout. Only one checkout is on screen at a time, so an ask while",
+        "  one is open is `busy` - the moment it ends, the next ask opens.",
         "",
         "  RESUME, THEN ANSWER. The result is sent after the game has been told",
         "  it is resumed, so the game's own celebration is visible.",
@@ -5560,7 +5623,7 @@
       },
       "rateLimit": {
         "perMinute": 12,
-        "$comment": "gem.requestPurchase's limit and its argument: it bounds a BUGGY game, not a hostile one. What bounds the player's experience is the activation check, the one-at-a-time rule and the back-off."
+        "$comment": "gem.requestPurchase's limit and its argument: it bounds a BUGGY game, not a hostile one, at a rate no player buying by hand reaches. What bounds the player's experience is the one-at-a-time rule."
       }
     },
     {
@@ -5578,9 +5641,9 @@
         "                the player left before it did): `gem.storePurchaseSettled`",
         "                follows when it does, and a game re-reads on resume too.",
         "  declined    - nothing was bought: the player closed the checkout,",
-        "                or the offer is cooling down (`cancelled`); or no",
-        "                press, another acting message open or a back-off",
-        "                running (`busy`).",
+        "                or the offer is cooling down (`cancelled`); or another",
+        "                acting message was open (`busy`). Either way the",
+        "                game's next ask is answered on its merits.",
         "  unavailable - no sale the parent can vouch for. With `store_off`",
         "                (the store withheld), `sign_in_required` (a guest),",
         "                `not_found` (an unknown SKU) or the provider's own",
@@ -5659,18 +5722,17 @@
         "gem.requestStorePurchase opens.",
         "",
         "EVERY RULE OF gem.requestStorePurchase HOLDS, and it shares them rather",
-        "than having its own: an acting message (a press the parent can see, one",
-        "at a time across all of them, both checked before `skuId` is resolved,",
-        "the answer bound to this frame session); only a SKU the parent would",
-        "list now; an offer cooling down opens nothing and answers `declined` /",
-        "`cancelled`; the SAME back-off, so a game cannot escape one by switching",
-        "message; resume, then answer; evidence, not accounting.",
+        "than having its own: an acting message (one at a time across all of",
+        "them, checked before `skuId` is resolved, no press needed, the answer",
+        "bound to this frame session); only a SKU the parent would list now; an",
+        "offer cooling down opens nothing and answers `declined` / `cancelled`;",
+        "no back-off; resume, then answer; evidence, not accounting.",
         "",
         "THE SHEET IS NOT A SECOND CONFIRMATION, and it does not change",
         "gem.requestStorePurchase's straight-to-checkout rule. It is the pitch;",
         "the checkout is still the confirmation, with its own pay control. The",
         "player leaving the sheet without pressing Buy is a dismissal, exactly",
-        "as closing a checkout is, and starts the back-off.",
+        "as closing a checkout is.",
         "",
         "A PARENT THAT ADVERTISES `storeOfferSheet` ADVERTISES `store`: the",
         "game's SKU comes from gem.storeOffersResult, and a purchase that answers",
@@ -5693,7 +5755,7 @@
       },
       "rateLimit": {
         "perMinute": 12,
-        "$comment": "gem.requestStorePurchase's limit and its argument: it bounds a BUGGY game, not a hostile one. What bounds the player's experience is the activation check, the one-at-a-time rule and the back-off."
+        "$comment": "gem.requestStorePurchase's limit and its argument: it bounds a BUGGY game, not a hostile one, at a rate no player buying by hand reaches. What bounds the player's experience is the one-at-a-time rule."
       }
     },
     {
@@ -5710,8 +5772,8 @@
         "                gem.storePurchaseSettled follows when it does.",
         "  declined    - nothing was bought: the player left the sheet or closed",
         "                the checkout, or the offer is cooling down (`cancelled`);",
-        "                or no press, another acting message open or a back-off",
-        "                running (`busy`).",
+        "                or another acting message was open (`busy`). Either way",
+        "                the game's next ask is answered on its merits.",
         "  unavailable - no sale the parent can vouch for. With `store_off`,",
         "                `sign_in_required`, `not_found` or the provider's own",
         "                failure code, nothing was bought. With `error`, the",

package/schema/capabilities.public.json

@@ -308,6 +308,12 @@
       "gates": [
         "gem.menuStyle"
       ]
+    },
+    "p2pRelayDrain": {
+      "implemented": true,
+      "gates": [
+        "gem.relayDraining"
+      ]
     }
   }
 }