Delivery semantics

This page describes the delivery contract of LowLatencyPubSub: what you can rely on, and what you must design for.

Online-only, best-effort

No persistence: the service does not store message history.
Online-only delivery: only listeners that are connected and effectively subscribed at the moment of publish may receive the message.
Best-effort: messages can be dropped due to network issues, disconnects, node overload, or slow consumers.

If you need guaranteed delivery, replay, or durable queues, you must build that above the transport (or use a different system).

There is no global ordering across the system.
Within one connection and one stream, messages are typically received in the order they are sent by the server on that connection.
Across reconnects, multi-region paths, or multiple writers, you must assume reordering is possible.

Recommendation: if ordering matters, include your own sequence number or timestamp in the payload and handle reordering on the client.

The protocol does not guarantee exactly-once delivery. In practice, duplicates can happen:

when clients reconnect and re-subscribe,
when your application retries publishes,
when your client code processes the same message twice after a transient failure.

Recommendation: make consumers idempotent when possible (for example, include a message id in payload and deduplicate on the client).

If a listener cannot read fast enough, the server must protect itself:

internal buffers may fill up,
the connection can be closed (a typical symptom is “disconnect while subscribed”),
some deployments may drop messages for that listener under pressure.

Recommendation:

Subscriptions are distributed across the service overlay and become effective after propagation.

After subscribe, there is a join window where early publishes may be missed.
In global setups, propagation delay can be hundreds of milliseconds up to ~1 second.

Recommendation:

subscribe first, then wait for an “ready/ack” signal (if your client protocol has it), or wait a small safety delay before publishing,
for critical “first message” flows, send a lightweight handshake message and retry until the listener confirms it received it.

You should assume:

See How delivery works for a high-level explanation.