foxyzandClaude Opus 5.5
d8a0729029
README for the repo page; HOW-IT-WORKS overview; ARCHITECTURE, PROTOCOL, DEVELOPMENT checked against the code; ROADMAP is backlog only (isolate/dedicated server, sync fixes, rendering+shaders, Windows build, Jellyfin epic). HANDOFF.md and mpv-http-contract.md folded in and deleted. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
94 lines
4.3 KiB
Markdown
94 lines
4.3 KiB
Markdown
# Protocol (proto = 4)
|
|
|
|
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/room_hub.dart`.
|
|
|
|
Any wire change bumps `RelayConstants.protoVersion` and edits this file in
|
|
the same commit. Changes are additive.
|
|
|
|
## 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 `room`.
|
|
- 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`, `room`, `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":4,"secret":"","user":{"name":"","avatar":""},
|
|
"media":{"name":"","size":0,"duration":0,"url":null}}
|
|
{"t":"ready","ready":true,"source":"manual"} source: manual | auto
|
|
{"t":"force","target":"all"|"<memberId>","ready":true}
|
|
{"t":"seek","position":123.4}
|
|
{"t":"swap","media":{"name":"","size":0,"duration":0,"url":"..."}}
|
|
{"t":"report","position":123.1,"buffered":6.2,"eventId":41}
|
|
{"t":"chat","text":"..."}
|
|
{"t":"kick","target":"<memberId>","reason":""}
|
|
```
|
|
|
|
Field notes:
|
|
- `hello.secret`: the server password; a server with an empty secret is open.
|
|
The member connecting from a loopback address is the host.
|
|
`hello.media` is carried but not used by the server today.
|
|
- `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":{<room>}}
|
|
{"t":"room","eventId":7,"transport":"playing"|"held","position":12.3,
|
|
"serverTime":"<ISO-8601 UTC>","mediaId":1,
|
|
"media":{name,size,duration,url?}|absent,
|
|
"members":[{"id","name","avatar","ready","inSet","buffered","stale"}]}
|
|
{"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 `room`.
|
|
- `room` is sent every second and on every change. `position` is the value at
|
|
`serverTime`; clients extrapolate while `transport` is `playing`.
|
|
`eventId` increases on seek, swap and transport changes.
|
|
`mediaId` increases on swap.
|
|
- `feed.action` values: `ready`, `unready`, `force-ready`, `force-unready`,
|
|
`force-play`, `force-hold`, `kick`, `join`, `leave`, `stale`, `swap`,
|
|
`seek`, `pause`, `resume`, `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 room
|
|
position and buffers. A joining member is `ready=false, inSet=false` until
|
|
the first `ready`. A socket that dies loses its token; reconnect is a fresh
|
|
`hello`, after which the client re-sends its prior ready flag.
|
|
|
|
## 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.
|