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//!
50//! # Azure-specific properties (for az:// locations)
51//! credential_vendor.azure_account_name = "mystorageaccount"  # required for Azure
52//! credential_vendor.azure_tenant_id = "my-tenant-id"
53//! credential_vendor.azure_duration_millis = "3600000"  # 1 hour (default, up to 7 days)
54//! ```
55//!
56//! ## Usage
57//!
58//! The recommended way to connect to a namespace is using [`ConnectBuilder`]:
59//!
60//! ```no_run
61//! # use lance_namespace_impls::ConnectBuilder;
62//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
63//! let namespace = ConnectBuilder::new("dir")
64//!     .property("root", "/path/to/data")
65//!     .connect()
66//!     .await?;
67//! # Ok(())
68//! # }
69//! ```
70
71pub mod connect;
72pub mod context;
73pub mod credentials;
74pub mod dir;
75
76#[cfg(feature = "rest")]
77pub mod rest;
78
79#[cfg(feature = "rest-adapter")]
80pub mod rest_adapter;
81
82// Re-export connect builder
83pub use connect::ConnectBuilder;
84pub use context::{DynamicContextProvider, OperationInfo};
85pub use dir::{DirectoryNamespace, DirectoryNamespaceBuilder, manifest::ManifestNamespace};
86
87// Re-export credential vending
88pub use credentials::{
89    CredentialVendor, DEFAULT_CREDENTIAL_DURATION_MILLIS, VendedCredentials,
90    create_credential_vendor_for_location, detect_provider_from_uri, has_credential_vendor_config,
91    redact_credential,
92};
93
94#[cfg(feature = "credential-vendor-aws")]
95pub use credentials::aws::{AwsCredentialVendor, AwsCredentialVendorConfig};
96#[cfg(feature = "credential-vendor-aws")]
97pub use credentials::aws_props;
98
99#[cfg(feature = "credential-vendor-gcp")]
100pub use credentials::gcp::{GcpCredentialVendor, GcpCredentialVendorConfig};
101#[cfg(feature = "credential-vendor-gcp")]
102pub use credentials::gcp_props;
103
104#[cfg(feature = "credential-vendor-azure")]
105pub use credentials::azure::{AzureCredentialVendor, AzureCredentialVendorConfig};
106#[cfg(feature = "credential-vendor-azure")]
107pub use credentials::azure_props;
108
109#[cfg(feature = "rest")]
110pub use rest::{RestNamespace, RestNamespaceBuilder};
111
112#[cfg(feature = "rest-adapter")]
113pub use rest_adapter::{RestAdapter, RestAdapterConfig, RestAdapterHandle};
lance_namespace_impls/lib.rs

lance_namespace_impls/
lib.rs
