Enum Handler 

#[non_exhaustive]
pub enum Handler {
    AtLeastOnce(AtLeastOnce),
    ExactlyOnce(ExactlyOnce),
}

A handler for acknowledging or rejecting messages.

Example

use google_cloud_pubsub::model::Message;
fn on_message(m: Message, h: Handler) {
  match process(m) {
    Ok(_) => h.ack(),
    Err(e) => {
        println!("failed to process message: {e:?}");
        h.nack();
    }
  }
}

fn process(m: Message) -> anyhow::Result<()> {
  // some business logic here...
}

To acknowledge (ack) a message, you call Handler::ack().

To reject (nack) a message, you call Handler::nack(). The service will redeliver the message.

Delivery attempts

If the subscription has a dead-letter topic configured, you can retrieve the delivery attempt count.

fn on_message(h: Handler) {
    match h.delivery_attempt() {
        Some(i) => println!("Delivery attempt: {i}"),
        None => println!("Delivery attempt: unknown"),
    }
}

Exactly-once delivery

If your subscription has exactly-once delivery enabled, you should destructure this enum into its Handler::ExactlyOnce branch.

Only when ExactlyOnce::confirmed_ack() returns Ok can you be certain that the message will not be redelivered.

use google_cloud_pubsub::model::Message;
async fn on_message(m: Message, h: Handler) {
  let Handler::ExactlyOnce(h) = h else {
    panic!("Oops, my subscription does not have exactly-once delivery enabled.")
  };
  match h.confirmed_ack().await {
    Ok(()) => println!("Confirmed ack for message={m:?}. The message will not be redelivered."),
    Err(e) => println!("Failed to confirm ack for message={m:?} with error={e:?}"),
  }
}

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

AtLeastOnce(AtLeastOnce)

A handler for at-least-once delivery.

The handler type is determined by the subscription configuration.

if let Handler::AtLeastOnce(h) = h {
    h.ack();
}

ExactlyOnce(ExactlyOnce)

A handler for exactly-once delivery.

The handler type is determined by the subscription configuration.

if let Handler::ExactlyOnce(h) = h {
    h.confirmed_ack().await?;
}

Implementations

impl Handler

pub fn ack(self)

Acknowledge the message associated with this handler.

Example

use google_cloud_pubsub::model::Message;
fn on_message(m: Message, h: Handler) {
  println!("Received message: {m:?}");
  h.ack();
}

Note that the acknowledgement is best effort. The message may still be redelivered to this client, or another client, even if exactly-once delivery is enabled on the subscription.

pub fn nack(self)

Rejects the message associated with this handler.

Example

use google_cloud_pubsub::model::Message;
fn on_message(m: Message, h: Handler) {
  println!("Received message: {m:?}");
  h.nack();
}

The message will be removed from this Subscriber’s lease management. The service will redeliver this message, possibly to another client.

pub fn delivery_attempt(&self) -> Option<i32>

Returns the delivery attempt count for this message, if available.

Example

fn on_message(h: Handler) {
    match h.delivery_attempt() {
        Some(i) => println!("Delivery attempt: {i}"),
        None => println!("Delivery attempt: unknown"),
    }
}

This returns None if dead-letter topics are not configured on the subscription.

Trait Implementations

impl Debug for Handler

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.