From 8e473e7405d307db44eb0e8ff28c004200ad43e7 Mon Sep 17 00:00:00 2001 From: Luke Wagner Date: Tue, 12 Sep 2023 17:30:41 -0500 Subject: [PATCH 1/6] Fill in the 'error' variant Resolves #49 --- wit/types.wit | 65 +++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 58 insertions(+), 7 deletions(-) diff --git a/wit/types.wit b/wit/types.wit index 0f3dba4..cc9277c 100644 --- a/wit/types.wit +++ b/wit/types.wit @@ -27,14 +27,65 @@ 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. + // The cases of this variant correspond to 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 { - invalid-url(string), - timeout-error(string), - protocol-error(string), - unexpected-error(string) + 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-error(HTTP-request-error-payload), + HTTP-request-denied, + HTTP-response-incomplete, + HTTP-response-header-section-size(u32), + HTTP-response-header-size(field-size-payload), + HTTP-response-body-size(u32), + HTTP-response-trailer-section-size(u32), + HTTP-response-trailer-size(field-size-payload), + HTTP-response-transfer-coding(string), + HTTP-response-content-coding(string), + HTTP-response-timeout, + HTTP-upgrade-failed, + HTTP-protocol-error, + proxy-internal-response, + proxy-internal-error, + proxy-configuration-error, + proxy-loop-detected + } + + // Defines the case payload type for `DNS-error` above: + record DNS-error-payload { + rcode: string, + info-code: u16 + } + + // Defines the case payload type for `TLS-alert-received` above: + record TLS-alert-received-payload { + alert-ID: u8, + alert-message: string + } + + // Defines the case payload type for `HTTP-request-error` above: + record HTTP-request-error-payload { + status-code: u16, + status-phrase: string + } + + // Defines the case payload type for `HTTP-response-{header,trailer}-size` above: + record field-size-payload { + field-name: string, + field-size: u32 } /// This type enumerates the different kinds of errors that may occur when From cd5cbf89568325434f9d867c8c2917b0f58948a2 Mon Sep 17 00:00:00 2001 From: Trevor Elliott Date: Tue, 7 Nov 2023 14:04:31 -0800 Subject: [PATCH 2/6] Switch to doc comments, make all variant fields optional --- wit/types.wit | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/wit/types.wit b/wit/types.wit index cc9277c..31a9bbb 100644 --- a/wit/types.wit +++ b/wit/types.wit @@ -27,8 +27,8 @@ interface types { other(string) } - // The cases of this variant correspond to the IANA HTTP Proxy Error Types: - // https://www.iana.org/assignments/http-proxy-status/http-proxy-status.xhtml#table-http-proxy-error-types + /// The cases of this variant correspond to 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 { DNS-timeout, DNS-error(DNS-error-payload), @@ -48,13 +48,13 @@ interface types { HTTP-request-error(HTTP-request-error-payload), HTTP-request-denied, HTTP-response-incomplete, - HTTP-response-header-section-size(u32), + HTTP-response-header-section-size(option), HTTP-response-header-size(field-size-payload), - HTTP-response-body-size(u32), - HTTP-response-trailer-section-size(u32), + HTTP-response-body-size(option), + HTTP-response-trailer-section-size(option), HTTP-response-trailer-size(field-size-payload), - HTTP-response-transfer-coding(string), - HTTP-response-content-coding(string), + HTTP-response-transfer-coding(option), + HTTP-response-content-coding(option), HTTP-response-timeout, HTTP-upgrade-failed, HTTP-protocol-error, @@ -64,28 +64,28 @@ interface types { proxy-loop-detected } - // Defines the case payload type for `DNS-error` above: + /// Defines the case payload type for `DNS-error` above: record DNS-error-payload { - rcode: string, - info-code: u16 + rcode: option, + info-code: option } - // Defines the case payload type for `TLS-alert-received` above: + /// Defines the case payload type for `TLS-alert-received` above: record TLS-alert-received-payload { - alert-ID: u8, - alert-message: string + alert-ID: option, + alert-message: option } - // Defines the case payload type for `HTTP-request-error` above: + /// Defines the case payload type for `HTTP-request-error` above: record HTTP-request-error-payload { - status-code: u16, - status-phrase: string + status-code: option, + status-phrase: option } - // Defines the case payload type for `HTTP-response-{header,trailer}-size` above: + /// Defines the case payload type for `HTTP-response-{header,trailer}-size` above: record field-size-payload { - field-name: string, - field-size: u32 + field-name: option, + field-size: option } /// This type enumerates the different kinds of errors that may occur when From c83597bc76e9105a3fe074d8dc20ef31b3fc04d8 Mon Sep 17 00:00:00 2001 From: Trevor Elliott Date: Tue, 7 Nov 2023 14:07:14 -0800 Subject: [PATCH 3/6] Rename error to error-code, and add the http-error-code downcast --- wit/handler.wit | 6 ++++-- wit/types.wit | 22 +++++++++++++++++----- 2 files changed, 21 insertions(+), 7 deletions(-) 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 31a9bbb..658d072 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. @@ -29,7 +29,7 @@ interface types { /// The cases of this variant correspond to 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 { + variant error-code { DNS-timeout, DNS-error(DNS-error-payload), destination-not-found, @@ -88,6 +88,18 @@ interface types { 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 { @@ -312,7 +324,7 @@ interface types { /// implementation determine how to respond with an HTTP error response. set: static func( param: response-outparam, - response: result, + response: result, ); } @@ -387,7 +399,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. @@ -483,7 +495,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>>; } } From 4850f668f1e159ae2aaaeef7ccbdf287410b3212 Mon Sep 17 00:00:00 2001 From: Trevor Elliott Date: Wed, 8 Nov 2023 16:49:20 -0800 Subject: [PATCH 4/6] Remove http-client-error, and add specializations --- wit/types.wit | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/wit/types.wit b/wit/types.wit index 658d072..86a505b 100644 --- a/wit/types.wit +++ b/wit/types.wit @@ -45,8 +45,12 @@ interface types { TLS-protocol-error, TLS-certificate-error, TLS-alert-received(TLS-alert-received-payload), - HTTP-request-error(HTTP-request-error-payload), HTTP-request-denied, + HTTP-request-length-required, + HTTP-request-content-too-large, + HTTP-request-URI-too-long, + HTTP-request-header-section-size(option), + HTTP-request-header-size(option), HTTP-response-incomplete, HTTP-response-header-section-size(option), HTTP-response-header-size(field-size-payload), @@ -76,12 +80,6 @@ interface types { alert-message: option } - /// Defines the case payload type for `HTTP-request-error` above: - record HTTP-request-error-payload { - status-code: option, - status-phrase: option - } - /// Defines the case payload type for `HTTP-response-{header,trailer}-size` above: record field-size-payload { field-name: option, From cbdcde3666393fed30b8cbdcf29648432a373c9b Mon Sep 17 00:00:00 2001 From: Trevor Elliott Date: Thu, 9 Nov 2023 16:11:35 -0800 Subject: [PATCH 5/6] Address remaining comments --- wit/types.wit | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/wit/types.wit b/wit/types.wit index 86a505b..f24c094 100644 --- a/wit/types.wit +++ b/wit/types.wit @@ -27,7 +27,7 @@ interface types { other(string) } - /// The cases of this variant correspond to the IANA HTTP Proxy Error Types: + /// 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, @@ -47,14 +47,18 @@ interface types { TLS-alert-received(TLS-alert-received-payload), HTTP-request-denied, HTTP-request-length-required, - HTTP-request-content-too-large, + 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-body-size(option), HTTP-response-trailer-section-size(option), HTTP-response-trailer-size(field-size-payload), HTTP-response-transfer-coding(option), @@ -62,10 +66,14 @@ interface types { HTTP-response-timeout, HTTP-upgrade-failed, HTTP-protocol-error, - proxy-internal-response, - proxy-internal-error, - proxy-configuration-error, - proxy-loop-detected + 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: @@ -76,7 +84,7 @@ interface types { /// Defines the case payload type for `TLS-alert-received` above: record TLS-alert-received-payload { - alert-ID: option, + alert-id: option, alert-message: option } From 5af2ac95eae2ffa6eceeb90696f3729bf47ae1b6 Mon Sep 17 00:00:00 2001 From: Trevor Elliott Date: Thu, 9 Nov 2023 16:11:55 -0800 Subject: [PATCH 6/6] Regenerate proxy.md --- proxy.md | 108 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 94 insertions(+), 14 deletions(-) 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