diff --git a/examples/app/join-emoji-name.json b/examples/app/join-emoji-name.json new file mode 100644 index 0000000..649f143 --- /dev/null +++ b/examples/app/join-emoji-name.json @@ -0,0 +1,10 @@ +{ + "type": "join", + "rider": "u-1842", + "route": "velodrome-250", + "room": "public", + "name": "Zo\u00eb \ud83c\udff3\ufe0f\u200d\ud83c\udf08", + "lap": 0, + "distance": 0, + "speed": 0 +} diff --git a/examples/app/ping.json b/examples/app/ping.json new file mode 100644 index 0000000..51619b9 --- /dev/null +++ b/examples/app/ping.json @@ -0,0 +1,4 @@ +{ + "type": "ping", + "ref": "hb-17" +} diff --git a/examples/invalid/app/invalid_value--name-bidi-override.json b/examples/invalid/app/invalid_value--name-bidi-override.json new file mode 100644 index 0000000..ea48659 --- /dev/null +++ b/examples/invalid/app/invalid_value--name-bidi-override.json @@ -0,0 +1,10 @@ +{ + "type": "join", + "rider": "u-1842", + "route": "velodrome-250", + "room": "public", + "name": "\u202eannA", + "lap": 0, + "distance": 0, + "speed": 0 +} diff --git a/examples/invalid/app/invalid_value--name-c1-control.json b/examples/invalid/app/invalid_value--name-c1-control.json new file mode 100644 index 0000000..b442827 --- /dev/null +++ b/examples/invalid/app/invalid_value--name-c1-control.json @@ -0,0 +1,10 @@ +{ + "type": "join", + "rider": "u-1842", + "route": "velodrome-250", + "room": "public", + "name": "Anna\u0085", + "lap": 0, + "distance": 0, + "speed": 0 +} diff --git a/examples/invalid/app/invalid_value--name-line-separator.json b/examples/invalid/app/invalid_value--name-line-separator.json new file mode 100644 index 0000000..1bcd336 --- /dev/null +++ b/examples/invalid/app/invalid_value--name-line-separator.json @@ -0,0 +1,10 @@ +{ + "type": "join", + "rider": "u-1842", + "route": "velodrome-250", + "room": "public", + "name": "Anna\u2028", + "lap": 0, + "distance": 0, + "speed": 0 +} diff --git a/examples/invalid/app/invalid_value--name-only-whitespace.json b/examples/invalid/app/invalid_value--name-only-whitespace.json new file mode 100644 index 0000000..6d19cae --- /dev/null +++ b/examples/invalid/app/invalid_value--name-only-whitespace.json @@ -0,0 +1,10 @@ +{ + "type": "join", + "rider": "u-1842", + "route": "velodrome-250", + "room": "public", + "name": " ", + "lap": 0, + "distance": 0, + "speed": 0 +} diff --git a/examples/invalid/app/invalid_value--name-private-use.json b/examples/invalid/app/invalid_value--name-private-use.json new file mode 100644 index 0000000..9c5f831 --- /dev/null +++ b/examples/invalid/app/invalid_value--name-private-use.json @@ -0,0 +1,10 @@ +{ + "type": "join", + "rider": "u-1842", + "route": "velodrome-250", + "room": "public", + "name": "Anna\ue000", + "lap": 0, + "distance": 0, + "speed": 0 +} diff --git a/examples/invalid/app/invalid_value--name-tag-character.json b/examples/invalid/app/invalid_value--name-tag-character.json new file mode 100644 index 0000000..a50e286 --- /dev/null +++ b/examples/invalid/app/invalid_value--name-tag-character.json @@ -0,0 +1,10 @@ +{ + "type": "join", + "rider": "u-1842", + "route": "velodrome-250", + "room": "public", + "name": "Anna\udb40\udc41", + "lap": 0, + "distance": 0, + "speed": 0 +} diff --git a/examples/invalid/app/invalid_value--name-zero-width-space.json b/examples/invalid/app/invalid_value--name-zero-width-space.json new file mode 100644 index 0000000..3a8cb33 --- /dev/null +++ b/examples/invalid/app/invalid_value--name-zero-width-space.json @@ -0,0 +1,10 @@ +{ + "type": "join", + "rider": "u-1842", + "route": "velodrome-250", + "room": "public", + "name": "An\u200bna", + "lap": 0, + "distance": 0, + "speed": 0 +} diff --git a/examples/server/pong.json b/examples/server/pong.json new file mode 100644 index 0000000..982ff07 --- /dev/null +++ b/examples/server/pong.json @@ -0,0 +1,4 @@ +{ + "type": "pong", + "ref": "hb-17" +} diff --git a/examples/server/welcome.json b/examples/server/welcome.json index 27d9834..4cd455c 100644 --- a/examples/server/welcome.json +++ b/examples/server/welcome.json @@ -1,6 +1,6 @@ { "type": "welcome", - "protocol": "0.1", + "protocol": "0.2", "connection": "c9Qe4", "limits": { "max_update_hz": 4, diff --git a/schemas/app-message.schema.json b/schemas/app-message.schema.json index 84867ea..499f613 100644 --- a/schemas/app-message.schema.json +++ b/schemas/app-message.schema.json @@ -75,7 +75,7 @@ "type": "string", "minLength": 1, "maxLength": 32, - "pattern": "^[^\\u0000-\\u001f\\u007f]+$" + "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f-\\u009f\\u00ad\\u0600-\\u0605\\u061c\\u06dd\\u070f\\u0890-\\u0891\\u08e2\\u180e\\u200b-\\u200c\\u200e-\\u200f\\u2028-\\u202e\\u2060-\\u2064\\u2066-\\u206f\\ue000-\\uf8ff\\ufeff\\ufff9-\\ufffb\ud804\udcbd\ud804\udccd\ud80d\udc30-\ud80d\udc3f\ud82f\udca0-\ud82f\udca3\ud834\udd73-\ud834\udd7a\udb40\udc01\udb40\udc20-\udb40\udc7f\udb80\udc00-\udbbf\udffd\udbc0\udc00-\udbff\udffd]+$" } }, "required": ["type", "rider", "route", "name"] @@ -105,6 +105,14 @@ "rider": { "$ref": "#/$defs/riderId" } }, "required": ["type", "rider"] + }, + { + "title": "ping", + "properties": { + "type": { "const": "ping" }, + "ref": { "$ref": "#/$defs/ref" } + }, + "required": ["type"] } ] } diff --git a/schemas/server-message.schema.json b/schemas/server-message.schema.json index cc34a01..34f9de6 100644 --- a/schemas/server-message.schema.json +++ b/schemas/server-message.schema.json @@ -32,7 +32,7 @@ "type": "string", "minLength": 1, "maxLength": 32, - "pattern": "^[^\\u0000-\\u001f\\u007f]+$" + "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f-\\u009f\\u00ad\\u0600-\\u0605\\u061c\\u06dd\\u070f\\u0890-\\u0891\\u08e2\\u180e\\u200b-\\u200c\\u200e-\\u200f\\u2028-\\u202e\\u2060-\\u2064\\u2066-\\u206f\\ue000-\\uf8ff\\ufeff\\ufff9-\\ufffb\ud804\udcbd\ud804\udccd\ud80d\udc30-\ud80d\udc3f\ud82f\udca0-\ud82f\udca3\ud834\udd73-\ud834\udd7a\udb40\udc01\udb40\udc20-\udb40\udc7f\udb80\udc00-\udbbf\udffd\udbc0\udc00-\udbff\udffd]+$" } } }, @@ -139,6 +139,14 @@ "fatal": { "type": "boolean" } }, "required": ["type", "code", "message", "fatal"] + }, + { + "title": "pong", + "properties": { + "type": { "const": "pong" }, + "ref": { "type": "string", "maxLength": 64 } + }, + "required": ["type"] } ] } diff --git a/spec/v0.md b/spec/v0.md index 3460c3f..e6ca727 100644 --- a/spec/v0.md +++ b/spec/v0.md @@ -46,7 +46,9 @@ Every message is one WebSocket text frame holding one JSON object with a string Binary frames are not used, and a server MUST close the connection if it receives one. Receivers MUST ignore unknown fields. A server MUST answer an unknown `type` with an -`error` (`unknown_type`). This lets new optional fields be added without a new version. +`error` (`unknown_type`). An app MUST ignore a server message with an unknown `type`, and MUST +accept unknown values of `error.code` (acting on `fatal`) and of `left.reason`. This lets new +optional fields, server messages, error codes and leave reasons be added without a new version. Any message from an app MAY carry a string field `ref` (at most 64 characters). If the server answers that message with an `error`, the error carries the same `ref`. @@ -80,6 +82,12 @@ can put riders on a route without watching it. The server sends a WebSocket ping at least every 15 seconds. If no pong arrives within 30 seconds, the server closes the connection. +An app can check that the server is still there with `ping` (section 6.6), which the server +answers with `pong` (section 7.7). An app that has received nothing for 20 seconds SHOULD send a +`ping`, and MAY treat the connection as closed if nothing arrives within the next 10 seconds. +An app that can see WebSocket pings MAY instead treat the connection as closed when no ping has +arrived for 45 seconds. + When a connection closes, all of its riders leave with reason `disconnect`. An app that reconnects MUST send `hello`, `subscribe` and `join` again. Its riders get new server IDs. @@ -204,14 +212,30 @@ not secret and give no privacy. | `rider` | yes | the app's own ID for this rider, 1 to 64 characters, unique within the connection | | `route` | yes | route ID | | `room` | no | room, default `public` | -| `name` | yes | display name, 1 to 32 characters, no control characters | +| `name` | yes | display name, 1 to 32 characters (section 6.3.1) | | `lap`, `distance`, `speed`, `power`, `cadence`, `heart_rate` | as in `update` | the starting state | +The state in `join` does not count towards `max_update_hz`: an app MAY send an `update` for the +rider right after its `join`. + The server never shows the app's `rider` value to other apps. Apps SHOULD NOT use personal data, such as an e-mail address, as the rider value. A rider that has already joined MUST leave before it joins again, on the same or another route. +#### 6.3.1 Display names + +A character is a Unicode code point. A name MUST NOT: + +- contain a character of the Unicode general categories Cc (control), Cf (format), Co (private + use), Zl (line separator) or Zp (paragraph separator), except U+200D ZERO WIDTH JOINER, which + emoji sequences need, +- consist only of whitespace (characters with the Unicode property `White_Space`). + +This keeps out invisible characters and bidirectional overrides, which would let a rider hide or +reverse their name in other apps. Servers answer such a name with `invalid_value`. Receivers MUST +display names as plain text, never as markup. + ### 6.4 `update` ```json @@ -249,6 +273,14 @@ rider leaves with reason `timeout`. The rider leaves its route with reason `leave`. +### 6.6 `ping` + +```json +{"type": "ping", "ref": "hb-17"} +``` + +The server answers with `pong` (section 7.7). See section 3.5 for when to send it. + ## 7. Messages from the server Remote riders are identified by an `id` the server assigns. It is at most 16 characters, unique @@ -258,7 +290,7 @@ riders. ### 7.1 `welcome` ```json -{"type": "welcome", "protocol": "0.1", "connection": "c9Qe4", +{"type": "welcome", "protocol": "0.2", "connection": "c9Qe4", "limits": {"max_update_hz": 4, "rider_timeout_s": 10, "max_riders": 200, "max_subscriptions": 16, "max_message_bytes": 65536}} ``` @@ -332,7 +364,15 @@ Apps SHOULD interpolate remote riders between updates so they move smoothly. | `rate_limited` | no | a rider was sent more often than `max_update_hz`; the entry is dropped | | `limit_exceeded` | no | `max_riders` or `max_subscriptions` reached | | `message_too_large` | yes | a message is larger than `max_message_bytes` | -| `too_many_errors` | yes | the connection keeps causing errors | +| `too_many_errors` | yes | the connection keeps causing errors; `rate_limited` does not count | + +### 7.7 `pong` + +```json +{"type": "pong", "ref": "hb-17"} +``` + +The answer to `ping`. It carries the `ref` of the `ping`, if it had one. ## 8. Usage statistics