@irtio/protocol 0.8.0 → 0.9.0

package/dist/index.d.ts

@@ -275,7 +275,47 @@ declare const ErrorCode: {
         readonly code: 34;
         readonly message: "room {roomId} was deleted by an operator; its stored state is gone";
     };
+    /**
+     * The box dropped this client because the socket stopped answering, not because anything about
+     * the game went wrong.
+     *
+     * Two mechanisms end here, and they are the two ways a client can be alive on paper and useless
+     * on the wire. The keepalive: the supervisor pings every {@link IDLE_PING_MS} and drops a
+     * session that has missed {@link IDLE_PING_MISSES} pongs, so a socket has about
+     * `IDLE_PING_MS * (IDLE_PING_MISSES + 1)` of silence before it goes. And the slow consumer:
+     * a client whose receive buffer keeps growing gets {@link ErrorCode.E_SLOW_CONSUMER} instead,
+     * which is the same family of problem said more precisely.
+     *
+     * Its own code because the alternative is what the platform did before: `terminate()`, which
+     * gives the browser a 1006 with no code and no reason, indistinguishable from a lost network,
+     * a crashed box and a closed room. A client that can read this can say "you were disconnected
+     * for being idle" and reconnect, which is the right move — nothing was lost and the room is
+     * still there. Not fatal, for that reason.
+     *
+     * Close code {@link CLOSE_IDLE_TIMEOUT}.
+     */
+    readonly E_IDLE_TIMEOUT: {
+        readonly code: 35;
+        readonly message: "connection idle: no response to {misses} keepalives over {seconds}s";
+    };
 };
+/**
+ * How often the box pings an open session, and how many unanswered pings it takes to drop it.
+ *
+ * Named here rather than only at the drop site because they are the two numbers a client author
+ * has to know to tell an idle drop from an outage, and the documented threshold has to come from
+ * the same constant the box enforces.
+ */
+declare const IDLE_PING_MS = 20000;
+declare const IDLE_PING_MISSES = 2;
+/**
+ * The WebSocket close code for {@link ErrorCode.E_IDLE_TIMEOUT}.
+ *
+ * In the application range beside {@link CLOSE_EGRESS_WALL} and {@link CLOSE_ROOM_DELETED}, for
+ * their reason: the client's `onclose` carries `{ code, reason }`, and a close a client should
+ * quietly reconnect from has to be distinguishable from one it must not.
+ */
+declare const CLOSE_IDLE_TIMEOUT = 4408;
 /**
  * The WebSocket close code the router uses for {@link ErrorCode.E_PLACEMENT}: RFC 6455's 1013,
  * "try again later". Distinct from the 1008 policy close and the 1011 internal-error close the
@@ -1611,4 +1651,4 @@ declare function originAllowed(origins: readonly string[], allowNoOrigin: boolea
  */
 declare function parseOriginList(raw: string | undefined): readonly string[];
 
