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

Commit e71028f

Browse files
bitfl0werbitfl0wer
committed
more websocket stuff
1 parent f5a3943 commit e71028f

File tree

3 files changed

+122
-20
lines changed

3 files changed

+122
-20
lines changed

‎.vscode/ltex.dictionary.en-US.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,3 +25,4 @@ Protobuf
2525
gzipped
2626
RawR
2727
OID
28+
apidocs

‎.vscode/ltex.hiddenFalsePositives.en-US.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,3 +65,4 @@
6565
{"rule":"REPEATED_VERBS","sentence":"^\\Q\\E(?:Dummy|Ina|Jimmy-)[0-9]+\\Q Hello Actor Receive Received upon establishing a connection.\\E$"}
6666
{"rule":"REPEATED_VERBS","sentence":"^\\Q\\E(?:Dummy|Ina|Jimmy-)[0-9]+\\Q New Session Actor Receive Received by all sessions except the new one.\\E$"}
6767
{"rule":"REPEATED_VERBS","sentence":"^\\Q\\E(?:Dummy|Ina|Jimmy-)[0-9]+\\Q Actor Certificate Invalidation Actor Send/Receive Received by server when an actor certificate has been invalidated.\\E$"}
68+
{"rule":"REPEATED_VERBS","sentence":"^\\Q\\E(?:Dummy|Ina|Jimmy-)[0-9]+\\Q Message Actor Receive Received when a message is sent to the actor.\\E$"}

‎docs/Protocol Specifications/core.md‎

Lines changed: 120 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -5,16 +5,16 @@ weight: 0
55

66
# polyproto Specification
77

