Struct RequestBuilder

Source

pub struct RequestBuilder<'a> { /* private fields */ }

Expand description

A request builder with no body or query parameters attached.

Obtained from any Client method constructor. Attach a JSON body via json or query parameters via query, or finalise directly with send / send_sync.

Implementations§

Source §

impl<'a> RequestBuilder<'a>

Source

pub fn json<T: Serialize>(self, body: T) -> JsonRequestBuilder<'a, T>

Attaches a JSON-serialisable body, transitioning to JsonRequestBuilder.

§Example

let item: Item = client
    .post("/items")
    .json(NewItem { name: "widget".to_string() })
    .send()
    .await?;

Examples found in repository ?

examples/socket_client_server.rs (line 153)

62async fn main() -> Result<(), Box<dyn std::error::Error>> {
63    // ── Build routes ──────────────────────────────────────────────────────────
64    let store: Arc<Mutex<Vec<Item>>> = Arc::new(Mutex::new(vec![]));
65
66    let mut server = Server::default();
67
68    // Plain GET — no body, no state.
69    server.mechanism(
70        ServerMechanism::get("/health")
71            .onconnect(|| async { reply!(json => Health { ok: true }) })
72    );
73
74    // POST with a JSON body — echoes back the created item.
75    server.mechanism(
76        ServerMechanism::post("/items")
77            .json::<NewItem>()
78            .onconnect(|body: NewItem| async move {
79                reply!(json => Item { id: 1, name: body.name }, status => Status::Created)
80            })
81    );
82
83    // GET with query parameters — filters the stored items by prefix.
84    server.mechanism({
85        let store = store.clone();
86        ServerMechanism::get("/items/search")
87            .state(store)
88            .query::<Filter>()
89            .onconnect(|state: Arc<Mutex<Vec<Item>>>, f: Filter| async move {
90                let items = state.lock().unwrap();
91                let matches: Vec<Item> = items
92                    .iter()
93                    .filter(|i| i.name.starts_with(&f.prefix))
94                    .cloned()
95                    .collect();
96                reply!(json => SearchResult { matches })
97            })
98    });
99
100    // POST with shared state — stores the item and returns it.
101    server.mechanism({
102        let store = store.clone();
103        ServerMechanism::post("/items/store")
104            .state(store)
105            .json::<NewItem>()
106            .onconnect(|state: Arc<Mutex<Vec<Item>>>, body: NewItem| async move {
107                let mut s = state.lock().unwrap();
108                let id = s.len() as u32 + 1;
109                let item = Item { id, name: body.name };
110                s.push(item.clone());
111                reply!(json => item, status => Status::Created)
112            })
113    });
114
115    // POST with authenticated-encrypted body (ChaCha20-Poly1305 via SerializationKey).
116    // The body is decrypted before the handler is called; a wrong key returns 403.
117    server.mechanism(
118        ServerMechanism::post("/items/secure")
119            .encryption::<NewItem>(SerializationKey::Default)
120            .onconnect(|body: NewItem| async move {
121                let item = Item { id: 99, name: body.name };
122                // The response must also be sealed so the client can open it.
123                reply!(sealed => item, key => SerializationKey::Default)
124            })
125    );
126
127    // ── Serve with graceful shutdown ──────────────────────────────────────────
128    let (tx, rx) = tokio::sync::oneshot::channel::<()>();
129    let server_handle = tokio::spawn(async move {
130        server.serve_with_graceful_shutdown(
131            ([127, 0, 0, 1], PORT),
132            async { rx.await.ok(); },
133        ).await;
134    });
135
136    // Give the server time to bind before firing requests.
137    tokio::time::sleep(Duration::from_millis(200)).await;
138    println!("Server started on port {PORT}");
139
140    // ── Client requests ───────────────────────────────────────────────────────
141    let client = ClientBuilder::new(Target::Localhost(PORT))
142        .timeout(Duration::from_secs(5))
143        .build_async();
144
145    // GET /health
146    let health: Health = client.get("/health").send().await?;
147    assert!(health.ok);
148    println!("GET  /health                → ok={}", health.ok);
149
150    // POST /items (JSON body)
151    let created: Item = client
152        .post("/items")
153        .json(NewItem { name: "widget".into() })
154        .send()
155        .await?;
156    assert_eq!(created.name, "widget");
157    println!("POST /items                 → {:?}", created);
158
159    // POST /items/store (shared state — populates the store)
160    let stored: Item = client
161        .post("/items/store")
162        .json(NewItem { name: "gadget".into() })
163        .send()
164        .await?;
165    println!("POST /items/store           → {:?}", stored);
166
167    let stored2: Item = client
168        .post("/items/store")
169        .json(NewItem { name: "gizmo".into() })
170        .send()
171        .await?;
172    println!("POST /items/store           → {:?}", stored2);
173
174    // GET /items/search?prefix=ga (query params)
175    let result: SearchResult = client
176        .get("/items/search")
177        .query(Filter { prefix: "ga".into() })
178        .send()
179        .await?;
180    assert!(result.matches.iter().all(|i| i.name.starts_with("ga")));
181    println!("GET  /items/search?prefix=ga → {} match(es): {:?}", result.matches.len(), result.matches);
182
183    // POST /items/secure (authenticated-encrypted body)
184    let secure_item = client
185        .post("/items/secure")
186        .encryption(NewItem { name: "secret".into() }, SerializationKey::Default)
187        .send::<Item>()
188        .await?;
189    assert_eq!(secure_item.name, "secret");
190    println!("POST /items/secure          → {:?}", secure_item);
191
192    // ── Shutdown ──────────────────────────────────────────────────────────────
193    tx.send(()).ok();
194    server_handle.await?;
195    println!("\nAll requests successful ✓");
196    Ok(())
197}

