types.wit

// The `wasi:http/types` interface is meant to be imported by components to
// define the HTTP resource types and operations used by the component's
// imported and exported interfaces.
interface types {
  use wasi:io/streams.{input-stream, output-stream}
  use wasi:poll/poll.{pollable}
  
  // This type corresponds to HTTP standard Methods.
  variant method {
    get,
    head,
    post,
    put,
    delete,
    connect,
    options,
    trace,
    patch,
    other(string)
  }

  // This type corresponds to HTTP standard Related Schemes.
  variant scheme {
    HTTP,
    HTTPS,
    other(string)
  }

  // TODO: perhaps better align with HTTP semantics?
  // This type enumerates the different kinds of errors that may occur when
  // initially returning a response.
  variant error {
      invalid-url(string),
      timeout-error(string),
      protocol-error(string),
      unexpected-error(string)
  }

  // This following block defines the `fields` resource which corresponds to
  // HTTP standard Fields. Soon, when resource types are added, the `type
  // fields = u32` type alias can be replaced by a proper `resource fields`
  // definition containing all the functions using the method syntactic sugar.
  type fields = u32
  drop-fields: func(fields: fields)
  new-fields: func(entries: list<tuple<string,list<u8>>>) -> fields
  fields-get: func(fields: fields, name: string) -> list<list<u8>>
  fields-set: func(fields: fields, name: string, value: list<list<u8>>)
  fields-delete: func(fields: fields, name: string)
  fields-append: func(fields: fields, name: string, value: list<u8>)
  fields-entries: func(fields: fields) -> list<tuple<string,list<u8>>>
  fields-clone: func(fields: fields) -> fields

  type headers = fields
  type trailers = fields

  // The following block defines stream types which corresponds to the HTTP
  // standard Contents and Trailers. With Preview3, all of these fields can be
  // replaced by a stream<u8, option<trailers>>. In the interim, we need to
  // build on separate resource types defined by `wasi:io/streams`. The
  // `finish-` functions emulate the stream's result value and MUST be called
  // exactly once after the final read/write from/to the stream before dropping
  // the stream. The optional `future-` types describe the asynchronous result of
  // reading/writing the optional HTTP trailers and MUST be waited on and dropped
  // to complete streaming the request/response.
  type incoming-stream = input-stream
  type outgoing-stream = output-stream
  finish-incoming-stream: func(s: incoming-stream) -> option<future-trailers>
  finish-outgoing-stream: func(s: outgoing-stream)
  finish-outgoing-stream-with-trailers: func(s: outgoing-stream, trailers: trailers) -> future-write-trailers-result

  // The following block defines the `future-trailers` resource, which is
  // returned when finishing an `incoming-stream` to asychronously produce the
  // final trailers.
  type future-trailers = u32
  drop-future-trailers: func(f: future-trailers)
  future-trailers-get: func(f: future-trailers) -> option<result<trailers, error>>
  listen-to-future-trailers: func(f: future-trailers) -> pollable

  // The following block defines the `future-write-trailers-result` resource,
  // which is returned when finishing an `outgoing-stream` and asychronously
  // indicates the success or failure of writing the trailers.
  type future-write-trailers-result = u32
  drop-future-write-trailers-result: func(f: future-write-trailers-result)
  future-write-trailers-result-get: func(f: future-write-trailers-result) -> option<result<_, error>>
  listen-to-future-write-trailers-result: func(f: future-write-trailers-result) -> pollable

