Agent WranglersLive connections
Pick polling, server-sent events or WebSockets by need, check access for the whole connection, cap each client and deliver from any server.
- Required 2
- Recommended 4
Required
Check access when the connection opens and while it lasts
API-70Sign the client in during the handshake, as for any request. Check permission for each channel it joins and each message it sends. Close the connection when its session ends.
Limit the connections and messages of each client
API-73Limit how many connections each account may hold open, how large one message may be and how many messages it may send per minute. Close or refuse the rest.
Recommended
Choose the transport that the feature needs
API-69Poll when a delay of 30 seconds or more is fine. Use server-sent events when only the server sends. Use WebSockets only when the client also sends a stream of messages.
Send heartbeats and drop dead connections
API-71Send a ping on every quiet WebSocket every 30 seconds, and close a connection that misses two pongs in a row.
Reconnect with backoff and resume from the last event
API-72Clients wait a random time before the first reconnect and longer after each failure. They resume from the last event ID they saw, so nothing is lost or shown twice.
Deliver events through a shared channel
API-74When more than one server holds connections, publish every event to a shared channel. Each server then delivers it to the clients connected to it.
For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/api-design/live-connections">Agent Wranglers API design playbook</a>. In code you write, add a comment next to it with the same link.