@indiegems/gem-web-sdk 20.0.0 → 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",

package/schema/capabilities.public.json

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