  // The following block defines the `incoming-request` and `outgoing-request`
  // resource types that correspond to HTTP standard Requests. Soon, when
  // resource types are added, the `u32` type aliases can be replaced by proper
  // `resource` type definitions containing all the functions as methods.
  // Later, Preview2 will allow both types to be merged together into a single
  // `request` type (that uses the single `stream` type mentioned above). The
  // `consume` and `write` methods may only be called once (and return failure
  // thereafter). The `headers` and `trailers` passed into and out of requests
  // are shared with the request, with all mutations visible to all uses.
  // Components MUST avoid updating `headers` and `trailers` after passing a
  // request that points to them to the outside world.
  type incoming-request = u32
  type outgoing-request = u32
  drop-incoming-request: func(request: incoming-request)
  drop-outgoing-request: func(request: outgoing-request)
  incoming-request-method: func(request: incoming-request) -> method
  incoming-request-path-with-query: func(request: incoming-request) -> option<string>
  incoming-request-scheme: func(request: incoming-request) -> option<scheme>
  incoming-request-authority: func(request: incoming-request) -> option<string>
  incoming-request-headers: func(request: incoming-request) -> headers
  incoming-request-consume: func(request: incoming-request) -> result<incoming-stream>
  new-outgoing-request: func(
    method: method,
    path-with-query: option<string>,
    scheme: option<scheme>,
    authority: option<string>,
    headers: headers
  ) -> result<outgoing-request, error>
  outgoing-request-write: func(request: outgoing-request) -> result<outgoing-stream>

  // Additional optional parameters that can be set when making a request.
  record request-options {
    // The following timeouts are specific to the HTTP protocol and work
    // independently of the overall timeouts passed to `io.poll.poll-oneoff`.

    // The timeout for the initial connect.
    connect-timeout-ms: option<u32>,

    // The timeout for receiving the first byte of the response body.
    first-byte-timeout-ms: option<u32>,

    // The timeout for receiving the next chunk of bytes in the response body
    // stream.
    between-bytes-timeout-ms: option<u32>
  }

  // The following block defines a special resource type used by the
  // `wasi:http/incoming-handler` interface. When resource types are added, this
  // block can be replaced by a proper `resource response-outparam { ... }`
  // definition. Later, with Preview3, the need for an outparam goes away entirely
  // (the `wasi:http/handler` interface used for both incoming and outgoing can
  // simply return a `stream`).
  type response-outparam = u32
  drop-response-outparam: func(response: response-outparam)
  set-response-outparam: func(param: response-outparam, response: result<outgoing-response, error>) -> result

  // This type corresponds to the HTTP standard Status Code.
  type status-code = u16

  // The following block defines the `incoming-response` and `outgoing-response`
  // resource types that correspond to HTTP standard Responses. Soon, when
  // resource types are added, the `u32` type aliases can be replaced by proper
  // `resource` type definitions containing all the functions as methods. Later,
  // Preview2 will allow both types to be merged together into a single `response`
  // type (that uses the single `stream` type mentioned above). The `consume` and
  // `write` methods may only be called once (and return failure thereafter).
  // The `headers` and `trailers` passed into and out of responses are shared
  // with the response, with all mutations visible to all uses. Components MUST
  // avoid updating `headers` and `trailers` after passing a response that
  // points to them to the outside world.
  type incoming-response = u32
  type outgoing-response = u32
  drop-incoming-response: func(response: incoming-response)
  drop-outgoing-response: func(response: outgoing-response)
  incoming-response-status: func(response: incoming-response) -> status-code
  incoming-response-headers: func(response: incoming-response) -> headers
  incoming-response-consume: func(response: incoming-response) -> result<incoming-stream>
  new-outgoing-response: func(
    status-code: status-code,
    headers: headers
  ) -> result<outgoing-response, error>
  outgoing-response-write: func(response: outgoing-response) -> result<outgoing-stream>

  // The following block defines a special resource type used by the
  // `wasi:http/outgoing-handler` interface to emulate
  // `future<result<response, error>>` in advance of Preview3. Given a
  // `future-incoming-response`, the client can call the non-blocking `get`
  // method to get the result if it is available. If the result is not available,
  // the client can call `listen` to get a `pollable` that can be passed to
  // `io.poll.poll-oneoff`.
  type future-incoming-response = u32
  drop-future-incoming-response: func(f: future-incoming-response)
  future-incoming-response-get: func(f: future-incoming-response) -> option<result<incoming-response, error>>
  listen-to-future-incoming-response: func(f: future-incoming-response) -> pollable
}