dynamo_table/

lib.rs

//! # DynamoDB Table Abstraction
//!
//! A high-level, type-safe DynamoDB table abstraction for Rust with support for:
//! - Batch operations (get, write, delete)
//! - Pagination and streaming
//! - Global Secondary Indexes (GSI)
//! - Conditional expressions
//! - Optimistic locking
//! - Automatic retry with exponential backoff
//!
//! ## Features
//!
//! - **Type-safe**: Leverage Rust's type system with `serde` for automatic serialization
//! - **Async-first**: Built on `tokio` and `aws-sdk-dynamodb`
//! - **Batch operations**: Efficiently process multiple items with automatic batching
//! - **Streaming**: Handle large result sets with async streams
//! - **Reserved word validation**: Debug-mode checks for DynamoDB reserved words
//! - **GSI support**: Query and scan Global Secondary Indexes
//! - **Consumed capacity tracking**: Global atomic counters for every operation, with `tracing`
//!   logging and automatic shutdown reporting via [`CapacityStatsGuard`] (feature `consumed_capacity_stats`, on by default)
//!
//! ## Quick Start
//!
//! ```rust,no_run
//! use dynamo_table::{DynamoTable, Error};
//! use serde::{Deserialize, Serialize};
//!
//! #[derive(Debug, Clone, Serialize, Deserialize)]
//! struct User {
//!     user_id: String,
//!     email: String,
//!     name: String,
//! }
//!
//! impl DynamoTable for User {
//!     type PK = String;
//!     type SK = String;
//!
//!     const TABLE: &'static str = "users";
//!     const PARTITION_KEY: &'static str = "user_id";
//!     const SORT_KEY: Option<&'static str> = None;
//!
//!     fn partition_key(&self) -> Self::PK {
//!         self.user_id.clone()
//!     }
//! }
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Error> {
//!     // Initialize the global DynamoDB client
//!     let config = aws_config::defaults(aws_config::BehaviorVersion::latest()).load().await;
//!     dynamo_table::init(&config).await;
//!
//!     // Put an item
//!     let user = User {
//!         user_id: "123".to_string(),
//!         email: "user@example.com".to_string(),
//!         name: "John Doe".to_string(),
//!     };
//!     user.add_item().await?;
//!
//!     // Get an item
//!     let retrieved = User::get_item(&"123".to_string(), None).await?;
//!
//!     // Query items
//!     let result = User::query_items(&"123".to_string(), None, None, None).await?;
//!
//!     Ok(())
//! }
//! ```
#![deny(
    warnings,
    bad_style,
    dead_code,
    improper_ctypes,
    non_shorthand_field_patterns,
    no_mangle_generic_items,
    overflowing_literals,
    path_statements,
    patterns_in_fns_without_body,
    unconditional_recursion,
    unused,
    unused_allocation,
    unused_comparisons,
    unused_parens,
    while_true,
    missing_debug_implementations,
    missing_docs,
    trivial_casts,
    trivial_numeric_casts,
    unreachable_pub,
    unused_extern_crates,
    unused_import_braces,
    unused_qualifications,
    unused_results,
    deprecated,
    unknown_lints,
    unreachable_code,
    unused_mut
)]

mod error;
pub use error::Error;

/// Consumed capacity tracking via global atomic counters (requires `consumed_capacity_stats` feature).
#[cfg(feature = "consumed_capacity_stats")]
pub mod consumed_capacity;

#[cfg(feature = "consumed_capacity_stats")]
pub use consumed_capacity::stats::{
    CapacityStats, CapacityStatsGuard, log_stats, operation_count, read_capacity_units, record,
    record_from_option, record_read, record_write, stats as consumed_capacity_stats,
    total_capacity_units, write_capacity_units,
};

/// Generic table module
pub mod table;

/// Methods of Generic table
pub mod methods;

/// Table setup utilities for testing
pub mod setup;

// Re-export main types for convenience
pub use methods::DynamoTableMethods;
pub use table::{CompositeKey, DynamoTable, GSITable};

// Re-export aws-config types for configuration
pub use aws_config::{
    BehaviorVersion, Region, SdkConfig, defaults,
    meta::region::{ProvideRegion, RegionProviderChain},
    retry::{RetryConfig, RetryMode},
    timeout::TimeoutConfig,
};

