componentized

This interface defines all of the types and methods for implementing HTTP Requests and Responses, both incoming and outgoing, as well as their headers, trailers, and bodies.

Types

use type duration

from wasi:clocks/monotonic-clock@0.2.0

A duration of time, in nanoseconds.

  • u64

use resource input-stream

from wasi:io/streams@0.2.0

An input bytestream.

input-streams are non-blocking to the extent practical on underlying platforms. I/O operations always return promptly; if fewer bytes are promptly available than requested, they return the number of bytes promptly available, which could even be zero. To wait for data to be available, use the subscribe function to obtain a pollable which can be polled for using wasi:io/poll.

  • functionread: func(len: u64) -> result<list<u8>, stream-error>

    Perform a non-blocking read from the stream.

    When the source of a read is binary data, the bytes from the source are returned verbatim. When the source of a read is known to the implementation to be text, bytes containing the UTF-8 encoding of the text are returned.

    This function returns a list of bytes containing the read data, when successful. The returned list will contain up to len bytes; it may return fewer than requested, but not more. The list is empty when no bytes are available for reading at this time. The pollable given by subscribe will be ready when more bytes are available.

    This function fails with a stream-error when the operation encounters an error, giving last-operation-failed, or when the stream is closed, giving closed.

    When the caller gives a len of 0, it represents a request to read 0 bytes. If the stream is still open, this call should succeed and return an empty list, or otherwise fail with closed.

    The len parameter is a u64, which could represent a list of u8 which is not possible to allocate in wasm32, or not desirable to allocate as as a return value by the callee. The callee may return a list of bytes less than len in size while more bytes are available for reading.

  • functionblocking-read: func(len: u64) -> result<list<u8>, stream-error>

    Read bytes from a stream, after blocking until at least one byte can be read. Except for blocking, behavior is identical to read.

  • functionskip: func(len: u64) -> result<u64, stream-error>

    Skip bytes from a stream. Returns number of bytes skipped.

    Behaves identical to read, except instead of returning a list of bytes, returns the number of bytes consumed from the stream.

  • functionblocking-skip: func(len: u64) -> result<u64, stream-error>

    Skip bytes from a stream, after blocking until at least one byte can be skipped. Except for blocking behavior, identical to skip.

  • functionsubscribe: func() -> pollable

    Create a pollable which will resolve once either the specified stream has bytes available to read or the other end of the stream has been closed. The created pollable is a child resource of the input-stream. Implementations may trap if the input-stream is dropped before all derived pollables created with this function are dropped.

use resource output-stream

from wasi:io/streams@0.2.0

An output bytestream.

output-streams are non-blocking to the extent practical on underlying platforms. Except where specified otherwise, I/O operations also always return promptly, after the number of bytes that can be written promptly, which could even be zero. To wait for the stream to be ready to accept data, the subscribe function to obtain a pollable which can be polled for using wasi:io/poll.

  • functioncheck-write: func() -> result<u64, stream-error>

    Check readiness for writing. This function never blocks.

    Returns the number of bytes permitted for the next call to write, or an error. Calling write with more bytes than this function has permitted will trap.

    When this function returns 0 bytes, the subscribe pollable will become ready when this function will report at least 1 byte, or an error.

  • functionwrite: func(contents: list<u8>) -> result<_, stream-error>

    Perform a write. This function never blocks.

    When the destination of a write is binary data, the bytes from contents are written verbatim. When the destination of a write is known to the implementation to be text, the bytes of contents are transcoded from UTF-8 into the encoding of the destination and then written.

    Precondition: check-write gave permit of Ok(n) and contents has a length of less than or equal to n. Otherwise, this function will trap.

    returns Err(closed) without writing if the stream has closed since the last call to check-write provided a permit.

  • functionblocking-write-and-flush: func( contents: list<u8>, ) -> result<_, stream-error>

    Perform a write of up to 4096 bytes, and then flush the stream. Block until all of these operations are complete, or an error occurs.

    This is a convenience wrapper around the use of check-write, subscribe, write, and flush, and is implemented with the following pseudo-code:

    let pollable = this.subscribe();
    while !contents.is_empty() {
    // Wait for the stream to become writable
    pollable.block();
    let Ok(n) = this.check-write(); // eliding error handling
    let len = min(n, contents.len());
    let (chunk, rest) = contents.split_at(len);
    this.write(chunk  );            // eliding error handling
    contents = rest;
    }
    this.flush();
    // Wait for completion of `flush`
    pollable.block();
    // Check for any errors that arose during `flush`
    let _ = this.check-write();         // eliding error handling
    
  • functionflush: func() -> result<_, stream-error>

    Request to flush buffered output. This function never blocks.

    This tells the output-stream that the caller intends any buffered output to be flushed. the output which is expected to be flushed is all that has been passed to write prior to this call.

    Upon calling this function, the output-stream will not accept any writes (check-write will return ok(0)) until the flush has completed. The subscribe pollable will become ready when the flush has completed and the stream can accept more writes.

  • functionblocking-flush: func() -> result<_, stream-error>

    Request to flush buffered output, and block until flush completes and stream is ready for writing again.

  • functionsubscribe: func() -> pollable

    Create a pollable which will resolve once the output-stream is ready for more writing, or an error has occured. When this pollable is ready, check-write will return ok(n) with n>0, or an error.

    If the stream is closed, this pollable is always ready immediately.

    The created pollable is a child resource of the output-stream. Implementations may trap if the output-stream is dropped before all derived pollables created with this function are dropped.

  • functionwrite-zeroes: func(len: u64) -> result<_, stream-error>

    Write zeroes to a stream.

    This should be used precisely like write with the exact same preconditions (must use check-write first), but instead of passing a list of bytes, you simply pass the number of zero-bytes that should be written.

  • functionblocking-write-zeroes-and-flush: func( len: u64, ) -> result<_, stream-error>

    Perform a write of up to 4096 zeroes, and then flush the stream. Block until all of these operations are complete, or an error occurs.

    This is a convenience wrapper around the use of check-write, subscribe, write-zeroes, and flush, and is implemented with the following pseudo-code:

    let pollable = this.subscribe();
    while num_zeroes != 0 {
    // Wait for the stream to become writable
    pollable.block();
    let Ok(n) = this.check-write(); // eliding error handling
    let len = min(n, num_zeroes);
    this.write-zeroes(len);         // eliding error handling
    num_zeroes -= len;
    }
    this.flush();
    // Wait for completion of `flush`
    pollable.block();
    // Check for any errors that arose during `flush`
    let _ = this.check-write();         // eliding error handling
    
  • functionsplice: func( src: borrow<input-stream>, len: u64, ) -> result<u64, stream-error>

    Read from one stream and write to another.

    The behavior of splice is equivelant to:

    1. calling check-write on the output-stream
    2. calling read on the input-stream with the smaller of the check-write permitted length and the len provided to splice
    3. calling write on the output-stream with that read data.

    Any error reported by the call to check-write, read, or write ends the splice and reports that error.

    This function returns the number of bytes transferred; it may be less than len.

  • functionblocking-splice: func( src: borrow<input-stream>, len: u64, ) -> result<u64, stream-error>

    Read from one stream and write to another, with blocking.

    This is similar to splice, except that it blocks until the output-stream is ready for writing, and the input-stream is ready for reading, before performing the splice.

