inferadb_ledger_sdk/lib.rs
1//! Production-grade Rust SDK for InferaDB Ledger service.
2//!
3//! Provides a high-level, ergonomic API for Rust applications to interact
4//! with Ledger's blockchain database. Wraps the gRPC services with automatic
5//! idempotency, resilient connectivity, and streaming support.
6//!
7//! # Features
8//!
9//! - **Type-safe API**: Strong typing for all Ledger operations
10//! - **Automatic idempotency**: Server-assigned sequences with UUID-based deduplication
11//! - **Resilient connectivity**: Exponential backoff retry and failover
12//! - **Streaming support**: WatchBlocks with automatic reconnection
13//! - **Cancellation support**: Per-request and client-level cancellation via `CancellationToken`
14//! - **Minimal-overhead abstractions**: Efficient serialization and connection pooling
15//!
16//! # Quick Start
17//!
18//! ```no_run
19//! use inferadb_ledger_sdk::{LedgerClient, ClientConfig, Operation, OrganizationSlug, UserSlug, ServerSource};
20//!
21//! #[tokio::main]
22//! async fn main() -> inferadb_ledger_sdk::Result<()> {
23//! let config = ClientConfig::builder()
24//! .servers(ServerSource::from_static(["http://localhost:50051"]))
25//! .client_id("my-app-001")
26//! .build()?;
27//!
28//! let client = LedgerClient::new(config).await?;
29//! # let organization = OrganizationSlug::new(1);
30//! # let caller = UserSlug::new(1);
31//!
32//! // Read operations
33//! let value = client.read(caller, organization, None, "user:123", None, None).await?;
34//!
35//! // Write operations with automatic idempotency
36//! let operations = vec![Operation::set_entity("user:123", b"data".to_vec(), None, None)];
37//! let result = client.write(caller, organization, None, operations, None).await?;
38//! println!("Committed at block {} with sequence {}", result.block_height, result.assigned_sequence);
39//!
40//! Ok(())
41//! }
42//! ```
43//!
44//! # Architecture
45//!
46//! ```text
47//! ┌─────────────────────────────────────────────────────────────┐
48//! │ LedgerClient (Public API) │
49//! │ .read() │ .write() │ .watch_blocks() │ .admin() │
50//! ├─────────────────────────────────────────────────────────────┤
51//! │ Idempotency Layer │
52//! │ UUID generation │ Retry key preservation │ Dedup │
53//! ├─────────────────────────────────────────────────────────────┤
54//! │ Resilience Layer (retry + cancellation) │
55//! │ Retry middleware │ Exponential backoff │ Timeout │
56//! ├─────────────────────────────────────────────────────────────┤
57//! │ Connection Pool │
58//! │ Channel management │ Load balancing │ Health checks │
59//! ├─────────────────────────────────────────────────────────────┤
60//! │ Tonic gRPC Clients │
61//! │ ReadServiceClient │ WriteServiceClient │ AdminService │
62//! └─────────────────────────────────────────────────────────────┘
63//! ```
64
65#![deny(unsafe_code, missing_docs)]
66
67mod builders;
68mod circuit_breaker;
69mod client;
70mod config;
71mod connection;
72mod discovery;
73mod error;
74mod metrics;
75pub mod mock;
76mod ops;
77pub(crate) mod proto_util;
78mod retry;
79pub mod server;
80mod streaming;
81pub mod token;
82mod tracing;
83mod types;
84
85// Public API exports
86pub use builders::{BatchReadBuilder, RelationshipQueryBuilder, WriteBuilder};
87pub use circuit_breaker::{CircuitBreaker, CircuitBreakerConfig, CircuitState};
88pub use client::LedgerClient;
89pub use config::{
90 CertificateData, ClientConfig, ClientConfigBuilder, DiscoveryConfig, RetryPolicy, TlsConfig,
91 TlsConfigBuilder,
92};
93pub use connection::ConnectionPool;
94pub use discovery::{DiscoveryResult, DiscoveryService, PeerInfo};
95pub use error::{Result, SdkError};
96// Re-export commonly used types from inferadb-ledger-types
97pub use inferadb_ledger_types::{
98 AppId, AppSlug, ClientAssertionId, InviteSlug, OrganizationId, OrganizationSlug, Region,
99 TeamId, TeamSlug, UserCredentialId, UserEmailId, UserRole, UserSlug, UserStatus, VaultId,
100 VaultSlug,
101};
102pub use metrics::{ConnectionEvent, MetricsSdkMetrics, NoopSdkMetrics, SdkMetrics};
103pub use retry::{with_retry, with_retry_cancellable};
104pub use server::{
105 DnsConfig, FileConfig, ResolvedServer, ServerResolver, ServerSelector, ServerSource,
106};
107pub use streaming::{HeightTracker, ReconnectingStream};
108pub use token::{PublicKeyInfo, TokenPair, ValidatedToken};
109pub use tracing::TraceConfig;
110pub use types::schema::{
111 SchemaDeployResult, SchemaDiffChange, SchemaVersion, SchemaVersionSummary,
112};
113// Public API exports — domain types (from types/ modules)
114pub use types::{
115 admin::{
116 BlindingKeyRehashStatus, BlindingKeyRotationStatus, EmailVerificationCode,
117 EmailVerificationResult, HealthCheckResult, HealthStatus, MigrationInfo,
118 OrganizationDeleteInfo, OrganizationInfo, OrganizationMemberInfo, OrganizationMemberRole,
119 OrganizationStatus, OrganizationTier, RegistrationResult, TeamInfo, TeamMemberInfo,
120 TeamMemberRole, UserEmailInfo, UserInfo, UserMigrationInfo, VaultInfo, VaultStatus,
121 },
122 app::{
123 AppClientAssertionInfo, AppClientSecretStatus, AppCredentialType, AppCredentialsInfo,
124 AppInfo, AppVaultConnectionInfo, CreateAppClientAssertionResult,
125 },
126 credential::{
127 CredentialData, CredentialType, PasskeyCredentialInfo, RecoveryCodeCredentialInfo,
128 RecoveryCodeResult, TotpAlgorithm, TotpCredentialInfo, UserCredentialInfo,
129 },
130 events::{
131 EventEmissionPath, EventFilter, EventOutcome, EventPage, EventScope, EventSource,
132 IngestRejection, IngestResult, SdkEventEntry, SdkIngestEventEntry,
133 },
134 invitation::{
135 InvitationCreated, InvitationInfo, InvitationPage, InvitationStatus,
136 ReceivedInvitationInfo, ReceivedInvitationPage,
137 },
138 query::{
139 Entity, ListEntitiesOpts, ListRelationshipsOpts, ListResourcesOpts, Operation, PagedResult,
140 Relationship, SetCondition, VerifiedValue,
141 },
142 read::{ReadConsistency, WriteSuccess},
143 streaming::BlockAnnouncement,
144 verified_read::{BlockHeader, ChainProof, Direction, MerkleProof, MerkleSibling, VerifyOpts},
145};