Struct ServerMechanism 

pub struct ServerMechanism { /* private fields */ }

Entry point for building an HTTP route.

Pairs an HTTP method with a URL path and acts as the root of a fluent builder chain. Optionally attach shared state, a JSON body expectation, or URL query parameter deserialisation — then finalise with onconnect (async) or onconnect_sync (sync) to produce a SocketType ready to be mounted on a Server.

Example

// Plain GET — no body, no state
let health = ServerMechanism::get("/health")
    .onconnect(|| async { reply!() });

// POST — JSON body deserialised into `CreateItem`
let create = ServerMechanism::post("/items")
    .json::<CreateItem>()
    .onconnect(|body| async move {
        let item = Item { id: 1, name: body.name };
        reply!(json => item, status => Status::Created)
    });

// GET — shared counter state injected on every request
let counter: Arc<Mutex<u64>> = Arc::new(Mutex::new(0));
let count_route = ServerMechanism::get("/count")
    .state(counter.clone())
    .onconnect(|state| async move {
        let n = *state.lock().unwrap();
        reply!(json => n)
    });

Implementations

impl ServerMechanism

pub fn get(path: impl Into<String>) -> Self

Creates a route matching HTTP GET requests at path.

Examples found in repository

examples/socket_client_server.rs (line 70)

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(path: impl Into<String>) -> Self

Creates a route matching HTTP POST requests at path.

Examples found in repository

examples/socket_client_server.rs (line 76)

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(path: impl Into<String>) -> Self

Creates a route matching HTTP PUT requests at path.

pub fn delete(path: impl Into<String>) -> Self

Creates a route matching HTTP DELETE requests at path.

pub fn patch(path: impl Into<String>) -> Self

Creates a route matching HTTP PATCH requests at path.

pub fn head(path: impl Into<String>) -> Self

Creates a route matching HTTP HEAD requests at path.

pub fn options(path: impl Into<String>) -> Self

Creates a route matching HTTP OPTIONS requests at path.

pub fn state<S: Clone + Send + Sync + 'static>( self, state: S, ) -> StatefulSocketBuilder<S>

Attaches shared state S to this route, transitioning to StatefulSocketBuilder.

A fresh clone of S is injected into the handler on every request.

Examples found in repository

examples/socket_client_server.rs (line 87)

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 json<T: DeserializeOwned + Send>(self) -> JsonSocketBuilder<T>

Declares that this route expects a JSON-encoded request body, transitioning to JsonSocketBuilder.

Examples found in repository

examples/socket_client_server.rs (line 77)

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 query<T: DeserializeOwned + Send>(self) -> QuerySocketBuilder<T>

Declares that this route extracts its input from URL query parameters, transitioning to QuerySocketBuilder.

pub fn encryption<T>(self, key: SerializationKey) -> EncryptedBodyBuilder<T>

Declares that this route expects an authenticated-encrypted request body (ChaCha20-Poly1305), transitioning to EncryptedBodyBuilder.

Examples found in repository

examples/socket_client_server.rs (line 119)

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 encrypted_query<T>( self, key: SerializationKey, ) -> EncryptedQueryBuilder<T>

Declares that this route expects authenticated-encrypted URL query parameters (ChaCha20-Poly1305), transitioning to EncryptedQueryBuilder.

pub fn onconnect<F, Fut, Re>(self, handler: F) -> SocketType

where F: Fn() -> Fut + Clone + Send + Sync + 'static, Fut: Future<Output = Result<Re, Rejection>> + Send, Re: Reply + Send,

Finalises this route with an async handler that receives no arguments.

Returns a SocketType ready to be passed to Server::mechanism.

Example

let route = ServerMechanism::get("/ping")
    .onconnect(|| async {
        reply!(json => Pong { ok: true })
    });

Examples found in repository

examples/socket_client_server.rs (line 71)

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 unsafe fn onconnect_sync<F, Re>(self, handler: F) -> SocketType

where F: Fn() -> Result<Re, Rejection> + Clone + Send + Sync + 'static, Re: Reply + Send + 'static,

Finalises this route with a synchronous handler that receives no arguments.

Safety

Every incoming request spawns an independent task on Tokio’s blocking thread pool. The pool caps the number of live OS threads (default 512), but the queue of waiting tasks is unbounded — under a traffic surge, tasks accumulate without limit, consuming unbounded memory and causing severe latency spikes or OOM crashes. Additionally, any panic inside the handler is silently converted into a 500 response, masking runtime errors. Callers must ensure the handler completes quickly and that adequate backpressure or rate limiting is applied externally.