use resource io-error

from wasi:io/error@0.2.0

A resource which represents some error information.

The only method provided by this resource is to-debug-string, which provides some human-readable information about the error.

In the wasi:io package, this resource is returned through the wasi:io/streams/stream-error type.

To provide more specific error information, other interfaces may provide functions to further "downcast" this error into more specific error information. For example, errors returned in streams derived from filesystem types to be described using the filesystem's own error-code type, using the function wasi:filesystem/types/filesystem-error-code, which takes a parameter borrow<error> and returns option<wasi:filesystem/types/error-code>.

The set of functions which can "downcast" an error into a more concrete type is open.

  • functionto-debug-string: func() -> string

    Returns a string that is suitable to assist humans in debugging this error.

    WARNING: The returned string should not be consumed mechanically! It may change across platforms, hosts, or other implementation details. Parsing this string is a major platform-compatibility hazard.

use resource pollable

from wasi:io/poll@0.2.0

pollable represents a single I/O event which may be ready, or not.

  • functionready: func() -> bool

    Return the readiness of a pollable. This function never blocks.

    Returns true when the pollable is ready, and false otherwise.

  • functionblock: func()

    block returns immediately if the pollable is ready, and otherwise blocks until ready.

    This function is equivalent to calling poll.poll on a list containing only this pollable.

variant method

This type corresponds to HTTP standard Methods.

  • get
  • head
  • post
  • put
  • delete
  • connect
  • options
  • trace
  • patch
  • other: string

variant scheme

This type corresponds to HTTP standard Related Schemes.

  • HTTP
  • HTTPS
  • other: string

record DNS-error-payload

Defines the case payload type for DNS-error above:

  • rcode: option<string>
  • info-code: option<u16>

record TLS-alert-received-payload

Defines the case payload type for TLS-alert-received above:

  • alert-id: option<u8>
  • alert-message: option<string>

record field-size-payload

Defines the case payload type for HTTP-response-{header,trailer}-size above:

  • field-name: option<string>
  • field-size: option<u32>

variant error-code

These cases are inspired by the IANA HTTP Proxy Error Types: https://www.iana.org/assignments/http-proxy-status/http-proxy-status.xhtml#table-http-proxy-error-types

  • DNS-timeout
  • DNS-error: DNS-error-payload
  • destination-not-found
  • destination-unavailable
  • destination-IP-prohibited
  • destination-IP-unroutable
  • connection-refused
  • connection-terminated
  • connection-timeout
  • connection-read-timeout
  • connection-write-timeout
  • connection-limit-reached
  • TLS-protocol-error
  • TLS-certificate-error
  • TLS-alert-received: TLS-alert-received-payload
  • HTTP-request-denied
  • HTTP-request-length-required
  • HTTP-request-body-size: option<u64>
  • HTTP-request-method-invalid
  • HTTP-request-URI-invalid
  • HTTP-request-URI-too-long
  • HTTP-request-header-section-size: option<u32>
  • HTTP-request-header-size: option<field-size-payload>
  • HTTP-request-trailer-section-size: option<u32>
  • HTTP-request-trailer-size: field-size-payload
  • HTTP-response-incomplete
  • HTTP-response-header-section-size: option<u32>
  • HTTP-response-header-size: field-size-payload
  • HTTP-response-body-size: option<u64>
  • HTTP-response-trailer-section-size: option<u32>
  • HTTP-response-trailer-size: field-size-payload
  • HTTP-response-transfer-coding: option<string>
  • HTTP-response-content-coding: option<string>
  • HTTP-response-timeout
  • HTTP-upgrade-failed
  • HTTP-protocol-error
  • loop-detected
  • configuration-error
  • internal-error: option<string>

    This is a catch-all error for anything that doesn't fit cleanly into a more specific case. It also includes an optional string for an unstructured description of the error. Users should not depend on the string for diagnosing errors, as it's not required to be consistent between implementations.

variant header-error

This type enumerates the different kinds of errors that may occur when setting or appending to a fields resource.

  • invalid-syntax

    This error indicates that a field-key or field-value was syntactically invalid when used with an operation that sets headers in a fields.

  • forbidden

    This error indicates that a forbidden field-key was used when trying to set a header in a fields.

  • immutable

    This error indicates that the operation on the fields was not permitted because the fields are immutable.

type field-key

Field keys are always strings.

  • string

type field-value

