foxyzandClaude Opus 5.5
d8d487c189
- User seeks are intercepted at the player (SyncPlayer), previewed locally, sent once 300 ms after the drag ends; own echoes are matched by seekSeq and never re-applied; the landed check can't reapply a stale target. 1 s position poll removed. - ping/pong clock offset (min-RTT ClockSync); positions use server time. - Reports carry duration; buffer gate is min(4 s, remaining - 2 s); new finished transport instead of a HELD stall at the end. - cache/readahead 150 s, 256 MiB demuxer cache, pins read back. - Resumed reports put a stale ready member back in the set; hello.resume takes over the old member after an unclean drop (no ghost). - Docs: roadmap rendering findings (HW path works; shaders verified). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
125 lines
6.3 KiB
Markdown
125 lines
6.3 KiB
Markdown
# Protocol (proto = 6)
|
|
|
|
Wire format only. Behavior (gate, clock, timeouts) is in
|
|
[ARCHITECTURE.md](ARCHITECTURE.md). Source of truth:
|
|
`packages/core/lib/src/protocol.dart` and `packages/server/lib/src/server_hub.dart`.
|
|
|
|
Any wire change bumps `RelayConstants.protoVersion` and edits this file in
|
|
the same commit. Changes are additive where possible; a client and server
|
|
with different `proto` refuse each other at `hello` (`proto mismatch`).
|
|
|
|
## Transport
|
|
|
|
- WebSocket at `/sync`, JSON text frames, each an object with a `t` field.
|
|
- The first client frame must be `hello` within 10 s. Server pings every 5 s.
|
|
- Match incoming frames by `t`, never by order: `welcome` can race `state`.
|
|
- Failures: server sends `{"t":"err","message":...}` and closes.
|
|
Messages: `bad hello: ...`, `proto mismatch: got X, want Y`, `wrong secret`,
|
|
`rejected: <reason>` (e.g. avatar too large), `bad message: ...` (a frame
|
|
with a non-finite number, e.g. NaN position), `bad swap media`,
|
|
`swap needs a url or the hosted file` (empty swap).
|
|
- `GET /health` returns JSON (`ok`, `name`, `proto`, `viewers`, `bytesServed`,
|
|
`uptimeSecs`; unauthenticated). `GET /m/<sid>/<token>/<name>`
|
|
serves the host's file (Range table in ARCHITECTURE.md).
|
|
|
|
## Client to server
|
|
|
|
```
|
|
{"t":"hello","proto":6,"secret":"","user":{"name":"","avatar":""},
|
|
"media":{"name":"","size":0,"duration":0,"url":null},"hostKey":"...",
|
|
"resume":"<token>"}
|
|
{"t":"ready","ready":true,"source":"manual"} source: manual | auto
|
|
{"t":"force","target":"all"|"<memberId>","ready":true}
|
|
{"t":"seek","position":123.4,"seq":3}
|
|
{"t":"swap","media":{"name":"","size":0,"duration":0,"url":"..."}}
|
|
{"t":"report","position":123.1,"buffered":6.2,"eventId":41,
|
|
"duration":1440.5,"mediaId":2}
|
|
{"t":"ping","c":1767225600000}
|
|
{"t":"chat","text":"..."}
|
|
{"t":"kick","target":"<memberId>","reason":""}
|
|
```
|
|
|
|
Field notes:
|
|
- `hello.secret`: the server password; a server with an empty secret is open.
|
|
`hello.media` is carried but not used by the server today.
|
|
- `hello.hostKey` (optional, omitted when empty): the hosting app
|
|
generates a random key per hosting, gives it to its server and sends it
|
|
from its own client. The member whose key equals the server's is the host
|
|
and cannot be kicked. A server without a key (the dedicated server) has no
|
|
host. Where the connection comes from does not matter.
|
|
- `hello.resume` (optional, omitted when empty): the token from this
|
|
client's previous `welcome`, sent on reconnect. If the server still has
|
|
that member and it is not kicked, the connection takes it over: `welcome`
|
|
returns the same `token` and `memberId`, the member keeps its flags, and
|
|
there is no `join`/`leave` feed. Otherwise it is ignored and a new member
|
|
joins.
|
|
- `seek.seq` (optional, default 0): increasing per client; echoed in
|
|
`state.seekSeq` so the sender recognises its own seek.
|
|
- `report.duration` / `report.mediaId` (optional, omitted when 0): the open
|
|
media's length in seconds and the `mediaId` it belongs to. The server takes
|
|
the first one whose `mediaId` is current while its media duration is 0.
|
|
- `ping.c`: the client's clock in epoch ms; answered with `pong`.
|
|
- `user.avatar`: base64 image, at most 256 KiB of characters. `name` is
|
|
trimmed, empty becomes `?`, cut to 32 characters.
|
|
- `chat.text` is cut to 500 characters.
|
|
- `swap.media.url` is the link; `name`, `size`, `duration` are informational.
|
|
- Frames before `welcome` (other than `hello`) are ignored; unparsable or
|
|
unknown frames are ignored silently.
|
|
|
|
## Server to client
|
|
|
|
```
|
|
{"t":"welcome","token":"...","memberId":"m1","mediaUrl":"...","state":{<state>}}
|
|
{"t":"state","eventId":7,"transport":"playing"|"held"|"finished","position":12.3,
|
|
"serverTime":"<ISO-8601 UTC>","mediaId":1,
|
|
"media":{name,size,duration,url?}|absent,
|
|
"members":[{"id","name","avatar","ready","inSet","buffered","stale"}],
|
|
"seekBy":"m1","seekSeq":3}
|
|
{"t":"pong","c":1767225600000,"s":1767225600012}
|
|
{"t":"feed","actor":"","action":"","target":"","reason":"","at":"<ISO-8601>"}
|
|
{"t":"chat","text":"...","from":"<name>"}
|
|
{"t":"kicked","reason":""}
|
|
{"t":"err","message":""}
|
|
```
|
|
|
|
- `welcome.token` is private to its owner and appears only in that member's
|
|
media URL. `mediaUrl` is omitted when there is no media; it is a built
|
|
`/m/...` URL for a host file (host part = what the client dialled), otherwise
|
|
the shared link.
|
|
`welcome.state` has the same shape as `state`.
|
|
- `state` is sent every second and on every change. `position` is the value at
|
|
`serverTime` (server clock); clients extrapolate while `transport` is
|
|
`playing`, on the server's clock (see `pong`). `finished`: the media
|
|
reached its end (`position` = duration); it stays until a seek or swap.
|
|
`eventId` increases on seek, swap and transport changes.
|
|
`mediaId` increases on swap. `media.duration` is 0 until a client reports
|
|
it. `seekBy` (member id) and `seekSeq` are present only while the current
|
|
`eventId` came from a seek.
|
|
- `pong.c` echoes the ping's `c`; `pong.s` is the server's clock in epoch ms
|
|
(the clock `serverTime` uses). With `t3` the local receive time, the offset
|
|
is `s - (c + t3) / 2`, accurate to half the round trip.
|
|
- `feed.action` values: `ready`, `unready`, `force-ready`, `force-unready`,
|
|
`force-play`, `force-hold`, `kick`, `join`, `leave`, `stale`, `swap`,
|
|
`seek`, `pause`, `resume`, `finished`, `chat`. `target` and `reason` are optional;
|
|
`reason` carries `auto`/`manual` for ready and `silent too long` or
|
|
`no signal` for leave/stale.
|
|
- Chat is delivered twice: a `chat` frame with the text and a textless
|
|
`feed` with `action:"chat"`. Render the `chat` frame only; the reference
|
|
client drops the textless feed entry.
|
|
|
|
## Join and reconnect
|
|
|
|
`hello` then `welcome`, then the app opens `mediaUrl`, seeks to the server
|
|
position and buffers. A joining member is `ready=false, inSet=false` until
|
|
the first `ready`. A socket the server sees close loses its token; reconnect
|
|
is a fresh `hello` (with `resume` = the old token), after which the client
|
|
re-sends its prior ready flag. If the old member was still there (unclean
|
|
drop), `resume` takes it over and the token and media URL stay the same.
|
|
|
|
## Reserved, not implemented
|
|
|
|
Server-held queue (`queue-add`, `queue-skip`) would auto-advance like a swap.
|
|
`RelayConstants.chunkBytes`, `creditWindowChunks`, `maxConcurrentOpen` and the
|
|
`open`, `ack`, `cancel`, `eof`, `buffered`, `state`, `event` kinds in
|
|
`MessageKind` are unused leftovers (the `state` frame does not use the enum).
|