-export { type AttributeOptions, BUS_CHANNEL_RE, BUS_ERRORS, BUS_LIMITS, BUS_MAILBOX_PREFIX, BUS_OUTBOX, BUS_OUTBOX_PREFIX, BUS_SHARD_STARTING, type BusErrorCode, type BusMailboxEntry, type BusOutboxEntry, type BusProblem, CLOSE_EGRESS_WALL, CLOSE_ROOM_DELETED, CLOSE_TRY_AGAIN_LATER, CODE_ALPHABET, CPU_QUOTA_PCT_MAX, CPU_QUOTA_PCT_MIN, type Call, type ChurnIds, type ClientCallable, type Credential, DEFAULT_MAX_AWAKE, DEFAULT_MEMORY_MB, DEFAULT_ROOM_TYPE, EMPTY_PROFILE, ERROR_CATALOGUE, type ErrorCatalogueEntry, ErrorCode, type ErrorCodeDef, type ErrorCodeName, type ErrorPayload, type Frame, FrameType, HELLO_SCHEMA_SWAP_BIT, type Hello, MATCH_CODE_LENGTH, MAX_AWAKE_MAX, MSG_KIND_TYPED, type Msg, type MsgTarget, NATIVE_RESERVE_FRACTION, PHYSICS_HEADROOM_MIB, PRESENCE_COLLECTION, PROFILE_KINDS, PROTOCOL_VERSION, type ParsedRoomId, type Ping, type Pong, type PresenceRecord, type ProfileKind, ProfileLedger, type ProfileRow, type ProfileSnapshot, RELAY_HASH8, RETENTION_MAX_MS, RETENTION_MIN_MS, RETENTION_RE, ROOMS_PER_VCPU, ROOM_CLASS_MAX_MB, ROOM_ID_RE, ROOM_MEMORY_MB_MAX, ROOM_MEMORY_MB_MIN, ROOM_TYPE_DELIMITER, ROOM_TYPE_RE, type Reply, type RoomSizeClass, type RoomTypeSizing, SUPERVISOR_BASELINE_MIB, VM_MEM_MIB_MAX, VM_MEM_MIB_MIN, type VmCpuSizing, type VmSizing, type VoiceClientMessage, type VoicePeer, type VoiceServerMessage, type VoiceTransportInfo, type Welcome, YOUNG_GEN_MB, builtinRpcs, busChannelProblem, busPayloadProblem, correctPayload, declarationsFit, decodeCall, decodeErrorPayload, decodeFrame, decodeHello, decodeMsg, decodePing, decodePong, decodeReply, decodeVoiceMessage, decodeWelcome, deltaPayload, diffProfiles, encodeCall, encodeCorrectFrame, encodeDeltaFrame, encodeErrorPayload, encodeFrame, encodeHello, encodeMsg, encodePing, encodePong, encodeReply, encodeSchemaFrame, encodeVoiceMessage, encodeWelcome, encodeWriteFrame, errorByCode, formatError, formatRoomId, isFrameType, isLocalhostOrigin, isMailboxAlarm, isOutboxAlarm, isRelayHash8, isTypedMsg, isVoiceMsg, mergeProfiles, nativeReserveOf, originAllowed, parseOriginList, parseRetention, parseRoomId, presenceEntity, readCorrectAppliedTick, readCorrectClientTick, readSchemaPayload, relaySchema, requestOwnership, roomClassFor, roomClassOfSource, roomHoursSourceFor, rpcByIdOf, rpcIdOf, rpcTable, scaleProfile, schemaPayload, topProfileRows, typeFootprintMib, typedMsgFromClientOk, vmCpuFor, vmSizeFor, withBuiltins, writePayload };
+export { type AttributeOptions, BUS_CHANNEL_RE, BUS_ERRORS, BUS_LIMITS, BUS_MAILBOX_PREFIX, BUS_OUTBOX, BUS_OUTBOX_PREFIX, BUS_SHARD_STARTING, type BusErrorCode, type BusMailboxEntry, type BusOutboxEntry, type BusProblem, CLOSE_EGRESS_WALL, CLOSE_IDLE_TIMEOUT, CLOSE_ROOM_DELETED, CLOSE_TRY_AGAIN_LATER, CODE_ALPHABET, CPU_QUOTA_PCT_MAX, CPU_QUOTA_PCT_MIN, type Call, type ChurnIds, type ClientCallable, type Credential, DEFAULT_MAX_AWAKE, DEFAULT_MEMORY_MB, DEFAULT_ROOM_TYPE, EMPTY_PROFILE, ERROR_CATALOGUE, type ErrorCatalogueEntry, ErrorCode, type ErrorCodeDef, type ErrorCodeName, type ErrorPayload, type Frame, FrameType, HELLO_SCHEMA_SWAP_BIT, type Hello, IDLE_PING_MISSES, IDLE_PING_MS, MATCH_CODE_LENGTH, MAX_AWAKE_MAX, MSG_KIND_TYPED, type Msg, type MsgTarget, NATIVE_RESERVE_FRACTION, PHYSICS_HEADROOM_MIB, PRESENCE_COLLECTION, PROFILE_KINDS, PROTOCOL_VERSION, type ParsedRoomId, type Ping, type Pong, type PresenceRecord, type ProfileKind, ProfileLedger, type ProfileRow, type ProfileSnapshot, RELAY_HASH8, RETENTION_MAX_MS, RETENTION_MIN_MS, RETENTION_RE, ROOMS_PER_VCPU, ROOM_CLASS_MAX_MB, ROOM_ID_RE, ROOM_MEMORY_MB_MAX, ROOM_MEMORY_MB_MIN, ROOM_TYPE_DELIMITER, ROOM_TYPE_RE, type Reply, type RoomSizeClass, type RoomTypeSizing, SUPERVISOR_BASELINE_MIB, VM_MEM_MIB_MAX, VM_MEM_MIB_MIN, type VmCpuSizing, type VmSizing, type VoiceClientMessage, type VoicePeer, type VoiceServerMessage, type VoiceTransportInfo, type Welcome, YOUNG_GEN_MB, builtinRpcs, busChannelProblem, busPayloadProblem, correctPayload, declarationsFit, decodeCall, decodeErrorPayload, decodeFrame, decodeHello, decodeMsg, decodePing, decodePong, decodeReply, decodeVoiceMessage, decodeWelcome, deltaPayload, diffProfiles, encodeCall, encodeCorrectFrame, encodeDeltaFrame, encodeErrorPayload, encodeFrame, encodeHello, encodeMsg, encodePing, encodePong, encodeReply, encodeSchemaFrame, encodeVoiceMessage, encodeWelcome, encodeWriteFrame, errorByCode, formatError, formatRoomId, isFrameType, isLocalhostOrigin, isMailboxAlarm, isOutboxAlarm, isRelayHash8, isTypedMsg, isVoiceMsg, mergeProfiles, nativeReserveOf, originAllowed, parseOriginList, parseRetention, parseRoomId, presenceEntity, readCorrectAppliedTick, readCorrectClientTick, readSchemaPayload, relaySchema, requestOwnership, roomClassFor, roomClassOfSource, roomHoursSourceFor, rpcByIdOf, rpcIdOf, rpcTable, scaleProfile, schemaPayload, topProfileRows, typeFootprintMib, typedMsgFromClientOk, vmCpuFor, vmSizeFor, withBuiltins, writePayload };

