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][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.

§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 without a specific backend.
  • rustls: Provides HTTPS support via rustls (requires tls feature).
  • 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 can choose a TLS backend:

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

§Custom TLS Backend

If you enable only the tls feature without a backend, 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, stream: Socket, domain: &'a str)
        -> 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()?;

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

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.