// Re-export aws-types for advanced configuration
pub use aws_types::sdk_config::Builder as SdkConfigBuilder;

// Re-export DynamoDB types
pub use aws_sdk_dynamodb;

// Re-export serde_dynamo for easy serialization/deserialization of DynamoDB items
pub use serde_dynamo;

use aws_sdk_dynamodb::Client as DynamoDbClient;
use aws_smithy_http_client::{
    Builder as SmithyHttpClientBuilder,
    tls::{self, TlsContext, TrustStore, rustls_provider::CryptoMode},
};
use tokio::sync::OnceCell;

/// Global DynamoDB client instance
static GLOBAL_CLIENT: OnceCell<DynamoDbClient> = OnceCell::const_new();

/// Initialize the global DynamoDB client with default sensible settings
///
/// This is called automatically by `dynamodb_client()` if not already initialized.
/// It configures:
/// - Adaptive retry mode with 3 max attempts
/// - Exponential backoff starting at 1 second
/// - Connect timeout: 3 seconds
/// - Read timeout: 20 seconds
/// - Operation timeout: 60 seconds
/// - LocalStack support via AWS_PROFILE=localstack
///
/// Note: This function is internal. Use `init()` or `init_with_client()` for
/// custom configuration, or let `dynamodb_client()` auto-initialize with defaults.
async fn aws_config_defaults() -> SdkConfig {
    use aws_config::BehaviorVersion;
    use aws_types::sdk_config::{RetryConfig, TimeoutConfig};
    use std::time::Duration;

    let timeout_config = TimeoutConfig::builder()
        .connect_timeout(Duration::from_secs(3))
        .read_timeout(Duration::from_secs(20))
        .operation_timeout(Duration::from_secs(60))
        .build();

    let mut loader = defaults(BehaviorVersion::latest())
        .retry_config(
            RetryConfig::adaptive()
                .with_max_attempts(3)
                .with_initial_backoff(Duration::from_secs(1)),
        )
        .timeout_config(timeout_config);

    // Support LocalStack via AWS_PROFILE=localstack
    if std::env::var("AWS_PROFILE").unwrap_or_default() == "localstack" {
        loader = loader
            .endpoint_url("http://127.0.0.1:4566")
            .http_client(localstack_http_client());
    }

    loader.load().await
}

fn localstack_http_client() -> aws_smithy_runtime_api::client::http::SharedHttpClient {
    // LocalStack test runs use plain HTTP, so native TLS roots are unnecessary.
    // Disabling them avoids rustls startup panics on machines with unreadable or invalid
    // system trust stores while preserving the same HTTP behavior for the local endpoint.
    let tls_context = TlsContext::builder()
        .with_trust_store(TrustStore::empty())
        .build()
        .expect("valid LocalStack TLS context");

    SmithyHttpClientBuilder::new()
        .tls_provider(tls::Provider::Rustls(CryptoMode::AwsLc))
        .tls_context(tls_context)
        .build_https()
}

/// Initialize the global DynamoDB client with a custom AWS config
///
/// Use this when you need custom AWS configuration beyond the defaults.
///
/// # Example
///
/// ```rust,no_run
/// #[tokio::main]
/// async fn main() {
///     let config = aws_config::defaults(aws_config::BehaviorVersion::latest())
///         .region(aws_config::Region::new("us-west-2"))
///         .load()
///         .await;
///     dynamo_table::init(&config).await;
///
///     // Now you can use table operations
/// }
/// ```
pub async fn init(config: &SdkConfig) {
    let _ = GLOBAL_CLIENT
        .get_or_init(|| async { DynamoDbClient::new(config) })
        .await;
}

/// Initialize the global DynamoDB client with a custom client instance
///
/// Useful for testing or when you need fine-grained control over client configuration.
///
/// # Example
///
/// ```rust,no_run
/// use aws_sdk_dynamodb::Client;
///
/// #[tokio::main]
/// async fn main() {
///     let config = aws_config::load_from_env().await;
///     let client = Client::new(&config);
///     dynamo_table::init_with_client(client).await;
/// }
/// ```
pub async fn init_with_client(client: DynamoDbClient) {
    let _ = GLOBAL_CLIENT.get_or_init(|| async { client }).await;
}

