fidius-guest::http
Rust
fidius::http — the brokered outbound HTTP client for sandboxed WASM connectors (FIDIUS-I-0028).
A connector’s read() calls get/post/send; the call crosses the
sandbox via wasi:http/outgoing-handler, where the host’s EgressPolicy
decides allow/deny/decorate before the request leaves the process. There is
no ambient network: the request only succeeds when the package declares the
http capability and the host supplied a policy (the two-key gate).
This module is #[cfg(target_family = "wasm")] and exists only in components
built for wasm32-wasip2. It is the one place the wasi:http version is
pinned (vendored WIT at crates/fidius-guest/wit, matched to the host’s
wasmtime-wasi-http); see [[FIDIUS-A-0005]] for the stability contract.
fn read(&self, cfg: Config) -> fidius::Stream<Record> { let resp = fidius::http::get(&cfg.url).expect("fetch"); // … parse resp.body into records …}Structs
Section titled “Structs”struct Request
Section titled “struct Request”pub
Derives: Debug, Clone
An outbound request. Build with Request::get/Request::post or the struct literal, then send.
Fields
Section titled “Fields”| Name | Type | Description |
|---|---|---|
method |
String |
HTTP method (uppercase, e.g. "GET", "POST"). |
url |
String |
Full URL: http://host[:port]/path?query or https://…. |
headers |
Vec<(String, String)> |
Request headers (name, value) pairs. |
body |
Vec<u8> |
Request body (empty for GET). |
timeout |
Option<core::time::Duration> |
Optional request timeout. When set, it bounds connect, first-byte, and between-bytes waits (wasi:http request-options); a slow upstream then fails with an HttpError instead of hanging the call. None = no fidius-imposed timeout (the host/runtime default applies). |
Methods
Section titled “Methods”pub
fn get(url: impl Into<String>) -> SelfA GET request for url.
Source
pub fn get(url: impl Into<String>) -> Self { Self { method: "GET".into(), url: url.into(), headers: Vec::new(), body: Vec::new(), timeout: None, } }pub
fn post(url: impl Into<String>, body: impl Into<Vec<u8>>) -> SelfA POST request for url with body.
Source
pub fn post(url: impl Into<String>, body: impl Into<Vec<u8>>) -> Self { Self { method: "POST".into(), url: url.into(), headers: Vec::new(), body: body.into(), timeout: None, } }header
Section titled “header”pub
fn header( mut self, name: impl Into<String>, value: impl Into<String>,) -> SelfAdd a header (builder style).
Source
pub fn header(mut self, name: impl Into<String>, value: impl Into<String>) -> Self { self.headers.push((name.into(), value.into())); self }timeout
Section titled “timeout”pub
fn timeout(mut self, dur: core::time::Duration) -> SelfSet a request timeout (builder style). Bounds connect / first-byte / between-bytes waits so a slow upstream fails fast instead of hanging.
Source
pub fn timeout(mut self, dur: core::time::Duration) -> Self { self.timeout = Some(dur); self }struct Response
Section titled “struct Response”pub
Derives: Debug, Clone
A response. body is the fully-read response body.
Fields
Section titled “Fields”| Name | Type | Description |
|---|---|---|
status |
u16 |
HTTP status code. |
headers |
Vec<(String, String)> |
Response headers (name, value) pairs. |
body |
Vec<u8> |
The response body, fully read. |
Methods
Section titled “Methods”is_success
Section titled “is_success”pub
fn is_success(&self) -> booltrue for a 2xx status.
Source
pub fn is_success(&self) -> bool { (200..300).contains(&self.status) }pub
fn text(&self) -> StringThe body as UTF-8 (lossy).
Source
pub fn text(&self) -> String { String::from_utf8_lossy(&self.body).into_owned() }struct HttpError
Section titled “struct HttpError”pub
Derives: Debug, Clone, PartialEq, Eq
A failed request. The most common cause in a sandbox is a denied egress: the host’s EgressPolicy refused the request, surfaced here as a transport error (the guest never learns the policy’s reasoning — by design).
Fields
Section titled “Fields”| Name | Type | Description |
|---|---|---|
message |
String |
A short, guest-visible description. |
Functions
Section titled “Functions”fn get
Section titled “fn get”pub
fn get(url: &str) -> Result<Response, HttpError>GET url.
Source
pub fn get(url: &str) -> Result<Response, HttpError> { send(Request::get(url))}fn post
Section titled “fn post”pub
fn post(url: &str, body: &[u8]) -> Result<Response, HttpError>POST body to url.
Source
pub fn post(url: &str, body: &[u8]) -> Result<Response, HttpError> { send(Request::post(url, body.to_vec()))}fn send
Section titled “fn send”pub
fn send(req: Request) -> Result<Response, HttpError>Send an arbitrary Request, blocking until the response is read. The host EgressPolicy is consulted before dispatch.
Source
pub fn send(req: Request) -> Result<Response, HttpError> { let (scheme, rest) = if let Some(r) = req.url.strip_prefix("http://") { (Scheme::Http, r) } else if let Some(r) = req.url.strip_prefix("https://") { (Scheme::Https, r) } else { return Err(HttpError::new(format!( "unsupported url scheme: {}", req.url ))); }; let (authority, path) = match rest.find('/') { Some(i) => (&rest[..i], &rest[i..]), None => (rest, "/"), };
let method = match req.method.as_str() { "GET" => Method::Get, "POST" => Method::Post, "PUT" => Method::Put, "DELETE" => Method::Delete, "HEAD" => Method::Head, "PATCH" => Method::Patch, other => Method::Other(other.to_string()), };
// Request headers. let fields = Fields::new(); for (name, value) in &req.headers { fields .append(name, &value.clone().into_bytes()) .map_err(|e| HttpError::new(format!("header {name}: {e:?}")))?; }
let outgoing = OutgoingRequest::new(fields); outgoing .set_method(&method) .map_err(|_| HttpError::new("set_method"))?; outgoing .set_scheme(Some(&scheme)) .map_err(|_| HttpError::new("set_scheme"))?; outgoing .set_authority(Some(authority)) .map_err(|_| HttpError::new("set_authority"))?; outgoing .set_path_with_query(Some(path)) .map_err(|_| HttpError::new("set_path"))?;
// Body: write (if any) then finish before dispatch. let body = outgoing.body().map_err(|_| HttpError::new("body"))?; if !req.body.is_empty() { let stream = body.write().map_err(|_| HttpError::new("body.write"))?; // wasi:io caps a single write at 4096; chunk to be safe. for chunk in req.body.chunks(4096) { stream .blocking_write_and_flush(chunk) .map_err(|e| HttpError::new(format!("write: {e:?}")))?; } drop(stream); } OutgoingBody::finish(body, None).map_err(|e| HttpError::new(format!("finish: {e:?}")))?;
// Build request-options when a timeout was set (wasi:http durations are // nanoseconds). The same bound applies to connect, first-byte, and // between-bytes waits so any stall fails fast. let options = req.timeout.map(|d| { let ns = d.as_nanos().min(u64::MAX as u128) as u64; let opts = RequestOptions::new(); let _ = opts.set_connect_timeout(Some(ns)); let _ = opts.set_first_byte_timeout(Some(ns)); let _ = opts.set_between_bytes_timeout(Some(ns)); opts }); let fut = outgoing_handler::handle(outgoing, options) .map_err(|e| HttpError::new(format!("dispatch denied or failed: {e:?}")))?; fut.subscribe().block(); let resp = fut .get() .ok_or_else(|| HttpError::new("no response"))? .map_err(|_| HttpError::new("response already taken"))? .map_err(|e| HttpError::new(format!("response error: {e:?}")))?;
let status = resp.status(); let headers = resp .headers() .entries() .into_iter() .map(|(k, v)| (k, String::from_utf8_lossy(&v).into_owned())) .collect();
let incoming = resp.consume().map_err(|_| HttpError::new("consume"))?; let stream = incoming.stream().map_err(|_| HttpError::new("stream"))?; let mut buf = Vec::new(); loop { match stream.blocking_read(8192) { Ok(chunk) if chunk.is_empty() => continue, Ok(chunk) => buf.extend_from_slice(&chunk), Err(StreamError::Closed) => break, Err(e) => return Err(HttpError::new(format!("read: {e:?}"))), } }
Ok(Response { status, headers, body: buf, })}