Skip to main content

Leases

A streaming pull leases each message: the client extends its ack deadline while the handler works, and flow control caps how many it holds.

A streaming pull: messages arrive under a lease the client extends while the application holds them, and acks go back in batchesgoogle-cloud-pubsubApplicationPub/Sub subscriptionan ack deadline per messageStreaming pullup to max_outstandingLease setchecked every 3 sAcks andnacks, sentin batchesevery 100 msHandlerholds the messageSettles it:ack or nackPast max_lease the client stops extending:the deadline runs out and the message comes back
The diagram as text
  1. google-cloud-pubsub: Streaming pull up to max_outstanding; Lease set checked every 3 s; Acks and nacks, sent in batches every 100 ms
  2. Application: Handler holds the message; Settles it: ack or nack
  3. Pub/Sub subscription an ack deadline per message → Streaming pull up to max_outstanding: messages
  4. Streaming pull up to max_outstanding → Lease set checked every 3 s
  5. Lease set checked every 3 s → Handler holds the message
  6. Handler holds the message → Settles it: ack or nack
  7. Lease set checked every 3 s → Pub/Sub subscription an ack deadline per message: extends
  8. Settles it: ack or nack → Acks and nacks, sent in batches every 100 ms: settled
  9. Acks and nacks, sent in batches every 100 ms → Pub/Sub subscription an ack deadline per message: ack, nack
  10. Past max_lease the client stops extending: the deadline runs out and the message comes back

A streaming pull is one long-lived gRPC stream per subscription. The service sends messages down it as they arrive, and each one comes with an ack deadline. A message that is neither acknowledged nor extended before its deadline is delivered again, possibly to another subscriber.

The client library holds that deadline off. It sends modifyAckDeadline for every message the application still holds, pushing each deadline at most ack_extension ahead (60 seconds by default, clamped to 10 to 600). It does so for at most max_lease, one hour by default. A process that dies sends no extensions, so its messages return to the subscription once their deadlines pass.

Flow control is on the stream. The service stops sending while max_outstanding messages (1000 by default) or 100 MiB are unsettled on it, and resumes when the count drops below. A slow handler therefore slows its own stream down, and the messages it has not received wait in the subscription.

An ack removes the message from the subscription. A nack is a modifyAckDeadline with a deadline of zero: the message leaves the lease set, and the service delivers it again, as Redelivery draws.

The figures are the google-cloud-pubsub 1.3 client's (Subscribe) and Google's (lease management).