Source

pub fn query<T: Serialize>(self, params: T) -> QueryRequestBuilder<'a, T>

Attaches query parameters that serialise into the URL query string, transitioning to QueryRequestBuilder.

§Example

let results: SearchResult = client
    .get("/search")
    .query(SearchParams { q: "rust".to_string(), page: 1 })
    .send()
    .await?;

Examples found in repository ?

examples/socket_client_server.rs (line 177)

62async fn main() -> Result<(), Box<dyn std::error::Error>> {
63    // ── Build routes ──────────────────────────────────────────────────────────
64    let store: Arc<Mutex<Vec<Item>>> = Arc::new(Mutex::new(vec![]));
65
66    let mut server = Server::default();
67
68    // Plain GET — no body, no state.
69    server.mechanism(
70        ServerMechanism::get("/health")
71            .onconnect(|| async { reply!(json => Health { ok: true }) })
72    );
73
74    // POST with a JSON body — echoes back the created item.
75    server.mechanism(
76        ServerMechanism::post("/items")
77            .json::<NewItem>()
78            .onconnect(|body: NewItem| async move {
79                reply!(json => Item { id: 1, name: body.name }, status => Status::Created)
80            })
81    );
82
83    // GET with query parameters — filters the stored items by prefix.
84    server.mechanism({
85        let store = store.clone();
86        ServerMechanism::get("/items/search")
87            .state(store)
88            .query::<Filter>()
89            .onconnect(|state: Arc<Mutex<Vec<Item>>>, f: Filter| async move {
90                let items = state.lock().unwrap();
91                let matches: Vec<Item> = items
92                    .iter()
93                    .filter(|i| i.name.starts_with(&f.prefix))
94                    .cloned()
95                    .collect();
96                reply!(json => SearchResult { matches })
97            })
98    });
99
100    // POST with shared state — stores the item and returns it.
101    server.mechanism({
102        let store = store.clone();
103        ServerMechanism::post("/items/store")
104            .state(store)
105            .json::<NewItem>()
106            .onconnect(|state: Arc<Mutex<Vec<Item>>>, body: NewItem| async move {
107                let mut s = state.lock().unwrap();
108                let id = s.len() as u32 + 1;
109                let item = Item { id, name: body.name };
110                s.push(item.clone());
111                reply!(json => item, status => Status::Created)
112            })
113    });
114
115    // POST with authenticated-encrypted body (ChaCha20-Poly1305 via SerializationKey).
116    // The body is decrypted before the handler is called; a wrong key returns 403.
117    server.mechanism(
118        ServerMechanism::post("/items/secure")
119            .encryption::<NewItem>(SerializationKey::Default)
120            .onconnect(|body: NewItem| async move {
121                let item = Item { id: 99, name: body.name };
122                // The response must also be sealed so the client can open it.
123                reply!(sealed => item, key => SerializationKey::Default)
124            })
125    );
126
127    // ── Serve with graceful shutdown ──────────────────────────────────────────
128    let (tx, rx) = tokio::sync::oneshot::channel::<()>();
129    let server_handle = tokio::spawn(async move {
130        server.serve_with_graceful_shutdown(
131            ([127, 0, 0, 1], PORT),
132            async { rx.await.ok(); },
133        ).await;
134    });
135
136    // Give the server time to bind before firing requests.
137    tokio::time::sleep(Duration::from_millis(200)).await;
138    println!("Server started on port {PORT}");
139
140    // ── Client requests ───────────────────────────────────────────────────────
141    let client = ClientBuilder::new(Target::Localhost(PORT))
142        .timeout(Duration::from_secs(5))
143        .build_async();
144
145    // GET /health
146    let health: Health = client.get("/health").send().await?;
147    assert!(health.ok);
148    println!("GET  /health                → ok={}", health.ok);
149
150    // POST /items (JSON body)
151    let created: Item = client
152        .post("/items")
153        .json(NewItem { name: "widget".into() })
154        .send()
155        .await?;
156    assert_eq!(created.name, "widget");
157    println!("POST /items                 → {:?}", created);
158
159    // POST /items/store (shared state — populates the store)
160    let stored: Item = client
161        .post("/items/store")
162        .json(NewItem { name: "gadget".into() })
163        .send()
164        .await?;
165    println!("POST /items/store           → {:?}", stored);
166
167    let stored2: Item = client
168        .post("/items/store")
169        .json(NewItem { name: "gizmo".into() })
170        .send()
171        .await?;
172    println!("POST /items/store           → {:?}", stored2);
173
174    // GET /items/search?prefix=ga (query params)
175    let result: SearchResult = client
176        .get("/items/search")
177        .query(Filter { prefix: "ga".into() })
178        .send()
179        .await?;
180    assert!(result.matches.iter().all(|i| i.name.starts_with("ga")));
181    println!("GET  /items/search?prefix=ga → {} match(es): {:?}", result.matches.len(), result.matches);
182
183    // POST /items/secure (authenticated-encrypted body)
184    let secure_item = client
185        .post("/items/secure")
186        .encryption(NewItem { name: "secret".into() }, SerializationKey::Default)
187        .send::<Item>()
188        .await?;
189    assert_eq!(secure_item.name, "secret");
190    println!("POST /items/secure          → {:?}", secure_item);
191
192    // ── Shutdown ──────────────────────────────────────────────────────────────
193    tx.send(()).ok();
194    server_handle.await?;
195    println!("\nAll requests successful ✓");
196    Ok(())
197}