8+
- Namespace: `core`
9+
- Version: `v0.1.0-alpha.1`
10+
- API version: `v0.1.0-alpha.1`
11+
- API documentation: [apidocs.polyproto.org](https://apidocs.polyproto.org)
12+
813
!!! warning
914

1015
The polyproto specification document is in an **alpha** phase. Please report any inconsistencies,
1116
missing or duplicate information and other mistakes at [github.com/polyphony-chat/docs/issues](https://github.com/polyphony-chat/docs/issues).
1217

13-
Version of this specification document: **v0.1.0-alpha.1** - Treat this as an unfinished draft.
14-
15-
Version of the [API documentation](https://apidocs.polyproto.org) applicable for this version
16-
of the specification document: **v0.1.0-alpha.1**
17-
1818
[Semantic versioning v2.0.0](https://semver.org/spec/v2.0.0.html) is used to version this specification.
1919

2020
- [polyproto Specification](#polyproto-specification)
@@ -27,7 +27,11 @@ of the specification document: **v0.1.0-alpha.1**
2727
- [3.2.1.1 Namespaces `n`](#3211-namespaces-n)
2828
- [3.2.1.2 Opcodes `op`](#3212-opcodes-op)
2929
- [3.2.1.3 Event names `t`](#3213-event-names-t)
30-
- [3.2.2 Events over REST](#322-events-over-rest)
30+
- [3.2.2 Heartbeats](#322-heartbeats)
31+
- [3.2.3 "Hello" event](#323-hello-event)
32+
- [3.2.4 Service channels](#324-service-channels)
33+
- [3.2.5 Identify](#325-identify)
34+
- [3.2.3 Events over REST](#323-events-over-rest)
3135
- [3.3 HTTP](#33-http)
3236
- [3.4 Internet Protocol (IP)](#34-internet-protocol-ip)
3337
- [4. Federated identity](#4-federated-identity)
@@ -236,7 +240,7 @@ on the specific event.
236240
| `t`¹ | ?string | Event name for this payload (only applicable for and present in DISPATCH opcode payloads). |
237241

238242
¹ These fields are only included for payloads received from a server and are `null` when `op`
239-
is not equal to DISPATCH.
243+
is not equal to `DISPATCH`.
240244

241245
##### 3.2.1.1 Namespaces `n`
242246

@@ -250,22 +254,118 @@ correctly interpreting the payload.
250254

251255
##### 3.2.1.2 Opcodes `op`
252256

253-
The following opcodes are defined by the `core` namespace, which is the namespace managed by this
254-
specification:
255-
256-
| Opcode | Name | Action | Description |
257-
| ------ | ------------------------------ | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
258-
| `0` | Dispatch | Actor Receive | Delivery of a message payload to a client. |
259-
| `1` | Heartbeat | Actor Send/Receive | Keep alive for the WebSocket session. |
260-
| `2` | Hello | Actor Receive | Received upon establishing a connection. |
261-
| `3` | Identify | Actor Send | Identify to the server. |
262-
| `4` | Server Certificate Change | Actor Receive | Received when the server's certificate changed. |
263-
| `5` | New Session | Actor Receive | Received by all sessions except the new one. |
264-
| `6` | Actor Certificate Invalidation | Actor Send/Receive | Received by server when an actor certificate has been invalidated. Sent to server when an actor invalidates one of their certificates. |
257+
The following opcodes are defined by the `core` namespace:
258+
259+
| Opcode | Name | Action | Description |
260+
| ------ | ------------------------------ | ------------------ | ---------------------------------------------------------------------------------------------------------------- |
261+
| `0` | Heartbeat | Actor Send/Receive | Keep alive for the WebSocket session. |
262+
| `1` | Hello | Actor Receive | Received upon establishing a connection. |
263+
| `2` | Identify | Actor Send | Identify to the server. |
264+
| `3` | New Session | Actor Receive | Received by all sessions except the new one. |
265+
| `4` | Actor Certificate Invalidation | Actor Send/Receive | An actor certificate has been invalidated. Sent *to* server when an actor invalidates one of their certificates. |
266+
| `5` | Resume | Actor Send | Resume a connection. |
267+
| `6` | Server Certificate Change | Actor Receive | Received when the server's certificate changed. |
268+
| `7` | Heartbeat ACK | Actor Receive | Acknowledgement of a heartbeat |
269+
| `8` | Service Channel | Actor Send/Receive | Open or close a service channel. |
270+
| `9` | Service Channel ACK | Actor Receive | Acknowledgement of a service channel event. |
265271

266272
##### 3.2.1.3 Event names `t`
267273

268-
#### 3.2.2 Events over REST
274+
The `t` field in a gateway event payload indicates the event name for this payload. Event names
275+
are only applicable for and present in `DISPATCH` opcode payloads.
276+
277+
Event names are strings defined by the namespace context and are used to differentiate between different
278+
types of events within the `DISPATCH` opcode.
279+
280+
String values for event names are to be formatted in `SCREAMING_SNAKE_CASE`.
281+
282+
#### 3.2.2 Heartbeats
283+
284+
Heartbeats are used to keep the WebSocket connection alive. The client sends a heartbeat event to the
285+
server with a specified interval, which then responds with an acknowledgement for the heartbeat.
286+
Servers must account for the time it takes for the client to send the heartbeat event. Before closing
287+
a connection due to a missed heartbeat, the server should request a heartbeat event from the client
288+
by sending a heartbeat event to the client.
289+
290+
The `d` payload for a heartbeat event is an empty object `{}`.
291+
292+
#### 3.2.3 "Hello" event
293+
294+
The "Hello" event is sent by the server to the client upon establishing a connection. The `d` payload
295+
for a "Hello" event is an object containing a `heartbeat_interval` field, which specifies the interval
296+
in milliseconds at which the client should send heartbeat events to the server.
297+
298+
!!! example "Example hello event payload"
299+
300+
```json
301+
{
302+
"heartbeat_interval": 45000
303+
}
304+
```
305+
306+
| Field | Type | Description |
307+
| -------------------- | ------ | ---------------------------------------------------------------------------------------- |
308+
| `heartbeat_interval` | uint32 | Interval in milliseconds at which the client should send heartbeat events to the server. |
309+
310+
#### 3.2.4 Service channels
311+
312+
Service channels act like topics in a pub/sub system. They allow clients to subscribe to a specific
313+
topic and receive messages sent to that topic.
314+
315+
Converting that analogy to polyproto, service channels allow clients to subscribe to gateway events
316+
of additional namespaces. Service channels allow a unified way of giving extensions access to WebSockets
317+
without having to initialize a separate WebSocket connection.
318+
319+
A service channel event payload has the following structure:
320+
321+
```json
322+
{
323+
"n": "core",
324+
"op": 8,
325+
"d": {
326+
"action": "subscribe",
327+
"service": "service_name"
328+
}
329+
}
330+
```
331+
332+
| Field | Type | Description |
333+
| --------- | ------ | ------------------------------------------------------------------------------------------ |
334+
| `action` | string | The action to perform on the service channel. Must be either `subscribe` or `unsubscribe`. |
335+
| `service` | string | The name of a polyproto service. |
336+
337+
The server must respond with a `Service Channel ACK` event payload, indicating whether the action
338+
was successful or not.
339+
340+
```json
341+
{
342+
"n": "core",
343+
"op": 9,
344+
"d": {
345+
"action": "subscribe",
346+
"service": "service_name",
347+
"success": true,
348+
"message": "Successfully subscribed to service_name"
349+
}
350+
}
351+
```
352+
353+
| Field | Type | Description |
354+
| --------- | ------- | ------------------------------------------------------------------------------------------ |
355+
| `action` | string | The action to perform on the service channel. Must be either `subscribe` or `unsubscribe`. |
356+
| `service` | string | The polyproto service that was specified in the opcode 8 request |
357+
| `success` | boolean | Whether the action was successful or not. |
358+
| `message` | string? | Only present if `success` is `false`. A message indicating why the action failed. |
359+
360+
If a successful subscription to a service channel is acknowledged, all further events and logic
361+
is defined by the service's specification.
362+
363+
#### 3.2.5 Identify
364+
365+
The "identify" event is sent by the client to the server to let the server know which actor the
366+
client is.
367+
368+
#### 3.2.3 Events over REST
269369

270370
For some implementation contexts, a constant WebSocket connection might not be wanted. A client can
271371
instead opt to query an API endpoint to receive events, which would normally be sent through the WebSocket

0 commit comments

Comments
 (0)