RobustSession protocol

This document outlines how RobustIRC clients and RobustIRC servers communicate. In IRC, communication happens over a single long-lived TCP connection. RobustIRC uses HTTP requests instead, so there are requests to create a session (≘ connect), delete the session (≘ disconnect), send a message (≘ send) and receive a number of messages (≘ receive).

The RobustIRC client can send these requests to any server in the network. In case the chosen server is not the raft leader, that server will proxy the request to the current leader (read-only requests such as GetMessages can be handled by raft followers as well). When a request was redirected, the Content-Location response header contains the current raft leader. Clients SHOULD direct further requests directly to the server specified in Content-Location in order to decrease load on the network and minimize latency. In case the chosen server cannot be reached or responds with an error, the client can chose another server, for example at random, to retry the request.

The behavior described in the previous paragraphs make this protocol resilient against network partitions and single-server unavailability.

RobustIRC mandates the use of an SRV DNS record to discover servers. The client gets a network address, e.g. robustirc.net and resolves the _robustirc._tcp SRV record, e.g. _robustirc._tcp.robustirc.net. The target:port tuples to which that SRV record resolves are used as initial list of servers. robustPing messages in the GetMessages response contain a list of servers so that clients don’t need to re-resolve but still get an up-to-date list of servers.

The advantage of using SRV records is that the network address is short and memorable, but RobustIRC servers can be hosted on different servers than the network address itself. E.g., robustirc.net’s A record points to github, but the _robustirc._tcp.robustirc.net record points to 3 different servers.

Clients MAY ignore the priority and weight fields of the SRV record, but SHOULD randomly shuffle the list of servers (as opposed to always connecting to the first one).

Each of the described Methods returns the HTTP 200 OK status code when successful or an HTTP error (e.g. 500 Internal Server Error) when things went wrong.

Each method (except for CreateSession) can return an HTTP 404 Not Found status code when the specified session was not found, or a HTTP 400 Bad Request if something with the request itself was wrong. All 4xx replies are permanent and clients SHOULD close the connection — no subsequent message with that same session id will be accepted.

In case the server replies with an error, the response body will contain a human-readable error message that the client should expose.

To avoid overloading the network, clients MUST use exponential backoff, with an upper cap on retries of at least 60 seconds (e.g. \(2^6 = 64\)).

This means: the time between two unsuccessful requests to any specific server (e.g. GetMessages) must be at least \(2^0 = 1\) second. For the next request, this time will be increased to \(2^1 = 2\) seconds, then \(2^2 = 4\) seconds, etc.

Furthermore, clients MUST delay connecting to a different server for a random duration between 250ms to at least 500ms to avoid the thundering herd problem.

Implementations MUST set their User-Agent string to a clear identifier, such as WeeChat RobustIRC plugin v1.0.