Field values should always be ASCII strings. However, in reality, HTTP implementations often have to interpret malformed values, so they are provided as a list of bytes.

  • list<u8>

resource fields

This following block defines the fields resource which corresponds to HTTP standard Fields. Fields are a common representation used for both Headers and Trailers.

A fields may be mutable or immutable. A fields created using the constructor, from-list, or clone will be mutable, but a fields resource given by other means (including, but not limited to, incoming-request.headers, outgoing-request.headers) might be be immutable. In an immutable fields, the set, append, and delete operations will fail with header-error.immutable.

  • constructor functionconstructor()

    Construct an empty HTTP Fields.

    The resulting fields is mutable.

  • static functionfrom-list: static func( entries: list<tuple<field-key, field-value>>, ) -> result<fields, header-error>

    Construct an HTTP Fields.

    The resulting fields is mutable.

    The list represents each key-value pair in the Fields. Keys which have multiple values are represented by multiple entries in this list with the same key.

    The tuple is a pair of the field key, represented as a string, and Value, represented as a list of bytes. In a valid Fields, all keys and values are valid UTF-8 strings. However, values are not always well-formed, so they are represented as a raw list of bytes.

    An error result will be returned if any header or value was syntactically invalid, or if a header was forbidden.

  • functionget: func(name: field-key) -> list<field-value>

    Get all of the values corresponding to a key. If the key is not present in this fields, an empty list is returned. However, if the key is present but empty, this is represented by a list with one or more empty field-values present.

  • functionhas: func(name: field-key) -> bool

    Returns true when the key is present in this fields. If the key is syntactically invalid, false is returned.

  • functionset: func( name: field-key, value: list<field-value>, ) -> result<_, header-error>

    Set all of the values for a key. Clears any existing values for that key, if they have been set.

    Fails with header-error.immutable if the fields are immutable.

  • functiondelete: func(name: field-key) -> result<_, header-error>

    Delete all values for a key. Does nothing if no values for the key exist.

    Fails with header-error.immutable if the fields are immutable.

  • functionappend: func( name: field-key, value: field-value, ) -> result<_, header-error>

    Append a value for a key. Does not change or delete any existing values for that key.

    Fails with header-error.immutable if the fields are immutable.

  • functionentries: func() -> list<tuple<field-key, field-value>>

    Retrieve the full set of keys and values in the Fields. Like the constructor, the list represents each key-value pair.

    The outer list represents each key-value pair in the Fields. Keys which have multiple values are represented by multiple entries in this list with the same key.

  • functionclone: func() -> fields

    Make a deep copy of the Fields. Equivelant in behavior to calling the fields constructor on the return value of entries. The resulting fields is mutable.

type headers

Headers is an alias for Fields.

type trailers

Trailers is an alias for Fields.

resource incoming-request

Represents an incoming HTTP Request.

  • functionmethod: func() -> method

    Returns the method of the incoming request.

  • functionpath-with-query: func() -> option<string>

    Returns the path with query parameters from the request, as a string.

  • functionscheme: func() -> option<scheme>

    Returns the protocol scheme from the request.

  • functionauthority: func() -> option<string>

    Returns the authority from the request, if it was present.

  • functionheaders: func() -> headers

    Get the headers associated with the request.

    The returned headers resource is immutable: set, append, and delete operations will fail with header-error.immutable.

    The headers returned are a child resource: it must be dropped before the parent incoming-request is dropped. Dropping this incoming-request before all children are dropped will trap.

  • functionconsume: func() -> result<incoming-body>

    Gives the incoming-body associated with this request. Will only return success at most once, and subsequent calls will return error.

resource outgoing-request

Represents an outgoing HTTP Request.

  • constructor functionconstructor(headers: headers)

    Construct a new outgoing-request with a default method of GET, and none values for path-with-query, scheme, and authority.

    • headers is the HTTP Headers for the Request.

    It is possible to construct, or manipulate with the accessor functions below, an outgoing-request with an invalid combination of scheme and authority, or headers which are not permitted to be sent. It is the obligation of the outgoing-handler.handle implementation to reject invalid constructions of outgoing-request.

  • functionbody: func() -> result<outgoing-body>

    Returns the resource corresponding to the outgoing Body for this Request.

    Returns success on the first call: the outgoing-body resource for this outgoing-request can be retrieved at most once. Subsequent calls will return error.

  • functionmethod: func() -> method

    Get the Method for the Request.

  • functionset-method: func(method: method) -> result

    Set the Method for the Request. Fails if the string present in a method.other argument is not a syntactically valid method.

  • functionpath-with-query: func() -> option<string>

    Get the combination of the HTTP Path and Query for the Request. When none, this represents an empty Path and empty Query.

  • functionset-path-with-query: func(path-with-query: option<string>) -> result

    Set the combination of the HTTP Path and Query for the Request. When none, this represents an empty Path and empty Query. Fails is the string given is not a syntactically valid path and query uri component.

  • functionscheme: func() -> option<scheme>

    Get the HTTP Related Scheme for the Request. When none, the implementation may choose an appropriate default scheme.

  • functionset-scheme: func(scheme: option<scheme>) -> result

    Set the HTTP Related Scheme for the Request. When none, the implementation may choose an appropriate default scheme. Fails if the string given is not a syntactically valid uri scheme.

  • functionauthority: func() -> option<string>

    Get the HTTP Authority for the Request. A value of none may be used with Related Schemes which do not require an Authority. The HTTP and HTTPS schemes always require an authority.

  • functionset-authority: func(authority: option<string>) -> result

    Set the HTTP Authority for the Request. A value of none may be used with Related Schemes which do not require an Authority. The HTTP and HTTPS schemes always require an authority. Fails if the string given is not a syntactically valid uri authority.

  • functionheaders: func() -> headers

    Get the headers associated with the Request.

    The returned headers resource is immutable: set, append, and delete operations will fail with header-error.immutable.

    This headers resource is a child: it must be dropped before the parent outgoing-request is dropped, or its ownership is transfered to another component by e.g. outgoing-handler.handle.

