Skip to main content

Redelivery

Pub/Sub delivers a message again after a nack or an expired deadline, until a dead-letter policy moves it to a dead-letter topic.

One delivery on Pub/Sub: an ack removes the message, a nack or an expired deadline brings it back until the dead-letter capA delivery of one messagedelivery_attempt: nack:removed fromthe subscriptionnack, or thedeadline expiresDead-letter policy:is n belowmaxDeliveryAttempts?At the cap:published to thedead-letter topicBelow the cap, orno policy: the retrypolicy waits, thenit comes backThe attempt count is approximateand can reset to zero
The diagram as text
  1. A delivery of one message delivery_attempt: n → ack: removed from the subscription
  2. A delivery of one message delivery_attempt: n → nack, or the deadline expires
  3. nack, or the deadline expires → Dead-letter policy: is n below maxDeliveryAttempts?
  4. Dead-letter policy: is n below maxDeliveryAttempts? → Below the cap, or no policy: the retry policy waits, then it comes back: below
  5. Dead-letter policy: is n below maxDeliveryAttempts? → At the cap: published to the dead-letter topic: at the cap
  6. Below the cap, or no policy: the retry policy waits, then it comes back → A delivery of one message delivery_attempt: n
  7. The attempt count is approximate and can reset to zero

A subscription redelivers at once by default. Its retry policy can add an exponential backoff instead, between 0 and 600 seconds (10 and 600 by default). The backoff is best effort: under many nacks a message may wait less.

A dead-letter policy is a property of the subscription: a dead-letter topic and maxDeliveryAttempts, from 5 to 100 (5 by default). Only a subscription with one counts attempts, and only then does a delivery carry delivery_attempt. Because forwarding is best effort, a message may be delivered a few more times than the cap.

The service moves a message by publishing it to the dead-letter topic and acknowledging it in the subscription. Its service agent needs the publisher role on that topic and the subscriber role on the subscription. A dead-letter topic with no subscription of its own loses what it receives.

Exactly-once delivery​

Exactly-once delivery is another property of the subscription, for pull and streaming pull. An ack the service confirms is final: the message is not delivered again. The client must ask for that confirmation, and the guarantee holds only for subscribers that connect in the same region, which a regional endpoint ensures. Its deliveries take noticeably longer than on a standard subscription.

In this crate​

A delivery reports delivery_attempt as the pubsub-delivery-attempt header. A registration's max_attempts(n) and dead_letter(topic) become the subscription's dead-letter policy, written when the subscription opens. A cap outside 5 to 100, or one of the two declared without the other, fails the start before any call to the service. How each handler outcome reaches this picture is on Settlement.

The rules are Google's (retry policy, dead-letter topics, exactly-once delivery).