fetchttp/
lib.rs

1//! # fetchttp
2//!
3//! A WHATWG Fetch API compliant HTTP client library for Rust.
4//!
5//! This library provides a familiar `fetch()` API that closely follows the
6//! [WHATWG Fetch specification](https://fetch.spec.whatwg.org/), making it easy
7//! for developers familiar with web APIs to use in Rust applications.
8//!
9//! ## Features
10//!
11//! - **Specification Compliant**: Implements the WHATWG Fetch API specification
12//! - **Async/Await Support**: Built on Tokio for modern async Rust
13//! - **Type Safety**: Leverages Rust's type system for safe HTTP operations
14//! - **JSON Support**: Built-in JSON serialization/deserialization with serde
15//! - **Flexible Bodies**: Support for text, bytes, and JSON request/response bodies
16//! - **Header Management**: Complete header manipulation API
17//! - **Request/Response Cloning**: Efficient cloning following the specification
18//! - **Abort Signals**: Request cancellation support
19//!
20//! ## Quick Start
21//!
22//! ### Simple GET Request
23//!
24//! ```rust
25//! use fetchttp::*;
26//!
27//! #[tokio::main]
28//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
29//!     let response = fetch("https://api.github.com/users/octocat", None).await?;
30//!     
31//!     if response.ok() {
32//!         let user: serde_json::Value = response.json().await?;
33//!         println!("User: {}", user["name"]);
34//!     }
35//!     
36//!     Ok(())
37//! }
38//! ```
39//!
40//! ### POST Request with JSON
41//!
42//! ```rust
43//! use fetchttp::*;
44//! use serde_json::json;
45//!
46//! #[tokio::main]
47//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
48//!     let data = json!({
49//!         "name": "John Doe",
50//!         "email": "john@example.com"
51//!     });
52//!     
53//!     let mut init = RequestInit::new();
54//!     init.method = Some("POST".to_string());
55//!     init.body = Some(ReadableStream::from_json(&data));
56//!     
57//!     let response = fetch("https://api.example.com/users", Some(init)).await?;
58//!     
59//!     if response.ok() {
60//!         println!("User created successfully!");
61//!     }
62//!     
63//!     Ok(())
64//! }
65//! ```
66//!
67//! ### Custom Headers
68//!
69//! ```rust
70//! use fetchttp::*;
71//!
72//! #[tokio::main]
73//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
74//!     let mut headers = Headers::new();
75//!     headers.set("Authorization", "Bearer your-token")?;
76//!     headers.set("User-Agent", "MyApp/1.0")?;
77//!     
78//!     let mut init = RequestInit::new();
79//!     init.headers = Some(headers);
80//!     
81//!     let response = fetch("https://api.example.com/protected", Some(init)).await?;
82//!     let text = response.text().await?;
83//!     
84//!     println!("Response: {}", text);
85//!     Ok(())
86//! }
87//! ```
88//!
89//! ## API Overview
90//!
91//! The main entry point is the [`fetch`] function, which takes a URL and optional
92//! [`RequestInit`] configuration. The function returns a [`Response`] that can be
93//! consumed in various ways:
94//!
95//! - [`Response::text()`] - Get response as text
96//! - [`Response::json()`] - Parse response as JSON
97//! - [`Response::array_buffer()`] - Get response as bytes
98//! - [`Response::blob()`] - Get response as blob (bytes)
99//!
100//! ## Error Handling
101//!
102//! The library uses a comprehensive error system with specific error types:
103//!
104//! - [`TypeError`] - Invalid arguments or operations
105//! - [`NetworkError`] - Network-related failures
106//! - [`AbortError`] - Request was aborted
107//!
108//! All errors implement the standard Rust error traits.
109
110mod abort;
111mod body;
112mod client;
113mod error;
114mod headers;
115mod request;
116mod response;
117
118// Re-export all public types and functions
119pub use abort::{AbortController, AbortSignal};
120pub use body::ReadableStream;
121pub use client::fetch;
122pub use error::{AbortError, FetchError, NetworkError, Result, TypeError};
123pub use headers::Headers;
124pub use request::{
125    Request, RequestCache, RequestCredentials, RequestInit, RequestMode, RequestRedirect,
126};
127pub use response::{Response, ResponseInit, ResponseType};
128
129// Re-export commonly used external types
130pub use bytes::Bytes;
131pub use serde_json::{Map as JsonMap, Value as JsonValue};
fetchttp/lib.rs

fetchttp/
lib.rs