resource request-options

Parameters for making an HTTP Request. Each of these parameters is currently an optional timeout applicable to the transport layer of the HTTP protocol.

These timeouts are separate from any the user may use to bound a blocking call to wasi:io/poll.poll.

  • constructor functionconstructor()

    Construct a default request-options value.

  • functionconnect-timeout: func() -> option<duration>

    The timeout for the initial connect to the HTTP Server.

  • functionset-connect-timeout: func(duration: option<duration>) -> result

    Set the timeout for the initial connect to the HTTP Server. An error return value indicates that this timeout is not supported.

  • functionfirst-byte-timeout: func() -> option<duration>

    The timeout for receiving the first byte of the Response body.

  • functionset-first-byte-timeout: func(duration: option<duration>) -> result

    Set the timeout for receiving the first byte of the Response body. An error return value indicates that this timeout is not supported.

  • functionbetween-bytes-timeout: func() -> option<duration>

    The timeout for receiving subsequent chunks of bytes in the Response body stream.

  • functionset-between-bytes-timeout: func(duration: option<duration>) -> result

    Set the timeout for receiving subsequent chunks of bytes in the Response body stream. An error return value indicates that this timeout is not supported.

resource response-outparam

Represents the ability to send an HTTP Response.

This resource is used by the wasi:http/incoming-handler interface to allow a Response to be sent corresponding to the Request provided as the other argument to incoming-handler.handle.

  • static functionset: static func( param: response-outparam, response: result<outgoing-response, error-code>, )

    Set the value of the response-outparam to either send a response, or indicate an error.

    This method consumes the response-outparam to ensure that it is called at most once. If it is never called, the implementation will respond with an error.

    The user may provide an error to response to allow the implementation determine how to respond with an HTTP error response.

type status-code

This type corresponds to the HTTP standard Status Code.

  • u16

resource incoming-response

Represents an incoming HTTP Response.

  • functionstatus: func() -> status-code

    Returns the status code from the incoming response.

  • functionheaders: func() -> headers

    Returns the headers from the incoming response.

    The returned headers resource is immutable: set, append, and delete operations will fail with header-error.immutable.

    This headers resource is a child: it must be dropped before the parent incoming-response is dropped.

  • functionconsume: func() -> result<incoming-body>

    Returns the incoming body. May be called at most once. Returns error if called additional times.

resource incoming-body

Represents an incoming HTTP Request or Response's Body.

A body has both its contents - a stream of bytes - and a (possibly empty) set of trailers, indicating that the full contents of the body have been received. This resource represents the contents as an input-stream and the delivery of trailers as a future-trailers, and ensures that the user of this interface may only be consuming either the body contents or waiting on trailers at any given time.

  • functionstream: func() -> result<input-stream>

    Returns the contents of the body, as a stream of bytes.

    Returns success on first call: the stream representing the contents can be retrieved at most once. Subsequent calls will return error.

    The returned input-stream resource is a child: it must be dropped before the parent incoming-body is dropped, or consumed by incoming-body.finish.

    This invariant ensures that the implementation can determine whether the user is consuming the contents of the body, waiting on the future-trailers to be ready, or neither. This allows for network backpressure is to be applied when the user is consuming the body, and for that backpressure to not inhibit delivery of the trailers if the user does not read the entire body.

  • static functionfinish: static func(this: incoming-body) -> future-trailers

    Takes ownership of incoming-body, and returns a future-trailers. This function will trap if the input-stream child is still alive.

resource future-trailers

Represents a future which may eventaully return trailers, or an error.

In the case that the incoming HTTP Request or Response did not have any trailers, this future will resolve to the empty set of trailers once the complete Request or Response body has been received.

  • functionsubscribe: func() -> pollable

    Returns a pollable which becomes ready when either the trailers have been received, or an error has occured. When this pollable is ready, the get method will return some.

  • functionget: func() -> option<result<result<option<trailers>, error-code>>>

    Returns the contents of the trailers, or an error which occured, once the future is ready.

    The outer option represents future readiness. Users can wait on this option to become some using the subscribe method.

    The outer result is used to retrieve the trailers or error at most once. It will be success on the first call in which the outer option is some, and error on subsequent calls.

    The inner result represents that either the HTTP Request or Response body, as well as any trailers, were received successfully, or that an error occured receiving them. The optional trailers indicates whether or not trailers were present in the body.

    When some trailers are returned by this method, the trailers resource is immutable, and a child. Use of the set, append, or delete methods will return an error, and the resource must be dropped before the parent future-trailers is dropped.

resource outgoing-response

Represents an outgoing HTTP Response.

  • constructor functionconstructor(headers: headers)

    Construct an outgoing-response, with a default status-code of 200. If a different status-code is needed, it must be set via the set-status-code method.

    • headers is the HTTP Headers for the Response.
  • functionstatus-code: func() -> status-code

    Get the HTTP Status Code for the Response.

  • functionset-status-code: func(status-code: status-code) -> result

    Set the HTTP Status Code for the Response. Fails if the status-code given is not a valid http status code.

  • functionheaders: func() -> headers

    Get the headers associated with the Request.

    The returned headers resource is immutable: set, append, and delete operations will fail with header-error.immutable.

    This headers resource is a child: it must be dropped before the parent outgoing-request is dropped, or its ownership is transfered to another component by e.g. outgoing-handler.handle.

  • functionbody: func() -> result<outgoing-body>

    Returns the resource corresponding to the outgoing Body for this Response.

    Returns success on the first call: the outgoing-body resource for this outgoing-response can be retrieved at most once. Subsequent calls will return error.

resource outgoing-body

Represents an outgoing HTTP Request or Response's Body.

