add Wit interfaces

README.md

@@ -1,3 +1,38 @@
 # WASI HTTP
 
-(This is a placeholder so there can be a PR to fill in the contents.)
+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 Preview2) once native stream support is added to the
+Component Model and Wit.
+
+The `wit` directory currently validates and can generate bindings with:
+```
+wit-bindgen c wit/ --world proxy
+```
+or can be manipulated in other ways with:
+```
+wasm-tools component wit wit/ ...
+```
+
+The HTTP proposal depends on the WASI IO and Logging proposals. For simplicity,
+the Wit files for these proposals are currently copied into the `wit/deps`
+directory and will be updated periodically to match their respective proposals.
+As the Wit tooling develops, we should be able to avoid this form of manual
+vendoring.
+
+### 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
+
+### TODO
+
+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/deps/io/streams.wit

@@ -0,0 +1,128 @@
+default interface streams {
+    /// An error type returned from a stream operation. Currently this
+    /// doesn't provide any additional information.
+    record stream-error {}
+
+    /// An input bytestream. In the future, this will be replaced by handle
+    /// types.
+    /// 
+    /// This conceptually represents a `stream<u8, _>`. It's temporary 
+    /// scaffolding until component-model's async features are ready. 
+    /// 
+    /// And at present, it is a `u32` instead of being an actual handle, until 
+    /// the wit-bindgen implementation of handles and resources is ready. 
+    type input-stream = u32
+
+    /// Read bytes from a stream.
+    ///
+    /// This function returns a list of bytes containing the data that was
+    /// read, along with a bool indicating whether the end of the stream
+    /// was reached. The returned list will contain up to `len` bytes; it
+    /// may return fewer than requested, but not more.
+    ///
+    /// Once a stream has reached the end, subsequent calls to read or
+    /// `skip` will always report end-of-stream rather than producing more
+    /// data.
+    ///
+    /// If `len` is 0, it represents a request to read 0 bytes, which should
+    /// always succeed, assuming the stream hasn't reached its end yet, and
+    /// return an empty list.
+    ///
+    /// The len here is a `u64`, but some callees may not be able to allocate
+    /// a buffer as large as that would imply.
+    /// FIXME: describe what happens if allocation fails.
+    read: func(
+        /// The stream to read from
+        src: input-stream,
+        /// The maximum number of bytes to read
+        len: u64
+    ) -> result<tuple<list<u8>, bool>, stream-error>
+
+    /// Skip bytes from a stream.
+    ///
+    /// This is similar to the `read` function, but avoids copying the
+    /// bytes into the instance.
+    ///
+    /// Once a stream has reached the end, subsequent calls to read or
+    /// `skip` will always report end-of-stream rather than producing more
+    /// data.
+    ///
+    /// This function returns the number of bytes skipped, along with a bool
+    /// indicating whether the end of the stream was reached. The returned
+    /// value will be at most `len`; it may be less.
+    skip: func(
+        /// The stream to skip in
+        src: input-stream,
+        /// The maximum number of bytes to skip.
+        len: u64,
+    ) -> result<tuple<u64, bool>, stream-error>
+
+    /// An output bytestream. In the future, this will be replaced by handle
+    /// types.
+    /// 
+    /// This conceptually represents a `stream<u8, _>`. It's temporary 
+    /// scaffolding until component-model's async features are ready. 
+    /// 
+    /// And at present, it is a `u32` instead of being an actual handle, until 
+    /// the wit-bindgen implementation of handles and resources is ready. 
+    type output-stream = u32
+
+    /// Write bytes to a stream.
+    ///
+    /// This function returns a `u64` indicating the number of bytes from
+    /// `buf` that were written; it may be less than the full list.
+    write: func(
+        /// The stream to write to
+        dst: output-stream,
+        /// Data to write
+        buf: list<u8>
+    ) -> result<u64, stream-error>
+
+    /// Write a single byte multiple times to a stream.
+    ///
+    /// This function returns a `u64` indicating the number of copies of
+    /// `byte` that were written; it may be less than `len`.
+    write-repeated: func(
+        /// The stream to write to
+        dst: output-stream,
+        /// The byte to write
+        byte: u8,
+        /// The number of times to write it
+        len: u64
+    ) -> result<u64, stream-error>
+
+    /// Read from one stream and write to another.
+    ///
+    /// This function returns the number of bytes transferred; it may be less
+    /// than `len`.
+    splice: func(
+        /// The stream to write to
+        dst: output-stream,
+        /// The stream to read from
+        src: input-stream,
+        /// The number of bytes to splice
+        len: u64,
+    ) -> result<tuple<u64, bool>, stream-error>
+
+    /// Forward the entire contents of an input stream to an output stream.
+    ///
+    /// This function repeatedly reads from the input stream and writes
+    /// the data to the output stream, until the end of the input stream
+    /// is reached, or an error is encountered.
+    ///
+    /// This function returns the number of bytes transferred.
+    forward: func(
+        /// The stream to write to
+        dst: output-stream,
+        /// The stream to read from
+        src: input-stream
+    ) -> result<u64, stream-error>
+
+    /// Dispose of the specified input-stream, after which it may no longer
+    /// be used.
+    drop-input-stream: func(f: input-stream)
+
+    /// Dispose of the specified output-stream, after which it may no longer
+    /// be used.
+    drop-output-stream: func(f: output-stream)
+}

