tinyget/
lib.rs

1//! # tinyget
2//! Simple, minimal-dependency HTTP client.
3//! The library has a very minimal API, so you'll probably know
4//! everything you need to after reading a few examples.
5//!
6//! # Additional features
7//!
8//! Since the crate is supposed to be minimal in terms of
9//! dependencies, there are no default features, and optional
10//! functionality can be enabled by specifying features for `tinyget`
11//! dependency in `Cargo.toml`:
12//!
13//! ```toml
14//! [dependencies]
15//! tinyget = { version = "1.1", features = ["https", "timeout"] }
16//! ```
17//!
18//! Below is the list of all available features.
19//!
20//! ## `https`
21//!
22//! This feature uses the (very good)
23//! [`tls-native`](https://crates.io/crates/native-tls) crate to secure the
24//! connection when needed. Note that if this feature is not enabled
25//! (and it is not by default), requests to urls that start with
26//! `https://` will fail and return a
27//! [`HttpsFeatureNotEnabled`](enum.Error.html#variant.HttpsFeatureNotEnabled)
28//! error.
29//!
30//! [`Request`](struct.Request.html) and
31//! [`Response`](struct.Response.html) expose
32//!
33//! ## `timeout`
34//!
35//! This feature adds the ability to set a timeout for the request.
36//! By default, a request has no timeout.  You can change this in two ways:
37//! - Use [`with_timeout`](struct.Request.html#method.with_timeout) on
38//!   your request to set the timeout per-request like so:
39//!   ```
40//!   tinyget::get("/").with_timeout(8).send();
41//!   ```
42//! - Set the environment variable `TINYGET_TIMEOUT` to the desired
43//!   amount of seconds until timeout. Ie. if you have a program called
44//!   `foo` that uses tinyget, and you want all the requests made by that
45//!   program to timeout in 8 seconds, you launch the program like so:
46//!   ```text,ignore
47//!   $ TINYGET_TIMEOUT=8 ./foo
48//!   ```
49//!   Or add the following somewhere before the requests in the code.
50//!   ```
51//!   std::env::set_var("TINYGET_TIMEOUT", "8");
52//!   ```
53//! If the timeout is set with `with_timeout`, the environment
54//! variable will be ignored.
55//!
56//! # Examples
57//!
58//! This is a simple example of sending a GET request and printing out
59//! the response's body, status code, and reason phrase. The `?` are
60//! needed because the server could return invalid UTF-8 in the body,
61//! or something could go wrong during the download.
62//!
63//! ```
64//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
65//! let response = tinyget::get("http://httpbin.org/ip").send()?;
66//! assert!(response.as_str()?.contains("\"origin\":"));
67//! assert_eq!(response.status_code, 200);
68//! assert_eq!(response.reason_phrase, "OK");
69//! # Ok(()) }
70//! ```
71//!
72//! ## Headers (sending)
73//!
74//! To add a header, add `with_header("Key", "Value")` before
75//! `send()`.
76//!
77//! ```
78//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
79//! let response = tinyget::get("http://httpbin.org/headers")
80//!     .with_header("Accept", "text/plain")
81//!     .with_header("X-Best-Mon", "Sylveon")
82//!     .send()?;
83//! let body_str = response.as_str()?;
84//! assert!(body_str.contains("\"Accept\": \"text/plain\""));
85//! assert!(body_str.contains("\"X-Best-Mon\": \"Sylveon\""));
86//! # Ok(()) }
87//! ```
88//!
89//! ## Headers (receiving)
90//!
91//! Reading the headers sent by the servers is done via the
92//! [`headers`](struct.Response.html#structfield.headers) field of the
93//! [`Response`](struct.Response.html). Note: the header field names
94//! (that is, the *keys* of the `HashMap`) are all lowercase: this is
95//! because the names are case-insensitive according to the spec, and
96//! this unifies the casings for easier `get()`ing.
97//!
98//! ```
99//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
100//! let response = tinyget::get("http://httpbin.org/ip").send()?;
101//! assert_eq!(response.headers.get("content-type").unwrap(), "application/json");
102//! # Ok(()) }
103//! ```
104//!
105//! ## Query Parameters
106//!
107//! To add query parameters to your request, use `with_query("key", "value")` before
108//! `send()`.
109//!
110//! ```
111//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
112//! let response = tinyget::get("http://httpbin.org/get")
113//!     .with_query("name", "John")
114//!     .with_query("age", "30")
115//!     .send()?;
116//! let body_str = response.as_str()?;
117//! assert!(body_str.contains("\"name\": \"John\""));
118//! assert!(body_str.contains("\"age\": \"30\""));
119//! # Ok(()) }
120//! ```
121//!
122//! ## Timeouts
123//! To avoid timing out, or limit the request's response time, use
124//! `with_timeout(n)` before `send()`. The given value is in seconds.
125//!
126//! NOTE: To Use this feature, you need to enable the `timeout` feature.
127//! ```no_run
128//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
129//! let response = tinyget::get("http://httpbin.org/delay/6")
130//!     .with_timeout(10)
131//!     .send()?;
132//! println!("{}", response.as_str()?);
133//! # Ok(()) }
134//! ```
135
136#![deny(missing_docs)]
137
138#[cfg(feature = "https")]
139extern crate native_tls;
140
141mod connection;
142mod error;
143mod request;
144mod response;
145
146pub use error::*;
147pub use request::*;
148pub use response::*;
tinyget/lib.rs

tinyget/
lib.rs