Source

pub async fn send<R: DeserializeOwned>(self) -> Result<R, Error>

Sends the request asynchronously and deserialises the response body as R.

§Example

let user: User = client.get("/users/1").send().await?;

Examples found in repository ?

examples/socket_client_server.rs (line 146)

62async fn main() -> Result<(), Box<dyn std::error::Error>> {
63    // ── Build routes ──────────────────────────────────────────────────────────
64    let store: Arc<Mutex<Vec<Item>>> = Arc::new(Mutex::new(vec![]));
65
66    let mut server = Server::default();
67
68    // Plain GET — no body, no state.
69    server.mechanism(
70        ServerMechanism::get("/health")
71            .onconnect(|| async { reply!(json => Health { ok: true }) })
72    );
73
74    // POST with a JSON body — echoes back the created item.
75    server.mechanism(
76        ServerMechanism::post("/items")
77            .json::<NewItem>()
78            .onconnect(|body: NewItem| async move {
79                reply!(json => Item { id: 1, name: body.name }, status => Status::Created)
80            })
81    );
82
83    // GET with query parameters — filters the stored items by prefix.
84    server.mechanism({
85        let store = store.clone();
86        ServerMechanism::get("/items/search")
87            .state(store)
88            .query::<Filter>()
89            .onconnect(|state: Arc<Mutex<Vec<Item>>>, f: Filter| async move {
90                let items = state.lock().unwrap();
91                let matches: Vec<Item> = items
92                    .iter()
93                    .filter(|i| i.name.starts_with(&f.prefix))
94                    .cloned()
95                    .collect();
96                reply!(json => SearchResult { matches })
97            })
98    });
99
100    // POST with shared state — stores the item and returns it.
101    server.mechanism({
102        let store = store.clone();
103        ServerMechanism::post("/items/store")
104            .state(store)
105            .json::<NewItem>()
106            .onconnect(|state: Arc<Mutex<Vec<Item>>>, body: NewItem| async move {
107                let mut s = state.lock().unwrap();
108                let id = s.len() as u32 + 1;
109                let item = Item { id, name: body.name };
110                s.push(item.clone());
111                reply!(json => item, status => Status::Created)
112            })
113    });
114
115    // POST with authenticated-encrypted body (ChaCha20-Poly1305 via SerializationKey).
116    // The body is decrypted before the handler is called; a wrong key returns 403.
117    server.mechanism(
118        ServerMechanism::post("/items/secure")
119            .encryption::<NewItem>(SerializationKey::Default)
120            .onconnect(|body: NewItem| async move {
121                let item = Item { id: 99, name: body.name };
122                // The response must also be sealed so the client can open it.
123                reply!(sealed => item, key => SerializationKey::Default)
124            })
125    );
126
127    // ── Serve with graceful shutdown ──────────────────────────────────────────
128    let (tx, rx) = tokio::sync::oneshot::channel::<()>();
129    let server_handle = tokio::spawn(async move {
130        server.serve_with_graceful_shutdown(
131            ([127, 0, 0, 1], PORT),
132            async { rx.await.ok(); },
133        ).await;
134    });
135
136    // Give the server time to bind before firing requests.
137    tokio::time::sleep(Duration::from_millis(200)).await;
138    println!("Server started on port {PORT}");
139
140    // ── Client requests ───────────────────────────────────────────────────────
141    let client = ClientBuilder::new(Target::Localhost(PORT))
142        .timeout(Duration::from_secs(5))
143        .build_async();
144
145    // GET /health
146    let health: Health = client.get("/health").send().await?;
147    assert!(health.ok);
148    println!("GET  /health                → ok={}", health.ok);
149
150    // POST /items (JSON body)
151    let created: Item = client
152        .post("/items")
153        .json(NewItem { name: "widget".into() })
154        .send()
155        .await?;
156    assert_eq!(created.name, "widget");
157    println!("POST /items                 → {:?}", created);
158
159    // POST /items/store (shared state — populates the store)
160    let stored: Item = client
161        .post("/items/store")
162        .json(NewItem { name: "gadget".into() })
163        .send()
164        .await?;
165    println!("POST /items/store           → {:?}", stored);
166
167    let stored2: Item = client
168        .post("/items/store")
169        .json(NewItem { name: "gizmo".into() })
170        .send()
171        .await?;
172    println!("POST /items/store           → {:?}", stored2);
173
174    // GET /items/search?prefix=ga (query params)
175    let result: SearchResult = client
176        .get("/items/search")
177        .query(Filter { prefix: "ga".into() })
178        .send()
179        .await?;
180    assert!(result.matches.iter().all(|i| i.name.starts_with("ga")));
181    println!("GET  /items/search?prefix=ga → {} match(es): {:?}", result.matches.len(), result.matches);
182
183    // POST /items/secure (authenticated-encrypted body)
184    let secure_item = client
185        .post("/items/secure")
186        .encryption(NewItem { name: "secret".into() }, SerializationKey::Default)
187        .send::<Item>()
188        .await?;
189    assert_eq!(secure_item.name, "secret");
190    println!("POST /items/secure          → {:?}", secure_item);
191
192    // ── Shutdown ──────────────────────────────────────────────────────────────
193    tx.send(()).ok();
194    server_handle.await?;
195    println!("\nAll requests successful ✓");
196    Ok(())
197}

