ppoppo-infra 0.1.0

Backend-agnostic infrastructure traits for caching, queuing, and messaging
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

//! # ppoppo-infra
//!
//! Backend-agnostic infrastructure traits for caching, queuing, and messaging.
//!
//! This crate defines the trait interfaces that backend implementations
//! (e.g., `ppoppo-pg` for PostgreSQL) implement. Consumers depend on
//! these traits for dependency injection, enabling backend swaps without
//! changing application code.
//!
//! ## Architecture
//!
//! ```text
//! ppoppo-infra (traits + types + decorators)
//!     ├── ppoppo-pg       (PostgreSQL impl)  → JobQueue, Lock, BufferQueue
//!     └── ppoppo-kvrocks  (KVRocks impl)     → Cache, Counter, RateLimit, PubSub
//! ```
//!
//! ## Traits
//!
//! | Trait / Type | Purpose |
//! |--------------|---------|
//! | [`Cache`] | Key-value store with TTL |
//! | [`Counter`] | Atomic increment/decrement |
//! | [`JobQueue`] | Reliable background job processing |
//! | [`Lock`] | Distributed locking |
//! | [`Publisher`] | Pub/sub messaging (write side) |
//! | [`Subscriber`] | Pub/sub messaging (read side) |
//! | [`PubSub`] | Composite: Publisher + Subscriber creation |
//! | [`RateLimit`] | Sliding window rate limiter |
//! | [`ResilientRateLimit`] | Fail-open decorator for any RateLimit impl |
//!
//! ## Extension Traits
//!
//! [`CacheExt`], [`JobQueueExt`], and [`PublisherExt`] provide typed
//! convenience methods (using `Serialize`/`DeserializeOwned`) on top
//! of the `serde_json::Value`-based core traits.
//!
//! ```rust,ignore
//! use ppoppo_infra::{Cache, CacheExt};
//!
//! async fn example(cache: &dyn Cache) {
//!     // Core trait: serde_json::Value
//!     cache.set("key", &json!({"name": "Alice"}), Some(300)).await?;
//!
//!     // Extension: typed convenience
//!     cache.set_typed("key", &user, Some(300)).await?;
//!     let user: Option<User> = cache.get_typed("key").await?;
//! }
//! ```

pub mod cache;
pub mod counter;
pub mod error;
pub mod ext;
pub mod job_queue;
pub mod lock;
pub mod publisher;
pub mod pubsub;
pub mod rate_limit;
pub mod resilient;
pub mod staging_flusher;
pub mod staging_writer;
pub mod subscriber;
pub mod types;

// Re-export traits
pub use cache::Cache;
pub use counter::Counter;
pub use error::{Error, Result};
pub use ext::{CacheExt, JobQueueExt, PublisherExt};
pub use job_queue::JobQueue;
pub use lock::{Lock, LockGuard};
pub use publisher::Publisher;
pub use pubsub::PubSub;
pub use rate_limit::RateLimit;
pub use resilient::ResilientRateLimit;
pub use staging_flusher::{StagingFlusher, StagingItem};
pub use staging_writer::StagingWriter;
pub use subscriber::Subscriber;

// Re-export types
pub use types::{
    Job, JobStatus, Notification, Priority, QueueStats, RateLimitResult, TypedJob,
};

// ═══════════════════════════════════════════════════════════════════════════════
// Compile-time assertions (RNAA §5)
// ═══════════════════════════════════════════════════════════════════════════════

static_assertions::assert_impl_all!(Error: Send, Sync);