/// Get a reference to the global DynamoDB client
///
/// Automatically initializes the client with sensible defaults if not already initialized.
/// For custom configuration, call [`init`] or [`init_with_client`] before using this function.
///
/// # Auto-Initialization
///
/// If not explicitly initialized, this function will automatically configure:
/// - Adaptive retry mode with 3 max attempts
/// - Exponential backoff starting at 1 second
/// - Connect timeout: 3 seconds
/// - Read timeout: 20 seconds
/// - Operation timeout: 60 seconds
/// - LocalStack support via AWS_PROFILE=localstack
///
/// # Example
///
/// ```rust,no_run
/// # async fn example() {
/// // Client auto-initializes with defaults on first use
/// let client = dynamo_table::dynamodb_client().await;
/// // Use client for custom operations
/// # }
/// ```
///
/// # Custom Configuration Example
///
/// ```rust,no_run
/// # async fn example() {
/// // Initialize with custom config before first use
/// let config = dynamo_table::defaults(dynamo_table::BehaviorVersion::latest())
///     .region(dynamo_table::Region::new("us-west-2"))
///     .load()
///     .await;
/// dynamo_table::init(&config).await;
///
/// // Now uses custom configuration
/// let client = dynamo_table::dynamodb_client().await;
/// # }
/// ```
pub async fn dynamodb_client() -> &'static DynamoDbClient {
    // Safe to unwrap because init_defaults() always sets it
    GLOBAL_CLIENT
        .get_or_init(|| async {
            let config = aws_config_defaults().await;
            DynamoDbClient::new(&config)
        })
        .await
}