A body has both its contents - a stream of bytes - and a (possibly empty) set of trailers, inducating the full contents of the body have been sent. This resource represents the contents as an output-stream child resource, and the completion of the body (with optional trailers) with a static function that consumes the outgoing-body resource, and ensures that the user of this interface may not write to the body contents after the body has been finished.

If the user code drops this resource, as opposed to calling the static method finish, the implementation should treat the body as incomplete, and that an error has occured. The implementation should propogate this error to the HTTP protocol by whatever means it has available, including: corrupting the body on the wire, aborting the associated Request, or sending a late status code for the Response.

  • functionwrite: func() -> result<output-stream>

    Returns a stream for writing the body contents.

    The returned output-stream is a child resource: it must be dropped before the parent outgoing-body resource is dropped (or finished), otherwise the outgoing-body drop or finish will trap.

    Returns success on the first call: the output-stream resource for this outgoing-body may be retrieved at most once. Subsequent calls will return error.

  • static functionfinish: static func( this: outgoing-body, trailers: option<trailers>, ) -> result<_, error-code>

    Finalize an outgoing body, optionally providing trailers. This must be called to signal that the response is complete. If the outgoing-body is dropped without calling outgoing-body.finalize, the implementation should treat the body as corrupted.

    Fails if the body's outgoing-request or outgoing-response was constructed with a Content-Length header, and the contents written to the body (via write) does not match the value given in the Content-Length.

resource future-incoming-response

Represents a future which may eventaully return an incoming HTTP Response, or an error.

This resource is returned by the wasi:http/outgoing-handler interface to provide the HTTP Response corresponding to the sent Request.

  • functionsubscribe: func() -> pollable

    Returns a pollable which becomes ready when either the Response has been received, or an error has occured. When this pollable is ready, the get method will return some.

  • functionget: func() -> option<result<result<incoming-response, error-code>>>

    Returns the incoming HTTP Response, or an error, once one is ready.

    The outer option represents future readiness. Users can wait on this option to become some using the subscribe method.

    The outer result is used to retrieve the response or error at most once. It will be success on the first call in which the outer option is some, and error on subsequent calls.

    The inner result represents that either the incoming HTTP Response status and headers have recieved successfully, or that an error occured. Errors may also occur while consuming the response body, but those will be reported by the incoming-body and its output-stream child.

Functions

functionhttp-error-code: func(err: borrow<io-error>) -> option<error-code>

Attempts to extract a http-related error from the wasi:io error provided.

Stream operations which return wasi:io/stream/stream-error::last-operation-failed have a payload of type wasi:io/error/error with more information about the operation that failed. This payload can be passed through to this function to see if there's http-related information about the error to return.

Note that this function is fallible because not all io-errors are http-related errors.

WIT

