7. The Universal Port Protocol

Reference · normative for the daemon's clients · the JSON protocol between `mesh-hub` and anything that attaches to it, over a WebSocket or a Unix socket

The daemon terminates one protocol on two transports. A client attaches under a name, publishes envelopes to channels, subscribes to filtered streams, and detaches; the daemon answers each request, pushes events, and enforces a connection policy that keeps a silent, slow or oversized peer from costing the others anything. The types are defined once, in mesh-port-protocol, and the daemon and the Rust client both use them; the thin Python and Node clients and the website’s browser client speak the same JSON. Version v0.

7.1 Transports and framing

Both carry the same message stream. Every message is a JSON object whose op field names the kind. The frames of every kind, each optional field present in one frame and absent in another, are pinned under mesh/mesh-port-protocol/fixtures/ (client.json, server.json) as the Rust types serialize them; the crate’s tests keep the files current, and the Python and Node thin clients’ tests decode every server frame from them and compare the frames they write with the client frames as parsed JSON. A daemon MUST refuse to bind a Unix socket path where another daemon is live (it probes the socket first and removes only a stale file), so a second daemon never steals a live one’s clients.

7.2 Client messages

id is echoed on the matching ack or error; a request without one gets a reply without one. A FilterSpec has six optional members that AND-combine: channel (exact or glob, db/*, **/foo), type_id, type_name (exact or glob), origin (the producer’s name@suffix), health (also stream peer state changes), and snapshot (reserved; ignored by v0). Fields at their defaults are omitted on the wire.

7.3 Daemon messages

A client MUST ignore an op it does not know and an ack key it does not know, so a later revision can add either without breaking it; the existing clients do.

7.4 Error codes

An error that answers no request, one without an id or with one no request is waiting on, is the daemon’s reason for the close that follows it, and a client reports it to every call still waiting and to whatever waits for the connection’s end; a daemon that carries on after such an error, as after bad_request for a frame it could not parse, fails no call by it.

The set grows: a later daemon may send a code this table does not list. A client keeps such a code as the text it arrived in and treats the reply as a refusal it cannot classify; the Rust client’s DevError::Daemon { code, .. } holds the string, and mesh_port_protocol::ErrorCode::parse returns None for it.

7.5 The connection policy

The daemon enforces eight limits, four timers and four sizes, each a command-line flag with a default; zero disables a timer, and zero on either cap refuses everything:

Acknowledgements and errors are never dropped; only events are subject to the queue. When a connection ends for any reason the daemon releases its name and closes its subscriptions at once.

7.6 A session

→ {"op":"attach","id":"1","name":"worker","protocol_version":"v0","capabilities":["send","subscribe","tap"]}
← {"op":"ack","id":"1","node_id":"worker@3f9a…","protocol_version":"v0","granted_capabilities":["send","subscribe","tap"]}
→ {"op":"subscribe","id":"2","filter":{"channel":"jobs/*"}}
← {"op":"ack","id":"2","subscription_id":"sub-default_hub-00000001"}
→ {"op":"send","id":"3","channel":"jobs/new","payload":"aGVsbG8="}
← {"op":"ack","id":"3","envelope_id":"9c1d…","persisted":true}
← {"op":"event","subscription_id":"sub-default_hub-00000001","envelope_id":"9c1d…","channel":"jobs/new","type_id":0,"origin":"worker@3f9a…","captured_at_unix_nanos":1758700000000000000,"payload":"aGVsbG8="}
→ {"op":"unsubscribe","id":"4","subscription_id":"sub-default_hub-00000001"}
← {"op":"ack","id":"4"}
→ {"op":"detach","id":"5"}
← {"op":"ack","id":"5","__detach":true}

7.7 What would refute this chapter

The protocol crate’s round-trip tests pin every message shape; the daemon’s tests attach, publish, subscribe and detach over both transports, refuse a second daemon on a live socket, close a silent connection after the idle window and a stalled one after the write window, keep a pinged client attached, reject an oversized frame with payload_too_large, show events_dropped in the unsubscribe ack of a subscriber that stopped reading, acknowledge a send the store refused with persisted: false while still delivering it to its subscribers, refuse a send whose payload is not padded standard base64 without publishing it, refuse the subscription past the cap with limit_exceeded and admit one again after an unsubscribe, and turn away the connection past the cap on both transports. A client that receives bytes this chapter does not describe, or a daemon that keeps a silent connection past its window, contradicts it.