Core model

Fibril uses a strict queue state machine. Each offset exists in at most one of three states:

Ready -> Inflight -> Acked
  ^         |
  +---------+
   retry or expired lease

Ready

A ready message is eligible for delivery. Consumers pull work rather than receiving an unbounded push stream.

Inflight

Polling leases a message to a consumer until a deadline. If the consumer does not settle the message before expiry, the broker can return it to Ready.

Acked

Acknowledgement is final. An acked offset does not re-enter delivery.

Explicit settlement

Manual-ack consumers decide what happens after processing:

Rust

msg.complete().await?;      // terminal success
msg.retry().await?;         // requeue immediately
msg.retry_after(std::time::Duration::from_secs(30)).await?; // requeue after a delay
msg.fail().await?;          // terminal failure

TypeScript

await msg.complete();         // terminal success
await msg.retry();            // requeue immediately
await msg.retryAfter(30_000); // requeue after a delay
await msg.fail();             // terminal failure

Python

await msg.complete()      # terminal success
await msg.retry()         # requeue immediately
await msg.retry_after(30) # requeue after a delay
await msg.fail()          # terminal failure

Go

msg.Complete()                        // terminal success
msg.Retry()                      // requeue immediately
msg.RetryAfter(30 * time.Second) // requeue after a delay
msg.Fail()                       // terminal failure

C#

msg.Complete();                                // terminal success
msg.Retry();                              // requeue immediately
msg.RetryAfter(TimeSpan.FromSeconds(30)); // requeue after a delay
msg.Fail();                               // terminal failure

Delayed retry keeps the message out of ready delivery until its retry deadline.

Why leasing

Leasing makes failure recovery explicit. A consumer can disappear without permanently taking messages with it, and bounded prefetch gives the broker a concrete backpressure mechanism.