wasmtime_wasi_http/
lib.rs

1//! # Wasmtime's WASI HTTP Implementation
2//!
3//! This crate is Wasmtime's host implementation of the `wasi:http` package as
4//! part of WASIp2. This crate's implementation is primarily built on top of
5//! [`hyper`] and [`tokio`].
6//!
7//! # WASI HTTP Interfaces
8//!
9//! This crate contains implementations of the following interfaces:
10//!
11//! * [`wasi:http/incoming-handler`]
12//! * [`wasi:http/outgoing-handler`]
13//! * [`wasi:http/types`]
14//!
15//! The crate also contains an implementation of the [`wasi:http/proxy`] world.
16//!
17//! [`wasi:http/proxy`]: crate::bindings::Proxy
18//! [`wasi:http/outgoing-handler`]: crate::bindings::http::outgoing_handler::Host
19//! [`wasi:http/types`]: crate::bindings::http::types::Host
20//! [`wasi:http/incoming-handler`]: crate::bindings::exports::wasi::http::incoming_handler::Guest
21//!
22//! This crate is very similar to [`wasmtime-wasi`] in the it uses the
23//! `bindgen!` macro in Wasmtime to generate bindings to interfaces. Bindings
24//! are located in the [`bindings`] module.
25//!
26//! # The `WasiHttpView` trait
27//!
28//! All `bindgen!`-generated `Host` traits are implemented in terms of a
29//! [`WasiHttpView`] trait which provides basic access to [`WasiHttpCtx`],
30//! configuration for WASI HTTP, and a [`wasmtime_wasi::ResourceTable`], the
31//! state for all host-defined component model resources.
32//!
33//! The [`WasiHttpView`] trait additionally offers a few other configuration
34//! methods such as [`WasiHttpView::send_request`] to customize how outgoing
35//! HTTP requests are handled.
36//!
37//! # Async and Sync
38//!
39//! There are both asynchronous and synchronous bindings in this crate. For
40//! example [`add_to_linker_async`] is for asynchronous embedders and
41//! [`add_to_linker_sync`] is for synchronous embedders. Note that under the
42//! hood both versions are implemented with `async` on top of [`tokio`].
43//!
44//! # Examples
45//!
46//! Usage of this crate is done through a few steps to get everything hooked up:
47//!
48//! 1. First implement [`WasiHttpView`] for your type which is the `T` in
49//!    [`wasmtime::Store<T>`].
50//! 2. Add WASI HTTP interfaces to a [`wasmtime::component::Linker<T>`]. There
51//!    are a few options of how to do this:
52//!    * Use [`add_to_linker_async`] to bundle all interfaces in
53//!      `wasi:http/proxy` together
54//!    * Use [`add_only_http_to_linker_async`] to add only HTTP interfaces but
55//!      no others. This is useful when working with
56//!      [`wasmtime_wasi::add_to_linker_async`] for example.
57//!    * Add individual interfaces such as with the
58//!      [`bindings::http::outgoing_handler::add_to_linker_get_host`] function.
59//! 3. Use [`ProxyPre`](bindings::ProxyPre) to pre-instantiate a component
60//!    before serving requests.
61//! 4. When serving requests use
62//!    [`ProxyPre::instantiate_async`](bindings::ProxyPre::instantiate_async)
63//!    to create instances and handle HTTP requests.
64//!
65//! A standalone example of doing all this looks like:
66//!
67//! ```no_run
68//! use anyhow::bail;
69//! use hyper::server::conn::http1;
70//! use std::sync::Arc;
71//! use tokio::net::TcpListener;
72//! use wasmtime::component::{Component, Linker, ResourceTable};
73//! use wasmtime::{Config, Engine, Result, Store};
74//! use wasmtime_wasi::{IoView, WasiCtx, WasiCtxBuilder, WasiView};
75//! use wasmtime_wasi_http::bindings::ProxyPre;
76//! use wasmtime_wasi_http::bindings::http::types::Scheme;
77//! use wasmtime_wasi_http::body::HyperOutgoingBody;
78//! use wasmtime_wasi_http::io::TokioIo;
79//! use wasmtime_wasi_http::{WasiHttpCtx, WasiHttpView};
80//!
81//! #[tokio::main]
82//! async fn main() -> Result<()> {
83//!     let component = std::env::args().nth(1).unwrap();
84//!
85//!     // Prepare the `Engine` for Wasmtime
86//!     let mut config = Config::new();
87//!     config.async_support(true);
88//!     let engine = Engine::new(&config)?;
89//!
90//!     // Compile the component on the command line to machine code
91//!     let component = Component::from_file(&engine, &component)?;
92//!
93//!     // Prepare the `ProxyPre` which is a pre-instantiated version of the
94//!     // component that we have. This will make per-request instantiation
95//!     // much quicker.
96//!     let mut linker = Linker::new(&engine);
97//!     wasmtime_wasi_http::add_to_linker_async(&mut linker)?;
98//!     let pre = ProxyPre::new(linker.instantiate_pre(&component)?)?;
99//!
100//!     // Prepare our server state and start listening for connections.
101//!     let server = Arc::new(MyServer { pre });
102//!     let listener = TcpListener::bind("127.0.0.1:8000").await?;
103//!     println!("Listening on {}", listener.local_addr()?);
104//!
105//!     loop {
106//!         // Accept a TCP connection and serve all of its requests in a separate
107//!         // tokio task. Note that for now this only works with HTTP/1.1.
108//!         let (client, addr) = listener.accept().await?;
109//!         println!("serving new client from {addr}");
110//!
111//!         let server = server.clone();
112//!         tokio::task::spawn(async move {
113//!             if let Err(e) = http1::Builder::new()
114//!                 .keep_alive(true)
115//!                 .serve_connection(
116//!                     TokioIo::new(client),
117//!                     hyper::service::service_fn(move |req| {
118//!                         let server = server.clone();
119//!                         async move { server.handle_request(req).await }
120//!                     }),
121//!                 )
122//!                 .await
123//!             {
124//!                 eprintln!("error serving client[{addr}]: {e:?}");
125//!             }
126//!         });
127//!     }
128//! }
129//!
130//! struct MyServer {
131//!     pre: ProxyPre<MyClientState>,
132//! }
133//!
134//! impl MyServer {
135//!     async fn handle_request(
136//!         &self,
137//!         req: hyper::Request<hyper::body::Incoming>,
138//!     ) -> Result<hyper::Response<HyperOutgoingBody>> {
139//!         // Create per-http-request state within a `Store` and prepare the
140//!         // initial resources  passed to the `handle` function.
141//!         let mut store = Store::new(
142//!             self.pre.engine(),
143//!             MyClientState {
144//!                 table: ResourceTable::new(),
145//!                 wasi: WasiCtxBuilder::new().inherit_stdio().build(),
146//!                 http: WasiHttpCtx::new(),
147//!             },
148//!         );
149//!         let (sender, receiver) = tokio::sync::oneshot::channel();
150//!         let req = store.data_mut().new_incoming_request(Scheme::Http, req)?;
151//!         let out = store.data_mut().new_response_outparam(sender)?;
152//!         let pre = self.pre.clone();
153//!
154//!         // Run the http request itself in a separate task so the task can
155//!         // optionally continue to execute beyond after the initial
156//!         // headers/response code are sent.
157//!         let task = tokio::task::spawn(async move {
158//!             let proxy = pre.instantiate_async(&mut store).await?;
159//!
160//!             if let Err(e) = proxy
161//!                 .wasi_http_incoming_handler()
162//!                 .call_handle(store, req, out)
163//!                 .await
164//!             {
165//!                 return Err(e);
166//!             }
167//!
168//!             Ok(())
169//!         });
170//!
171//!         match receiver.await {
172//!             // If the client calls `response-outparam::set` then one of these
173//!             // methods will be called.
174//!             Ok(Ok(resp)) => Ok(resp),
175//!             Ok(Err(e)) => Err(e.into()),
176//!
177//!             // Otherwise the `sender` will get dropped along with the `Store`
178//!             // meaning that the oneshot will get disconnected and here we can
179//!             // inspect the `task` result to see what happened
180//!             Err(_) => {
181//!                 let e = match task.await {
182//!                     Ok(Ok(())) => {
183//!                         bail!("guest never invoked `response-outparam::set` method")
184//!                     }
185//!                     Ok(Err(e)) => e,
186//!                     Err(e) => e.into(),
187//!                 };
188//!                 return Err(e.context("guest never invoked `response-outparam::set` method"));
189//!             }
190//!         }
191//!     }
192//! }
193//!
194//! struct MyClientState {
195//!     wasi: WasiCtx,
196//!     http: WasiHttpCtx,
197//!     table: ResourceTable,
198//! }
199//! impl IoView for MyClientState {
200//!     fn table(&mut self) -> &mut ResourceTable {
201//!         &mut self.table
202//!     }
203//! }
204//! impl WasiView for MyClientState {
205//!     fn ctx(&mut self) -> &mut WasiCtx {
206//!         &mut self.wasi
207//!     }
208//! }
209//!
210//! impl WasiHttpView for MyClientState {
211//!     fn ctx(&mut self) -> &mut WasiHttpCtx {
212//!         &mut self.http
213//!     }
214//! }
215//! ```
216
217#![deny(missing_docs)]
218#![doc(test(attr(deny(warnings))))]
219#![doc(test(attr(allow(dead_code, unused_variables, unused_mut))))]
220#![expect(clippy::allow_attributes_without_reason, reason = "crate not migrated")]
221
222mod error;
223mod http_impl;
224mod types_impl;
225
226pub mod body;
227pub mod io;
228pub mod types;
229
230pub mod bindings;
231
232pub use crate::error::{
233    http_request_error, hyper_request_error, hyper_response_error, HttpError, HttpResult,
234};
235#[doc(inline)]
236pub use crate::types::{
237    WasiHttpCtx, WasiHttpImpl, WasiHttpView, DEFAULT_OUTGOING_BODY_BUFFER_CHUNKS,
238    DEFAULT_OUTGOING_BODY_CHUNK_SIZE,
239};
240use wasmtime_wasi::IoImpl;
241/// Add all of the `wasi:http/proxy` world's interfaces to a [`wasmtime::component::Linker`].
242///
243/// This function will add the `async` variant of all interfaces into the
244/// `Linker` provided. By `async` this means that this function is only
245/// compatible with [`Config::async_support(true)`][async]. For embeddings with
246/// async support disabled see [`add_to_linker_sync`] instead.
247///
248/// [async]: wasmtime::Config::async_support
249///
250/// # Example
251///
252/// ```
253/// use wasmtime::{Engine, Result, Config};
254/// use wasmtime::component::{ResourceTable, Linker};
255/// use wasmtime_wasi::{IoView, WasiCtx, WasiView};
256/// use wasmtime_wasi_http::{WasiHttpCtx, WasiHttpView};
257///
258/// fn main() -> Result<()> {
259///     let mut config = Config::new();
260///     config.async_support(true);
261///     let engine = Engine::new(&config)?;
262///
263///     let mut linker = Linker::<MyState>::new(&engine);
264///     wasmtime_wasi_http::add_to_linker_async(&mut linker)?;
265///     // ... add any further functionality to `linker` if desired ...
266///
267///     Ok(())
268/// }
269///
270/// struct MyState {
271///     ctx: WasiCtx,
272///     http_ctx: WasiHttpCtx,
273///     table: ResourceTable,
274/// }
275///
276/// impl IoView for MyState {
277///     fn table(&mut self) -> &mut ResourceTable { &mut self.table }
278/// }
279/// impl WasiHttpView for MyState {
280///     fn ctx(&mut self) -> &mut WasiHttpCtx { &mut self.http_ctx }
281/// }
282/// impl WasiView for MyState {
283///     fn ctx(&mut self) -> &mut WasiCtx { &mut self.ctx }
284/// }
285/// ```
286pub fn add_to_linker_async<T>(l: &mut wasmtime::component::Linker<T>) -> anyhow::Result<()>
287where
288    T: WasiHttpView + wasmtime_wasi::WasiView,
289{
290    let io_closure = type_annotate_io::<T, _>(|t| wasmtime_wasi::IoImpl(t));
291    wasmtime_wasi::bindings::io::poll::add_to_linker_get_host(l, io_closure)?;
292    wasmtime_wasi::bindings::io::error::add_to_linker_get_host(l, io_closure)?;
293    wasmtime_wasi::bindings::io::streams::add_to_linker_get_host(l, io_closure)?;
294
295    let closure = type_annotate_wasi::<T, _>(|t| wasmtime_wasi::WasiImpl(wasmtime_wasi::IoImpl(t)));
296    wasmtime_wasi::bindings::clocks::wall_clock::add_to_linker_get_host(l, closure)?;
297    wasmtime_wasi::bindings::clocks::monotonic_clock::add_to_linker_get_host(l, closure)?;
298    wasmtime_wasi::bindings::cli::stdin::add_to_linker_get_host(l, closure)?;
299    wasmtime_wasi::bindings::cli::stdout::add_to_linker_get_host(l, closure)?;
300    wasmtime_wasi::bindings::cli::stderr::add_to_linker_get_host(l, closure)?;
301    wasmtime_wasi::bindings::random::random::add_to_linker_get_host(l, closure)?;
302
303    add_only_http_to_linker_async(l)
304}
305
306// NB: workaround some rustc inference - a future refactoring may make this
307// obsolete.
308fn type_annotate_http<T, F>(val: F) -> F
309where
310    F: Fn(&mut T) -> WasiHttpImpl<&mut T>,
311{
312    val
313}
314fn type_annotate_wasi<T, F>(val: F) -> F
315where
316    F: Fn(&mut T) -> wasmtime_wasi::WasiImpl<&mut T>,
317{
318    val
319}
320fn type_annotate_io<T, F>(val: F) -> F
321where
322    F: Fn(&mut T) -> wasmtime_wasi::IoImpl<&mut T>,
323{
324    val
325}
326
327/// A slimmed down version of [`add_to_linker_async`] which only adds
328/// `wasi:http` interfaces to the linker.
329///
330/// This is useful when using [`wasmtime_wasi::add_to_linker_async`] for
331/// example to avoid re-adding the same interfaces twice.
332pub fn add_only_http_to_linker_async<T>(
333    l: &mut wasmtime::component::Linker<T>,
334) -> anyhow::Result<()>
335where
336    T: WasiHttpView,
337{
338    let closure = type_annotate_http::<T, _>(|t| WasiHttpImpl(IoImpl(t)));
339    crate::bindings::http::outgoing_handler::add_to_linker_get_host(l, closure)?;
340    crate::bindings::http::types::add_to_linker_get_host(l, closure)?;
341
342    Ok(())
343}
344
345/// Add all of the `wasi:http/proxy` world's interfaces to a [`wasmtime::component::Linker`].
346///
347/// This function will add the `sync` variant of all interfaces into the
348/// `Linker` provided. For embeddings with async support see
349/// [`add_to_linker_async`] instead.
350///
351/// # Example
352///
353/// ```
354/// use wasmtime::{Engine, Result, Config};
355/// use wasmtime::component::{ResourceTable, Linker};
356/// use wasmtime_wasi::{IoView, WasiCtx, WasiView};
357/// use wasmtime_wasi_http::{WasiHttpCtx, WasiHttpView};
358///
359/// fn main() -> Result<()> {
360///     let config = Config::default();
361///     let engine = Engine::new(&config)?;
362///
363///     let mut linker = Linker::<MyState>::new(&engine);
364///     wasmtime_wasi_http::add_to_linker_sync(&mut linker)?;
365///     // ... add any further functionality to `linker` if desired ...
366///
367///     Ok(())
368/// }
369///
370/// struct MyState {
371///     ctx: WasiCtx,
372///     http_ctx: WasiHttpCtx,
373///     table: ResourceTable,
374/// }
375/// impl IoView for MyState {
376///     fn table(&mut self) -> &mut ResourceTable { &mut self.table }
377/// }
378/// impl WasiHttpView for MyState {
379///     fn ctx(&mut self) -> &mut WasiHttpCtx { &mut self.http_ctx }
380/// }
381/// impl WasiView for MyState {
382///     fn ctx(&mut self) -> &mut WasiCtx { &mut self.ctx }
383/// }
384/// ```
385pub fn add_to_linker_sync<T>(l: &mut wasmtime::component::Linker<T>) -> anyhow::Result<()>
386where
387    T: WasiHttpView + wasmtime_wasi::WasiView,
388{
389    let io_closure = type_annotate_io::<T, _>(|t| wasmtime_wasi::IoImpl(t));
390    // For the sync linker, use the definitions of poll and streams from the
391    // wasmtime_wasi::bindings::sync space because those are defined using in_tokio.
392    wasmtime_wasi::bindings::sync::io::poll::add_to_linker_get_host(l, io_closure)?;
393    wasmtime_wasi::bindings::sync::io::streams::add_to_linker_get_host(l, io_closure)?;
394    // The error interface in the wasmtime_wasi is synchronous
395    wasmtime_wasi::bindings::io::error::add_to_linker_get_host(l, io_closure)?;
396
397    let closure = type_annotate_wasi::<T, _>(|t| wasmtime_wasi::WasiImpl(wasmtime_wasi::IoImpl(t)));
398
399    wasmtime_wasi::bindings::clocks::wall_clock::add_to_linker_get_host(l, closure)?;
400    wasmtime_wasi::bindings::clocks::monotonic_clock::add_to_linker_get_host(l, closure)?;
401    wasmtime_wasi::bindings::cli::stdin::add_to_linker_get_host(l, closure)?;
402    wasmtime_wasi::bindings::cli::stdout::add_to_linker_get_host(l, closure)?;
403    wasmtime_wasi::bindings::cli::stderr::add_to_linker_get_host(l, closure)?;
404    wasmtime_wasi::bindings::random::random::add_to_linker_get_host(l, closure)?;
405
406    add_only_http_to_linker_sync(l)?;
407
408    Ok(())
409}
410
411/// A slimmed down version of [`add_to_linker_sync`] which only adds
412/// `wasi:http` interfaces to the linker.
413///
414/// This is useful when using [`wasmtime_wasi::add_to_linker_sync`] for
415/// example to avoid re-adding the same interfaces twice.
416pub fn add_only_http_to_linker_sync<T>(l: &mut wasmtime::component::Linker<T>) -> anyhow::Result<()>
417where
418    T: WasiHttpView,
419{
420    let closure = type_annotate_http::<T, _>(|t| WasiHttpImpl(IoImpl(t)));
421
422    crate::bindings::http::outgoing_handler::add_to_linker_get_host(l, closure)?;
423    crate::bindings::http::types::add_to_linker_get_host(l, closure)?;
424
425    Ok(())
426}
wasmtime_wasi_http/lib.rs

wasmtime_wasi_http/
lib.rs
