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