package/dist/index.js

@@ -168,9 +168,35 @@ var ErrorCode = {
   E_ROOM_DELETED: {
     code: 34,
     message: "room {roomId} was deleted by an operator; its stored state is gone"
-  }
+  },
   // ---- end M6 lane A ----
+  /**
+   * The box dropped this client because the socket stopped answering, not because anything about
+   * the game went wrong.
+   *
+   * Two mechanisms end here, and they are the two ways a client can be alive on paper and useless
+   * on the wire. The keepalive: the supervisor pings every {@link IDLE_PING_MS} and drops a
+   * session that has missed {@link IDLE_PING_MISSES} pongs, so a socket has about
+   * `IDLE_PING_MS * (IDLE_PING_MISSES + 1)` of silence before it goes. And the slow consumer:
+   * a client whose receive buffer keeps growing gets {@link ErrorCode.E_SLOW_CONSUMER} instead,
+   * which is the same family of problem said more precisely.
+   *
+   * Its own code because the alternative is what the platform did before: `terminate()`, which
+   * gives the browser a 1006 with no code and no reason, indistinguishable from a lost network,
+   * a crashed box and a closed room. A client that can read this can say "you were disconnected
+   * for being idle" and reconnect, which is the right move — nothing was lost and the room is
+   * still there. Not fatal, for that reason.
+   *
+   * Close code {@link CLOSE_IDLE_TIMEOUT}.
+   */
+  E_IDLE_TIMEOUT: {
+    code: 35,
+    message: "connection idle: no response to {misses} keepalives over {seconds}s"
+  }
 };
+var IDLE_PING_MS = 2e4;
+var IDLE_PING_MISSES = 2;
+var CLOSE_IDLE_TIMEOUT = 4408;
 var CLOSE_TRY_AGAIN_LATER = 1013;
 var CLOSE_EGRESS_WALL = 4290;
 var CLOSE_ROOM_DELETED = 4291;
@@ -1305,6 +1331,7 @@ export {
   BUS_OUTBOX_PREFIX,
   BUS_SHARD_STARTING,
   CLOSE_EGRESS_WALL,
+  CLOSE_IDLE_TIMEOUT,
   CLOSE_ROOM_DELETED,
   CLOSE_TRY_AGAIN_LATER,
   CODE_ALPHABET,
@@ -1318,6 +1345,8 @@ export {
   ErrorCode,
   FrameType,
   HELLO_SCHEMA_SWAP_BIT,
+  IDLE_PING_MISSES,
+  IDLE_PING_MS,
   MATCH_CODE_LENGTH,
   MAX_AWAKE_MAX,
   MSG_KIND_TYPED,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@irtio/protocol",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "irtio wire protocol: frames, framing, session payloads, error codes, built-in presence",
   "license": "MIT",
   "publishConfig": {
@@ -20,7 +20,7 @@
     "dist"
   ],
   "dependencies": {
-    "@irtio/schema": "0.8.0"
+    "@irtio/schema": "0.9.0"
   },
   "scripts": {
     "build": "tsup",