Source

pub fn send_sync<R: DeserializeOwned>(self) -> Result<R, Error>

Sends the request synchronously and deserialises the response body as R.

§Example

let user: User = client.get("/users/1").send_sync()?;

Source

pub fn encryption<T: Encode>( self, body: T, key: SerializationKey, ) -> EncryptedBodyRequestBuilder<'a, T>

Attaches an authenticated-encrypted body (ChaCha20-Poly1305), transitioning to EncryptedBodyRequestBuilder.

The body is sealed with the given SerializationKey and sent as application/octet-stream; the response is opened with the same key. For plain-JSON routes use .json(body) instead.

§Example

use toolkit_zero::socket::SerializationKey;
let resp: Resp = client
    .post("/compute")
    .encryption(Req { value: 42 }, SerializationKey::Default)
    .send()
    .await?;

Examples found in repository ?

examples/socket_client_server.rs (line 186)

62async fn main() -> Result<(), Box<dyn std::error::Error>> {
63    // ── Build routes ──────────────────────────────────────────────────────────
64    let store: Arc<Mutex<Vec<Item>>> = Arc::new(Mutex::new(vec![]));
65
66    let mut server = Server::default();
67
68    // Plain GET — no body, no state.
69    server.mechanism(
70        ServerMechanism::get("/health")
71            .onconnect(|| async { reply!(json => Health { ok: true }) })
72    );
73
74    // POST with a JSON body — echoes back the created item.
75    server.mechanism(
76        ServerMechanism::post("/items")
77            .json::<NewItem>()
78            .onconnect(|body: NewItem| async move {
79                reply!(json => Item { id: 1, name: body.name }, status => Status::Created)
80            })
81    );
82
83    // GET with query parameters — filters the stored items by prefix.
84    server.mechanism({
85        let store = store.clone();
86        ServerMechanism::get("/items/search")
87            .state(store)
88            .query::<Filter>()
89            .onconnect(|state: Arc<Mutex<Vec<Item>>>, f: Filter| async move {
90                let items = state.lock().unwrap();
91                let matches: Vec<Item> = items
92                    .iter()
93                    .filter(|i| i.name.starts_with(&f.prefix))
94                    .cloned()
95                    .collect();
96                reply!(json => SearchResult { matches })
97            })
98    });
99
100    // POST with shared state — stores the item and returns it.
101    server.mechanism({
102        let store = store.clone();
103        ServerMechanism::post("/items/store")
104            .state(store)
105            .json::<NewItem>()
106            .onconnect(|state: Arc<Mutex<Vec<Item>>>, body: NewItem| async move {
107                let mut s = state.lock().unwrap();
108                let id = s.len() as u32 + 1;
109                let item = Item { id, name: body.name };
110                s.push(item.clone());
111                reply!(json => item, status => Status::Created)
112            })
113    });
114
115    // POST with authenticated-encrypted body (ChaCha20-Poly1305 via SerializationKey).
116    // The body is decrypted before the handler is called; a wrong key returns 403.
117    server.mechanism(
118        ServerMechanism::post("/items/secure")
119            .encryption::<NewItem>(SerializationKey::Default)
120            .onconnect(|body: NewItem| async move {
121                let item = Item { id: 99, name: body.name };
122                // The response must also be sealed so the client can open it.
123                reply!(sealed => item, key => SerializationKey::Default)
124            })
125    );
126
127    // ── Serve with graceful shutdown ──────────────────────────────────────────
128    let (tx, rx) = tokio::sync::oneshot::channel::<()>();
129    let server_handle = tokio::spawn(async move {
130        server.serve_with_graceful_shutdown(
131            ([127, 0, 0, 1], PORT),
132            async { rx.await.ok(); },
133        ).await;
134    });
135
136    // Give the server time to bind before firing requests.
137    tokio::time::sleep(Duration::from_millis(200)).await;
138    println!("Server started on port {PORT}");
139
140    // ── Client requests ───────────────────────────────────────────────────────
141    let client = ClientBuilder::new(Target::Localhost(PORT))
142        .timeout(Duration::from_secs(5))
143        .build_async();
144
145    // GET /health
146    let health: Health = client.get("/health").send().await?;
147    assert!(health.ok);
148    println!("GET  /health                → ok={}", health.ok);
149
150    // POST /items (JSON body)
151    let created: Item = client
152        .post("/items")
153        .json(NewItem { name: "widget".into() })
154        .send()
155        .await?;
156    assert_eq!(created.name, "widget");
157    println!("POST /items                 → {:?}", created);
158
159    // POST /items/store (shared state — populates the store)
160    let stored: Item = client
161        .post("/items/store")
162        .json(NewItem { name: "gadget".into() })
163        .send()
164        .await?;
165    println!("POST /items/store           → {:?}", stored);
166
167    let stored2: Item = client
168        .post("/items/store")
169        .json(NewItem { name: "gizmo".into() })
170        .send()
171        .await?;
172    println!("POST /items/store           → {:?}", stored2);
173
174    // GET /items/search?prefix=ga (query params)
175    let result: SearchResult = client
176        .get("/items/search")
177        .query(Filter { prefix: "ga".into() })
178        .send()
179        .await?;
180    assert!(result.matches.iter().all(|i| i.name.starts_with("ga")));
181    println!("GET  /items/search?prefix=ga → {} match(es): {:?}", result.matches.len(), result.matches);
182
183    // POST /items/secure (authenticated-encrypted body)
184    let secure_item = client
185        .post("/items/secure")
186        .encryption(NewItem { name: "secret".into() }, SerializationKey::Default)
187        .send::<Item>()
188        .await?;
189    assert_eq!(secure_item.name, "secret");
190    println!("POST /items/secure          → {:?}", secure_item);
191
192    // ── Shutdown ──────────────────────────────────────────────────────────────
193    tx.send(()).ok();
194    server_handle.await?;
195    println!("\nAll requests successful ✓");
196    Ok(())
197}

Source

pub fn encrypted_query<T: Encode>( self, params: T, key: SerializationKey, ) -> EncryptedQueryRequestBuilder<'a, T>

Attaches authenticated-encrypted query parameters (ChaCha20-Poly1305), transitioning to EncryptedQueryRequestBuilder.

The params are sealed and sent as ?data=<base64url>; the response is opened with the same key. For plain query-string routes use .query(params) instead.

§Example

use toolkit_zero::socket::SerializationKey;
let page: Page = client
    .get("/items")
    .encrypted_query(Filter { page: 1 }, SerializationKey::Default)
    .send()
    .await?;