fn _assert_not_reserved_key(key: &str) {
    // https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ReservedWords.html
    #[rustfmt::skip]
    const KEYS: [&str; 573] = [
"abort", "absolute", "action", "add", "after", "agent", "aggregate", "all", "allocate", "alter", "analyze", "and", "any", "archive", "are", "array", "as", "asc", "ascii", "asensitive", "assertion", "asymmetric", "at", "atomic", "attach", "attribute", "auth", "authorization", "authorize", "auto", "avg", "back", "backup", "base", "batch", "before", "begin", "between", "bigint", "binary", "bit", "blob", "block", "boolean", "both", "breadth", "bucket", "bulk", "by", "byte", "call", "called", "calling", "capacity", "cascade", "cascaded", "case", "cast", "catalog", "char", "character", "check", "class", "clob", "close", "cluster", "clustered", "clustering", "clusters", "coalesce", "collate", "collation", "collection", "column", "columns", "combine", "comment", "commit", "compact", "compile", "compress", "condition", "conflict", "connect", "connection", "consistency", "consistent", "constraint", "constraints", "constructor", "consumed", "continue", "convert", "copy", "corresponding", "count", "counter", "create", "cross", "cube", "current", "cursor", "cycle", "data", "database", "date", "datetime", "day", "deallocate", "dec", "decimal", "declare", "default", "deferrable", "deferred", "define", "defined", "definition", "delete", "delimited", "depth", "deref", "desc", "describe", "descriptor", "detach", "deterministic", "diagnostics", "directories", "disable", "disconnect", "distinct", "distribute", "do", "domain", "double", "drop", "dump", "duration", "dynamic", "each", "element", "else", "elseif", "empty", "enable", "end", "equal", "equals", "error", "escape", "escaped", "eval", "evaluate", "exceeded", "except", "exception", "exceptions", "exclusive", "exec", "execute", "exists", "exit", "explain", "explode", "export", "expression", "extended", "external", "extract", "fail", "false", "family", "fetch", "fields", "file", "filter", "filtering", "final", "finish", "first", "fixed", "flattern", "float", "for", "force", "foreign", "format", "forward", "found", "free", "from", "full", "function", "functions", "general", "generate", "get", "glob", "global", "go", "goto", "grant", "greater", "group", "grouping", "handler", "hash", "have", "having", "heap", "hidden", "hold", "hour", "identified", "identity", "if", "ignore", "immediate", "import", "in", "including", "inclusive", "increment", "incremental", "index", "indexed", "indexes", "indicator", "infinite", "initially", "inline", "inner", "innter", "inout", "input", "insensitive", "insert", "instead", "int", "integer", "intersect", "interval", "into", "invalidate", "is", "isolation", "item", "items", "iterate", "join", "key", "keys", "lag", "language", "large", "last", "lateral", "lead", "leading", "leave", "left", "length", "less", "level", "like", "limit", "limited", "lines", "list", "load", "local", "localtime", "localtimestamp", "location", "locator", "lock", "locks", "log", "loged", "long", "loop", "lower", "map", "match", "materialized", "max", "maxlen", "member", "merge", "method", "metrics", "min", "minus", "minute", "missing", "mod", "mode", "modifies", "modify", "module", "month", "multi", "multiset", "name", "names", "national", "natural", "nchar", "nclob", "new", "next", "no", "none", "not", "null", "nullif", "number", "numeric", "object", "of", "offline", "offset", "old", "on", "online", "only", "opaque", "open", "operator", "option", "or", "order", "ordinality", "other", "others", "out", "outer", "output", "over", "overlaps", "override", "owner", "pad", "parallel", "parameter", "parameters", "partial", "partition", "partitioned", "partitions", "path", "percent", "percentile", "permission", "permissions", "pipe", "pipelined", "plan", "pool", "position", "precision", "prepare", "preserve", "primary", "prior", "private", "privileges", "procedure", "processed", "project", "projection", "property", "provisioning", "public", "put", "query", "quit", "quorum", "raise", "random", "range", "rank", "raw", "read", "reads", "real", "rebuild", "record", "recursive", "reduce", "ref", "reference", "references", "referencing", "regexp", "region", "reindex", "relative", "release", "remainder", "rename", "repeat", "replace", "request", "reset", "resignal", "resource", "response", "restore", "restrict", "result", "return", "returning", "returns", "reverse", "revoke", "right", "role", "roles", "rollback", "rollup", "routine", "row", "rows", "rule", "rules", "sample", "satisfies", "save", "savepoint", "scan", "schema", "scope", "scroll", "search", "second", "section", "segment", "segments", "select", "self", "semi", "sensitive", "separate", "sequence", "serializable", "session", "set", "sets", "shard", "share", "shared", "short", "show", "signal", "similar", "size", "skewed", "smallint", "snapshot", "some", "source", "space", "spaces", "sparse", "specific", "specifictype", "split", "sql", "sqlcode", "sqlerror", "sqlexception", "sqlstate", "sqlwarning", "start", "state", "static", "status", "storage", "store", "stored", "stream", "string", "struct", "style", "sub", "submultiset", "subpartition", "substring", "subtype", "sum", "super", "symmetric", "synonym", "system", "table", "tablesample", "temp", "temporary", "terminated", "text", "than", "then", "throughput", "time", "timestamp", "timezone", "tinyint", "to", "token", "total", "touch", "trailing", "transaction", "transform", "translate", "translation", "treat", "trigger", "trim", "true", "truncate", "ttl", "tuple", "type", "under", "undo", "union", "unique", "unit", "unknown", "unlogged", "unnest", "unprocessed", "unsigned", "until", "update", "upper", "url", "usage", "use", "user", "users", "using", "uuid", "vacuum", "value", "valued", "values", "varchar", "variable", "variance", "varint", "varying", "view", "views", "virtual", "void", "wait", "when", "whenever", "where", "while", "window", "with", "within", "without", "work", "wrapped", "write", "year", "zone "
];

    debug_assert!(!KEYS.contains(&key), "Reserved key: {key}");
}

#[allow(unused_variables)]
pub(crate) fn assert_not_reserved_key(key: &str) {
    #[cfg(debug_assertions)]
    _assert_not_reserved_key(key);
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_composite_key_tuple() {
        let key: CompositeKey<String, String> =
            ("user123".to_string(), Some("order456".to_string()));
        assert_eq!(key.0, "user123");
        assert_eq!(key.1, Some("order456".to_string()));
    }

    #[test]
    fn test_composite_key_no_sort_key() {
        let key: CompositeKey<String, String> = ("user123".to_string(), None);
        assert_eq!(key.0, "user123");
        assert_eq!(key.1, None);
    }

    #[cfg(debug_assertions)]
    #[test]
    #[should_panic(expected = "Reserved key: user")]
    fn test_assert_reserved_key_panics() {
        assert_not_reserved_key("user");
    }

    #[cfg(debug_assertions)]
    #[test]
    fn test_assert_not_reserved_key_ok() {
        assert_not_reserved_key("user_id");
        assert_not_reserved_key("custom_field");
    }
}