Fill in README.md, at Luke to list of champions

README.md

@@ -2,18 +2,83 @@
 
 A proposed [WebAssembly System Interface](https://github.com/WebAssembly/WASI) API.
 
-This proposal currently only contains the proposed Wit interfaces with light
-explanation in comments; more work is necessary to fully document the proposal.
-The Wit comments annotate where the proposed interface is expected to change in
-the short term (for Preview2) once resources and handles are re-added to Wit,
-and then after that (for Preview3) once native stream support is added to the
-Component Model and Wit.
-
-The `wit` directory currently validates and can generate bindings with:
+### Current Phase
+
+wasi-http is currently in [Phase 1](https://github.com/WebAssembly/WASI/blob/main/Proposals.md#phase-1---feature-proposal-cg).
+
+### Champions
+
+* Piotr Sikora
+* Jiaxiao Zhou
+* Dan Chiarlone
+* David Justice
+* Luke Wagner
+
+### Phase 4 Advancement Criteria
+
+TODO
+
+### 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
 ```
-or can be manipulated in other ways with:
+and can be validated and otherwise manipulated via:
 ```
 wasm-tools component wit wit/ ...
 ```
@@ -25,15 +90,8 @@ in the root directory, which fetches the live contents of the `main` branch of
 each proposal. As things stablize, `wit/deps.toml` will be updated to refer to
 versioned releases.
 
-### Current Phase
-
-wasi-http is currently in [Phase 1](https://github.com/WebAssembly/WASI/blob/main/Proposals.md).
-
-### Champions
-
-Piotr Sikora, Jiaxiao Zhou, Dan Chiarlone, David Justice
+### References & acknowledgements
 
-### TODO
+* This proposal was seeded by and developed in consultation with
+  [proxy-wasm](https://github.com/proxy-wasm/spec).
 
-This readme needs to be expanded to cover a number of additional fields suggested in the
-[WASI Proposal template](https://github.com/WebAssembly/wasi-proposal-template).

wit/incoming-handler.wit → wit/handler.wit

@@ -24,3 +24,22 @@ interface incoming-handler {
     response-out: response-outparam
   )
 }
+
+// The `wasi:http/outgoing-handler` interface is meant to be imported by
+// components and implemented by the host.
+//
+//   NOTE: in Preview3, this interface will be merged with
+//   `wasi:http/outgoing-handler` into a single `wasi:http/handler` interface
+//   that takes a `request` parameter and returns a `response` result.
+//
+interface outgoing-handler {
+  use types.{outgoing-request, request-options, future-incoming-response}
+
+  // The parameter and result types of the `handle` function allow the caller
+  // to concurrently stream the bodies of the outgoing request and the incoming
+  // response.
+  handle: func(
+    request: outgoing-request,
+    options: option<request-options>
+  ) -> future-incoming-response
+}