icepick 0.3.0

Experimental Rust client for Apache Iceberg with WASM support for AWS S3 Tables and Cloudflare R2
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

//! Iceberg REST catalog implementation with pluggable authentication

mod auth;
mod options;
pub mod r2;
pub mod register;
pub(crate) mod rest;
pub mod rest_catalog;
pub mod retry;

#[cfg(not(target_family = "wasm"))]
pub mod s3_tables;

// New trait-based API
mod catalog_trait;

pub use catalog_trait::Catalog;
pub use options::{CatalogOptions, HttpClientConfig};
pub use rest_catalog::{RestAuthProvider, RestCatalog, RestCatalogBuilder};
pub use retry::{BackoffStrategy, RetryConfig};

// Make auth providers internal - not part of public API
pub use auth::BearerTokenAuthProvider;

#[cfg(not(target_family = "wasm"))]
pub use auth::SigV4AuthProvider;

use crate::error::Error;
use async_trait::async_trait;

/// Result type for catalog operations (internal)
pub(crate) type Result<T> = std::result::Result<T, CatalogError>;

/// Error types for catalog operations with retry semantics
#[derive(Debug, thiserror::Error)]
pub enum CatalogError {
    /// Transient errors that may succeed on retry (network issues, 5xx errors, rate limits)
    #[error("Transient error: {0}")]
    Transient(String),

    /// Permanent errors that should not be retried (4xx errors, auth failures, not found)
    #[error("Permanent error: {0}")]
    Permanent(String),

    /// Timeout exceeded
    #[error("Operation timed out after {0:?}")]
    Timeout(std::time::Duration),

    // Legacy error variants (internal use, mapped to Transient/Permanent)
    #[error("Resource not found: {0}")]
    NotFound(String),

    #[error("Conflict: {0}")]
    Conflict(String),

    #[error("Invalid request: {0}")]
    InvalidRequest(String),

    #[error("Authentication failed: {0}")]
    AuthError(String),

    #[error("HTTP error: {0}")]
    HttpError(String),

    #[error("Server error {status}: {message}")]
    ServerError { status: u16, message: String },

    #[error("Network error: {0}")]
    Network(reqwest::Error),

    #[cfg(not(target_family = "wasm"))]
    #[error("Invalid ARN: {0}")]
    InvalidArn(String),

    #[error("Unexpected error: {0}")]
    Unexpected(String),
}

impl CatalogError {
    /// Returns true if this error is retryable
    pub fn is_retryable(&self) -> bool {
        match self {
            CatalogError::Transient(_) | CatalogError::Network(_) => true,
            CatalogError::ServerError { status, .. } if *status >= 500 => true,
            _ => false,
        }
    }
}

/// Configuration for R2 Data Catalog (internal)
#[derive(Debug, Clone)]
pub(crate) struct R2Config {
    pub account_id: String,
    pub bucket_name: String,
    pub api_token: String,
    pub endpoint_override: Option<String>,
}

/// Authentication provider trait for signing/authenticating requests (internal)
#[cfg_attr(not(target_family = "wasm"), async_trait)]
#[cfg_attr(target_family = "wasm", async_trait(?Send))]
pub(crate) trait AuthProvider: Send + Sync + std::fmt::Debug {
    /// Sign or authenticate an HTTP request
    async fn sign_request(&self, request: reqwest::Request) -> Result<reqwest::Request>;
}

pub(crate) fn map_catalog_error(err: CatalogError) -> Error {
    match err {
        CatalogError::Transient(message) => {
            Error::unexpected(format!("Transient error: {}", message))
        }
        CatalogError::Permanent(message) => {
            Error::unexpected(format!("Permanent error: {}", message))
        }
        CatalogError::Timeout(duration) => {
            Error::unexpected(format!("Timeout after {:?}", duration))
        }
        CatalogError::NotFound(resource) => Error::not_found(resource),
        CatalogError::Conflict(message) => Error::conflict(message),
        CatalogError::InvalidRequest(message) => Error::invalid_request(message),
        CatalogError::AuthError(provider) => Error::unauthorized(provider),
        CatalogError::HttpError(message) => Error::unexpected(message),
        CatalogError::ServerError { status, message } => Error::server_error(status, message),
        CatalogError::Network(source) => Error::NetworkError { source },
        #[cfg(not(target_family = "wasm"))]
        CatalogError::InvalidArn(arn) => Error::invalid_arn(arn),
        CatalogError::Unexpected(message) => Error::unexpected(message),
    }
}