/// This interface defines all of the types and methods for implementing
/// HTTP Requests and Responses, both incoming and outgoing, as well as
/// their headers, trailers, and bodies.
interface types {
  use wasi:clocks/monotonic-clock@0.2.0.{duration};
  use wasi:io/streams@0.2.0.{input-stream, output-stream};
  use wasi:io/error@0.2.0.{error as io-error};
  use wasi:io/poll@0.2.0.{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),
  }

  /// Defines the case payload type for `DNS-error` above:
  record DNS-error-payload {
    rcode: option<string>,
    info-code: option<u16>,
  }

  /// Defines the case payload type for `TLS-alert-received` above:
  record TLS-alert-received-payload {
    alert-id: option<u8>,
    alert-message: option<string>,
  }

  /// Defines the case payload type for `HTTP-response-{header,trailer}-size` above:
  record field-size-payload {
    field-name: option<string>,
    field-size: option<u32>,
  }

  /// These cases are inspired by the IANA HTTP Proxy Error Types:
  /// https://www.iana.org/assignments/http-proxy-status/http-proxy-status.xhtml#table-http-proxy-error-types
  variant error-code {
    DNS-timeout,
    DNS-error(DNS-error-payload),
    destination-not-found,
    destination-unavailable,
    destination-IP-prohibited,
    destination-IP-unroutable,
    connection-refused,
    connection-terminated,
    connection-timeout,
    connection-read-timeout,
    connection-write-timeout,
    connection-limit-reached,
    TLS-protocol-error,
    TLS-certificate-error,
    TLS-alert-received(TLS-alert-received-payload),
    HTTP-request-denied,
    HTTP-request-length-required,
    HTTP-request-body-size(option<u64>),
    HTTP-request-method-invalid,
    HTTP-request-URI-invalid,
    HTTP-request-URI-too-long,
    HTTP-request-header-section-size(option<u32>),
    HTTP-request-header-size(option<field-size-payload>),
    HTTP-request-trailer-section-size(option<u32>),
    HTTP-request-trailer-size(field-size-payload),
    HTTP-response-incomplete,
    HTTP-response-header-section-size(option<u32>),
    HTTP-response-header-size(field-size-payload),
    HTTP-response-body-size(option<u64>),
    HTTP-response-trailer-section-size(option<u32>),
    HTTP-response-trailer-size(field-size-payload),
    HTTP-response-transfer-coding(option<string>),
    HTTP-response-content-coding(option<string>),
    HTTP-response-timeout,
    HTTP-upgrade-failed,
    HTTP-protocol-error,
    loop-detected,
    configuration-error,
    /// This is a catch-all error for anything that doesn't fit cleanly into a
    /// more specific case. It also includes an optional string for an
    /// unstructured description of the error. Users should not depend on the
    /// string for diagnosing errors, as it's not required to be consistent
    /// between implementations.
    internal-error(option<string>),
  }

  /// This type enumerates the different kinds of errors that may occur when
  /// setting or appending to a `fields` resource.
  variant header-error {
    /// This error indicates that a `field-key` or `field-value` was
    /// syntactically invalid when used with an operation that sets headers in a
    /// `fields`.
    invalid-syntax,
    /// This error indicates that a forbidden `field-key` was used when trying
    /// to set a header in a `fields`.
    forbidden,
    /// This error indicates that the operation on the `fields` was not
    /// permitted because the fields are immutable.
    immutable,
  }

  /// Field keys are always strings.
  type field-key = string;

  /// Field values should always be ASCII strings. However, in
  /// reality, HTTP implementations often have to interpret malformed values,
  /// so they are provided as a list of bytes.
  type field-value = list<u8>;

  /// This following block defines the `fields` resource which corresponds to
  /// HTTP standard Fields. Fields are a common representation used for both
  /// Headers and Trailers.
  ///
  /// A `fields` may be mutable or immutable. A `fields` created using the
  /// constructor, `from-list`, or `clone` will be mutable, but a `fields`
  /// resource given by other means (including, but not limited to,
  /// `incoming-request.headers`, `outgoing-request.headers`) might be be
  /// immutable. In an immutable fields, the `set`, `append`, and `delete`
  /// operations will fail with `header-error.immutable`.
  resource fields {
    /// Construct an empty HTTP Fields.
    ///
    /// The resulting `fields` is mutable.
    constructor();
    /// Construct an HTTP Fields.
    ///
    /// The resulting `fields` is mutable.
    ///
    /// The list represents each key-value pair in the Fields. Keys
    /// which have multiple values are represented by multiple entries in this
    /// list with the same key.
    ///
    /// The tuple is a pair of the field key, represented as a string, and
    /// Value, represented as a list of bytes. In a valid Fields, all keys
    /// and values are valid UTF-8 strings. However, values are not always
    /// well-formed, so they are represented as a raw list of bytes.
    ///
    /// An error result will be returned if any header or value was
    /// syntactically invalid, or if a header was forbidden.
    from-list: static func(entries: list<tuple<field-key, field-value>>) -> result<fields, header-error>;
    /// Get all of the values corresponding to a key. If the key is not present
    /// in this `fields`, an empty list is returned. However, if the key is
    /// present but empty, this is represented by a list with one or more
    /// empty field-values present.
    get: func(name: field-key) -> list<field-value>;
    /// Returns `true` when the key is present in this `fields`. If the key is
    /// syntactically invalid, `false` is returned.
    has: func(name: field-key) -> bool;
    /// Set all of the values for a key. Clears any existing values for that
    /// key, if they have been set.
    ///
    /// Fails with `header-error.immutable` if the `fields` are immutable.
    set: func(name: field-key, value: list<field-value>) -> result<_, header-error>;
    /// Delete all values for a key. Does nothing if no values for the key
    /// exist.
    ///
    /// Fails with `header-error.immutable` if the `fields` are immutable.
    delete: func(name: field-key) -> result<_, header-error>;
    /// Append a value for a key. Does not change or delete any existing
    /// values for that key.
    ///
    /// Fails with `header-error.immutable` if the `fields` are immutable.
    append: func(name: field-key, value: field-value) -> result<_, header-error>;
    /// Retrieve the full set of keys and values in the Fields. Like the
    /// constructor, the list represents each key-value pair.
    ///
    /// The outer list represents each key-value pair in the Fields. Keys
    /// which have multiple values are represented by multiple entries in this
    /// list with the same key.
    entries: func() -> list<tuple<field-key, field-value>>;
    /// Make a deep copy of the Fields. Equivelant in behavior to calling the
    /// `fields` constructor on the return value of `entries`. The resulting
    /// `fields` is mutable.
    clone: func() -> fields;
  }

  /// Headers is an alias for Fields.
  type headers = fields;

  /// Trailers is an alias for Fields.
  type trailers = fields;

  /// Represents an incoming HTTP Request.
  resource incoming-request {
    /// Returns the method of the incoming request.
    method: func() -> method;
    /// Returns the path with query parameters from the request, as a string.
    path-with-query: func() -> option<string>;
    /// Returns the protocol scheme from the request.
    scheme: func() -> option<scheme>;
    /// Returns the authority from the request, if it was present.
    authority: func() -> option<string>;
    /// Get the `headers` associated with the request.
    ///
    /// The returned `headers` resource is immutable: `set`, `append`, and
    /// `delete` operations will fail with `header-error.immutable`.
    ///
    /// The `headers` returned are a child resource: it must be dropped before
    /// the parent `incoming-request` is dropped. Dropping this
    /// `incoming-request` before all children are dropped will trap.
    headers: func() -> headers;
    /// Gives the `incoming-body` associated with this request. Will only
    /// return success at most once, and subsequent calls will return error.
    consume: func() -> result<incoming-body>;
  }

  /// Represents an outgoing HTTP Request.
  resource outgoing-request {
    /// Construct a new `outgoing-request` with a default `method` of `GET`, and
    /// `none` values for `path-with-query`, `scheme`, and `authority`.
    ///
    /// * `headers` is the HTTP Headers for the Request.
    ///
    /// It is possible to construct, or manipulate with the accessor functions
    /// below, an `outgoing-request` with an invalid combination of `scheme`
    /// and `authority`, or `headers` which are not permitted to be sent.
    /// It is the obligation of the `outgoing-handler.handle` implementation
    /// to reject invalid constructions of `outgoing-request`.
    constructor(headers: headers);
    /// Returns the resource corresponding to the outgoing Body for this
    /// Request.
    ///
    /// Returns success on the first call: the `outgoing-body` resource for
    /// this `outgoing-request` can be retrieved at most once. Subsequent
    /// calls will return error.
    body: func() -> result<outgoing-body>;
    /// Get the Method for the Request.
    method: func() -> method;
    /// Set the Method for the Request. Fails if the string present in a
    /// `method.other` argument is not a syntactically valid method.
    set-method: func(method: method) -> result;
    /// Get the combination of the HTTP Path and Query for the Request.
    /// When `none`, this represents an empty Path and empty Query.
    path-with-query: func() -> option<string>;
    /// Set the combination of the HTTP Path and Query for the Request.
    /// When `none`, this represents an empty Path and empty Query. Fails is the
    /// string given is not a syntactically valid path and query uri component.
    set-path-with-query: func(path-with-query: option<string>) -> result;
    /// Get the HTTP Related Scheme for the Request. When `none`, the
    /// implementation may choose an appropriate default scheme.
    scheme: func() -> option<scheme>;
    /// Set the HTTP Related Scheme for the Request. When `none`, the
    /// implementation may choose an appropriate default scheme. Fails if the
    /// string given is not a syntactically valid uri scheme.
    set-scheme: func(scheme: option<scheme>) -> result;
    /// Get the HTTP Authority for the Request. A value of `none` may be used
    /// with Related Schemes which do not require an Authority. The HTTP and
    /// HTTPS schemes always require an authority.
    authority: func() -> option<string>;
    /// Set the HTTP Authority for the Request. A value of `none` may be used
    /// with Related Schemes which do not require an Authority. The HTTP and
    /// HTTPS schemes always require an authority. Fails if the string given is
    /// not a syntactically valid uri authority.
    set-authority: func(authority: option<string>) -> result;
    /// Get the headers associated with the Request.
    ///
    /// The returned `headers` resource is immutable: `set`, `append`, and
    /// `delete` operations will fail with `header-error.immutable`.
    ///
    /// This headers resource is a child: it must be dropped before the parent
    /// `outgoing-request` is dropped, or its ownership is transfered to
    /// another component by e.g. `outgoing-handler.handle`.
    headers: func() -> headers;
  }

  /// Parameters for making an HTTP Request. Each of these parameters is
  /// currently an optional timeout applicable to the transport layer of the
  /// HTTP protocol.
  ///
  /// These timeouts are separate from any the user may use to bound a
  /// blocking call to `wasi:io/poll.poll`.
  resource request-options {
    /// Construct a default `request-options` value.
    constructor();
    /// The timeout for the initial connect to the HTTP Server.
    connect-timeout: func() -> option<duration>;
    /// Set the timeout for the initial connect to the HTTP Server. An error
    /// return value indicates that this timeout is not supported.
    set-connect-timeout: func(duration: option<duration>) -> result;
    /// The timeout for receiving the first byte of the Response body.
    first-byte-timeout: func() -> option<duration>;
    /// Set the timeout for receiving the first byte of the Response body. An
    /// error return value indicates that this timeout is not supported.
    set-first-byte-timeout: func(duration: option<duration>) -> result;
    /// The timeout for receiving subsequent chunks of bytes in the Response
    /// body stream.
    between-bytes-timeout: func() -> option<duration>;
    /// Set the timeout for receiving subsequent chunks of bytes in the Response
    /// body stream. An error return value indicates that this timeout is not
    /// supported.
    set-between-bytes-timeout: func(duration: option<duration>) -> result;
  }

  /// Represents the ability to send an HTTP Response.
  ///
  /// This resource is used by the `wasi:http/incoming-handler` interface to
  /// allow a Response to be sent corresponding to the Request provided as the
  /// other argument to `incoming-handler.handle`.
  resource response-outparam {
    /// Set the value of the `response-outparam` to either send a response,
    /// or indicate an error.
    ///
    /// This method consumes the `response-outparam` to ensure that it is
    /// called at most once. If it is never called, the implementation
    /// will respond with an error.
    ///
    /// The user may provide an `error` to `response` to allow the
    /// implementation determine how to respond with an HTTP error response.
    set: static func(param: response-outparam, response: result<outgoing-response, error-code>);
  }

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

  /// Represents an incoming HTTP Response.
  resource incoming-response {
    /// Returns the status code from the incoming response.
    status: func() -> status-code;
    /// Returns the headers from the incoming response.
    ///
    /// The returned `headers` resource is immutable: `set`, `append`, and
    /// `delete` operations will fail with `header-error.immutable`.
    ///
    /// This headers resource is a child: it must be dropped before the parent
    /// `incoming-response` is dropped.
    headers: func() -> headers;
    /// Returns the incoming body. May be called at most once. Returns error
    /// if called additional times.
    consume: func() -> result<incoming-body>;
  }

  /// Represents an incoming HTTP Request or Response's Body.
  ///
  /// A body has both its contents - a stream of bytes - and a (possibly
  /// empty) set of trailers, indicating that the full contents of the
  /// body have been received. This resource represents the contents as
  /// an `input-stream` and the delivery of trailers as a `future-trailers`,
  /// and ensures that the user of this interface may only be consuming either
  /// the body contents or waiting on trailers at any given time.
  resource incoming-body {
    /// Returns the contents of the body, as a stream of bytes.
    ///
    /// Returns success on first call: the stream representing the contents
    /// can be retrieved at most once. Subsequent calls will return error.
    ///
    /// The returned `input-stream` resource is a child: it must be dropped
    /// before the parent `incoming-body` is dropped, or consumed by
    /// `incoming-body.finish`.
    ///
    /// This invariant ensures that the implementation can determine whether
    /// the user is consuming the contents of the body, waiting on the
    /// `future-trailers` to be ready, or neither. This allows for network
    /// backpressure is to be applied when the user is consuming the body,
    /// and for that backpressure to not inhibit delivery of the trailers if
    /// the user does not read the entire body.
    %stream: func() -> result<input-stream>;
    /// Takes ownership of `incoming-body`, and returns a `future-trailers`.
    /// This function will trap if the `input-stream` child is still alive.
    finish: static func(this: incoming-body) -> future-trailers;
  }

  /// Represents a future which may eventaully return trailers, or an error.
  ///
  /// In the case that the incoming HTTP Request or Response did not have any
  /// trailers, this future will resolve to the empty set of trailers once the
  /// complete Request or Response body has been received.
  resource future-trailers {
    /// Returns a pollable which becomes ready when either the trailers have
    /// been received, or an error has occured. When this pollable is ready,
    /// the `get` method will return `some`.
    subscribe: func() -> pollable;
    /// Returns the contents of the trailers, or an error which occured,
    /// once the future is ready.
    ///
    /// The outer `option` represents future readiness. Users can wait on this
    /// `option` to become `some` using the `subscribe` method.
    ///
    /// The outer `result` is used to retrieve the trailers or error at most
    /// once. It will be success on the first call in which the outer option
    /// is `some`, and error on subsequent calls.
    ///
    /// The inner `result` represents that either the HTTP Request or Response
    /// body, as well as any trailers, were received successfully, or that an
    /// error occured receiving them. The optional `trailers` indicates whether
    /// or not trailers were present in the body.
    ///
    /// When some `trailers` are returned by this method, the `trailers`
    /// resource is immutable, and a child. Use of the `set`, `append`, or
    /// `delete` methods will return an error, and the resource must be
    /// dropped before the parent `future-trailers` is dropped.
    get: func() -> option<result<result<option<trailers>, error-code>>>;
  }

  /// Represents an outgoing HTTP Response.
  resource outgoing-response {
    /// Construct an `outgoing-response`, with a default `status-code` of `200`.
    /// If a different `status-code` is needed, it must be set via the
    /// `set-status-code` method.
    ///
    /// * `headers` is the HTTP Headers for the Response.
    constructor(headers: headers);
    /// Get the HTTP Status Code for the Response.
    status-code: func() -> status-code;
    /// Set the HTTP Status Code for the Response. Fails if the status-code
    /// given is not a valid http status code.
    set-status-code: func(status-code: status-code) -> result;
    /// Get the headers associated with the Request.
    ///
    /// The returned `headers` resource is immutable: `set`, `append`, and
    /// `delete` operations will fail with `header-error.immutable`.
    ///
    /// This headers resource is a child: it must be dropped before the parent
    /// `outgoing-request` is dropped, or its ownership is transfered to
    /// another component by e.g. `outgoing-handler.handle`.
    headers: func() -> headers;
    /// Returns the resource corresponding to the outgoing Body for this Response.
    ///
    /// Returns success on the first call: the `outgoing-body` resource for
    /// this `outgoing-response` can be retrieved at most once. Subsequent
    /// calls will return error.
    body: func() -> result<outgoing-body>;
  }

  /// Represents an outgoing HTTP Request or Response's Body.
  ///
  /// A body has both its contents - a stream of bytes - and a (possibly
  /// empty) set of trailers, inducating the full contents of the body
  /// have been sent. This resource represents the contents as an
  /// `output-stream` child resource, and the completion of the body (with
  /// optional trailers) with a static function that consumes the
  /// `outgoing-body` resource, and ensures that the user of this interface
  /// may not write to the body contents after the body has been finished.
  ///
  /// If the user code drops this resource, as opposed to calling the static
  /// method `finish`, the implementation should treat the body as incomplete,
  /// and that an error has occured. The implementation should propogate this
  /// error to the HTTP protocol by whatever means it has available,
  /// including: corrupting the body on the wire, aborting the associated
  /// Request, or sending a late status code for the Response.
  resource outgoing-body {
    /// Returns a stream for writing the body contents.
    ///
    /// The returned `output-stream` is a child resource: it must be dropped
    /// before the parent `outgoing-body` resource is dropped (or finished),
    /// otherwise the `outgoing-body` drop or `finish` will trap.
    ///
    /// Returns success on the first call: the `output-stream` resource for
    /// this `outgoing-body` may be retrieved at most once. Subsequent calls
    /// will return error.
    write: func() -> result<output-stream>;
    /// Finalize an outgoing body, optionally providing trailers. This must be
    /// called to signal that the response is complete. If the `outgoing-body`
    /// is dropped without calling `outgoing-body.finalize`, the implementation
    /// should treat the body as corrupted.
    ///
    /// Fails if the body's `outgoing-request` or `outgoing-response` was
    /// constructed with a Content-Length header, and the contents written
    /// to the body (via `write`) does not match the value given in the
    /// Content-Length.
    finish: static func(this: outgoing-body, trailers: option<trailers>) -> result<_, error-code>;
  }

  /// Represents a future which may eventaully return an incoming HTTP
  /// Response, or an error.
  ///
  /// This resource is returned by the `wasi:http/outgoing-handler` interface to
  /// provide the HTTP Response corresponding to the sent Request.
  resource future-incoming-response {
    /// Returns a pollable which becomes ready when either the Response has
    /// been received, or an error has occured. When this pollable is ready,
    /// the `get` method will return `some`.
    subscribe: func() -> pollable;
    /// Returns the incoming HTTP Response, or an error, once one is ready.
    ///
    /// The outer `option` represents future readiness. Users can wait on this
    /// `option` to become `some` using the `subscribe` method.
    ///
    /// The outer `result` is used to retrieve the response or error at most
    /// once. It will be success on the first call in which the outer option
    /// is `some`, and error on subsequent calls.
    ///
    /// The inner `result` represents that either the incoming HTTP Response
    /// status and headers have recieved successfully, or that an error
    /// occured. Errors may also occur while consuming the response body,
    /// but those will be reported by the `incoming-body` and its
    /// `output-stream` child.
    get: func() -> option<result<result<incoming-response, error-code>>>;
  }

  /// Attempts to extract a http-related `error` from the wasi:io `error`
  /// provided.
  ///
  /// Stream operations which return
  /// `wasi:io/stream/stream-error::last-operation-failed` have a payload of
  /// type `wasi:io/error/error` with more information about the operation
  /// that failed. This payload can be passed through to this function to see
  /// if there's http-related information about the error to return.
  ///
  /// Note that this function is fallible because not all io-errors are
  /// http-related errors.
  http-error-code: func(err: borrow<io-error>) -> option<error-code>;
}