diff --git a/proxy.md b/proxy.md index 4194b5e..cef8d2a 100644 --- a/proxy.md +++ b/proxy.md @@ -644,6 +644,9 @@ their headers, trailers, and bodies.

#### `type output-stream` [`output-stream`](#output_stream)

+#### `type stream-error` +[`error`](#error) +

#### `type pollable` [`pollable`](#pollable)

@@ -670,16 +673,76 @@ their headers, trailers, and bodies.

  • HTTPS
  • other: string
    • -

    variant error

    -

    TODO: perhaps better align with HTTP semantics? -This type enumerates the different kinds of errors that may occur when -initially returning a response.

    +

    record DNS-error-payload

    +

    Defines the case payload type for DNS-error above:

    +
    Record Fields
    + +

    record TLS-alert-received-payload

    +

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

    +
    Record Fields
    + +

    record field-size-payload

    +

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

    +
    Record Fields
    + +

    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

    Variant Cases

    variant header-error

    This type enumerates the different kinds of errors that may occur when @@ -728,6 +791,23 @@ so they are provided as a list of bytes.

    resource future-incoming-response

    Functions

    +

    http-error-code: func

    +

    Attempts to extract a http-related error from the stream error +provided.

    +

    Stream operations which return stream-error::last-operation-failed have +a payload 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 stream-related errors +are http-related errors.

    +
    Params
    + +
    Return values
    +

    [constructor]fields: func

    Construct an empty HTTP Fields.

    Return values
    @@ -1118,7 +1198,7 @@ implementation determine how to respond with an HTTP error response.

    Params

    [method]incoming-response.status: func

    Returns the status code from the incoming response.

    @@ -1210,7 +1290,7 @@ trailers were present in the body.

    Return values

    [constructor]outgoing-response: func

    Construct an outgoing-response, with a default status-code of 200. @@ -1331,7 +1411,7 @@ but those will be reported by the incoming-body

    Return values

    Import interface wasi:http/outgoing-handler

    This interface defines a handler of outgoing HTTP Requests. It should be @@ -1347,8 +1427,8 @@ imported by components which wish to make HTTP Requests.

    #### `type future-incoming-response` [`future-incoming-response`](#future_incoming_response)

    -#### `type error` -[`error`](#error) +#### `type error-code` +[`error-code`](#error_code)

    ----

    Functions

    @@ -1368,7 +1448,7 @@ through the future-incoming-response
    Return values

    Export interface wasi:http/incoming-handler

    diff --git a/wit/handler.wit b/wit/handler.wit index 21b97a3..a34a064 100644 --- a/wit/handler.wit +++ b/wit/handler.wit @@ -22,7 +22,9 @@ interface incoming-handler { /// 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}; + 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 @@ -37,5 +39,5 @@ interface outgoing-handler { handle: func( request: outgoing-request, options: option - ) -> result; + ) -> result; } diff --git a/wit/types.wit b/wit/types.wit index 0f3dba4..f24c094 100644 --- a/wit/types.wit +++ b/wit/types.wit @@ -3,7 +3,7 @@ /// their headers, trailers, and bodies. interface types { use wasi:clocks/monotonic-clock.{duration}; - use wasi:io/streams.{input-stream, output-stream}; + use wasi:io/streams.{input-stream, output-stream, error as stream-error}; use wasi:io/poll.{pollable}; /// This type corresponds to HTTP standard Methods. @@ -27,16 +27,85 @@ interface types { 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) + /// 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), + HTTP-request-method-invalid, + HTTP-request-URI-invalid, + HTTP-request-URI-too-long, + HTTP-request-header-section-size(option), + HTTP-request-header-size(option), + HTTP-request-trailer-section-size(option), + HTTP-request-trailer-size(field-size-payload), + HTTP-response-incomplete, + HTTP-response-header-section-size(option), + HTTP-response-header-size(field-size-payload), + HTTP-response-body-size(option), + HTTP-response-trailer-section-size(option), + HTTP-response-trailer-size(field-size-payload), + HTTP-response-transfer-coding(option), + HTTP-response-content-coding(option), + 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) + } + + /// Defines the case payload type for `DNS-error` above: + record DNS-error-payload { + rcode: option, + info-code: option + } + + /// Defines the case payload type for `TLS-alert-received` above: + record TLS-alert-received-payload { + alert-id: option, + alert-message: option } + /// Defines the case payload type for `HTTP-response-{header,trailer}-size` above: + record field-size-payload { + field-name: option, + field-size: option + } + + /// Attempts to extract a http-related `error` from the stream `error` + /// provided. + /// + /// Stream operations which return `stream-error::last-operation-failed` have + /// a payload 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 stream-related errors + /// are http-related errors. + http-error-code: func(err: borrow) -> option; + /// This type enumerates the different kinds of errors that may occur when /// setting or appending to a `fields` resource. variant header-error { @@ -261,7 +330,7 @@ interface types { /// implementation determine how to respond with an HTTP error response. set: static func( param: response-outparam, - response: result, + response: result, ); } @@ -336,7 +405,7 @@ interface types { /// 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. - get: func() -> option, error>>; + get: func() -> option, error-code>>; } /// Represents an outgoing HTTP Response. @@ -432,7 +501,7 @@ interface types { /// 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>>; + get: func() -> option>>; } }