componentized/directory

wasi:http

interface dependency

WASI HTTP interfaces for HTTP client and server

interface handler wasi:http/handler@0.3.0 since 0.3.0

This interface defines a handler of HTTP Requests.

In a wasi:http/service this interface is exported to respond to an incoming HTTP Request with a Response.

In wasi:http/middleware this interface is both exported and imported as the "downstream" and "upstream" directions of the middleware chain.

Types

use resource request

from wasi:http/types@0.3.0

Represents an HTTP Request.

  • new: static func( headers: headers, contents: option<stream<u8>>, trailers: future<result<option<trailers>, error-code>>, options: option<request-options>, ) -> tuple<request, future<result<_, error-code>>>

    Construct a new 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.

    contents is the optional body content stream with none representing a zero-length content stream. Once it is closed, trailers future must resolve to a result. If trailers resolves to an error, underlying connection will be closed immediately.

    options is optional request-options resource to be used if the request is sent over a network connection.

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

    The returned future resolves to result of transmission of this request.

  • get-method: func() -> method

    Get the Method for the Request.

  • set-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.

  • get-path-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.

  • set-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.

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

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

  • set-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.

  • get-authority: func() -> option<string>

    Get the authority of the Request's target URI. 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.

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

    Set the authority of the Request's target URI. 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.

  • get-options: func() -> option<request-options>

    Get the request-options to be associated with this request

    The returned request-options resource is immutable: set-* operations will fail if invoked.

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

  • get-headers: 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.

  • consume-body: static func( this: request, res: future<result<_, error-code>>, ) -> tuple<stream<u8>, future<result<option<trailers>, error-code>>>

    Get body of the Request.

    Stream returned by this method represents the contents of the body. Once the stream is reported as closed, callers should await the returned future to determine whether the body was received successfully. The future will only resolve after the stream is reported as closed.

    This function takes a res future as a parameter, which can be used to communicate an error in handling of the request.

    Note that function will move the request, but references to headers or request options acquired from it previously will remain valid.

use resource response

from wasi:http/types@0.3.0

Represents an HTTP Response.

  • new: static func( headers: headers, contents: option<stream<u8>>, trailers: future<result<option<trailers>, error-code>>, ) -> tuple<response, future<result<_, error-code>>>

    Construct a new 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.

    contents is the optional body content stream with none representing a zero-length content stream. Once it is closed, trailers future must resolve to a result. If trailers resolves to an error, underlying connection will be closed immediately.

    The returned future resolves to result of transmission of this response.

  • get-status-code: func() -> status-code

    Get the HTTP Status Code for the Response.

  • set-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.

  • get-headers: func() -> headers

    Get the headers associated with the Response.

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

  • consume-body: static func( this: response, res: future<result<_, error-code>>, ) -> tuple<stream<u8>, future<result<option<trailers>, error-code>>>

    Get body of the Response.

    Stream returned by this method represents the contents of the body. Once the stream is reported as closed, callers should await the returned future to determine whether the body was received successfully. The future will only resolve after the stream is reported as closed.

    This function takes a res future as a parameter, which can be used to communicate an error in handling of the response.

    Note that function will move the response, but references to headers acquired from it previously will remain valid.

use variant error-code

from wasi:http/types@0.3.0

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.

Functions

handle: async func(request: request) -> result<response, error-code>

This function may be called with either an incoming request read from the network or a request synthesized or forwarded by another component.

WIT

/// This interface defines a handler of HTTP Requests.
///
/// In a `wasi:http/service` this interface is exported to respond to an
/// incoming HTTP Request with a Response.
///
/// In `wasi:http/middleware` this interface is both exported and imported as
/// the "downstream" and "upstream" directions of the middleware chain.
@since(version = 0.3.0)
interface handler {
  use types.{request, response, error-code};

  /// This function may be called with either an incoming request read from the
  /// network or a request synthesized or forwarded by another component.
  handle: async func(request: request) -> result<response, error-code>;
}