Queue depth, backpressure, and what happens when an agent stays offline
A mediator's whole purpose is holding messages for someone who is not there. So "the queue is not empty" is not a problem: it is the product working. The questions that matter are: how long will it hold, how big may a message be, and what happens when those limits are reached.
The two limits, with their defaults
| Limit | Default | What it governs |
|---|---|---|
ENVELOPE_MAX_BYTES |
1 MiB (1,048,576) | The largest single envelope the mediator will accept |
RETENTION_DAYS |
14 days | How long a queued message is held before it is eligible for removal |
These are the shipped defaults, and a deployment can configure them. Read them as the shape of the policy, not as a service-level guarantee, relay is beta and offers no SLA.
The size limit is a design constraint, not a nuisance
A 1 MiB envelope cap means a mediator is not a file transfer service. DIDComm attachments can carry payloads, and the temptation is to route a large document through the same channel as the message describing it.
The better pattern is the one the web already uses: send a small message containing a reference, and move the bulk out of band. That keeps queue behaviour predictable and, worth noting for what a mediator can and cannot see, keeps envelope sizes from becoming a louder fingerprint than they need to be.
The retention limit is where "offline" stops being free
Fourteen days is generous for an agent that wakes daily and pointless for one that has been abandoned. After the retention window a queued message is eligible for removal, and the practical consequence is blunt: an agent that stays offline long enough loses messages, and the sender is not told. DIDComm has no delivery guarantee that survives an absent recipient indefinitely, no mediator can offer one without unbounded storage.
If your agent might be offline for weeks, design for it: a resynchronisation step on reconnect beats assuming the queue held everything.
Backpressure, and the failure that looks like backpressure
Real backpressure is a mediator declining work it cannot hold. The more common cause of a growing queue is not the mediator at all: it is an agent that collects messages and never acknowledges them.
Under Pickup 3.0 the mediator deletes a message only when the agent confirms receipt. No acknowledgement, no deletion. The symptoms:
- the same messages are re-delivered on every pickup, forever, and
- the queue grows without bound until a limit stops it.
Acknowledge after you have durably stored the message, not on receipt, see Pickup Protocol 3.0. Acknowledging then crashing loses the message permanently, because the mediator correctly deleted its copy.
What an operator can see
Queue depth per recipient, message ages, delivery and failure events, all metadata, never contents.
A delivery.failed event is emitted when delivery does not succeed, so failures are observable rather
than inferred from an unchanging number. See
webhooks and delivery logs and
reading the operator console.
The public console preview renders sample data and says so. Any queue figure visible there is illustrative and must not be quoted as a metric.
Practical rules
- Acknowledge properly. It fixes most queue growth.
- Keep envelopes small; move bulk out of band.
- Assume the queue is not archival. Fourteen days is a buffer, not storage.
- Reconcile on reconnect if long absences are expected.
Relay implements Coordinate Mediation 2.0 and Pickup 3.0; no independent DIDComm conformance suite has been run, so "implements" is the claim and "conformant" is not.