klauthed-data 0.6.0

Data-access building blocks for klauthed: pagination, transactional outbox, idempotency, locks, and caching.
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
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

#![deny(unsafe_code)]
#![deny(missing_docs)]
#![cfg_attr(
    not(test),
    deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::indexing_slicing)
)]

//! Data-layer connectors for klauthed services.
//!
//! This crate turns the typed configuration sections from
//! [`klauthed_core::config`] into **real, connected resources** — database
//! pools, cache clients — so a service never hand-rolls connection wiring.
//!
//! Every backend lives behind a Cargo feature, so a service compiles only the
//! drivers it actually uses:
//!
//! (Plain code spans below rather than intra-doc links, since these items are
//! feature-gated and absent from a default-feature doc build.)
//!
//! | Feature        | Provides                                              |
//! |----------------|-------------------------------------------------------|
//! | `postgres`     | `db::connect` for PostgreSQL (implies `sql`)         |
//! | `mysql`        | `db::connect` for MySQL/MariaDB (implies `sql`)      |
//! | `sqlite`       | `db::connect` for SQLite (implies `sql`)             |
//! | `redis`        | `cache::connect_redis`                               |
//! | `cache-memory` | `cache::build_memory_cache` (moka, in-process)      |
//! | `nats`         | `messaging::connect_nats` (async-nats)              |
//! | `rabbitmq`     | `messaging::connect_rabbitmq` (lapin / AMQP)        |
//! | `kafka`        | `messaging::connect_kafka` (rskafka, pure Rust)     |
//! | `storage`      | `storage::connect` for local filesystem             |
//! | `storage-s3`   | `storage::connect` for S3 / S3-compatible           |
//! | `storage-gcs`  | `storage::connect` for Google Cloud Storage         |
//! | `storage-azure`| `storage::connect` for Azure Blob Storage           |
//! | `mongodb`      | `db::mongo::connect` for MongoDB                    |
//!
//! ```no_run
//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
//! use klauthed_core::config::Config;
//!
//! let config = Config::load().await?;
//!
//! # #[cfg(feature = "sql")]
//! let pool = klauthed_data::db::connect(&config.database()?).await?;
//! # Ok(())
//! # }
//! ```

pub mod error;

// ── Reliability patterns ──────────────────────────────────────────────────────
//
// Backend-agnostic traits with in-memory implementations. These are always
// compiled (no feature gate) since they carry no driver dependencies; real
// Postgres/Redis backends are in sub-modules gated by their own features.

pub mod idempotency;
pub mod locks;
pub mod outbox;
pub mod rate_limit;

// The `db` module houses the relational connector (sql feature) and the
// MongoDB sub-module (mongodb feature). It is compiled whenever any of those
// features is active.
#[cfg(any(feature = "sql", feature = "mongodb"))]
pub mod db;

#[cfg(any(feature = "redis", feature = "cache-memory"))]
pub mod cache;

#[cfg(any(feature = "nats", feature = "rabbitmq", feature = "kafka"))]
pub mod messaging;

#[cfg(feature = "storage")]
pub mod storage;

// Embedded, versioned schema migrations over a relational pool.
#[cfg(feature = "sql")]
pub mod migrate;

// Auto-configuration starter: build the SQL pool from config into an AppContext.
#[cfg(feature = "sql")]
pub mod starter;

// ── Stub modules reserved for future implementation ───────────────────────────
pub mod eventbus;
pub mod pagination;
pub mod saga;
pub mod transaction;

pub use error::DataError;

#[cfg(feature = "sql")]
pub use migrate::{Migration, Migrator};
#[cfg(feature = "sql")]
pub use sqlx::AnyPool;
#[cfg(feature = "sql")]
pub use starter::DataStarter;

pub use idempotency::{
    IdempotencyRecord, IdempotencyStatus, IdempotencyStore, InMemoryIdempotencyStore, Outcome,
};
pub use locks::{InMemoryLockManager, LockGuard, LockManager, LockToken};
pub use outbox::{InMemoryOutbox, Outbox, OutboxEntry, OutboxId};

/// Common imports for the data layer: `use klauthed_data::prelude::*;`.
pub mod prelude {
    #[cfg(feature = "sql")]
    pub use crate::{AnyPool, DataStarter, Migration, Migrator};
    pub use crate::{
        DataError, IdempotencyStore, InMemoryIdempotencyStore, InMemoryLockManager, InMemoryOutbox,
        LockGuard, LockManager, LockToken, Outbox, OutboxEntry, OutboxId,
    };
}

#[cfg(feature = "sql")]
pub use outbox::SqlOutbox;

#[cfg(feature = "redis")]
pub use locks::redis::RedisLockManager;

#[cfg(feature = "redis")]
pub use idempotency::redis::RedisIdempotencyStore;

#[cfg(feature = "mongodb")]
pub use outbox::MongoOutbox;

#[cfg(feature = "mongodb")]
pub use locks::mongo::MongoLockManager;

#[cfg(feature = "mongodb")]
pub use idempotency::mongo::MongoIdempotencyStore;