Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions examples/app/join-emoji-name.json
Original file line number Diff line number Diff line change
@@ -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
}
4 changes: 4 additions & 0 deletions examples/app/ping.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"type": "ping",
"ref": "hb-17"
}
10 changes: 10 additions & 0 deletions examples/invalid/app/invalid_value--name-bidi-override.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
{
"type": "join",
"rider": "u-1842",
"route": "velodrome-250",
"room": "public",
"name": "\u202eannA",
"lap": 0,
"distance": 0,
"speed": 0
}
10 changes: 10 additions & 0 deletions examples/invalid/app/invalid_value--name-c1-control.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
{
"type": "join",
"rider": "u-1842",
"route": "velodrome-250",
"room": "public",
"name": "Anna\u0085",
"lap": 0,
"distance": 0,
"speed": 0
}
10 changes: 10 additions & 0 deletions examples/invalid/app/invalid_value--name-line-separator.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
{
"type": "join",
"rider": "u-1842",
"route": "velodrome-250",
"room": "public",
"name": "Anna\u2028",
"lap": 0,
"distance": 0,
"speed": 0
}
10 changes: 10 additions & 0 deletions examples/invalid/app/invalid_value--name-only-whitespace.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
{
"type": "join",
"rider": "u-1842",
"route": "velodrome-250",
"room": "public",
"name": " ",
"lap": 0,
"distance": 0,
"speed": 0
}
10 changes: 10 additions & 0 deletions examples/invalid/app/invalid_value--name-private-use.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
{
"type": "join",
"rider": "u-1842",
"route": "velodrome-250",
"room": "public",
"name": "Anna\ue000",
"lap": 0,
"distance": 0,
"speed": 0
}
10 changes: 10 additions & 0 deletions examples/invalid/app/invalid_value--name-tag-character.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
{
"type": "join",
"rider": "u-1842",
"route": "velodrome-250",
"room": "public",
"name": "Anna\udb40\udc41",
"lap": 0,
"distance": 0,
"speed": 0
}
10 changes: 10 additions & 0 deletions examples/invalid/app/invalid_value--name-zero-width-space.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
{
"type": "join",
"rider": "u-1842",
"route": "velodrome-250",
"room": "public",
"name": "An\u200bna",
"lap": 0,
"distance": 0,
"speed": 0
}
4 changes: 4 additions & 0 deletions examples/server/pong.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"type": "pong",
"ref": "hb-17"
}
2 changes: 1 addition & 1 deletion examples/server/welcome.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"type": "welcome",
"protocol": "0.1",
"protocol": "0.2",
"connection": "c9Qe4",
"limits": {
"max_update_hz": 4,
Expand Down
10 changes: 9 additions & 1 deletion schemas/app-message.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
Expand Down Expand Up @@ -105,6 +105,14 @@
"rider": { "$ref": "#/$defs/riderId" }
},
"required": ["type", "rider"]
},
{
"title": "ping",
"properties": {
"type": { "const": "ping" },
"ref": { "$ref": "#/$defs/ref" }
},
"required": ["type"]
}
]
}
10 changes: 9 additions & 1 deletion schemas/server-message.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -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]+$"
}
}
},
Expand Down Expand Up @@ -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"]
}
]
}
48 changes: 44 additions & 4 deletions spec/v0.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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}}
```

Expand Down Expand Up @@ -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

Expand Down
Loading