stac_client/
lib.rs

1//! # STAC Client for Rust
2//!
3//! A friendly, async client for the [SpatioTemporal Asset Catalog (STAC)](https://stacspec.org/)
4//! specification, written in Rust.
5//!
6//! This library helps you interact with STAC APIs to find and retrieve geospatial data. It is
7//! built on `tokio` for async operations and `reqwest` for HTTP requests.
8//!
9//! ## Project Goals
10//!
11//! - **Idiomatic Rust API**: Provide an API that feels natural to Rust developers.
12//! - **Minimal Dependencies**: Keep the dependency tree small and manageable.
13//! - **Well-Documented**: Offer clear documentation for all public APIs.
14//! - **Thoroughly Tested**: Maintain high test coverage to ensure stability.
15//!
16//! ## Quick Start
17//!
18//! ```rust,no_run
19//! use stac_client::{Client, SearchBuilder};
20//! use std::error::Error;
21//!
22//! #[tokio::main]
23//! async fn main() -> Result<(), Box<dyn Error>> {
24//!     let url = "https://planetarycomputer.microsoft.com/api/stac/v1";
25//!     let client = Client::new(url)?;
26//!
27//!     let search = SearchBuilder::new()
28//!         .collections(vec!["sentinel-2-l2a".to_string()])
29//!         .limit(10)
30//!         .build();
31//!
32//!     let results = client.search(&search).await?;
33//!     println!("Found {} items.", results.features.len());
34//!
35//!     Ok(())
36//! }
37//! ```
38//!
39//! ## Optional Features
40//!
41//! - `pagination`: Enables the `Client::search_next_page` method for easy pagination.
42//! - `resilience`: Enables resilience features including retries with exponential backoff,
43//!   jitter, and timeout configurations. Use `ClientBuilder` to configure these features.
44//! - `auth`: Enables pluggable authentication support with `ApiKey`, `BearerToken`, and
45//!   custom `AuthLayer` implementations for protected STAC APIs.
46//!
47//! ### Using the Resilience Feature
48//!
49//! When the `resilience` feature is enabled, you can use `ClientBuilder` to configure
50//! retry and timeout behavior:
51//!
52//! ```rust,no_run
53//! # #[cfg(feature = "resilience")]
54//! # {
55//! use stac_client::{ClientBuilder, ResiliencePolicy};
56//! use std::time::Duration;
57//!
58//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
59//! // Create a custom resilience policy
60//! let policy = ResiliencePolicy::new()
61//!     .max_attempts(5)
62//!     .base_delay(Duration::from_millis(100))
63//!     .max_delay(Duration::from_secs(30))
64//!     .retry_5xx(true)
65//!     .retry_429(true)
66//!     .request_timeout(Some(Duration::from_secs(30)))
67//!     .connect_timeout(Some(Duration::from_secs(10)))
68//!     .total_timeout(Some(Duration::from_secs(120)));
69//!
70//! // Build a client with the policy
71//! let client = ClientBuilder::new("https://planetarycomputer.microsoft.com/api/stac/v1")
72//!     .resilience_policy(policy)
73//!     .build()?;
74//!
75//! // Use the client normally - retries and timeouts are handled automatically
76//! let catalog = client.get_catalog().await?;
77//! # Ok(())
78//! # }
79//! # }
80//! ```
81//!
82//! ### Using the Authentication Feature
83//!
84//! When the `auth` feature is enabled, you can add authentication layers to your client:
85//!
86//! ```rust,no_run
87//! # #[cfg(all(feature = "resilience", feature = "auth"))]
88//! # {
89//! use stac_client::{ClientBuilder, auth::{ApiKey, BearerToken}};
90//!
91//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
92//! // API Key authentication
93//! let client = ClientBuilder::new("https://api.example.com/stac")
94//!     .auth_layer(ApiKey::new("X-API-Key", "your-secret-key"))
95//!     .build()?;
96//!
97//! // Bearer token authentication
98//! let client = ClientBuilder::new("https://api.example.com/stac")
99//!     .auth_layer(BearerToken::new("your-jwt-token"))
100//!     .build()?;
101//!
102//! // Multiple auth layers can be combined
103//! let client = ClientBuilder::new("https://api.example.com/stac")
104//!     .auth_layer(ApiKey::new("X-API-Key", "key123"))
105//!     .auth_layer(BearerToken::new("token456"))
106//!     .build()?;
107//!
108//! // Use the client - auth is applied automatically
109//! let catalog = client.get_catalog().await?;
110//! # Ok(())
111//! # }
112//! # }
113//! ```
114
115#![deny(missing_docs)]
116#![deny(unused_must_use)]
117#![deny(rust_2018_idioms)]
118#![deny(unreachable_pub)]
119#![deny(clippy::all)]
120#![deny(clippy::pedantic)]
121#![allow(clippy::module_name_repetitions)]
122
123/// The core STAC API client and search builder.
124pub mod client;
125/// Error and result types.
126pub mod error;
127/// STAC data models, such as `Item`, `Collection`, and `Catalog`.
128pub mod models;
129
130#[cfg(feature = "resilience")]
131/// Resilience policy for retries and timeouts.
132pub mod resilience;
133
134#[cfg(feature = "auth")]
135/// Authentication layer support for pluggable auth mechanisms.
136pub mod auth;
137
138pub use client::{Client, SearchBuilder};
139pub use error::{Error, Result};
140pub use models::*;
141
142#[cfg(any(feature = "resilience", feature = "auth"))]
143pub use client::ClientBuilder;
144#[cfg(feature = "resilience")]
145pub use resilience::ResiliencePolicy;
146
147#[cfg(feature = "auth")]
148pub use auth::{ApiKey, AuthLayer, BearerToken};
stac_client/lib.rs

stac_client/
lib.rs
