The durable wire (experimental)

Experimental. The wire may change, or the feature may be removed, in a later minor release. Versions and the telling hello says how a change reaches you.

The durable wire is how Collie talks to a durable agent. This page explains it for a builder who writes a durable agent without the SDK, or wants to know what the SDK does. The exact rules are in WIRE.md, and where this page and that file differ, WIRE.md is right. The durable SDK speaks all of it for you.

What travels

Collie dials and the durable agent listens, and every exchange is one HTTP request with a JSON body.

The durable agent listens on a private Unix socket, or behind TLS at a URL (Transports). Collie polls it: there is no push, no WebSocket and no stream. Every path starts with /session/v1, which is a fixed name, not the version. Every call but the first hello carries the version in the header X-Collie-Session. A request body is one JSON object of at most 64 KiB, and an empty POST body reads as {}.

Every error is a JSON body with a code, such as 409 stale or 404 no-such-pane. Any other path answers 404 not-found. A reply over its limit is not read, and a POST whose reply is cut has an unknown outcome (Request ids).

Hello and epoch

hello says who the durable agent is, and the epoch says which start of it Collie is talking to.

Collie first calls hello without the version header, picks the highest version both sides speak, and sends it on every later call. While ready is false, every route but hello answers 503 starting, and the phone shows the durable agent as starting. A durable agent sets ready only once every conversation is shown again and every open ask raised again, so a restart never shows half a layout.

The snapshot's ETag is "<epoch>-<rev>". rev rises on every change a reader could see, so a 304 costs the durable agent next to nothing. A new epoch tells Collie the durable agent restarted. Collie keeps showing the panes it has until it reads the new snapshot. It then reads each pane with its old cursor and gets the pane's whole current view in one reply.

One failed read after a good one keeps the last snapshot for that poll. Two failures in a row show the durable agent as unreachable. A socket path that fails the privacy walk is unreachable at once.

Asks and answers

An ask is a question card, and it is open from the durable agent's ask event until its ask-closed.

A tap that comes after the decision gets 409 decided with the first outcome, and nothing runs. The card then says who decided first: "Decided in the durable agent.", "Timed out before an answer.", or, after another tap, "Already answered. This card goes away on the next update." An ask the durable agent does not know any more answers 200 too-late. The card then says "Not taken. The question may show again in a moment.", because after a restart the durable agent may raise it again under the same id.

An ask is one of four kinds: permission, choice, text or form. Each has its own answer shape, listed with the SDK's Questions.

Request ids

Every act from the phone has a request id, so it runs at most once.

The phone mints one request id per intent, and Collie writes its own receipt before it passes the id on. The durable agent keeps at least the last 500 ids of its epoch. A repeat of a finished id gets the first reply again with replayed: true and runs nothing. The same id with another payload gets 409 request-id-reused.

Collie never retries a POST by itself. A POST that times out, loses its connection or gets a 5xx has an unknown outcome. For an answer, the card then says "Not sure the answer arrived. Try again sends it once more.", and Try again sends the same request id, so the durable agent's memory answers a repeat.

A retry that finds the ask closed or the turn moved cannot tell whether the first try landed. Collie then answers the phone "maybe applied", the card says "May already be applied. Check the chat.", and the act is never sent a third time.

Transports

A durable agent uses one of two transports: a private socket on Collie's machine, or TLS with a token.

The bytes are the same on both: the routes, the bodies, the version header, the ETag and the error codes. Only who may reach the durable agent differs.

Each timeout is a deadline for the whole exchange, from connect to the last byte. Over TLS every poll is a request your host may bill, a 304 included.

Limits

Collie cuts or refuses anything past these limits, so a durable agent that stays inside them loses nothing.

A string over its limit is cut, and its controls and invisible characters are removed. A list over its limit keeps its first entries. A history page over its limit is not read at all.

Versions and the telling hello

Today there is one wire version, 1, and Collie speaks 1..1.

When version 2 ships, Collie will accept version 1 for one minor release after it, and the minor after that drops it. A reader ignores a field, an event type, an item kind or a code it does not know. A field added inside version 1, such as expiresAt or decidedBy, is optional. A new required field, a new meaning for an old field, or a removed field needs a new version.

An ask of a kind the phone does not know shows as one it cannot answer from the phone, with no buttons.

When the two ranges do not meet, Collie reads nothing more from the durable agent. Once per epoch of the durable agent it sends one more hello, this time with its own version, so the durable agent can log the mismatch on its side. The durable agent answers 409 incompatible with a refusal that names both ranges. This is the telling hello.

Collie writes one line in its log for each range it refuses, and collie doctor shows both ranges. The durable agent's home on the phone says the same sentence, for example "The durable agent speaks wire v2, this Collie speaks v1. Update Collie, or the agent's SDK." Update the older side.

Where the exact rules are

WIRE.md is the contract, with every shape, code and rule.

The decisions behind it are records in the repository: