How delivery works

1. A client opens an overlay session and attaches to a nearby edge (WebSocket or browser WebTransport).
2. It authenticates with an access token.
3. A writer publishes a payload to tenant + channel.
4. The overlay forwards the message along measured relay paths.
5. Edges fan out to listeners currently subscribed to that tenant and a matching channel pattern.

You do not dial every peer. FastPubSub is the relay.

Need the exact contract (drops, duplicates, ordering, backpressure)? See Delivery semantics.

Online-only delivery (no persistence)

FastPubSub does not store message history. Messages go only to listeners that are connected and subscribed at publish time. An offline listener does not get a replay.

That keeps the hot path short: receive, authorize, route, deliver. Disk writes and replication acks would add latency on every hop.

Need a log or replay? Put your own broker next to FastPubSub (subscribe, persist, republish). We are also building an open-source FastPubSub broker for that role. Until it is out, FastPubSub itself stays online-only.

Path reliability

The overlay keeps measuring latency, jitter, and loss between relays. When a public Internet path degrades, traffic moves to another measured route. During reconvergence some messages may be lost. The stream continues. FastPubSub guarantees the path, not every sample.

Subscribe join window

A listener starts receiving only after its subscription has reached the relevant relays and the publisher’s side of the overlay.

How long that takes depends on distance. Nearby servers usually see the join in a few milliseconds. Farther hops take longer. A long path such as Frankfurt to Australia is typically a few hundred milliseconds (around 400 ms is a realistic far-end case), not a hard SLA.

If a writer publishes immediately after a subscribe, the first messages may miss that listener. Subscribe first. Wait for the SDK subscribe ack when you have one. Then publish.

Delivery modes

Default publish() is broadcast: every current subscriber matching the channel can receive the message.

publishWithOptions / publish_with_options can select deliver-one modes:

• broadcast — all matching subscribers
• deliverOneLowLatency — one overlay node with subscribers (lowest inter-node latency), then one local connection on that edge
• deliverOneRandom — one random overlay node with subscribers, then one local connection

If nobody is subscribed, deliver-one does nothing.