think about sequence numbers and resume events

Author: bitfl0wer

docs/Protocol Specifications/core.md

@@ -26,6 +26,7 @@ weight: 0
       - [3.2.1 Gateway Event Payloads](#321-gateway-event-payloads)
         - [3.2.1.1 Namespaces `n`](#3211-namespaces-n)
         - [3.2.1.2 Opcodes `op`](#3212-opcodes-op)
+        - [3.2.1.3 Sequence numbers `s`](#3213-sequence-numbers-s)
       - [3.2.2 Heartbeats](#322-heartbeats)
       - [3.2.3 Gateway event payload definitions](#323-gateway-event-payload-definitions)
         - [3.2.3.1 "Hello" event](#3231-hello-event)
@@ -237,11 +238,12 @@ end
 Gateway event payloads share a general structure, though the content of the `d` field varies depending
 on the specific event.
 
-| Field | Type       | Description                                                                                |
-| ----- | ---------- | ------------------------------------------------------------------------------------------ |
-| `n`   | string     | [Namespace](#82-namespaces) context for this payload.                                      |
-| `op`  | integer    | Gateway Opcode indicating the type of payload.                                             |
-| `d`   | JSON value | The event data associated with this payload.                                               |
+| Field | Type       | Description                                                         |
+| ----- | ---------- | ------------------------------------------------------------------- |
+| `n`   | string     | [Namespace](#82-namespaces) context for this payload.               |
+| `op`  | uint16     | Gateway Opcode indicating the type of payload.                      |
+| `d`   | JSON value | The event data associated with this payload.                        |
+| `s`   | uint32     | Sequence number of the event, used for guaranteed, ordered delivery |
 
 ##### 3.2.1.1 Namespaces `n`
 
@@ -264,12 +266,27 @@ The following opcodes are defined by the `core` namespace:
 | `2`    | Identify                       | Actor Send         | Identify to the server.                                                                                          |
 | `3`    | New Session                    | Actor Receive      | Received by all sessions except the new one.                                                                     |
 | `4`    | Actor Certificate Invalidation | Actor Send/Receive | An actor certificate has been invalidated. Sent *to* server when an actor invalidates one of their certificates. |
-| `5`    | Resume                         | Actor Send         | Resume a connection.                                                                                             |
+| `5`    | Resume                         | Actor Send/Receive | Replay events after re-connecting.                                                                               |
 | `6`    | Server Certificate Change      | Actor Receive      | Received when the server's certificate changed.                                                                  |
 | `7`    | Heartbeat ACK                  | Actor Receive      | Acknowledgement of a heartbeat                                                                                   |
 | `8`    | Service Channel                | Actor Send/Receive | Open or close a service channel.                                                                                 |
 | `9`    | Service Channel ACK            | Actor Receive      | Acknowledgement of a service channel event.                                                                      |
 
+##### 3.2.1.3 Sequence numbers `s`
+
+<!-->
+TODO
+<-->
+
+!!! bug TODO
+
+    How are we going to do sequence numbers? Requirements are:
+
+    - Guaranteed, ordered delivery of payloads
+    - Notice delivery gaps, especially when connection stability is flawed
+
+    See: https://chatgpt.com/share/678e89ba-aa20-8004-bde7-4a33bab804b9
+
 #### 3.2.2 Heartbeats
 
 Heartbeats are used to keep the WebSocket connection alive. The client continuously sends a heartbeat
@@ -429,6 +446,9 @@ occurs.
 
 ##### 3.2.3.6 Resume event
 
+When a client re-connects to a polyproto WebSocket gateway server, the client may send a resume event
+to the server instead of identifying.
+
 TODO
 
 ##### 3.2.3.7 Server certificate change event