grafos_mq/
lib.rs

1//! Lease-based message queue over fabric resources.
2//!
3//! `grafos-mq` provides partitioned topic-based messaging where each partition
4//! is a ring buffer in leased fabric memory. Producers send messages with
5//! round-robin or key-hash partitioning. Consumers poll from assigned
6//! partitions with offset tracking and seek support.
7//!
8//! # Architecture
9//!
10//! ```text
11//! Producer -----> TopicManager -----> Partition 0 (ring buffer in MemLease)
12//!            |                   |--> Partition 1
13//!            |                   |--> Partition N
14//!            |
15//! Consumer <----> OffsetStore
16//!            |
17//! ConsumerGroup --> partition assignment (decentralized, lease-based liveness)
18//!            |
19//! DlqRouter -----> DLQ Topic (separate topic for dead letters)
20//! ```
21//!
22//! # Quick start
23//!
24//! ```rust
25//! use grafos_mq::topic::{TopicManager, TopicConfig};
26//! use grafos_mq::producer::Producer;
27//! use grafos_mq::consumer::{Consumer, SeekPolicy};
28//! use grafos_mq::offset::MemOffsetStore;
29//!
30//! # grafos_std::host::reset_mock();
31//! # grafos_std::host::mock_set_fbmu_arena_size(1 << 20);
32//! let mut mgr = TopicManager::new();
33//! mgr.create("events", TopicConfig::default())?;
34//!
35//! // Produce
36//! let mut prod = Producer::new("events");
37//! prod.send(&mut mgr, b"hello")?;
38//! prod.send(&mut mgr, b"world")?;
39//!
40//! // Consume
41//! let store = MemOffsetStore::new();
42//! let mut consumer = Consumer::new("events", "my-group");
43//! consumer.assign(&[0, 1, 2, 3]);
44//! consumer.seek(&mgr, &store, SeekPolicy::Earliest)?;
45//! let msgs = consumer.poll(&mgr, 100)?;
46//! assert_eq!(msgs.len(), 2);
47//! # Ok::<(), grafos_std::FabricError>(())
48//! ```
49//!
50//! # Feature flags
51//!
52//! | Feature | Default | Effect |
53//! |---------|---------|--------|
54//! | `std` | Yes | Enables `std` in grafos-std |
55//! | `durable` | No | Enables durable partition spill to block storage |
56//! | `observe` | No | Enables observability hooks |
57//! | `exactly-once` | No | Enables epoch fencing for exactly-once semantics |
58
59#![cfg_attr(not(feature = "std"), no_std)]
60
61extern crate alloc;
62
63pub mod consumer;
64pub mod dlq;
65pub mod group;
66pub mod locator;
67pub mod message;
68pub mod offset;
69pub mod partition;
70pub mod producer;
71pub mod topic;
72pub mod uri;
73
74#[cfg(feature = "observe")]
75pub mod observe_hooks;
grafos_mq/lib.rs

grafos_mq/
lib.rs
