componentized

This interface defines a handler of outgoing HTTP Requests. It should be imported by components which wish to make HTTP Requests.

Types

use resource outgoing-request

from wasi:http/types@0.2.0

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.

use resource request-options

from wasi:http/types@0.2.0

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.

use resource future-incoming-response

from wasi:http/types@0.2.0

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.

use variant error-code

from wasi:http/types@0.2.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

functionhandle: func( request: outgoing-request, options: option<request-options>, ) -> result<future-incoming-response, error-code>

This function is invoked with an outgoing HTTP Request, and it returns a resource future-incoming-response which represents an HTTP Response which may arrive in the future.

The options argument accepts optional parameters for the HTTP protocol's transport layer.

This function may return an error if the outgoing-request is invalid or not allowed to be made. Otherwise, protocol errors are reported through the future-incoming-response.

WIT

/// This interface defines a handler of outgoing HTTP Requests. It should be
/// imported by components which wish to make HTTP Requests.
interface outgoing-handler {
  use types.{outgoing-request, request-options, future-incoming-response, error-code};

  /// This function is invoked with an outgoing HTTP Request, and it returns
  /// a resource `future-incoming-response` which represents an HTTP Response
  /// which may arrive in the future.
  ///
  /// The `options` argument accepts optional parameters for the HTTP
  /// protocol's transport layer.
  ///
  /// This function may return an error if the `outgoing-request` is invalid
  /// or not allowed to be made. Otherwise, protocol errors are reported
  /// through the `future-incoming-response`.
  handle: func(request: outgoing-request, options: option<request-options>) -> result<future-incoming-response, error-code>;
}