componentized/directory

wasi:http

interface dependency

A WASI API for sending and receiving HTTP requests and responses.

interface outgoing-handler wasi:http/outgoing-handler@0.2.6 since 0.2.0

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-requestsince 0.2.0

from wasi:http/types@0.2.6

Represents an outgoing HTTP Request.

  • constructor(headers: headers)since 0.2.0

    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.

  • body: func() -> result<outgoing-body>since 0.2.0

    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.

  • method: func() -> methodsince 0.2.0

    Get the Method for the Request.

  • set-method: func(method: method) -> resultsince 0.2.0

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

  • path-with-query: func() -> option<string>since 0.2.0

    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>) -> resultsince 0.2.0

    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.

  • scheme: func() -> option<scheme>since 0.2.0

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

  • set-scheme: func(scheme: option<scheme>) -> resultsince 0.2.0

    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.

  • authority: func() -> option<string>since 0.2.0

    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>) -> resultsince 0.2.0

    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.

  • headers: func() -> headerssince 0.2.0

    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 transferred to another component by e.g. outgoing-handler.handle.

use resource request-optionssince 0.2.0

from wasi:http/types@0.2.6

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()since 0.2.0

    Construct a default request-options value.

  • connect-timeout: func() -> option<duration>since 0.2.0

    The timeout for the initial connect to the HTTP Server.

  • set-connect-timeout: func(duration: option<duration>) -> resultsince 0.2.0

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

  • first-byte-timeout: func() -> option<duration>since 0.2.0

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

  • set-first-byte-timeout: func(duration: option<duration>) -> resultsince 0.2.0

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

  • between-bytes-timeout: func() -> option<duration>since 0.2.0

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

  • set-between-bytes-timeout: func(duration: option<duration>) -> resultsince 0.2.0

    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-responsesince 0.2.0

from wasi:http/types@0.2.6

Represents a future which may eventually 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.

  • subscribe: func() -> pollablesince 0.2.0

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

  • get: func() -> option<result<result<incoming-response, error-code>>>since 0.2.0

    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 received successfully, or that an error occurred. 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-codesince 0.2.0

from wasi:http/types@0.2.6

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: func( request: outgoing-request, options: option<request-options>, ) -> result<future-incoming-response, error-code>since 0.2.0

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.
@since(version = 0.2.0)
interface outgoing-handler {
  @since(version = 0.2.0)
  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`.
  @since(version = 0.2.0)
  handle: func(request: outgoing-request, options: option<request-options>) -> result<future-incoming-response, error-code>;
}