Crate slinger

Crate slinger 

Source
Expand description

GitHub crates-io docs-rs

§slinger (投石器)

The slinger crate provides a convenient, low-level HTTP Client.

It handles many of the things that most people just expect an HTTP client to do for them.

Additional learning resources include:

§Making a GET request

For a single request, you can use the get shortcut method.

 async fn run() -> Result<(), Box<dyn std::error::Error>> {
   let body = slinger::get("https://httpbin.org/get").await?
     .text()?;
   println!("body = {body:?}");
   Ok(())
 }

NOTE: If you plan to perform multiple requests, it is best to create a Client and reuse it, taking advantage of keep-alive connection pooling.

§Making POST requests (or setting request bodies)

There are several ways you can set the body of a request. The basic one is by using the body() method of a RequestBuilder. This lets you set the exact raw bytes of what the body should be. It accepts various types, including String and Vec<u8>. If you wish to pass a custom type, you can use the slinger::Body constructors.

 let client = slinger::Client::new();
 let res = client.post("http://httpbin.org/post")
     .body("the exact body that is sent")
     .send().await?;

§Redirect Policies

By default, a Client will automatically handle HTTP redirects, having a maximum redirect chain of 10 hops. To customize this behavior, a redirect::Policy can be used with a ClientBuilder.

§Cookies

The automatic storing and sending of session cookies can be enabled with the [cookie_store][client::ClientBuilder::cookie_store] method on ClientBuilder.

§Proxies

 async fn run() -> std::result::Result<(), Box<dyn std::error::Error>> {
   let proxy = slinger::Proxy::parse("http://user:pass@127.0.0.1:1080").unwrap();
   // let proxy = slinger::Proxy::parse("socks5://user:pass@127.0.0.1:1080").unwrap();
   let client = slinger::ClientBuilder::default().proxy(proxy).build().unwrap();
   let resp = client.get("https://httpbin.org/get").send().await?;
   println!("{:?}", resp);
   Ok(())
 }

§TLS

A Client will use transport layer security (TLS) by default to connect to HTTPS destinations.

  • Additional server certificates can be configured on a ClientBuilder with the [tls::Certificate][tls::Certificate] type.
  • Client certificates can be added to a ClientBuilder with the [tls::Identity][tls::Identity] type.
  • Various parts of TLS can also be configured or even disabled on the ClientBuilder.

§TLS Backend

When the rustls feature is enabled (recommended), slinger uses rustls as the default TLS backend through the unified CustomTlsConnector interface. This provides a consistent API regardless of which TLS implementation you use.

You can also provide your own TLS implementation by implementing the CustomTlsConnector trait and setting it with ConnectorBuilder::custom_tls_connector().

§Optional Features

The following are a list of [Cargo features][cargo-features] that can be enabled or disabled:

  • charset: Improved support for decoding text.
  • cookie: Provides cookie session support.
  • tls: Base TLS feature flag. Enables TLS types and interfaces.
  • rustls: Provides HTTPS support via rustls (requires tls feature). This is the recommended TLS backend.
  • serde: Provides serialization and deserialization support.
  • gzip: Provides response body gzip decompression.
  • http2: Provides HTTP/2 support (requires a TLS backend).

§TLS Backend Selection

When the tls feature is enabled, you have several options:

  • Enable rustls for the default pure Rust TLS implementation (recommended)
  • Or provide a custom TLS connector by implementing the CustomTlsConnector trait

§Custom TLS Backend

If you enable the tls feature, you can implement your own TLS handshake logic using any TLS library (OpenSSL, BoringSSL, native-tls, etc.):

ⓘ
use slinger::{ConnectorBuilder, CustomTlsConnector};

struct MyTlsConnector;

impl CustomTlsConnector for MyTlsConnector {
    fn connect<'a>(&'a self, domain: &'a str, stream: Socket)
        -> Pin<Box<dyn Future<Output = Result<Socket>> + Send + 'a>>
    {
        // Your TLS implementation here
        todo!()
    }
}

let connector = ConnectorBuilder::default()
    .custom_tls_connector(Arc::new(MyTlsConnector))
    .build()?;

When the rustls feature is enabled, rustls is provided as the default implementation but you can still override it with your own custom connector if needed.

Re-exports§

pub use http;

Modules§

record
record info
redirect
Redirect Handling

Structs§

Body
A body.
Client
A Client to make Requests with.
ClientBuilder
A ClientBuilder can be used to create a Client with custom configuration.
Connector
Connector
ConnectorBuilder
ConnectorBuilder
RawRequest
Unsafe specifies whether to use raw engine for sending Non RFC-Compliant requests.
Request
A request which can be executed with Client::execute().
RequestBuilder
A builder to construct the properties of a Request.
Response
A Response to a submitted Request.
ResponseBuilder
A builder to construct the properties of a Response.
ResponseConfig
response config
Socket
Socket
StreamingResponse
A streaming HTTP response that allows the body to be read like a BufReader.

Enums§

Error
The Errors that may occur when processing a slinger.
Proxy
Configuration of a proxy that a Client should pass requests to.

Functions§

get
Shortcut method to quickly make a GET request.
raw
Shortcut method to quickly make a RAW request.

Type Aliases§

Result
A Result alias where the Err case is slinger::Error.