Protocols as Promises

A protocol is a promise two strangers agree to keep. Neither party has met the other. Neither will read the other’s source code. The only thing standing between them and chaos is a written specification and a shared willingness to honour it.

The boring parts are the load-bearing parts

The exciting parts of a protocol — the new feature, the cool extension, the performance trick — are not what keeps it alive. The boring parts do that. Version numbers. Error codes. What counts as a malformed message. What the server is allowed to do when the client sends something it does not understand. These are the conditions under which the promise can still be kept when something goes wrong, and something will always eventually go wrong.

A protocol that only works on the happy path is not a protocol. It is a coincidence. The first time a network blips, a clock skews, a client falls behind on releases, or a malicious actor sends a deliberately malformed frame, the coincidence collapses, and every implementation downstream has to invent its own recovery story. The recovery stories will not agree. The system is now a tower of competing improvisations held together by goodwill.

Forwards and backwards compatibility are ethical commitments

Every protocol upgrade is a promise to the implementers who shipped against the previous version. They wrote code in good faith. They built businesses on top of the assumption that the contract would hold. Breaking the contract silently — changing a field’s meaning, removing a status code, tightening validation without warning — is not a technical decision. It is a breach of trust at scale.

Good protocol design treats compatibility as the default and breakage as an event that requires ceremony: a major version bump, a deprecation window with real timelines, a migration path documented in detail, an escape hatch for the implementers who cannot move on your timeline. Bad protocol design treats compatibility as a constraint to be minimized so the maintainers can keep moving. The maintainers are not the customer. The ecosystem is.

The specification is the substrate

An unwritten protocol is a protocol whose canonical reference is the source code of whoever happens to be most popular. This is how monocultures are born, and how the smaller players in an ecosystem get forced into a permanent role of guessing what the leader meant. If the protocol matters, write it down. Write it down with examples. Write it down with the edge cases. Write it down with the deliberate ambiguities labeled as such, so the implementer does not assume one resolution and discover, six months later, that another implementer assumed the opposite.

A specification is not a marketing document. It does not get to use the word ‘should’ when it means ‘must.’ RFC 2119 exists for a reason. Use the keywords. Mean them. The reader is going to base production decisions on the precision of your prose.

What to do when you must extend

Leave room to extend, but never silently. A reserved field is a future feature with a name. An ignored unknown is a forwards-compatibility gift to your future self. A capability negotiation step at the start of a session is a thousand times cheaper than discovering, at scale, that half the implementations cannot handle the new option you shipped.

And document the extension contract before you ship the first extension. If the rule for unknown fields is ‘ignore’, say so. If the rule is ‘reject’, say so, and accept that you have just constrained every future change. Either is defensible. What is not defensible is leaving the rule unspecified and letting the ecosystem split into ‘strict’ and ‘lenient’ camps that quietly stop being interoperable.

Design like a stranger is going to read it

Design protocols the way you would draft a contract with a stranger you trust but cannot supervise. Be explicit. Be conservative. Leave room to extend, but never silently. Assume that the version of the world in which everyone updates simultaneously does not exist, because it never has.

The protocol that survives is the one whose authors took the boring parts seriously. The exciting parts are why people adopt it. The boring parts are why they stay.