Skip to main content

photon_backend_nats/
lib.rs

1//! NATS `JetStream` [`StoragePort`](photon_backend::StoragePort) for distributed Photon delivery.
2//!
3//! Wraps `JetStream` consumer groups, checkpoint persistence, and stream sharding behind the shared
4//! storage contract. Enable via the `nats` feature on the
5//! [`photon`](https://docs.rs/uf-photon/latest/photon/) public crate.
6//!
7//! Connection and stream options: [`NatsConfig`] and [`NatsStoragePortBuilder`]
8//! (builder methods + env fallbacks documented on the builder).
9//!
10//! Wire with [`PhotonBuilder::storage_port`](https://docs.rs/uf-photon/latest/photon/struct.PhotonBuilder.html#method.storage_port)
11//! after [`NatsStoragePortBuilder::build`](NatsStoragePortBuilder::build).
12//!
13//! ## Entry points
14//!
15//! - [`NatsStoragePort`] — `JetStream` storage adapter
16//! - [`NatsConfig`] / [`NatsStoragePortBuilder`] — connection and stream options
17//! - [`nats_url_from_env`] — resolve broker URL from environment
18//!
19//! Performance methodology: [`photon-bench/PERFORMANCE_STUDY.md`](../../photon-bench/PERFORMANCE_STUDY.md).
20//!
21//! ## Topic mapping (NATS)
22//!
23//! - **Subject:** `photon.{topic}` when `stream_shards = 1`; `photon-s.{shard}.{topic}` when sharded.
24//! - **`JetStream` stream:** default `photon` with `photon.>`; sharded mode uses `photon-0`…`photon-(K-1)`.
25//! - **Checkpoints:** KV bucket `photon-checkpoints` (skipped when [`ReplayCursor::TailOnly`]).
26//! - **Replay:** [`ReplayCursor::StreamSeq`] uses `JetStream` stream sequence; [`ReplayCursor::TailOnly`] tails live only.
27
28#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]
29mod checkpoint;
30mod config;
31mod connect;
32mod consumer;
33mod kv;
34mod message;
35mod port;
36mod publish;
37mod replicas;
38mod retention;
39mod stream;
40pub mod stream_shard;
41mod subject;
42
43pub use config::{
44    NatsConfig, NatsStoragePortBuilder, ReplayCursor, CREDS_ENV, MAX_INFLIGHT_ENV,
45    REPLAY_CURSOR_ENV, STREAM_ENV, SYNC_ACK_ENV, URL_ENV,
46};
47pub use consumer::{deliver_subject_for, durable_consumer_name};
48pub use port::{nats_url_from_env, NatsStoragePort};
49pub use replicas::REPLICAS_ENV;
50pub use retention::RETENTION_ENV;
51pub use stream_shard::STREAM_SHARDS_ENV;