jcardena.com › Blog › Contracts Before Code: Guarantees for a Production Messaging Layer
184 posts
EN ES

Contracts Before Code: Guarantees for a Production Messaging Layer

Software

Before implementing a messaging layer, we defined its contracts: membership enforced by the protocol, order in the same write, reconnect as truth, empty push, shippable licenses.

Contracts Before Code: Guarantees for a Production Messaging Layer

Published November 2026, dated to the month the work was done.

TL;DR: A messaging layer looks like a pipe. It is a set of guarantees: order, recovery, membership and audit. Before writing code, our team evaluated established open-source messaging systems layer by layer. Several layers have credible building blocks. The delivery service does not, and licenses need the same governance as the cryptography. The contracts came first.

Our production platform runs on messages. A person writes, a service or an agent reads, something answers, and an operator approves. The platform needs a messaging capability whose security, delivery, recovery and audit guarantees our team can govern directly, with end-to-end encryption as a day-one guarantee.

A production messaging layer looks simple and hides real complexity. Before any greenfield build, I wanted the established open-source designs tested against our guarantees. The short version: several layers have credible open-source building blocks, but nothing we evaluated met the full delivery contract. The delivery service that orders and recovers messages is ours to build, and licenses must be governed as carefully as the cryptography.

Survey open-sourcemessaging systemsVerify eachproject is liveRead the code atsourceScore each layerChoose thebuilding blocksWrite thecontracts
How the evaluation was run

How the evaluation was run

We surveyed a broad set of maintained public messaging projects, then re-checked the shortlist live before reading anything closely. Several projects had moved, been renamed or been archived since they were first indexed. Stale indexes would have pointed the design at archived code.

We divided the evaluation across five domains: encryption protocols, the client library ecosystem, server design, wire protocols as they are publicly documented, and the user interface layer of several clients.

Five layers, one decision that shapes the rest

A messaging layer has five parts: group encryption, the client core, the server, transport and storage. Several have a credible open-source answer. The delivery server does not.

The decision that shapes everything is group encryption. The established design, sender keys, gives each sender a key that is shared with every member. In common sender-key designs, removing a member means distributing fresh keys to everyone who remains, so the cost grows with the group, and recovery after a key compromise depends on how often keys are rotated.

The newer standard, MLS (RFC 9420), organizes keys in a tree. The cost of a membership change grows with the logarithm of the group size, and the protocol provides membership changes and post-removal key evolution, subject to correct implementation and endpoint security. The same group-state model can cover one-to-one conversations and multiple devices. MLS is also part of the GSMA's RCS Universal Profile 3.0, which gives it multi-vendor support. For our membership and recovery guarantees, MLS was the better match.

How we judged the implementation

The required properties chose the stack, not the other way round: memory safety, one core that serves every screen, typed boundaries, and dependencies we can see and govern. Rust meets those properties, so we chose it. The language is a means, not the point.

  • The building blocks exist. There are maintained MLS implementations, a key transparency library, a Noise handshake library, a QUIC transport, and a mature client SDK whose structure is worth copying even if its network layer is never used.
  • One core, many screens. The clients that age best share one core and generate typed bindings for each mobile platform. The alternative, separate code for each platform, shows up as version drift between apps and as separate client teams for each platform.
  • Licenses must be visible. When dependencies are statically linked into one binary, as is common in Rust, a copyleft dependency's terms can reach the whole program. At least one widely used messaging protocol library, libsignal, is published under the AGPL, whose network clause can apply even when code runs only on a server. We treat license interpretation as a legal review item, not an engineering judgment.

That last point became a rule our team now applies well beyond messaging:

Keep two lists. A reading list, where any license is fine. A dependency list, where only licenses you can ship are allowed.
CLIENTNative UITyped bindingsEncrypted localstoreGROUP CRYPTOMLS group cryptoKey transparencyTRANSPORTSend queueQUICNoise handshakeSERVEROrdered messagestoreId-only pushDelivery service
The stack the study recommends

What the servers taught us

Several systems on our shortlist were read at source level, from team chat to peer-to-peer. The pattern is consistent. Across the shortlist, the live socket is only a nudge. It tells the client something changed. Correctness comes from the client re-reading the store when it reconnects. One system aims for exactly-once delivery, and it pairs that with a clear escape: when the queue is gone, the client does a full resync.

Three more lessons went into the design notes:

  • Order messages inside the write. The cleanest design assigns each message its sequence number in the same transaction that stores it. That removes a whole class of ordering bugs. Allocating numbers separately leaves room for counter corruption.
  • Push should carry nothing. The safest push payload is an id and a type. Several systems send message text in the push. Changing that later means shipping new mobile apps, so the id-only mode comes first.
  • Key transparency from the start. Retrofitting it after clients ship is costly.

What nobody hands you

We found no open delivery service ready for this shape of estate: identity, a device registry, key distribution, an offline queue, many devices per person, receipts and wake-up. MLS defines the group cryptography and then stops. The delivery service that orders and routes its messages is an explicit platform responsibility, and it is ours to build. Private identity lookup is similar: we found no maintained implementation that met our contract, so it is a platform service we own.

These are the largest pieces of the work. That bound has to be visible before implementation, not after it is underway.

The contracts, before any code

This is Governance-Driven Contract Design in its plainest form. The outcome comes first: messages between people, services and agents that we can verify, recover and audit. Then the guarantees the delivery service must keep:

  • Removing a member is enforced at the protocol level, not by a server promise.
  • Every message gets its order in the same write that stores it.
  • Reconnect is the source of truth. The live socket is only a hint.
  • Push carries an id and a type, never content.
  • Every dependency is on the shippable list before it is linked.

Each guarantee is a contract at a door: between client and server, between the server and the store, between our code and someone else's license. Research first, code second. The language was the fashionable part. The contracts are what will still hold.

Every line holds.

JC
Juan Cardena
Enterprise AI & Agentic Systems Architect

Enterprise architect with 25 years across web, software, data, and AI. MIT CDAO ’25. Writing on agentic AI in production.