Skip to content
This repository was archived by the owner on Aug 15, 2025. It is now read-only.

Commit 1b56e5e

Browse files
bitfl0werbitfl0wer
committed
mostly define resume and resumed events
1 parent c40a58d commit 1b56e5e

File tree

1 file changed

+101
-19
lines changed
  • docs/Protocol Specifications

1 file changed

+101
-19
lines changed

‎docs/Protocol Specifications/core.md‎

Lines changed: 101 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ weight: 0
3434
- [3.2.3.3 Service channels](#3233-service-channels)
3535
- [3.2.3.4 New session event](#3234-new-session-event)
3636
- [3.2.3.5 Actor certificate invalidation event](#3235-actor-certificate-invalidation-event)
37-
- [3.2.3.6 Resume event](#3236-resume-event)
37+
- [3.2.3.6 "Resume" event and "resumed" event](#3236-resume-event-and-resumed-event)
3838
- [3.2.3.7 Server certificate change event](#3237-server-certificate-change-event)
3939
- [3.2.3.8 Heartbeat and heartbeat ACK events](#3238-heartbeat-and-heartbeat-ack-events)
4040
- [3.2.4 Establishing a connection](#324-establishing-a-connection)
@@ -271,11 +271,12 @@ The following opcodes are defined by the `core` namespace:
271271
| `2` | Identify | Actor Send | Identify to the server. |
272272
| `3` | New Session | Actor Receive | Received by all sessions except the new one. |
273273
| `4` | Actor Certificate Invalidation | Actor Send/Receive | An actor certificate has been invalidated. Sent *to* server when an actor invalidates one of their certificates. |
274-
| `5` | Resume | Actor Send/Receive | Replay events after re-connecting. |
274+
| `5` | Resume | Actor Send | Request the replaying events after re-connecting. |
275275
| `6` | Server Certificate Change | Actor Receive | Received when the server's certificate changed. |
276276
| `7` | Heartbeat ACK | Actor Receive | Acknowledgement of a heartbeat |
277277
| `8` | Service Channel | Actor Send/Receive | Open or close a service channel. |
278278
| `9` | Service Channel ACK | Actor Receive | Acknowledgement of a service channel event. |
279+
| `10` | Resumed | Actor Receive | Replayed events. |
279280

280281
##### 3.2.1.3 Sequence numbers `s`
281282

@@ -479,12 +480,94 @@ occurs.
479480
| `invalidSince` | uint64 | UNIX timestamp of the point in time where this ID-Cert became invalid on |
480481
| `signature` | string | Signature of a string concatenation of the `invalidSince` timestamp and the `serial` number, in that order. Clients must verify this signature, verifying that the signature was generated by the private key of the revoked certificate. |
481482

482-
##### 3.2.3.6 Resume event
483+
##### 3.2.3.6 "Resume" event and "resumed" event
483484

484485
When a client re-connects to a polyproto WebSocket gateway server, the client may send a resume event
485-
to the server instead of identifying.
486+
to the server instead of identifying. The resumed event sent by the server informs the client
487+
about everything the client has missed since their last active connection to the gateway.
486488

487-
TODO
489+
TODO: Must the resume event not contain a token?
490+
491+
!!! example "Example resume event structure"
492+
493+
```json
494+
{
495+
"n": "core",
496+
"op": 5,
497+
"d": {
498+
"s": 12
499+
}
500+
}
501+
```
502+
503+
| Field | Type | Description |
504+
| ----- | ------ | --------------------------------------------------------------------------------------- |
505+
| `s` | uint64 | Sequence number of the last event received by the client; aka. "Where to receive from". |
506+
507+
!!! example "Example "resumed" event"
508+
509+
```json
510+
{
511+
"n": "core",
512+
"op": 10,
513+
"d": {
514+
[
515+
{
516+
"n": "core",
517+
"op": 6,
518+
"d": {
519+
"payload data"
520+
}
521+
},
522+
{
523+
"n": "core",
524+
"op": 9,
525+
"d": {
526+
...
527+
}
528+
},
529+
...
530+
]
531+
},
532+
}
533+
```
534+
535+
As touched on earlier, the "resumed" event contains all relevant events the client has missed.
536+
537+
"Missed events" are events with
538+
539+
$$
540+
s_{event} \gt s_{resume}
541+
$$
542+
543+
where $s_{resume}$ is equal to the parameter `s` supplied by the client in the resume event.
544+
545+
A set of "relevant events" is a set of events which meet both of the following conditions:
546+
547+
1. Each event in the set is intended to be received by the client
548+
2. The set must contain the lowest possible amount of events necessary for the client to be informed
549+
about everything that happened while they were disconnected.
550+
551+
!!! example "Example for condition #2"
552+
553+
Assume, that an event "total number of messages sent" exists. The value of this event
554+
payload is a number, representing the total number of messages sent on the entire server. Under
555+
normal circumstances, each client receives this imaginary event every time this state changes.
556+
557+
For the client to resume, the server should not send each individual update of this value to the
558+
client as part of the "resumed" event. Instead, it would be sufficient to send the most
559+
up-to-date value of this event as part of the "resumed" payload, since how many times this event
560+
has been fired and what previous values of this event were, has no impact
561+
on the validity or state of other events.
562+
563+
Certificate change events are an example of events, where all intermediary values of the event
564+
are important as well. This is because a client could have sent a message where the signature was
565+
generated using a revoked certificate. In other words, intermediary values of this event type
566+
affect the validity or state of other events.
567+
568+
Servers may reject a clients' wish to resume, if the number of events that would need to be replayed
569+
is too high for the server to process. In this case, the request to resume is met with a close code
570+
of `4010` by the server and the connection is terminated.
488571

489572
##### 3.2.3.7 Server certificate change event
490573

@@ -608,20 +691,19 @@ to the recipient. In addition to the pre-defined status codes in [IETF RFC #6455
608691
polyproto servers and clients must know of and use the following status codes in their appropriate
609692
situations:
610693

611-
| Code | Description | Explanation | Eligible for `RESUME`? | Sent by server? | Sent by client? |
612-
| ------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | --------------- | --------------- |
613-
| `4000` | Unknown error | An unknown error has occurred and the connection was terminated. | x | x | x |
614-
| `4001` | Unknown opcode | The client has sent a message with an unknown [opcode](#3212-opcodes-op) to the server. | x | x | |
615-
| `4002` | Invalid payload | The client has sent a message with an invalid payload to the server. | x | x | |
616-
| `4003` | Not authenticated | The server has received a message from the client before the client identified itself, or the clients' session has been invalidated. | | x | |
617-
| `4004` | Invalid authentication | The authentication token received by the server as part of the identify payload is invalid. | | x | |
618-
| `4005` | Already authenticated | The client has sent an identify payload even though it has already identified successfully. | | x | |
619-
| `4006` | Reserved | 4006 is a reserved value and has no function in polyproto v1.0. The specific meaning may be defined in the future. | | | |
620-
| `4007` | Invalid sequence number(s) | The client has sent a heartbeat containing sequence numbers that were invalid. | x | x | |
621-
| `4008` | Rate limited | The client has sent payloads too quickly. | | x | |
622-
| `4009` | Timeout | The session has been deemed to be timed out. This can happen if a heartbeat or heartbeat ACK has not been sent in due time. | x (If sent by server) | X | x |
623-
624-
TODO
694+
| Code | Description | Explanation | Eligible for `RESUME`? | Sent by server? | Sent by client? |
695+
| ------ | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | --------------- | --------------- |
696+
| `4000` | Unknown error | An unknown error has occurred and the connection was terminated. | x | x | x |
697+
| `4001` | Unknown opcode | The client has sent a message with an unknown [opcode](#3212-opcodes-op) to the server. | x | x | |
698+
| `4002` | Invalid payload | The client has sent a message with an invalid payload to the server. | x | x | |
699+
| `4003` | Not authenticated | The server has received a message from the client before the client identified itself, or the clients' session has been invalidated. | | x | |
700+
| `4004` | Invalid authentication | The authentication token received by the server as part of the identify payload is invalid. | | x | |
701+
| `4005` | Already authenticated | The client has sent an identify payload even though it has already identified successfully. | | x | |
702+
| `4006` | Reserved | 4006 is a reserved value and has no function in polyproto v1.0. The specific meaning may be defined in the future. | | | |
703+
| `4007` | Invalid sequence number(s) | The client has sent a heartbeat containing sequence numbers that were invalid. | x | x | |
704+
| `4008` | Rate limited | The client has sent payloads too quickly. | | x | |
705+
| `4009` | Timeout | The session has been deemed to be timed out. This can happen if a heartbeat or heartbeat ACK has not been sent in due time. | x (If sent by server) | x | x |
706+
| `4010` | Unresumeable | The server has determined that this session cannot be resumed. The client should initiate a new, fresh connection to the gateway instead. | | x | |
625707

626708
#### 3.2.6 Guaranteed delivery of gateway messages through package acknowledgement
627709

0 commit comments

Comments
 (0)