lance_namespace_impls/
lib.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright The Lance Authors
3
4//! Lance Namespace implementations.
5//!
6//! This crate provides various implementations of the Lance Namespace trait.
7//!
8//! ## Features
9//!
10//! - `rest`: REST API-based namespace implementation
11//! - `rest-adapter`: REST server adapter that exposes any namespace via HTTP
12//! - `dir-aws`, `dir-azure`, `dir-gcp`, `dir-oss`: Cloud storage backend support for directory namespace (via lance-io)
13//! - `credential-vendor-aws`, `credential-vendor-gcp`, `credential-vendor-azure`: Credential vending for cloud storage
14//!
15//! ## Implementations
16//!
17//! - `DirectoryNamespace`: Directory-based implementation (always available)
18//! - `RestNamespace`: REST API-based implementation (requires `rest` feature)
19//!
20//! ## Credential Vending
21//!
22//! The `credentials` module provides temporary credential vending for cloud storage:
23//! - AWS: STS AssumeRole with scoped IAM policies (requires `credential-vendor-aws` feature)
24//! - GCP: OAuth2 tokens with access boundaries (requires `credential-vendor-gcp` feature)
25//! - Azure: SAS tokens with user delegation keys (requires `credential-vendor-azure` feature)
26//!
27//! The credential vendor is automatically selected based on the table location URI scheme:
28//! - `s3://` for AWS
29//! - `gs://` for GCP
30//! - `az://` for Azure
31//!
32//! Configuration properties (prefixed with `credential_vendor.`, prefix is stripped):
33//!
34//! ```text
35//! # Required to enable credential vending
36//! credential_vendor.enabled = "true"
37//!
38//! # Common properties (apply to all providers)
39//! credential_vendor.permission = "read"          # read, write, or admin (default: read)
40//!
41//! # AWS-specific properties (for s3:// locations)
42//! credential_vendor.aws_role_arn = "arn:aws:iam::123456789012:role/MyRole"  # required for AWS
43//! credential_vendor.aws_duration_millis = "3600000"  # 1 hour (default, range: 15min-12hrs)
44//!
45//! # GCP-specific properties (for gs:// locations)
46//! # Note: GCP uses ADC; set GOOGLE_APPLICATION_CREDENTIALS env var for service account key
47//! # Note: GCP token duration cannot be configured; it's determined by the STS endpoint
48//! credential_vendor.gcp_service_account = "my-sa@project.iam.gserviceaccount.com"
49//! credential_vendor.gcp_workload_identity_provider = "projects/123456/locations/global/workloadIdentityPools/pool/providers/provider"
50//! credential_vendor.gcp_impersonation_service_account = "my-sa@project.iam.gserviceaccount.com"
51//!
52//! # Azure-specific properties (for az:// locations)
53//! credential_vendor.azure_account_name = "mystorageaccount"  # required for Azure
54//! credential_vendor.azure_tenant_id = "my-tenant-id"
55//! credential_vendor.azure_federated_client_id = "my-app-client-id"
56//! credential_vendor.azure_duration_millis = "3600000"  # 1 hour (default, up to 7 days)
57//! ```
58//!
59//! ## Usage
60//!
61//! The recommended way to connect to a namespace is using [`ConnectBuilder`]:
62//!
63//! ```no_run
64//! # use lance_namespace_impls::ConnectBuilder;
65//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
66//! let namespace = ConnectBuilder::new("dir")
67//!     .property("root", "/path/to/data")
68//!     .connect()
69//!     .await?;
70//! # Ok(())
71//! # }
72//! ```
73
74pub mod connect;
75pub mod context;
76pub mod credentials;
77pub mod dir;
78
79#[cfg(feature = "rest")]
80pub mod rest;
81
82#[cfg(feature = "rest-adapter")]
83pub mod rest_adapter;
84
85// Re-export connect builder
86pub use connect::ConnectBuilder;
87pub use context::{DynamicContextProvider, OperationInfo};
88pub use dir::{
89    DirectoryNamespace, DirectoryNamespaceBuilder, OpsMetrics, manifest::ManifestNamespace,
90};
91
92// Re-export credential vending
93pub use credentials::{
94    CredentialVendor, DEFAULT_CREDENTIAL_DURATION_MILLIS, VendedCredentials,
95    create_credential_vendor_for_location, detect_provider_from_uri, has_credential_vendor_config,
96    redact_credential,
97};
98
99#[cfg(feature = "credential-vendor-aws")]
100pub use credentials::aws::{AwsCredentialVendor, AwsCredentialVendorConfig};
101#[cfg(feature = "credential-vendor-aws")]
102pub use credentials::aws_props;
103
104#[cfg(feature = "credential-vendor-gcp")]
105pub use credentials::gcp::{GcpCredentialVendor, GcpCredentialVendorConfig};
106#[cfg(feature = "credential-vendor-gcp")]
107pub use credentials::gcp_props;
108
109#[cfg(feature = "credential-vendor-azure")]
110pub use credentials::azure::{AzureCredentialVendor, AzureCredentialVendorConfig};
111#[cfg(feature = "credential-vendor-azure")]
112pub use credentials::azure_props;
113
114#[cfg(feature = "rest")]
115pub use rest::{RestNamespace, RestNamespaceBuilder};
116
117#[cfg(feature = "rest-adapter")]
118pub use rest_adapter::{RestAdapter, RestAdapterConfig, RestAdapterHandle};
lance_namespace_impls/lib.rs

lance_namespace_impls/
lib.rs
