Acknowledgement

ack acknowledges a delivery, retry nacks it so Pub/Sub redelivers it, and drop acknowledges one that is not worth another attempt.

Pub/Sub settles each message on its own, by acknowledging it or by giving it back. ack acknowledges, and the subscription does not deliver the message again. retry nacks, and the subscription redelivers the message, possibly to another consumer. A subscription with no retry policy redelivers at once; one with an exponential backoff policy waits first. drop acknowledges too: Pub/Sub has no verb that discards a message without settling it. The one exception is the last delivery a dead-letter policy allows: there drop nacks, so the service moves the message to the dead-letter topic. A delayed retry is retry_after.

Exactly-once subscriptions

A subscription with exactly-once delivery on guarantees that an acknowledged message is not delivered again. It is a property of the subscription's configuration, and the crate reads it off each delivery. On such a subscription an ack and a nack wait for the service to confirm them. An acknowledgement the service rejects, such as one whose lease has expired, fails the settlement with an AckError that carries the cause, and the message may come back. On other subscriptions an ack is sent in the background and returns at once. The guarantee holds for subscribers in the subscription's region, which a locational endpoint pins.

Example

A reservation acknowledges an order it reserved, drops an order with nothing to reserve, and asks for another delivery while the stock is out.

Macros

examples/pubsub_settlement.rs

/// Reserves stock for an order.
#[subscriber(GooglePubSub::new("orders-workers").create_with_topic("orders"))]
async fn reserve(order: &Order) -> HandlerOutcome {
    if order.quantity == 0 {
        // Nothing to reserve, now or later: acknowledged, never redelivered.
        return HandlerOutcome::drop();
    }
    if !order.in_stock {
        // Nacked: the subscription delivers the order again.
        return HandlerOutcome::retry();
    }
    tracing::info!(order.id, "stock reserved");
    HandlerOutcome::ack()
}

Manual

examples/manual/pubsub_settlement.rs

/// Reserves stock for an order.
struct Reserve;

impl Handle<Order> for Reserve {
    fn handle(
        &self,
        order: &Order,
        _outs: &(),
        _ctx: &mut Context<'_>,
    ) -> impl Future<Output = Result<(), HandlerOutcome>> {
        if order.quantity == 0 {
            // Nothing to reserve, now or later: acknowledged, never redelivered.
            return ready(Err(HandlerOutcome::drop()));
        }
        if !order.in_stock {
            // Nacked: the subscription delivers the order again.
            return ready(Err(HandlerOutcome::retry()));
        }
        tracing::info!(order.id, "stock reserved");
        ready(Ok(()))
    }
}