wit/deps/logging/handler.wit

@@ -0,0 +1,31 @@
+/// # WASI Logging API
+///
+/// WASI Logging is a logging API intended to let users emit log messages with
+/// simple priority levels and context values.
+default interface handler {
+  /// A log level, describing a kind of message.
+  enum level {
+     /// Describes messages about the values of variables and the flow of control
+     /// within a program.
+     trace,
+
+     /// Describes messages likely to be of interest to someone debugging a program.
+     debug,
+
+     /// Describes messages likely to be of interest to someone monitoring a program.
+     info,
+
+     /// Describes messages indicating hazardous situations.
+     warn,
+
+     /// Describes messages indicating serious errors.
+     error,
+  }
+
+  /// Emit a log message.
+  ///
+  /// A log message has a `level` describing what kind of message is being sent,
+  /// a context, which is an uninterpreted string meant to help consumers group
+  /// similar messages, and a string containing the message text.
+  log: func(level: level, context: string, message: string)
+}

wit/incoming-handler.wit

@@ -0,0 +1,21 @@
+// The `wasi:http/incoming-handler` interface is meant to be exported by
+// components and called by the host in response to a new incoming HTTP
+// response.
+//
+//   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.
+//
+default interface incoming-handler {
+  use pkg.types.{incoming-request, response-outparam}
+
+  // The `handle` function takes an outparam instead of returning its response
+  // so that the component may stream its response while streaming any other
+  // request or response bodies. The callee MUST write a response to the
+  // `response-out` and then finish the response before returning. The `handle`
+  // function is allowed to continue execution after finishing the response's
+  // output stream. While this post-response execution is taken off the
+  // critical path, since there is no return value, there is no way to report
+  // its success or failure.
+  handle: func(request: incoming-request, response-out: response-outparam)
+}

wit/outgoing-handler.wit

@@ -0,0 +1,15 @@
+// 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.
+//
+default interface outgoing-handler {
+  use pkg.types.{outgoing-request, incoming-response, error}
+
+  // 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) -> result<incoming-response, error>
+}

wit/proxy.wit

@@ -0,0 +1,32 @@
+// The `wasi:http/proxy` world captures a widely-implementable intersection of
+// hosts that includes HTTP forward and reverse proxies. Components targeting
+// this world may concurrently stream in and out any number of incoming and
+// outgoing HTTP requests.
+default world proxy {
+
+  // This is the default logging handler to use when user code simply wants to
+  // log to a developer-facing console (e.g., via `console.log()`).
+  import console: logging.handler
+
+  // TODO: add `import metrics: metrics.counters`
+
+  // This is the default handler to use when user code simply wants to make an
+  // HTTP request (e.g., via `fetch()`) but doesn't otherwise specify a
+  // particular handler.
+  import default-upstream-HTTP: pkg.outgoing-handler
+
+  // TODO: Once the underlying Wit template machinery is implemented, add:
+  //
+  //  import upstreams: interface {
+  //    *: pkg.outgoing-handler
+  //  }
+  //
+  // which will allow a component to import any number of non-default backends
+  // that HTTP requests can be dispatched to.
+
+  // The host delivers incoming HTTP requests to a component by calling the
+  // `handle` function of this exported interface. A host may arbitrarily reuse
+  // or not reuse component instance when delivering incoming HTTP requests and
+  // thus a component must be able to handle 0..N calls to `handle`.
+  export HTTP: pkg.incoming-handler
+}