Skip to main content

Subscriptions

A Pulsar subscription is a named cursor the broker stores. Every subscription receives the whole topic, and its type decides how its consumers share it.

Two subscriptions on one topic, each with its own cursor, and how the consumers of one subscription share it under each of the four typesTopic ordersThe consumers of one subscription, by its typeExclusiveSharedFailoverKeyShared0123456Subscription auditcursor at entry 1Subscription billingcursor at entry 5C1 gets every messageC2 waits for C1C1 gets entry 5C2 gets entry 6C1 active, in orderC2 waits as standbykey A goes to C1key B goes to C2The broker stores each cursor: a subscription outlives its consumersand receives every message published while they are away
The diagram as text
  1. Topic orders: 0; 1; 2; 3; 4; 5; 6
  2. The consumers of one subscription, by its type: C1 gets every message; C2 waits for C1; C1 gets entry 5; C2 gets entry 6; C1 active, in order; C2 waits as standby; key A goes to C1; key B goes to C2
  3. Exclusive: C1 gets every message; C2 waits for C1
  4. Shared: C1 gets entry 5; C2 gets entry 6
  5. Failover: C1 active, in order; C2 waits as standby
  6. KeyShared: key A goes to C1; key B goes to C2
  7. Subscription audit cursor at entry 1 → 1: reads next
  8. Subscription billing cursor at entry 5 → 5: reads next
  9. Subscription billing cursor at entry 5 → The consumers of one subscription, by its type
  10. The broker stores each cursor: a subscription outlives its consumers and receives every message published while they are away

Two subscriptions on one topic never affect each other. Each has its own cursor and receives every message. Consumers that attach under the same subscription name share that one cursor. The subscription is durable: it stays on the broker when its last consumer leaves, and the backlog grows until a consumer returns.

SubscriptionType picks how the consumers of one subscription share it:

TypeConsumersOrder
Exclusiveone; a second waitskept
Shared (default)all, each message to one of themnone
Failoverone active, the others on standbykept
KeySharedall, each key to one of themkept per key

A second consumer of an Exclusive subscription is answered "consumer busy". The client treats that answer as one to retry, and by default it retries without a limit, five seconds apart. So the second consumer waits for the first to leave, and its service does not start. OperationRetries bounds the tries, and subscribing then fails with PulsarError::Subscribe.

The server creates a subscription the first time a consumer names it, positioned at the newest message: the pulsar client asks for that position unless told otherwise, and this crate leaves it. A service that starts somewhere else repositions the subscription with a seek, which PulsarPosition names. A seek moves the stored cursor itself, so it applies on every start, not only the first.

A subscription over a list of topics, or over a pattern, is one consumer per topic inside the client, read as one stream. A pattern matches topics by their full names. The client lists the topics again every 30 seconds, so a topic created after the subscription opened joins it on the next listing.

The model is Apache Pulsar's own (subscriptions, subscription types). How a consumer acknowledges is on Acknowledgement.