Manual Acknowledgment

Manual acknowledgment ensures at-least-once delivery by requiring explicit confirmation that an event was processed. This is essential for critical reliability patterns like payment processing or database synchronization.

Ack Modes

Mode	Behavior
auto	Events are acknowledged automatically upon delivery.
manual	You must explicitly call ack(), nak(), or term() for each event.

---

Acknowledgment Methods

Method	Description
ack(eventId)	Success: Confirms processing is complete.
nak(eventId, delay?)	Retry: Requests redelivery (optionally after a delay).
term(eventId)	Terminal Failure: Permanently rejects the event (no redelivery).

---

Example Usage

TypeScript

import { ironflow } from "@ironflow/browser";

const sub = await ironflow.subscribe("events:payment.>", {
  ackMode: "manual",
  onEvent: async (event) => {
    try {
      await processPayment(event.data);
      // Use the 'sub' object to acknowledge
      await sub.ack(event.eventId);
    } catch (err) {
      // Retry in 5 seconds
      await sub.nak(event.eventId, 5000);
    }
  },
});

Go

subClient := client.CreateSubscriptionClient()
if err := subClient.Connect(ctx); err != nil {
    log.Fatal(err)
}
defer subClient.Close()

sub, _ := subClient.SubscribeAckable(ctx, "events:payment.>", &ironflow.SubscribeOptions{
    AckMode: ironflow.AckModeManual,
})

for event := range sub.Events() {
    if err := processPayment(event.Data); err != nil {
        sub.Nak(event.ID, 5*time.Second)
    } else {
        sub.Ack(event.ID)
    }
}

Best Practices

1. Timeout Handling: Ensure your processing logic completes before the server’s visibility timeout.
2. Idempotency: Always implement idempotency in your onEvent handlers, as network issues can cause duplicate deliveries before an ack is received.
3. Use TERM for Invalid Data: Don’t use nak() for validation errors; use term() to prevent an infinite retry loop of bad data.