Skip to main content

Lifecycle

PubSubBroker::new records configuration, connect builds the clients, startup opens each subscription, and shutdown flushes the publishers.

The broker's three states as types, and what each transition does on Pub/SubBrokerOn Pub/SubPubSubBroker::new(project)ConnectedPubSubBrokerClosed: ()Configuration only,no I/OFour clients builtfor the connectionEach subscription:topology createdwhere declared, thenits stream openedA topic's first publishstarts its publisherClosed, then everytopic's publisherflushedA publisher used before connect or after shutdownanswers NotConnected, never a silent success
The diagram as text
  1. Broker: PubSubBroker::new (project); ConnectedPubSubBroker; Closed: ()
  2. On Pub/Sub: Configuration only, no I/O; Four clients built for the connection; Each subscription: topology created where declared, then its stream opened; A topic's first publish starts its publisher; Closed, then every topic's publisher flushed
  3. PubSubBroker::new (project) → ConnectedPubSubBroker: connect(self)
  4. ConnectedPubSubBroker → Closed: (): shutdown(self)
  5. Configuration only, no I/O → Four clients built for the connection
  6. Four clients built for the connection → Each subscription: topology created where declared, then its stream opened
  7. Each subscription: topology created where declared, then its stream opened → A topic's first publish starts its publisher
  8. A topic's first publish starts its publisher → Closed, then every topic's publisher flushed
  9. A publisher used before connect or after shutdown answers NotConnected, never a silent success

new does no I/O, so the service's builder stays synchronous. A publisher taken from the broker before connect shares the connection the runtime fills in later.

Each subscription opens once, at startup. Its descriptor is checked first: an empty name, a dead-letter cap outside 5 to 100, or half a declaration fails the start before any call to the service. A descriptor with create_with_topic then creates the topic, the dead-letter topic and the subscription where they are missing, the subscription with message ordering on. Against Pub/Sub that needs the permissions to create topics and subscriptions. A subscription that already exists and has a declared dead-letter policy gets that policy written onto it. Then the streaming pull opens.

A registration mounted by a bare name declares its retries the same way. Two registrations of one subscription with different declarations fail the start, because a subscription carries one dead-letter policy.

Shutdown marks the connection closed, then flushes every topic's publisher so batched messages reach the service. The closed state carries nothing. A subscription stops when the runtime drops it: the client stops reading and keeps extending the leases of messages still held, until they settle.