Crate ppoppo_infra 

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

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.

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?;
}

Re-exports

pub use cache::Cache;

pub use counter::Counter;

pub use error::Error;

pub use error::Result;

pub use ext::CacheExt;

pub use ext::JobQueueExt;

pub use ext::PublisherExt;

pub use job_queue::JobQueue;

pub use lock::Lock;

pub use lock::LockGuard;

pub use publisher::Publisher;

pub use pubsub::PubSub;

pub use rate_limit::RateLimit;

pub use resilient::ResilientRateLimit;

pub use staging_flusher::StagingFlusher;

pub use staging_flusher::StagingItem;

pub use staging_writer::StagingWriter;

pub use subscriber::Subscriber;

pub use types::Job;

pub use types::JobStatus;

pub use types::Notification;

pub use types::Priority;

pub use types::QueueStats;

pub use types::RateLimitResult;

pub use types::TypedJob;

Modules

cache

Backend-agnostic cache trait.

counter

Backend-agnostic counter trait.

error

Backend-agnostic error types for infrastructure operations.

ext

Extension traits with typed convenience methods.

job_queue

Backend-agnostic job queue trait.

lock

Backend-agnostic distributed lock trait.

publisher

Backend-agnostic publisher trait (write side of pub/sub).

pubsub

Composite pub/sub trait binding Publisher and Subscriber to the same backend.

rate_limit

Backend-agnostic rate limiter trait.

resilient

Fail-open decorator for rate limiting.

staging_flusher

Backend-agnostic staging flusher trait.

staging_writer

Backend-agnostic staging writer trait.

subscriber

Backend-agnostic subscriber trait (read side of pub/sub).

types

Shared types used across infrastructure trait boundaries.