Struct ClientBuilder 

pub struct ClientBuilder { /* private fields */ }

Fluent builder for Client with optional timeout and other configuration.

Use this instead of the bare Client::new_* constructors when you need to configure a request timeout.

Example

use std::time::Duration;
use toolkit_zero::socket::client::{ClientBuilder, Target};

// Async client with a 10-second timeout
let client = ClientBuilder::new(Target::Localhost(8080))
    .timeout(Duration::from_secs(10))
    .build_async();

// Sync client with a 30-second timeout
let client = ClientBuilder::new(Target::Remote("https://api.example.com".to_string()))
    .timeout(Duration::from_secs(30))
    .build_sync();

Implementations

impl ClientBuilder

pub fn new(target: Target) -> Self

Create a new builder for the given Target.

Examples found in repository

examples/socket_client_server.rs (line 141)

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(())
}

examples/socket_macros.rs (line 155)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let store: Arc<Mutex<Vec<Item>>> = Arc::new(Mutex::new(vec![]));
    let mut server = Server::default();

    // ── Register routes via #[mechanism] ────────────────────────────────────
    //
    // Each attribute expands to:
    //   server.mechanism(ServerMechanism::METHOD(path)[.modifier()].onconnect(fn));

    // Plain GET — no body, no state.
    #[mechanism(server, GET, "/health")]
    async fn health_handler() {
        reply!(json => Health { ok: true })
    }

    // POST + JSON body — returns the created item.
    #[mechanism(server, POST, "/items", json)]
    async fn create_item(body: NewItem) {
        reply!(json => Item { id: 1, name: body.name }, status => Status::Created)
    }

    // GET + query params — echoes back the search prefix.
    // (Filtered search requires access to the store; see /items/store below.)
    #[mechanism(server, GET, "/items/search", state(store.clone()), query)]
    async fn search_items(state: Arc<Mutex<Vec<Item>>>, f: Filter) {
        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 + shared state + JSON body — persists the item.
    #[mechanism(server, POST, "/items/store", state(store.clone()), json)]
    async fn store_item(state: Arc<Mutex<Vec<Item>>>, body: NewItem) {
        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 + AEAD-encrypted body (ChaCha20-Poly1305 via SerializationKey).
    // The body is decrypted before the handler is called; the response is
    // sealed so the client's `.send::<Item>()` can open it automatically.
    #[mechanism(server, POST, "/items/secure", encrypted(SerializationKey::Default))]
    async fn secure_create(body: NewItem) {
        let item = Item { id: 99, name: body.name };
        reply!(sealed => item, key => SerializationKey::Default)
    }

    // ── Start the server in the background via .background() ────────────────
    //
    // Previously this required manually wrapping the `.await` call inside
    // `tokio::spawn(async move { server.serve_*(…).await; })`.
    // `.background()` is the idiomatic shorthand for exactly that pattern.
    let (tx, rx) = tokio::sync::oneshot::channel::<()>();
    let server_handle = server
        .serve_with_graceful_shutdown(
            ([127, 0, 0, 1], PORT),
            async { rx.await.ok(); },
        )
        .background();                               // ← non-blocking spawn

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

    // ── Issue all requests via #[request] ───────────────────────────────────
    //
    // Each attribute expands to an expression that sends the request and awaits
    // the response, binding the decoded value to a local with the function name.

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

    // Async GET /health — plain request, no body.
    #[request(client, GET, "/health", async)]
    async fn health_resp() -> Health {}
    assert!(health_resp.ok);
    println!("GET  /health                → ok={}", health_resp.ok);

    // Async POST /items — JSON body.
    #[request(client, POST, "/items", json(NewItem { name: "widget".to_string() }), async)]
    async fn created() -> Item {}
    assert_eq!(created.name, "widget");
    println!("POST /items                 → {:?}", created);

    // Store a couple of items so the search route has data.
    #[request(client, POST, "/items/store", json(NewItem { name: "gadget".to_string() }), async)]
    async fn stored1() -> Item {}
    println!("POST /items/store           → {:?}", stored1);

    #[request(client, POST, "/items/store", json(NewItem { name: "gizmo".to_string() }), async)]
    async fn stored2() -> Item {}
    println!("POST /items/store           → {:?}", stored2);

    // Async GET /items/search?prefix=ga — query params with shared state.
    #[request(client, GET, "/items/search", query(Filter { prefix: "ga".to_string() }), async)]
    async fn results() -> SearchResult {}
    assert!(results.matches.iter().all(|i| i.name.starts_with("ga")));
    println!(
        "GET  /items/search?prefix=ga → {} match(es): {:?}",
        results.matches.len(),
        results.matches
    );

    // Async POST /items/secure — AEAD-encrypted body.
    #[request(client, POST, "/items/secure", encrypted(NewItem { name: "secret".to_string() }, SerializationKey::Default), async)]
    async fn secure_item() -> Item {}
    assert_eq!(secure_item.name, "secret");
    println!("POST /items/secure          → {:?}", secure_item);

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

pub fn timeout(self, duration: Duration) -> Self

Set a request timeout.

Both the async and blocking reqwest clients will respect this duration. Requests that do not complete within the timeout are cancelled and return a reqwest::Error with is_timeout() = true.

Examples found in repository

examples/socket_client_server.rs (line 142)

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(())
}

examples/socket_macros.rs (line 156)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let store: Arc<Mutex<Vec<Item>>> = Arc::new(Mutex::new(vec![]));
    let mut server = Server::default();

    // ── Register routes via #[mechanism] ────────────────────────────────────
    //
    // Each attribute expands to:
    //   server.mechanism(ServerMechanism::METHOD(path)[.modifier()].onconnect(fn));

    // Plain GET — no body, no state.
    #[mechanism(server, GET, "/health")]
    async fn health_handler() {
        reply!(json => Health { ok: true })
    }

    // POST + JSON body — returns the created item.
    #[mechanism(server, POST, "/items", json)]
    async fn create_item(body: NewItem) {
        reply!(json => Item { id: 1, name: body.name }, status => Status::Created)
    }

    // GET + query params — echoes back the search prefix.
    // (Filtered search requires access to the store; see /items/store below.)
    #[mechanism(server, GET, "/items/search", state(store.clone()), query)]
    async fn search_items(state: Arc<Mutex<Vec<Item>>>, f: Filter) {
        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 + shared state + JSON body — persists the item.
    #[mechanism(server, POST, "/items/store", state(store.clone()), json)]
    async fn store_item(state: Arc<Mutex<Vec<Item>>>, body: NewItem) {
        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 + AEAD-encrypted body (ChaCha20-Poly1305 via SerializationKey).
    // The body is decrypted before the handler is called; the response is
    // sealed so the client's `.send::<Item>()` can open it automatically.
    #[mechanism(server, POST, "/items/secure", encrypted(SerializationKey::Default))]
    async fn secure_create(body: NewItem) {
        let item = Item { id: 99, name: body.name };
        reply!(sealed => item, key => SerializationKey::Default)
    }

    // ── Start the server in the background via .background() ────────────────
    //
    // Previously this required manually wrapping the `.await` call inside
    // `tokio::spawn(async move { server.serve_*(…).await; })`.
    // `.background()` is the idiomatic shorthand for exactly that pattern.
    let (tx, rx) = tokio::sync::oneshot::channel::<()>();
    let server_handle = server
        .serve_with_graceful_shutdown(
            ([127, 0, 0, 1], PORT),
            async { rx.await.ok(); },
        )
        .background();                               // ← non-blocking spawn

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

    // ── Issue all requests via #[request] ───────────────────────────────────
    //
    // Each attribute expands to an expression that sends the request and awaits
    // the response, binding the decoded value to a local with the function name.

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

    // Async GET /health — plain request, no body.
    #[request(client, GET, "/health", async)]
    async fn health_resp() -> Health {}
    assert!(health_resp.ok);
    println!("GET  /health                → ok={}", health_resp.ok);

    // Async POST /items — JSON body.
    #[request(client, POST, "/items", json(NewItem { name: "widget".to_string() }), async)]
    async fn created() -> Item {}
    assert_eq!(created.name, "widget");
    println!("POST /items                 → {:?}", created);

    // Store a couple of items so the search route has data.
    #[request(client, POST, "/items/store", json(NewItem { name: "gadget".to_string() }), async)]
    async fn stored1() -> Item {}
    println!("POST /items/store           → {:?}", stored1);

    #[request(client, POST, "/items/store", json(NewItem { name: "gizmo".to_string() }), async)]
    async fn stored2() -> Item {}
    println!("POST /items/store           → {:?}", stored2);

    // Async GET /items/search?prefix=ga — query params with shared state.
    #[request(client, GET, "/items/search", query(Filter { prefix: "ga".to_string() }), async)]
    async fn results() -> SearchResult {}
    assert!(results.matches.iter().all(|i| i.name.starts_with("ga")));
    println!(
        "GET  /items/search?prefix=ga → {} match(es): {:?}",
        results.matches.len(),
        results.matches
    );

    // Async POST /items/secure — AEAD-encrypted body.
    #[request(client, POST, "/items/secure", encrypted(NewItem { name: "secret".to_string() }, SerializationKey::Default), async)]
    async fn secure_item() -> Item {}
    assert_eq!(secure_item.name, "secret");
    println!("POST /items/secure          → {:?}", secure_item);

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

pub fn build_async(self) -> Client

Build an async-only Client. Safe to call from any context, including inside #[tokio::main].

Examples found in repository

examples/socket_client_server.rs (line 143)

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(())
}

examples/socket_macros.rs (line 157)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let store: Arc<Mutex<Vec<Item>>> = Arc::new(Mutex::new(vec![]));
    let mut server = Server::default();

    // ── Register routes via #[mechanism] ────────────────────────────────────
    //
    // Each attribute expands to:
    //   server.mechanism(ServerMechanism::METHOD(path)[.modifier()].onconnect(fn));

    // Plain GET — no body, no state.
    #[mechanism(server, GET, "/health")]
    async fn health_handler() {
        reply!(json => Health { ok: true })
    }

    // POST + JSON body — returns the created item.
    #[mechanism(server, POST, "/items", json)]
    async fn create_item(body: NewItem) {
        reply!(json => Item { id: 1, name: body.name }, status => Status::Created)
    }

    // GET + query params — echoes back the search prefix.
    // (Filtered search requires access to the store; see /items/store below.)
    #[mechanism(server, GET, "/items/search", state(store.clone()), query)]
    async fn search_items(state: Arc<Mutex<Vec<Item>>>, f: Filter) {
        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 + shared state + JSON body — persists the item.
    #[mechanism(server, POST, "/items/store", state(store.clone()), json)]
    async fn store_item(state: Arc<Mutex<Vec<Item>>>, body: NewItem) {
        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 + AEAD-encrypted body (ChaCha20-Poly1305 via SerializationKey).
    // The body is decrypted before the handler is called; the response is
    // sealed so the client's `.send::<Item>()` can open it automatically.
    #[mechanism(server, POST, "/items/secure", encrypted(SerializationKey::Default))]
    async fn secure_create(body: NewItem) {
        let item = Item { id: 99, name: body.name };
        reply!(sealed => item, key => SerializationKey::Default)
    }

    // ── Start the server in the background via .background() ────────────────
    //
    // Previously this required manually wrapping the `.await` call inside
    // `tokio::spawn(async move { server.serve_*(…).await; })`.
    // `.background()` is the idiomatic shorthand for exactly that pattern.
    let (tx, rx) = tokio::sync::oneshot::channel::<()>();
    let server_handle = server
        .serve_with_graceful_shutdown(
            ([127, 0, 0, 1], PORT),
            async { rx.await.ok(); },
        )
        .background();                               // ← non-blocking spawn

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

    // ── Issue all requests via #[request] ───────────────────────────────────
    //
    // Each attribute expands to an expression that sends the request and awaits
    // the response, binding the decoded value to a local with the function name.

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

    // Async GET /health — plain request, no body.
    #[request(client, GET, "/health", async)]
    async fn health_resp() -> Health {}
    assert!(health_resp.ok);
    println!("GET  /health                → ok={}", health_resp.ok);

    // Async POST /items — JSON body.
    #[request(client, POST, "/items", json(NewItem { name: "widget".to_string() }), async)]
    async fn created() -> Item {}
    assert_eq!(created.name, "widget");
    println!("POST /items                 → {:?}", created);

    // Store a couple of items so the search route has data.
    #[request(client, POST, "/items/store", json(NewItem { name: "gadget".to_string() }), async)]
    async fn stored1() -> Item {}
    println!("POST /items/store           → {:?}", stored1);

    #[request(client, POST, "/items/store", json(NewItem { name: "gizmo".to_string() }), async)]
    async fn stored2() -> Item {}
    println!("POST /items/store           → {:?}", stored2);

    // Async GET /items/search?prefix=ga — query params with shared state.
    #[request(client, GET, "/items/search", query(Filter { prefix: "ga".to_string() }), async)]
    async fn results() -> SearchResult {}
    assert!(results.matches.iter().all(|i| i.name.starts_with("ga")));
    println!(
        "GET  /items/search?prefix=ga → {} match(es): {:?}",
        results.matches.len(),
        results.matches
    );

    // Async POST /items/secure — AEAD-encrypted body.
    #[request(client, POST, "/items/secure", encrypted(NewItem { name: "secret".to_string() }, SerializationKey::Default), async)]
    async fn secure_item() -> Item {}
    assert_eq!(secure_item.name, "secret");
    println!("POST /items/secure          → {:?}", secure_item);

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

pub fn build_sync(self) -> Client

Build a sync-only Client.

Panics

Panics if called from within an async context (same restriction as reqwest::blocking::Client). See Client::new_sync for details.

pub fn build(self) -> Client

Build a client that supports both async and blocking sends.

Panics

Panics if called from within an async context. See Client::new for details.