https://github.com/WebAssembly/wasi-http
https://github.com/WebAssembly/wasi-http
proposal wasi
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/WebAssembly/wasi-http
- Owner: WebAssembly
- License: other
- Created: 2021-07-29T23:17:17.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2025-06-10T19:44:07.000Z (4 months ago)
- Last Synced: 2025-06-10T20:41:00.005Z (4 months ago)
- Topics: proposal, wasi
- Size: 379 KB
- Stars: 189
- Watchers: 35
- Forks: 30
- Open Issues: 37
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# WASI HTTP
A proposed [WebAssembly System Interface](https://github.com/WebAssembly/WASI) API.
### Current Phase
wasi-http is currently in [Phase 3](https://github.com/WebAssembly/WASI/blob/main/Proposals.md#phase-3---implementation-phase-cg--wg)
### Champions
* Piotr Sikora
* Jiaxiao Zhou
* Dan Chiarlone
* David Justice
* Luke Wagner
### Portability Criteria
WASI-http must have at least two complete independent implementations
demonstrating embeddability in a production HTTP server context.
### Introduction
The WASI-http proposal defines a collection of [interfaces] for sending and
receiving HTTP requests and responses. WASI-http additionally defines a
[world], `wasi:http/proxy`, that circumscribes a minimal execution environment
for wasm HTTP [proxies].
[Interfaces]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md#wit-interfaces
[World]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md#wit-worlds
[Proxies]: https://httpwg.org/http-core/draft-ietf-httpbis-semantics-latest.html#intermediaries
### Goals
The proposal intends to abstract over HTTP version and transport protocol
choices (such as HTTP/1.1, HTTP/2 or HTTP/3) by mapping directly to the
abstract [HTTP Semantics], allowing hosts to (mostly) transparently use any of
these.
The `wasi:http/proxy` world is meant to be implementable by a wide variety of
hosts including Web [service workers], forward- and reverse-[proxies] and
[origin servers] by requiring a minimal set of additional runtime support.
The `wasi:http/proxy` world is meant to support flexible auto-scaling
("serverless") execution by moving the core `accept()` loop into the host and
allowing the host to dynamically spin up wasm instances in response to arriving
requests.
The `wasi:http/proxy` world is meant to allow the chaining of HTTP
intermediaries to be implemented directly in terms of [Component Model] linking.
(Fully realizing this goal will require additional features only available in
the [Preview 3] timeframe.)
[HTTP Semantics]: https://httpwg.org/http-core/draft-ietf-httpbis-semantics-latest.html
[Service Workers]: https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API
[Origin Servers]: https://httpwg.org/http-core/draft-ietf-httpbis-semantics-latest.html#origin.server
[Component Model]: https://github.com/WebAssembly/component-model/
[Preview 3]: https://github.com/WebAssembly/WASI/blob/main/docs/WitInWasi.md#streams
### Non-goals
WASI-http does not intend to define a more fully-featured cloud execution
environment (for this, see the [wasi-cloud-core] proposal).
[wasi-cloud-core]: https://github.com/WebAssembly/wasi-cloud-core
### API walk-through
The proposal can be understood by first reading the comments of [`proxy.wit`],
then [`handler.wit`] and finally [`types.wit`].
[`proxy.wit`]: ./wit/proxy.wit
[`handler.wit`]: ./wit/handler.wit
[`types.wit`]: ./wit/types.wit
### Working with the WIT
Bindings can be generated from the `wit` directory via:
```
wit-bindgen c wit/ --world proxy
```
and can be validated and otherwise manipulated via:
```
wasm-tools component wit wit/ ...
```
The `wit/deps` directory contains a live snapshot of the contents of several
other WASI proposals upon which this proposal depends. It is automatically
updated by running [`wit-deps update`](https://crates.io/crates/wit-deps-cli)
in the root directory, which fetches the live contents of the `main` branch of
each proposal. As things stabilize, `wit/deps.toml` will be updated to refer to
versioned releases.
### References & acknowledgements
* This proposal was seeded by and developed in consultation with
[proxy-wasm](https://github.com/proxy-wasm/spec).