Struct Client 

pub struct Client { /* private fields */ }

HTTP client for making typed requests against a Target server.

A Client is created in one of three modes depending on which send variants you need:

Constructor	send() (async)	send_sync() (blocking)	Safe in async context
Client::new_async	✓	✗	✓
Client::new_sync	✗	✓	✓
Client::new	✓	✓	✗ — panics if called inside a tokio runtime

reqwest::blocking::Client internally creates its own single-threaded tokio runtime. If you call Client::new() (or Client::new_sync()) from within an existing async context (e.g. inside #[tokio::main]) it will panic. Use Client::new_async() when your program is async-first and only call Client::new_sync() / Client::new() before entering any async runtime.

Example

// Async-only client — safe inside #[tokio::main]
let client = Client::new_async(Target::Localhost(8080));

let items: Vec<Item> = client.get("/items").send().await?;
let created: Item = client.post("/items").json(NewItem { name: "w".into() }).send().await?;

Implementations

impl Client

pub fn new_async(target: Target) -> Self

Creates an async-only client. Safe to call from any context, including inside #[tokio::main]. Calling .send_sync() on builders from this client will panic.

pub fn new_sync(target: Target) -> Self

Creates a sync-only client. Must not be called from within an async context (inside #[tokio::main] or similar) — doing so panics. Calling .send() on builders from this client will panic with a message pointing to Client::new_async.

Panics

Panics at construction time if called inside a tokio runtime (same restriction as reqwest::blocking::Client). Prefer Client::new_async for async contexts.

pub fn new(target: Target) -> Self

Creates a client supporting both async and blocking sends.

Panics

Panics immediately if called from within an async context (e.g. inside #[tokio::main], tokio::spawn, or any .await call chain). This happens because reqwest::blocking::Client creates its own internal tokio runtime, and Rust/tokio forbids nesting two runtimes in the same thread.

If you are in an async context, use Client::new_async instead. If you only need blocking calls, use Client::new_sync before entering any runtime.

Example

// Correct — called from synchronous main before any async runtime starts
fn main() {
    let client = Client::new(Target::Localhost(8080));
    // ... use client.send_sync() and client.send() via manual runtime
}

// WRONG — will panic at runtime:
// #[tokio::main]
// async fn main() { let client = Client::new(...); }  // panics!

pub fn base_url(&self) -> String

Returns the base URL derived from the configured Target.

pub fn get(&self, endpoint: impl Into<String>) -> RequestBuilder<'_>

Starts a GET request builder for endpoint.

Examples found in repository

examples/socket_client_server.rs (line 146)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // ── Build routes ──────────────────────────────────────────────────────────
    let store: Arc<Mutex<Vec<Item>>> = Arc::new(Mutex::new(vec![]));

    let mut server = Server::default();

    // Plain GET — no body, no state.
    server.mechanism(
        ServerMechanism::get("/health")
            .onconnect(|| async { reply!(json => Health { ok: true }) })
    );

    // POST with a JSON body — echoes back the created item.
    server.mechanism(
        ServerMechanism::post("/items")
            .json::<NewItem>()
            .onconnect(|body: NewItem| async move {
                reply!(json => Item { id: 1, name: body.name }, status => Status::Created)
            })
    );

    // GET with query parameters — filters the stored items by prefix.
    server.mechanism({
        let store = store.clone();
        ServerMechanism::get("/items/search")
            .state(store)
            .query::<Filter>()
            .onconnect(|state: Arc<Mutex<Vec<Item>>>, f: Filter| async move {
                let items = state.lock().unwrap();
                let matches: Vec<Item> = items
                    .iter()
                    .filter(|i| i.name.starts_with(&f.prefix))
                    .cloned()
                    .collect();
                reply!(json => SearchResult { matches })
            })
    });

    // POST with shared state — stores the item and returns it.
    server.mechanism({
        let store = store.clone();
        ServerMechanism::post("/items/store")
            .state(store)
            .json::<NewItem>()
            .onconnect(|state: Arc<Mutex<Vec<Item>>>, body: NewItem| async move {
                let mut s = state.lock().unwrap();
                let id = s.len() as u32 + 1;
                let item = Item { id, name: body.name };
                s.push(item.clone());
                reply!(json => item, status => Status::Created)
            })
    });

    // POST with authenticated-encrypted body (ChaCha20-Poly1305 via SerializationKey).
    // The body is decrypted before the handler is called; a wrong key returns 403.
    server.mechanism(
        ServerMechanism::post("/items/secure")
            .encryption::<NewItem>(SerializationKey::Default)
            .onconnect(|body: NewItem| async move {
                let item = Item { id: 99, name: body.name };
                // The response must also be sealed so the client can open it.
                reply!(sealed => item, key => SerializationKey::Default)
            })
    );

    // ── Serve with graceful shutdown ──────────────────────────────────────────
    let (tx, rx) = tokio::sync::oneshot::channel::<()>();
    let server_handle = tokio::spawn(async move {
        server.serve_with_graceful_shutdown(
            ([127, 0, 0, 1], PORT),
            async { rx.await.ok(); },
        ).await;
    });

    // Give the server time to bind before firing requests.
    tokio::time::sleep(Duration::from_millis(200)).await;
    println!("Server started on port {PORT}");

    // ── Client requests ───────────────────────────────────────────────────────
    let client = ClientBuilder::new(Target::Localhost(PORT))
        .timeout(Duration::from_secs(5))
        .build_async();

    // GET /health
    let health: Health = client.get("/health").send().await?;
    assert!(health.ok);
    println!("GET  /health                → ok={}", health.ok);

    // POST /items (JSON body)
    let created: Item = client
        .post("/items")
        .json(NewItem { name: "widget".into() })
        .send()
        .await?;
    assert_eq!(created.name, "widget");
    println!("POST /items                 → {:?}", created);

    // POST /items/store (shared state — populates the store)
    let stored: Item = client
        .post("/items/store")
        .json(NewItem { name: "gadget".into() })
        .send()
        .await?;
    println!("POST /items/store           → {:?}", stored);

    let stored2: Item = client
        .post("/items/store")
        .json(NewItem { name: "gizmo".into() })
        .send()
        .await?;
    println!("POST /items/store           → {:?}", stored2);

    // GET /items/search?prefix=ga (query params)
    let result: SearchResult = client
        .get("/items/search")
        .query(Filter { prefix: "ga".into() })
        .send()
        .await?;
    assert!(result.matches.iter().all(|i| i.name.starts_with("ga")));
    println!("GET  /items/search?prefix=ga → {} match(es): {:?}", result.matches.len(), result.matches);

    // POST /items/secure (authenticated-encrypted body)
    let secure_item = client
        .post("/items/secure")
        .encryption(NewItem { name: "secret".into() }, SerializationKey::Default)
        .send::<Item>()
        .await?;
    assert_eq!(secure_item.name, "secret");
    println!("POST /items/secure          → {:?}", secure_item);

    // ── Shutdown ──────────────────────────────────────────────────────────────
    tx.send(()).ok();
    server_handle.await?;
    println!("\nAll requests successful ✓");
    Ok(())
}

pub fn post(&self, endpoint: impl Into<String>) -> RequestBuilder<'_>

Starts a POST request builder for endpoint.

Examples found in repository

examples/socket_client_server.rs (line 152)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // ── Build routes ──────────────────────────────────────────────────────────
    let store: Arc<Mutex<Vec<Item>>> = Arc::new(Mutex::new(vec![]));

    let mut server = Server::default();

    // Plain GET — no body, no state.
    server.mechanism(
        ServerMechanism::get("/health")
            .onconnect(|| async { reply!(json => Health { ok: true }) })
    );

    // POST with a JSON body — echoes back the created item.
    server.mechanism(
        ServerMechanism::post("/items")
            .json::<NewItem>()
            .onconnect(|body: NewItem| async move {
                reply!(json => Item { id: 1, name: body.name }, status => Status::Created)
            })
    );

    // GET with query parameters — filters the stored items by prefix.
    server.mechanism({
        let store = store.clone();
        ServerMechanism::get("/items/search")
            .state(store)
            .query::<Filter>()
            .onconnect(|state: Arc<Mutex<Vec<Item>>>, f: Filter| async move {
                let items = state.lock().unwrap();
                let matches: Vec<Item> = items
                    .iter()
                    .filter(|i| i.name.starts_with(&f.prefix))
                    .cloned()
                    .collect();
                reply!(json => SearchResult { matches })
            })
    });

    // POST with shared state — stores the item and returns it.
    server.mechanism({
        let store = store.clone();
        ServerMechanism::post("/items/store")
            .state(store)
            .json::<NewItem>()
            .onconnect(|state: Arc<Mutex<Vec<Item>>>, body: NewItem| async move {
                let mut s = state.lock().unwrap();
                let id = s.len() as u32 + 1;
                let item = Item { id, name: body.name };
                s.push(item.clone());
                reply!(json => item, status => Status::Created)
            })
    });

    // POST with authenticated-encrypted body (ChaCha20-Poly1305 via SerializationKey).
    // The body is decrypted before the handler is called; a wrong key returns 403.
    server.mechanism(
        ServerMechanism::post("/items/secure")
            .encryption::<NewItem>(SerializationKey::Default)
            .onconnect(|body: NewItem| async move {
                let item = Item { id: 99, name: body.name };
                // The response must also be sealed so the client can open it.
                reply!(sealed => item, key => SerializationKey::Default)
            })
    );

    // ── Serve with graceful shutdown ──────────────────────────────────────────
    let (tx, rx) = tokio::sync::oneshot::channel::<()>();
    let server_handle = tokio::spawn(async move {
        server.serve_with_graceful_shutdown(
            ([127, 0, 0, 1], PORT),
            async { rx.await.ok(); },
        ).await;
    });

    // Give the server time to bind before firing requests.
    tokio::time::sleep(Duration::from_millis(200)).await;
    println!("Server started on port {PORT}");

    // ── Client requests ───────────────────────────────────────────────────────
    let client = ClientBuilder::new(Target::Localhost(PORT))
        .timeout(Duration::from_secs(5))
        .build_async();

    // GET /health
    let health: Health = client.get("/health").send().await?;
    assert!(health.ok);
    println!("GET  /health                → ok={}", health.ok);

    // POST /items (JSON body)
    let created: Item = client
        .post("/items")
        .json(NewItem { name: "widget".into() })
        .send()
        .await?;
    assert_eq!(created.name, "widget");
    println!("POST /items                 → {:?}", created);

    // POST /items/store (shared state — populates the store)
    let stored: Item = client
        .post("/items/store")
        .json(NewItem { name: "gadget".into() })
        .send()
        .await?;
    println!("POST /items/store           → {:?}", stored);

    let stored2: Item = client
        .post("/items/store")
        .json(NewItem { name: "gizmo".into() })
        .send()
        .await?;
    println!("POST /items/store           → {:?}", stored2);

    // GET /items/search?prefix=ga (query params)
    let result: SearchResult = client
        .get("/items/search")
        .query(Filter { prefix: "ga".into() })
        .send()
        .await?;
    assert!(result.matches.iter().all(|i| i.name.starts_with("ga")));
    println!("GET  /items/search?prefix=ga → {} match(es): {:?}", result.matches.len(), result.matches);

    // POST /items/secure (authenticated-encrypted body)
    let secure_item = client
        .post("/items/secure")
        .encryption(NewItem { name: "secret".into() }, SerializationKey::Default)
        .send::<Item>()
        .await?;
    assert_eq!(secure_item.name, "secret");
    println!("POST /items/secure          → {:?}", secure_item);

    // ── Shutdown ──────────────────────────────────────────────────────────────
    tx.send(()).ok();
    server_handle.await?;
    println!("\nAll requests successful ✓");
    Ok(())
}

pub fn put(&self, endpoint: impl Into<String>) -> RequestBuilder<'_>

Starts a PUT request builder for endpoint.

pub fn delete(&self, endpoint: impl Into<String>) -> RequestBuilder<'_>

Starts a DELETE request builder for endpoint.

pub fn patch(&self, endpoint: impl Into<String>) -> RequestBuilder<'_>

Starts a PATCH request builder for endpoint.

pub fn head(&self, endpoint: impl Into<String>) -> RequestBuilder<'_>

Starts a HEAD request builder for endpoint.

pub fn options(&self, endpoint: impl Into<String>) -> RequestBuilder<'_>

Starts an OPTIONS request builder for endpoint.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.