|
|
@@ -1,15 +1,23 @@
|
|
|
-//! Publish–subscribe manager.
|
|
|
+//! Publish/Subscribe core
|
|
|
//!
|
|
|
-//! This is a event-agnostic Publish-subscriber producer and consumer.
|
|
|
+//! This module defines the transport-agnostic pub/sub primitives used by both
|
|
|
+//! mint and wallet components. The design prioritizes:
|
|
|
//!
|
|
|
-//! This is a generic implementation for
|
|
|
-//! [NUT-17](<https://github.com/cashubtc/nuts/blob/main/17.md>) with a type
|
|
|
-//! agnostic Publish-subscribe manager.
|
|
|
+//! - **Request coalescing**: multiple local subscribers to the same remote topic
|
|
|
+//! result in a single upstream subscription, with local fan‑out.
|
|
|
+//! - **Latest-on-subscribe** (NUT-17): on (re)subscription, the most recent event
|
|
|
+//! is fetched and delivered before streaming new ones.
|
|
|
+//! - **Backpressure-aware delivery**: bounded channels + drop policies prevent
|
|
|
+//! a slow consumer from stalling the whole pipeline.
|
|
|
+//! - **Resilience**: automatic reconnect with exponential backoff; WebSocket
|
|
|
+//! streaming when available, HTTP long-poll fallback otherwise.
|
|
|
//!
|
|
|
-//! The manager has a method for subscribers to subscribe to events with a
|
|
|
-//! generic type that must be converted to a vector of topics.
|
|
|
-//!
|
|
|
-//! Events are also generic that should implement the `Event` trait.
|
|
|
+//! Terms used throughout the module:
|
|
|
+//! - **Event**: a domain object that maps to one or more `Topic`s via `Event::get_topics`.
|
|
|
+//! - **Topic**: an index/type that defines storage and matching semantics.
|
|
|
+//! - **SubscriptionRequest**: a domain-specific filter that can be converted into
|
|
|
+//! low-level transport messages (e.g., WebSocket subscribe frames).
|
|
|
+//! - **Spec**: type bundle tying `Event`, `Topic`, `SubscriptionId`, and serialization.
|
|
|
|
|
|
mod error;
|
|
|
mod pubsub;
|
