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//!
45//! ### Using the Resilience Feature
46//!
47//! When the `resilience` feature is enabled, you can use `ClientBuilder` to configure
48//! retry and timeout behavior:
49//!
50//! ```rust,no_run
51//! # #[cfg(feature = "resilience")]
52//! # {
53//! use stac_client::{ClientBuilder, ResiliencePolicy};
54//! use std::time::Duration;
55//!
56//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
57//! // Create a custom resilience policy
58//! let policy = ResiliencePolicy::new()
59//!     .max_attempts(5)
60//!     .base_delay(Duration::from_millis(100))
61//!     .max_delay(Duration::from_secs(30))
62//!     .retry_5xx(true)
63//!     .retry_429(true)
64//!     .request_timeout(Some(Duration::from_secs(30)))
65//!     .connect_timeout(Some(Duration::from_secs(10)))
66//!     .total_timeout(Some(Duration::from_secs(120)));
67//!
68//! // Build a client with the policy
69//! let client = ClientBuilder::new("https://planetarycomputer.microsoft.com/api/stac/v1")
70//!     .resilience_policy(policy)
71//!     .build()?;
72//!
73//! // Use the client normally - retries and timeouts are handled automatically
74//! let catalog = client.get_catalog().await?;
75//! # Ok(())
76//! # }
77//! # }
78//! ```
79
80#![deny(missing_docs)]
81#![deny(unused_must_use)]
82#![deny(rust_2018_idioms)]
83#![deny(unreachable_pub)]
84#![deny(clippy::all)]
85#![deny(clippy::pedantic)]
86#![allow(clippy::module_name_repetitions)]
87
88/// The core STAC API client and search builder.
89pub mod client;
90/// Error and result types.
91pub mod error;
92/// STAC data models, such as `Item`, `Collection`, and `Catalog`.
93pub mod models;
94
95#[cfg(feature = "resilience")]
96/// Resilience policy for retries and timeouts.
97pub mod resilience;
98
99pub use client::{Client, SearchBuilder};
100pub use error::{Error, Result};
101pub use models::*;
102
103#[cfg(feature = "resilience")]
104pub use client::ClientBuilder;
105#[cfg(feature = "resilience")]
106pub use resilience::ResiliencePolicy;
stac_client/lib.rs

stac_client/
lib.rs
