// 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.
default interface types {
use io.streams.{input-stream, output-stream}
use 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,string>>) -> fields
fields-get: func(fields: fields, name: string) -> list<string>
fields-set: func(fields: fields, name: string, value: list<string>)
fields-delete: func(fields: fields, name: string)
fields-append: func(fields: fields, name: string, value: string)
fields-entries: func(fields: fields) -> list<tuple<string,string>>
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.
type incoming-stream = input-stream
type outgoing-stream = output-stream
finish-incoming-stream: func(s: incoming-stream) -> option<trailers>
finish-outgoing-stream: func(s: outgoing-stream, trailers: option<trailers>)
// 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).
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: func(request: incoming-request) -> string
incoming-request-query: func(request: incoming-request) -> string
incoming-request-scheme: func(request: incoming-request) -> option<scheme>
incoming-request-authority: func(request: incoming-request) -> 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: string,
query: string,
scheme: option<scheme>,
authority: string,
headers: headers
) -> outgoing-request
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).
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
) -> outgoing-response
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
}