ppoppo_infra/
lib.rs

1//! # ppoppo-infra
2//!
3//! Backend-agnostic infrastructure traits for caching, queuing, and messaging.
4//!
5//! This crate defines the trait interfaces that backend implementations
6//! (e.g., `ppoppo-pg` for PostgreSQL) implement. Consumers depend on
7//! these traits for dependency injection, enabling backend swaps without
8//! changing application code.
9//!
10//! ## Architecture
11//!
12//! ```text
13//! ppoppo-infra (traits + types + decorators)
14//!     ├── ppoppo-pg       (PostgreSQL impl)  → JobQueue, Lock, BufferQueue
15//!     └── ppoppo-kvrocks  (KVRocks impl)     → Cache, Counter, RateLimit, PubSub
16//! ```
17//!
18//! ## Traits
19//!
20//! | Trait / Type | Purpose |
21//! |--------------|---------|
22//! | [`Cache`] | Key-value store with TTL |
23//! | [`Counter`] | Atomic increment/decrement |
24//! | [`JobQueue`] | Reliable background job processing |
25//! | [`Lock`] | Distributed locking |
26//! | [`Publisher`] | Pub/sub messaging (write side) |
27//! | [`Subscriber`] | Pub/sub messaging (read side) |
28//! | [`PubSub`] | Composite: Publisher + Subscriber creation |
29//! | [`RateLimit`] | Sliding window rate limiter |
30//! | [`ResilientRateLimit`] | Fail-open decorator for any RateLimit impl |
31//!
32//! ## Extension Traits
33//!
34//! [`CacheExt`], [`JobQueueExt`], and [`PublisherExt`] provide typed
35//! convenience methods (using `Serialize`/`DeserializeOwned`) on top
36//! of the `serde_json::Value`-based core traits.
37//!
38//! ```rust,ignore
39//! use ppoppo_infra::{Cache, CacheExt};
40//!
41//! async fn example(cache: &dyn Cache) {
42//!     // Core trait: serde_json::Value
43//!     cache.set("key", &json!({"name": "Alice"}), Some(300)).await?;
44//!
45//!     // Extension: typed convenience
46//!     cache.set_typed("key", &user, Some(300)).await?;
47//!     let user: Option<User> = cache.get_typed("key").await?;
48//! }
49//! ```
50
51pub mod cache;
52pub mod counter;
53pub mod error;
54pub mod ext;
55pub mod job_queue;
56pub mod lock;
57pub mod publisher;
58pub mod pubsub;
59pub mod rate_limit;
60pub mod resilient;
61pub mod staging_flusher;
62pub mod staging_writer;
63pub mod subscriber;
64pub mod types;
65
66// Re-export traits
67pub use cache::Cache;
68pub use counter::Counter;
69pub use error::{Error, Result};
70pub use ext::{CacheExt, JobQueueExt, PublisherExt};
71pub use job_queue::JobQueue;
72pub use lock::{Lock, LockGuard};
73pub use publisher::Publisher;
74pub use pubsub::PubSub;
75pub use rate_limit::RateLimit;
76pub use resilient::ResilientRateLimit;
77pub use staging_flusher::{StagingFlusher, StagingItem};
78pub use staging_writer::StagingWriter;
79pub use subscriber::Subscriber;
80
81// Re-export types
82pub use types::{
83    Job, JobStatus, Notification, Priority, QueueStats, RateLimitResult, TypedJob,
84};
85
86// ═══════════════════════════════════════════════════════════════════════════════
87// Compile-time assertions (RNAA §5)
88// ═══════════════════════════════════════════════════════════════════════════════
89
90static_assertions::assert_impl_all!(Error: Send, Sync);
ppoppo_infra/lib.rs

ppoppo_infra/
lib.rs
