draft-ietf-httpbis-proxy-status-08.txt | draft-ietf-httpbis-proxy-status-latest.txt | |||
---|---|---|---|---|
HTTP Working Group M. Nottingham | HTTP Working Group M. Nottingham | |||
Internet-Draft Fastly | Internet-Draft Fastly | |||
Intended status: Standards Track P. Sikora | Intended status: Standards Track P. Sikora | |||
Expires: April 16, 2022 Google | Expires: November 16, 2024 Google | |||
October 13, 2021 | May 15, 2024 | |||
The Proxy-Status HTTP Response Header Field | The Proxy-Status HTTP Response Header Field | |||
draft-ietf-httpbis-proxy-status-08 | draft-ietf-httpbis-proxy-status-latest | |||
Abstract | Abstract | |||
This document defines the Proxy-Status HTTP field to convey the | This document defines the Proxy-Status HTTP response field to convey | |||
details of intermediary response handling, including generated | the details of an intermediary's response handling, including | |||
errors. | generated errors. | |||
Note to Readers | About This Document | |||
_RFC EDITOR: please remove this section before publication_ | This note is to be removed before publishing as an RFC. | |||
Discussion of this draft takes place on the HTTP working group | Status information for this document may be found at | |||
mailing list (ietf-http-wg@w3.org), which is archived at | <https://datatracker.ietf.org/doc/draft-ietf-httpbis-proxy-status/>. | |||
https://lists.w3.org/Archives/Public/ietf-http-wg/ [1]. | ||||
Working Group information can be found at https://httpwg.org/ [2]; | Discussion of this document takes place on the HTTP Working Group | |||
source code and issues list for this draft can be found at | mailing list (<mailto:ietf-http-wg@w3.org>), which is archived at | |||
https://github.com/httpwg/http-extensions/labels/proxy-status [3]. | <https://lists.w3.org/Archives/Public/ietf-http-wg/>. Working Group | |||
information can be found at <https://httpwg.org/>. | ||||
Source for this draft and an issue tracker can be found at | ||||
<https://github.com/httpwg/http-extensions/labels/proxy-status>. | ||||
Status of This Memo | Status of This Memo | |||
This Internet-Draft is submitted in full conformance with the | This Internet-Draft is submitted in full conformance with the | |||
provisions of BCP 78 and BCP 79. | provisions of BCP 78 and BCP 79. | |||
Internet-Drafts are working documents of the Internet Engineering | Internet-Drafts are working documents of the Internet Engineering | |||
Task Force (IETF). Note that other groups may also distribute | Task Force (IETF). Note that other groups may also distribute | |||
working documents as Internet-Drafts. The list of current Internet- | working documents as Internet-Drafts. The list of current Internet- | |||
Drafts is at https://datatracker.ietf.org/drafts/current/. | Drafts is at https://datatracker.ietf.org/drafts/current/. | |||
Internet-Drafts are draft documents valid for a maximum of six months | Internet-Drafts are draft documents valid for a maximum of six months | |||
and may be updated, replaced, or obsoleted by other documents at any | and may be updated, replaced, or obsoleted by other documents at any | |||
time. It is inappropriate to use Internet-Drafts as reference | time. It is inappropriate to use Internet-Drafts as reference | |||
material or to cite them other than as "work in progress." | material or to cite them other than as "work in progress." | |||
This Internet-Draft will expire on April 16, 2022. | This Internet-Draft will expire on November 16, 2024. | |||
Copyright Notice | Copyright Notice | |||
Copyright (c) 2021 IETF Trust and the persons identified as the | Copyright (c) 2024 IETF Trust and the persons identified as the | |||
document authors. All rights reserved. | document authors. All rights reserved. | |||
This document is subject to BCP 78 and the IETF Trust's Legal | This document is subject to BCP 78 and the IETF Trust's Legal | |||
Provisions Relating to IETF Documents | Provisions Relating to IETF Documents | |||
(https://trustee.ietf.org/license-info) in effect on the date of | (https://trustee.ietf.org/license-info) in effect on the date of | |||
publication of this document. Please review these documents | publication of this document. Please review these documents | |||
carefully, as they describe your rights and restrictions with respect | carefully, as they describe your rights and restrictions with respect | |||
to this document. Code Components extracted from this document must | to this document. Code Components extracted from this document must | |||
include Simplified BSD License text as described in Section 4.e of | include Simplified BSD License text as described in Section 4.e of | |||
the Trust Legal Provisions and are provided without warranty as | the Trust Legal Provisions and are provided without warranty as | |||
described in the Simplified BSD License. | described in the Simplified BSD License. | |||
1. Introduction | 1. Introduction | |||
HTTP intermediaries (see Section 3.7 of [HTTP]) -- including both | HTTP intermediaries (see Section 3.7 of [HTTP]) -- including both | |||
forward proxies and gateways (also known as "reverse proxies") -- | forward proxies and gateways (also known as "reverse proxies") -- | |||
have become an increasingly significant part of HTTP deployments. In | have become an increasingly significant part of HTTP deployments. In | |||
particular, reverse proxies and Content Delivery Networks (CDNs) form | particular, reverse proxies and content delivery networks (CDNs) form | |||
part of the critical infrastructure of many Web sites. | part of the critical infrastructure of many websites. | |||
Typically, HTTP intermediaries forward requests towards the origin | Typically, HTTP intermediaries forward requests towards the origin | |||
server (inbound) and then forward their responses back to clients | server (inbound) and then forward their responses back to clients | |||
(outbound). However, if an error occurs before a response is | (outbound). However, if an error occurs before a response is | |||
obtained from an inbound server, the response is often generated by | obtained from an inbound server, the response is often generated by | |||
the intermediary itself. | the intermediary itself. | |||
HTTP accommodates these types of errors with a few status codes; for | HTTP accommodates these types of errors with a few status codes -- | |||
example, 502 Bad Gateway and 504 Gateway Timeout. However, | for example, 502 (Bad Gateway) and 504 (Gateway Timeout). However, | |||
experience has shown that more information is necessary to aid | experience has shown that more information is necessary to aid | |||
debugging and communicate what's happened to the client. | debugging and communicate what's happened to the client. | |||
Additionally, intermediaries sometimes want to convey additional | Additionally, intermediaries sometimes want to convey additional | |||
information about their handling of a response, even if they did not | information about their handling of a response, even if they did not | |||
generate it. | generate it. | |||
To enable these uses, Section 2 defines a new HTTP response field to | To enable these uses, Section 2 defines a new HTTP response field to | |||
allow intermediaries to convey details of their handling of a | allow intermediaries to convey details of their handling of a | |||
response. Section 2.1 enumerates the information that can be added | response. Section 2.1 enumerates the information that can be added | |||
to the field by intermediaries, which can be extended as per | to the field by intermediaries, which can be extended per | |||
Section 2.2. Section 2.3 defines a set of error types for use when a | Section 2.2. Section 2.3 defines a set of error types for use when a | |||
proxy encounters an issue when obtaining a response for the request; | proxy encounters an issue when obtaining a response for the request; | |||
these can likewise be extended as per Section 2.4. | these can likewise be extended per Section 2.4. | |||
1.1. Notational Conventions | 1.1. Notational Conventions | |||
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | |||
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and | "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and | |||
"OPTIONAL" in this document are to be interpreted as described in BCP | "OPTIONAL" in this document are to be interpreted as described in | |||
14 [RFC2119] [RFC8174] when, and only when, they appear in all | BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all | |||
capitals, as shown here. | capitals, as shown here. | |||
This specification uses Structured Fields [STRUCTURED-FIELDS] to | This document uses the following terminology from Section 3 of | |||
specify syntax and parsing, and ABNF [RFC5234] as a shorthand for | [STRUCTURED-FIELDS] to specify syntax and parsing: List, String, | |||
that syntax. The terms sf-list, sf-item, sf-string, sf-token, sf- | Token, Integer, and Byte Sequence. | |||
integer and key refer to the structured types defined therein. | ||||
Note that in this specification, "proxy" is used to indicate both | Note that in this specification, "proxy" is used to indicate both | |||
forward and reverse proxies, otherwise known as gateways. "Next hop" | forward and reverse proxies, otherwise known as gateways. "Next hop" | |||
indicates the connection in the direction leading to the origin | indicates the connection in the direction leading to the origin | |||
server for the request. | server for the request. | |||
2. The Proxy-Status HTTP Field | 2. The Proxy-Status HTTP Field | |||
The Proxy-Status HTTP response field allows an intermediary to convey | The Proxy-Status HTTP response field allows an intermediary to convey | |||
additional information about its handling of a response and its | additional information about its handling of a response and its | |||
associated request. The syntax of this header field conforms to | associated request. | |||
[STRUCTURED-FIELDS]. | ||||
It is a List ([STRUCTURED-FIELDS], Section 3.1): | ||||
Proxy-Status = sf-list | ||||
Each member of the list represents an intermediary that has handled | Its value is a List (see Section 3.1 of [STRUCTURED-FIELDS]). Each | |||
the response. The first member of the list represents the | member of the List represents an intermediary that has handled the | |||
intermediary closest to the origin server, and the last member of the | response. The first member represents the intermediary closest to | |||
list represents the intermediary closest to the user agent. | the origin server, and the last member represents the intermediary | |||
closest to the user agent. | ||||
For example: | For example: | |||
Proxy-Status: revproxy1.example.net, ExampleCDN | Proxy-Status: revproxy1.example.net, ExampleCDN | |||
indicates that this response was handled first by | indicates that this response was handled first by | |||
revproxy1.example.net (a reverse proxy adjacent to the origin server) | revproxy1.example.net (a reverse proxy adjacent to the origin server) | |||
and then ExampleCDN. | and then ExampleCDN. | |||
Intermediaries determine when it is appropriate to add the Proxy- | Intermediaries determine when it is appropriate to add the Proxy- | |||
Status field to a response. Some might decide to append to it to all | Status field to a response. Some might decide to append it to all | |||
responses, whereas others might only do so when specifically | responses, whereas others might only do so when specifically | |||
configured to, or when the request contains a header field that | configured to or when the request contains a header field that | |||
activates a debugging mode. | activates a debugging mode. | |||
Each member of the list identifies the intermediary that inserted the | Each member of the List identifies the intermediary that inserted the | |||
value, and MUST have a type of either sf-string or sf-token. | value and MUST have a type of either String or Token . Depending on | |||
Depending on the deployment, this might be a service name (but not a | the deployment, this might be a service name (but not a software or | |||
software or hardware product name; e.g., "Example CDN"is appropriate, | hardware product name; e.g., "ExampleCDN" is appropriate, but | |||
but "ExampleProxy" is not, because it doesn't identify the | "ExampleProxy" is not because it doesn't identify the deployment), a | |||
deployment), a hostname ("proxy-3.example.com"), an IP address, or a | hostname ("proxy-3.example.com"), an IP address, or a generated | |||
generated string. | string. | |||
Parameters on each member (as per Section 3.1.2 of | Parameters of each member (per Section 3.1.2 of [STRUCTURED-FIELDS]) | |||
[STRUCTURED-FIELDS]) convey additional information about that | convey additional information about that intermediary's handling of | |||
intermediary's handling of the response and its associated request; | the response and its associated request; see Section 2.1. While all | |||
see Section 2.1. While all of these parameters are OPTIONAL, | of these parameters are OPTIONAL, intermediaries are encouraged to | |||
intermediaries are encouraged to provide as much information as | provide as much information as possible (but see Section 4 for | |||
possible (but see Section 4 for security considerations in doing so). | security considerations in doing so). | |||
When adding a value to the Proxy-Status field, intermediaries SHOULD | When adding a value to the Proxy-Status field, intermediaries SHOULD | |||
preserve the existing members of the field to allow debugging of the | preserve the existing members of the field to allow debugging of the | |||
entire chain of intermediaries handling the request, unless | entire chain of intermediaries handling the request unless explicitly | |||
explicitly configured to remove them (e.g., to prevent internal | configured to remove them (e.g., to prevent internal network details | |||
network details from leaking; see Section 4). | from leaking; see Section 4). | |||
Origin servers MUST NOT generate the Proxy-Status field. | Origin servers MUST NOT generate the Proxy-Status field. | |||
Proxy-Status MAY be sent as a HTTP trailer field. For example, if an | Proxy-Status MAY be sent as an HTTP trailer field. For example, if | |||
intermediary is streaming a response and the inbound connection | an intermediary is streaming a response and the inbound connection | |||
suddenly terminates, Proxy-Status can only be appended to the trailer | suddenly terminates, Proxy-Status can only be appended to the trailer | |||
section of the outbound message, since the header section has already | section of the outbound message since the header section has already | |||
been sent. However, because it might be silently discarded along the | been sent. However, because it might be silently discarded along the | |||
path to the user agent (as is the case for all trailer fields; see | path to the user agent (as is the case for all trailer fields; see | |||
Section 6.5 of [HTTP]), Proxy-Status SHOULD NOT be sent as a trailer | Section 6.5 of [HTTP]), Proxy-Status SHOULD NOT be sent as a trailer | |||
field unless it is not possible to send it in the header section. | field unless it is not possible to send it in the header section. | |||
To allow recipients to reconstruct the relative ordering of Proxy- | To allow recipients to reconstruct the relative ordering of Proxy- | |||
Status members conveyed in trailer fields with those conveyed in | Status members conveyed in trailer fields with those conveyed in | |||
header fields, an intermediary MUST NOT send Proxy-Status as a | header fields, an intermediary MUST NOT send Proxy-Status as a | |||
trailer field unless it has also generated a Proxy-Status header | trailer field unless it has also generated a Proxy-Status header | |||
field with the same member (although potentially different | field with the same member (although potentially different | |||
skipping to change at page 5, line 4 ¶ | skipping to change at page 4, line 46 ¶ | |||
parameters) in that message. | parameters) in that message. | |||
For example, a proxy identified as 'ThisProxy' that receives a | For example, a proxy identified as 'ThisProxy' that receives a | |||
response bearing a header field: | response bearing a header field: | |||
Proxy-Status: SomeOtherProxy | Proxy-Status: SomeOtherProxy | |||
would add its own entry to the header field: | would add its own entry to the header field: | |||
Proxy-Status: SomeOtherProxy, ThisProxy | Proxy-Status: SomeOtherProxy, ThisProxy | |||
thus allowing it to append a trailer field: | thus allowing it to append a trailer field: | |||
Proxy-Status: ThisProxy; error=read_timeout | Proxy-Status: ThisProxy; error=read_timeout | |||
which would thereby allow a downstream recipient to understand that | ||||
... which would thereby allow a downstream recipient to understand | processing by 'SomeOtherProxy' occurred before 'ThisProxy'. | |||
that processing by 'SomeOtherProxy' occurred before 'ThisProxy'. | ||||
A client MAY promote the Proxy-Status trailer field into a header | A client MAY promote the Proxy-Status trailer field into a header | |||
field by following these steps: | field by following these steps: | |||
1. For each member trailer_member of the Proxy-Status trailer field | 1. For each member trailer_member of the Proxy-Status trailer field | |||
value: | value: | |||
1. Let header_member be the first (left-most) value of the | 1. Let header_member be the first (leftmost) value of the Proxy- | |||
Proxy-Status header field value, comparing the sf-token or | Status header field value, comparing the String or Token | |||
sf-string character-by-character and without consideration of | character by character without consideration of parameters. | |||
parameters. | ||||
2. If no matching header_member is found, continue processing | 2. If no matching header_member is found, continue processing | |||
the next trailer_member. | the next trailer_member. | |||
3. Replace header_member with trailer_member in its entirety, | 3. Replace header_member with trailer_member in its entirety, | |||
including any parameters. | including any parameters. | |||
2. Remove the Proxy-Status trailer field, if empty. | 2. Remove the Proxy-Status trailer field if empty. | |||
2.1. Proxy-Status Parameters | 2.1. Proxy-Status Parameters | |||
This section lists parameters that can be used on the members of the | This section lists parameters that can be used on the members of the | |||
Proxy-Status field. Unrecognised parameters MUST be ignored. | Proxy-Status field. Unrecognised parameters MUST be ignored. | |||
2.1.1. error | 2.1.1. error | |||
The "error" parameter's value is an sf-token that is a Proxy Error | The "error" parameter's value is a Token that is a proxy error type. | |||
Type. When present, it indicates that the intermediary encountered | When present, it indicates that the intermediary encountered an issue | |||
an issue when obtaining this response. | when obtaining this response. | |||
The presence of some Proxy Error Types indicates that the response | The presence of some proxy error types indicates that the response | |||
was generated by the intermediary itself, rather than being forwarded | was generated by the intermediary itself, rather than being forwarded | |||
from the origin server. This is the case when, for example, the | from the origin server. This is the case when, for example, the | |||
origin server can't be contacted, so the proxy has to create its own | origin server can't be contacted, so the proxy has to create its own | |||
response. | response. | |||
Other Proxy Error Types can be added to (potentially partial) | Other proxy error types can be added to (potentially partial) | |||
responses that were generated by the origin server or some other | responses that were generated by the origin server or some other | |||
inbound server. For example, if the forward connection abruptly | inbound server. For example, if the forward connection abruptly | |||
closes, an intermediary might add Proxy-Status with an appropriate | closes, an intermediary might add Proxy-Status with an appropriate | |||
error as a trailer field. | error as a trailer field. | |||
Proxy Error Types that are registered with a 'Response only generated | Proxy error types that are registered with a 'Response only generated | |||
by intermediaries' value of 'true' indicate that they can only occur | by intermediaries' value of 'true' indicate that they can only occur | |||
on responses generated by the intermediary. If the value is 'false', | in responses generated by the intermediary. If the value is 'false', | |||
the response might be generated by the intermediary or an inbound | the response might be generated by the intermediary or an inbound | |||
server. | server. | |||
Section 2.3 lists the Proxy Error Types defined in this document; new | Section 2.3 lists the proxy error types defined in this document; new | |||
ones can be defined using the procedure outlined in Section 2.4. | ones can be defined using the procedure outlined in Section 2.4. | |||
For example: | For example: | |||
HTTP/1.1 504 Gateway Timeout | HTTP/1.1 504 Gateway Timeout | |||
Proxy-Status: ExampleCDN; error=connection_timeout | Proxy-Status: ExampleCDN; error=connection_timeout | |||
indicates that this 504 response was generated by ExampleCDN, due to | indicates that this 504 response was generated by ExampleCDN due to a | |||
a connection timeout when going forward. | connection timeout when going forward. | |||
Or: | Or: | |||
HTTP/1.1 429 Too Many Requests | HTTP/1.1 429 Too Many Requests | |||
Proxy-Status: r34.example.net; error=http_request_error, ExampleCDN | Proxy-Status: r34.example.net; error=http_request_error, ExampleCDN | |||
indicates that this 429 Too Many Requests response was generated by | indicates that this 429 (Too Many Requests) response was generated by | |||
r34.example.net, not the CDN or the origin. | r34.example.net, not the CDN or the origin. | |||
When sending the error parameter, the most specific Proxy Error Type | When sending the error parameter, the most specific proxy error type | |||
SHOULD be sent, provided that it accurately represents the error | SHOULD be sent, provided that it accurately represents the error | |||
condition. If an appropriate Proxy Error Type is not defined, there | condition. If an appropriate proxy error type is not defined, there | |||
are a number of generic error types (e.g., proxy_internal_error, | are a number of generic error types (e.g., proxy_internal_error, | |||
http_protocol_error) that can be used. If they are not suitable, | http_protocol_error) that can be used. If they are not suitable, | |||
consider registering a new Proxy Error Type (see Section 2.4). | consider registering a new proxy error type (see Section 2.4). | |||
Each Proxy Error Type has a Recommended HTTP Status Code. When | Each proxy error type has a recommended HTTP status code. When | |||
generating a HTTP response containing "error", its HTTP status code | generating an HTTP response containing the "error", its HTTP status | |||
SHOULD be set to the Recommended HTTP Status Code. However, there | code SHOULD be set to the recommended HTTP status code. However, | |||
may be circumstances (e.g., for backwards compatibility with previous | there may be circumstances (e.g., for backwards compatibility with | |||
behaviours, a status code has already been sent) when another status | previous behaviours, a status code has already been sent) when | |||
code might be used. | another status code might be used. | |||
Proxy Error Types can also define any number of extra parameters for | Proxy error types can also define any number of extra parameters for | |||
use with that type. Their use, like all parameters, is optional. As | use with that type. Their use, like all parameters, is optional. As | |||
a result, if an extra parameter is used with a Proxy Error Type for | a result, if an extra parameter is used with a proxy error type for | |||
which it is not defined, it will be ignored. | which it is not defined, it will be ignored. | |||
2.1.2. next-hop | 2.1.2. next-hop | |||
The "next-hop" parameter's value is an sf-string or sf-token that | The "next-hop" parameter's value is a String or Token that identifies | |||
identifies the intermediary or origin server selected (and used, if | the intermediary or origin server selected (and used, if contacted) | |||
contacted) to obtain this response. It might be a hostname, IP | to obtain this response. It might be a hostname, IP address, or | |||
address, or alias. | alias. | |||
For example: | For example: | |||
Proxy-Status: cdn.example.org; next-hop=backend.example.org:8001 | Proxy-Status: cdn.example.org; next-hop=backend.example.org:8001 | |||
indicates that cdn.example.org used backend.example.org:8001 as the | indicates that cdn.example.org used backend.example.org:8001 as the | |||
next hop for this request. | next hop for this request. | |||
2.1.3. next-protocol | 2.1.3. next-protocol | |||
The "next-protocol" parameter's value indicates the ALPN protocol | The "next-protocol" parameter's value indicates the Application-Layer | |||
identifier [RFC7301] of the protocol used by the intermediary to | Protocol Negotiation (ALPN) protocol identifier [RFC7301] of the | |||
connect to the next hop when obtaining this response. | protocol used by the intermediary to connect to the next hop when | |||
obtaining this response. | ||||
The value MUST be either an sf-token or sf-binary, representing a TLS | The value MUST be either a Token or Byte Sequence representing a TLS | |||
Application-Layer Protocol Negotiation (ALPN) Protocol ID (see | ALPN Protocol ID (see <https://www.iana.org/assignments/tls- | |||
https://www.iana.org/assignments/tls-extensiontype-values/tls- | extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol- | |||
extensiontype-values.xhtml#alpn-protocol-ids [4]). If the protocol | ids>). If the protocol identifier is able to be expressed as a Token | |||
identifier is able to be expressed as an sf-token using ASCII | using ASCII encoding, that form MUST be used. | |||
encoding, that form MUST be used. | ||||
For example: | For example: | |||
Proxy-Status: "proxy.example.org"; next-protocol=h2 | Proxy-Status: "proxy.example.org"; next-protocol=h2 | |||
Note that the APLN identifier is being used here to identify the | Note that the ALPN identifier is being used here to identify the | |||
protocol in use; it may or may not have been actually used in the | protocol in use; it may or may not have been actually used in the | |||
protocol negotiation. | protocol negotiation. | |||
2.1.4. received-status | 2.1.4. received-status | |||
The "received-status" parameter's value indicates the HTTP status | The "received-status" parameter's value indicates the HTTP status | |||
code that the intermediary received from the next hop server when | code that the intermediary received from the next-hop server when | |||
obtaining this response. | obtaining this response. | |||
The value MUST be an sf-integer. | The value MUST be an Integer. | |||
For example: | For example: | |||
Proxy-Status: ExampleCDN; received-status=200 | Proxy-Status: ExampleCDN; received-status=200 | |||
2.1.5. details | 2.1.5. details | |||
The "details" parameter's value is an sf-string containing additional | The "details" parameter's value is a String containing additional | |||
information not captured anywhere else. This can include | information not captured anywhere else. This can include | |||
implementation-specific or deployment-specific information. | implementation-specific or deployment-specific information. | |||
For example: | For example: | |||
Proxy-Status: proxy.example.net; error="http_protocol_error"; | Proxy-Status: proxy.example.net; error="http_protocol_error"; | |||
details="Malformed response header: space before colon" | details="Malformed response header: space before colon" | |||
2.2. Defining New Proxy-Status Parameters | 2.2. Defining New Proxy-Status Parameters | |||
New Proxy-Status Parameters can be defined by registering them in the | New Proxy-Status parameters can be defined by registering them in the | |||
HTTP Proxy-Status Parameters registry. | "HTTP Proxy-Status Parameters" registry. | |||
Registration requests are reviewed and approved by Expert Review, as | Registration requests are reviewed and approved by Expert Review, per | |||
per [RFC8126], Section 4.5. A specification document is appreciated, | [RFC8126], Section 4.5. A specification document is appreciated but | |||
but not required. | not required. | |||
The Expert(s) should consider the following factors when evaluating | The expert(s) should consider the following factors when evaluating | |||
requests: | requests: | |||
o Community feedback | o Community feedback | |||
o If the value is sufficiently well-defined | o If the value is sufficiently well defined | |||
o Generic parameters are preferred over vendor-specific, | o Generic parameters are preferred over vendor-specific, | |||
application-specific or deployment-specific values. If a generic | application-specific, or deployment-specific values. If a generic | |||
value cannot be agreed upon in the community, the parameter's name | value cannot be agreed upon in the community, the parameter's name | |||
should be correspondingly specific (e.g., with a prefix that | should be correspondingly specific (e.g., with a prefix that | |||
identifies the vendor, application or deployment). | identifies the vendor, application, or deployment). | |||
o Parameter names should not conflict with registered extra | o Parameter names should not conflict with registered extra | |||
parameters in the Proxy Error Type Registry. | parameters in the "HTTP Proxy Error Types" registry. | |||
Registration requests should use the following template: | Registration requests should use the following template: | |||
o Name: [a name for the Proxy-Status Parameter that matches key] | Name: [a name for the Proxy-Status parameter that matches key] | |||
o Description: [a description of the parameter semantics and value] | Description: [a description of the parameter semantics and value] | |||
o Reference: [to a specification defining this parameter; optional] | Reference: [to a specification defining this parameter; optional] | |||
See the registry at https://iana.org/assignments/http-proxy-status | See the registry at <https://www.iana.org/assignments/http-proxy- | |||
[5] for details on where to send registration requests. | status> for details on where to send registration requests. | |||
2.3. Proxy Error Types | 2.3. Proxy Error Types | |||
This section lists the Proxy Error Types defined by this document. | This section lists the proxy error types defined by this document. | |||
See Section 2.4 for information about defining new Proxy Error Types. | See Section 2.4 for information about defining new proxy error types. | |||
Note that implementations might not produce all Proxy Error Types. | Note that implementations might not produce all proxy error types. | |||
The set of types below is designed to map to existing states in | The set of types below is designed to map to existing states in | |||
implementations, and so may not be applicable to some. | implementations and therefore may not be applicable to some. | |||
2.3.1. DNS Timeout | 2.3.1. DNS Timeout | |||
o Name: dns_timeout | Name: dns_timeout | |||
o Description: The intermediary encountered a timeout when trying to | Description: The intermediary encountered a timeout when trying to | |||
find an IP address for the next hop hostname. | find an IP address for the next-hop hostname. | |||
o Extra Parameters: None. | Extra Parameters: None | |||
o Recommended HTTP status code: 504 | Recommended HTTP Status Code: 504 | |||
o Response only generated by intermediaries: true | Response Only Generated by Intermediaries: true | |||
o Reference: [this document] | Reference: RFC 9209 | |||
2.3.2. DNS Error | 2.3.2. DNS Error | |||
o Name: dns_error | Name: dns_error | |||
o Description: The intermediary encountered a DNS error when trying | Description: The intermediary encountered a DNS error when trying to | |||
to find an IP address for the next hop hostname. | find an IP address for the next-hop hostname. | |||
o Extra Parameters: | Extra Parameters: | |||
* rcode: A sf-string conveying the DNS RCODE that indicates the | rcode: A String conveying the DNS RCODE that indicates the error | |||
error type. See [RFC8499], Section 3. | type. See [RFC8499], Section 3. | |||
* info-code: A sf-integer conveying the Extended DNS Error Code | info-code: An Integer conveying the Extended DNS Error Code INFO- | |||
info-code. See [RFC8914]. | CODE. See [RFC8914]. | |||
o Recommended HTTP status code: 502 | Recommended HTTP Status Code: 502 | |||
o Response only generated by intermediaries: true | Response Only Generated by Intermediaries: true | |||
o Reference: [this document] | Reference: RFC 9209 | |||
2.3.3. Destination Not Found | 2.3.3. Destination Not Found | |||
o Name: destination_not_found | Name: destination_not_found | |||
o Description: The intermediary cannot determine the appropriate | Description: The intermediary cannot determine the appropriate next | |||
next hop to use for this request; for example, it may not be | hop to use for this request; for example, it may not be | |||
configured. Note that this error is specific to gateways, which | configured. Note that this error is specific to gateways, which | |||
typically require specific configuration to identify the "backend" | typically require specific configuration to identify the "backend" | |||
server; forward proxies use in-band information to identify the | server; forward proxies use in-band information to identify the | |||
origin server. | origin server. | |||
o Extra Parameters: None. | Extra Parameters: None | |||
Recommended HTTP Status Code: 500 | ||||
o Recommended HTTP status code: 500 | ||||
o Response only generated by intermediaries: true | Response Only Generated by Intermediaries: true | |||
o Reference: [this document] | Reference: RFC 9209 | |||
2.3.4. Destination Unavailable | 2.3.4. Destination Unavailable | |||
o Name: destination_unavailable | Name: destination_unavailable | |||
o Description: The intermediary considers the next hop to be | Description: The intermediary considers the next hop to be | |||
unavailable; e.g., recent attempts to communicate with it may have | unavailable; e.g., recent attempts to communicate with it may have | |||
failed, or a health check may indicate that it is down. | failed, or a health check may indicate that it is down. | |||
o Extra Parameters: None. | Extra Parameters: None | |||
o Recommended HTTP status code: 503 | Recommended HTTP Status Code: 503 | |||
o Response only generated by intermediaries: true | Response Only Generated by Intermediaries: true | |||
o Reference: [this document] | Reference: RFC 9209 | |||
2.3.5. Destination IP Prohibited | 2.3.5. Destination IP Prohibited | |||
o Name: destination_ip_prohibited | Name: destination_ip_prohibited | |||
o Description: The intermediary is configured to prohibit | Description: The intermediary is configured to prohibit connections | |||
connections to the next hop IP address. | to the next-hop IP address. | |||
o Extra Parameters: None. | Extra Parameters: None | |||
o Recommended HTTP status code: 502 | Recommended HTTP Status Code: 502 | |||
o Response only generated by intermediaries: true | Response Only Generated by Intermediaries: true | |||
o Reference: [this document] | ||||
2.3.6. Destination IP Unroutable | Reference: RFC 9209 | |||
o Name: destination_ip_unroutable | 2.3.6. Destination IP Unroutable | |||
o Description: The intermediary cannot find a route to the next hop | Name: destination_ip_unroutable | |||
IP address. | ||||
o Extra Parameters: None. | Description: The intermediary cannot find a route to the next-hop IP | |||
address. | ||||
o Recommended HTTP status code: 502 | Extra Parameters: None | |||
o Response only generated by intermediaries: true | Recommended HTTP Status Code: 502 | |||
Response Only Generated by Intermediaries: true | ||||
o Reference: [this document] | Reference: RFC 9209 | |||
2.3.7. Connection Refused | 2.3.7. Connection Refused | |||
o Name: connection_refused | Name: connection_refused | |||
o Description: The intermediary's connection to the next hop was | Description: The intermediary's connection to the next hop was | |||
refused. | refused. | |||
o Extra Parameters: None. | Extra Parameters: None | |||
o Recommended HTTP status code: 502 | Recommended HTTP Status Code: 502 | |||
o Response only generated by intermediaries: true | Response Only Generated by Intermediaries: true | |||
o Reference: [this document] | Reference: RFC 9209 | |||
2.3.8. Connection Terminated | 2.3.8. Connection Terminated | |||
o Name: connection_terminated | Name: connection_terminated | |||
o Description: The intermediary's connection to the next hop was | Description: The intermediary's connection to the next hop was | |||
closed before complete response was received. | closed before a complete response was received. | |||
o Extra Parameters: None. | Extra Parameters: None | |||
o Recommended HTTP status code: 502 | Recommended HTTP Status Code: 502 | |||
o Response only generated by intermediaries: false | Response Only Generated by Intermediaries: false | |||
o Reference: [this document] | Reference: RFC 9209 | |||
2.3.9. Connection Timeout | 2.3.9. Connection Timeout | |||
o Name: connection_timeout | Name: connection_timeout | |||
o Description: The intermediary's attempt to open a connection to | Description: The intermediary's attempt to open a connection to the | |||
the next hop timed out. | next hop timed out. | |||
o Extra Parameters: None. | Extra Parameters: None | |||
o Recommended HTTP status code: 504 | Recommended HTTP Status Code: 504 | |||
o Response only generated by intermediaries: true | Response Only Generated by Intermediaries: true | |||
o Reference: [this document] | Reference: RFC 9209 | |||
2.3.10. Connection Read Timeout | 2.3.10. Connection Read Timeout | |||
o Name: connection_read_timeout | Name: connection_read_timeout | |||
o Description: The intermediary was expecting data on a connection | Description: The intermediary was expecting data on a connection | |||
(e.g., part of a response), but did not receive any new data in a | (e.g., part of a response) but did not receive any new data in a | |||
configured time limit. | configured time limit. | |||
o Extra Parameters: None. | Extra Parameters: None | |||
o Recommended HTTP status code: 504 | Recommended HTTP Status Code: 504 | |||
o Response only generated by intermediaries: false | Response Only Generated by Intermediaries: false | |||
o Reference: [this document] | Reference: RFC 9209 | |||
2.3.11. Connection Write Timeout | 2.3.11. Connection Write Timeout | |||
o Name: connection_write_timeout | Name: connection_write_timeout | |||
o Description: The intermediary was attempting to write data to a | Description: The intermediary was attempting to write data to a | |||
connection, but was not able to (e.g., because its buffers were | connection but was not able to (e.g., because its buffers were | |||
full). | full). | |||
o Extra Parameters: None. | Extra Parameters: None | |||
o Recommended HTTP status code: 504 | Recommended HTTP Status Code: 504 | |||
o Response only generated by intermediaries: false | Response Only Generated by Intermediaries: false | |||
o Reference: [this document] | Reference: RFC 9209 | |||
2.3.12. Connection Limit Reached | 2.3.12. Connection Limit Reached | |||
o Name: connection_limit_reached | Name: connection_limit_reached | |||
o Description: The intermediary is configured to limit the number of | Description: The intermediary is configured to limit the number of | |||
connections it has to the next hop, and that limit has been | connections it has to the next hop, and that limit has been | |||
passed. | exceeded. | |||
o Extra Parameters: None. | Extra Parameters: None | |||
o Recommended HTTP status code: 503 | Recommended HTTP Status Code: 503 | |||
o Response only generated by intermediaries: true | Response Only Generated by Intermediaries: true | |||
o Reference: [this document] | Reference: RFC 9209 | |||
2.3.13. TLS Protocol Error | 2.3.13. TLS Protocol Error | |||
o Name: tls_protocol_error | Name: tls_protocol_error | |||
o Description: The intermediary encountered a TLS error when | Description: The intermediary encountered a TLS error when | |||
communicating with the next hop, either during handshake or | communicating with the next hop, either during the handshake or | |||
afterwards. | afterwards. | |||
o Extra Parameters: None. | Extra Parameters: None | |||
o Recommended HTTP status code: 502 | Recommended HTTP Status Code: 502 | |||
o Response only generated by intermediaries: false | Response Only Generated by Intermediaries: false | |||
o Reference: [this document] | Reference: RFC 9209 | |||
o Notes: Not appropriate when a TLS alert is received; see | Notes: Not appropriate when a TLS alert is received; see | |||
tls_alert_received | tls_alert_received. | |||
2.3.14. TLS Certificate Error | 2.3.14. TLS Certificate Error | |||
o Name: tls_certificate_error | Name: tls_certificate_error | |||
o Description: The intermediary encountered an error when verifying | Description: The intermediary encountered an error when verifying | |||
the certificate presented by the next hop. | the certificate presented by the next hop. | |||
o Extra Parameters: None. | Extra Parameters: None | |||
o Recommended HTTP status code: 502 | Recommended HTTP Status Code: 502 | |||
o Response only generated by intermediaries: true | Response Only Generated by Intermediaries: true | |||
o Reference: [this document] | ||||
Reference: RFC 9209 | ||||
2.3.15. TLS Alert Received | 2.3.15. TLS Alert Received | |||
o Name: tls_alert_received | Name: tls_alert_received | |||
o Description: The intermediary received a TLS alert from the next | Description: The intermediary received a TLS alert from the next | |||
hop. | hop. | |||
o Extra Parameters: | Extra Parameters: | |||
* alert-id: an sf-integer containing the applicable value from | alert-id: An Integer containing the applicable value from the | |||
the TLS Alerts registry. See {!RFC8446}}. | "TLS Alerts" registry. See [RFC8446]. | |||
* alert-message: an sf-token or sf-string containing the | alert-message: A Token or String containing the applicable | |||
applicable description string from the TLS Alerts registry. | description string from the "TLS Alerts" registry. See | |||
See [RFC8446]. | [RFC8446]. | |||
o Recommended HTTP status code: 502 | Recommended HTTP Status Code: 502 | |||
o Response only generated by intermediaries: false | Response Only Generated by Intermediaries: false | |||
o Reference: [this document] | Reference: RFC 9209 | |||
2.3.16. HTTP Request Error | 2.3.16. HTTP Request Error | |||
o Name: http_request_error | Name: http_request_error | |||
o Description: The intermediary is generating a client (4xx) | Description: The intermediary is generating a client (4xx) response | |||
response on the origin's behalf. Applicable status codes include | on the origin's behalf. Applicable status codes include (but are | |||
(but are not limited to) 400, 403, 405, 406, 408, 411, 413, 414, | not limited to) 400, 403, 405, 406, 408, 411, 413, 414, 415, 416, | |||
415, 416, 417, 429. | 417, and 429. | |||
o Extra Parameters: | Extra Parameters: | |||
* status-code: an sf-integer containing the generated status | status-code: An Integer containing the generated status code. | |||
code. | ||||
* status-phrase: an sf-string containing the generated status | status-phrase: A String containing the generated status phrase. | |||
phrase. | ||||
o Recommended HTTP status code: The applicable 4xx status code | Recommended HTTP Status Code: The applicable 4xx status code | |||
o Response only generated by intermediaries: true | Response Only Generated by Intermediaries: true | |||
o Reference: [this document] | Reference: RFC 9209 | |||
o Notes: This type helps distinguish between responses generated by | ||||
Notes: This type helps distinguish between responses generated by | ||||
intermediaries from those generated by the origin. | intermediaries from those generated by the origin. | |||
2.3.17. HTTP Request Denied | 2.3.17. HTTP Request Denied | |||
o Name: http_request_denied | Name: http_request_denied | |||
o Description: The intermediary rejected the HTTP request based on | Description: The intermediary rejected the HTTP request based on its | |||
its configuration and/or policy settings. The request wasn't | configuration and/or policy settings. The request wasn't | |||
forwarded to the next hop. | forwarded to the next hop. | |||
o Extra Parameters: None. | Extra Parameters: None | |||
o Recommended HTTP status code: 403 | ||||
o Response only generated by intermediaries: true | Recommended HTTP Status Code: 403 | |||
o Reference: [this document] | Response Only Generated by Intermediaries: true | |||
Reference: RFC 9209 | ||||
2.3.18. HTTP Incomplete Response | 2.3.18. HTTP Incomplete Response | |||
o Name: http_response_incomplete | Name: http_response_incomplete | |||
o Description: The intermediary received an incomplete response to | Description: The intermediary received an incomplete response to the | |||
the request from the next hop. | request from the next hop. | |||
o Extra Parameters: None. | Extra Parameters: None | |||
o Recommended HTTP status code: 502 | Recommended HTTP Status Code: 502 | |||
o Response only generated by intermediaries: false | Response Only Generated by Intermediaries: false | |||
o Reference: [this document] | Reference: RFC 9209 | |||
2.3.19. HTTP Response Header Section Too Large | 2.3.19. HTTP Response Header Section Too Large | |||
o Name: http_response_header_section_size | Name: http_response_header_section_size | |||
o Description: The intermediary received a response to the request | Description: The intermediary received a response to the request | |||
whose header section was considered too large. | whose header section was considered too large. | |||
o Extra Parameters: | Extra Parameters: | |||
* header-section-size: an sf-integer indicating how large the | header-section-size: An Integer indicating how large the received | |||
headers received were. Note that they might not be complete; | headers were. Note that they might not be complete; i.e., the | |||
i.e., the intermediary may have discarded or refused additional | intermediary may have discarded or refused additional data. | |||
data. | ||||
o Recommended HTTP status code: 502 | Recommended HTTP Status Code: 502 | |||
o Response only generated by intermediaries: false | Response Only Generated by Intermediaries: false | |||
o Reference: [this document] | Reference: RFC 9209 | |||
2.3.20. HTTP Response Header Field Line Too Large | 2.3.20. HTTP Response Header Field Line Too Large | |||
o Name: http_response_header_size | Name: http_response_header_size | |||
o Description: The intermediary received a response to the request | Description: The intermediary received a response to the request | |||
containing an individual header field line that was considered too | containing an individual header field line that was considered too | |||
large. | large. | |||
o Extra Parameters: | Extra Parameters: | |||
* header-name: an sf-string indicating the name of the header | header-name: A String indicating the name of the header field | |||
field that triggered the error. | that triggered the error. | |||
* header-size: an sf-integer indicating the size of the header | header-size: An Integer indicating the size of the header field | |||
field that triggered the error. | that triggered the error. | |||
o Recommended HTTP status code: 502 | Recommended HTTP Status Code: 502 | |||
o Response only generated by intermediaries: false | Response Only Generated by Intermediaries: false | |||
o Reference: [this document] | Reference: RFC 9209 | |||
2.3.21. HTTP Response Body Too Large | 2.3.21. HTTP Response Body Too Large | |||
o Name: http_response_body_size | Name: http_response_body_size | |||
o Description: The intermediary received a response to the request | Description: The intermediary received a response to the request | |||
whose body was considered too large. | whose body was considered too large. | |||
o Extra Parameters: | Extra Parameters: | |||
* body-size: an sf-integer indicating how large the body received | body-size: An Integer indicating how large the received body was. | |||
was. Note that it may not have been complete; i.e., the | Note that it may not have been complete; i.e., the intermediary | |||
intermediary may have discarded or refused additional data. | may have discarded or refused additional data. | |||
o Recommended HTTP status code: 502 | Recommended HTTP Status Code: 502 | |||
o Response only generated by intermediaries: false | Response Only Generated by Intermediaries: false | |||
o Reference: [this document] | Reference: RFC 9209 | |||
2.3.22. HTTP Response Trailer Section Too Large | 2.3.22. HTTP Response Trailer Section Too Large | |||
o Name: http_response_trailer_section_size | Name: http_response_trailer_section_size | |||
o Description: The intermediary received a response to the request | Description: The intermediary received a response to the request | |||
whose trailer section was considered too large. | whose trailer section was considered too large. | |||
o Extra Parameters: | Extra Parameters: | |||
* trailer-section-size: an sf-integer indicating how large the | trailer-section-size: An Integer indicating how large the | |||
trailers received were. Note that they might not be complete; | received trailers were. Note that they might not be complete; | |||
i.e., the intermediary may have discarded or refused additional | i.e., the intermediary may have discarded or refused additional | |||
data. | data. | |||
o Recommended HTTP status code: 502 | Recommended HTTP Status Code: 502 | |||
o Response only generated by intermediaries: false | Response Only Generated by Intermediaries: false | |||
o Reference: [this document] | Reference: RFC 9209 | |||
2.3.23. HTTP Response Trailer Field Line Too Large | 2.3.23. HTTP Response Trailer Field Line Too Large | |||
o Name: http_response_trailer_size | Name: http_response_trailer_size | |||
o Description: The intermediary received a response to the request | Description: The intermediary received a response to the request | |||
containing an individual trailer field line that was considered | containing an individual trailer field line that was considered | |||
too large. | too large. | |||
o Extra Parameters: | Extra Parameters: | |||
* trailer-name: an sf-string indicating the name of the trailer | trailer-name: A String indicating the name of the trailer field | |||
field that triggered the error. | that triggered the error. | |||
* trailer-size: an sf-integer indicating the size of the trailer | trailer-size: An Integer indicating the size of the trailer field | |||
field that triggered the error. | that triggered the error. | |||
o Recommended HTTP status code: 502 | Recommended HTTP Status Code: 502 | |||
o Response only generated by intermediaries: false | Response Only Generated by Intermediaries: false | |||
o Reference: [this document] | Reference: RFC 9209 | |||
2.3.24. HTTP Response Transfer-Coding Error | 2.3.24. HTTP Response Transfer-Coding Error | |||
o Name: http_response_transfer_coding | Name: http_response_transfer_coding | |||
o Description: The intermediary encountered an error decoding the | Description: The intermediary encountered an error decoding the | |||
transfer-coding of the response. | transfer coding of the response. | |||
o Extra Parameters: | Extra Parameters: | |||
* coding: an sf-token containing the specific coding (from the | coding: A Token containing the specific coding (from the "HTTP | |||
HTTP Transfer Coding Registry) that caused the error. | Transfer Coding Registry") that caused the error. | |||
o Recommended HTTP status code: 502 | Recommended HTTP Status Code: 502 | |||
o Response only generated by intermediaries: false | Response Only Generated by Intermediaries: false | |||
o Reference: [this document] | Reference: RFC 9209 | |||
2.3.25. HTTP Response Content-Coding Error | 2.3.25. HTTP Response Content-Coding Error | |||
o Name: http_response_content_coding | Name: http_response_content_coding | |||
o Description: The intermediary encountered an error decoding the | Description: The intermediary encountered an error decoding the | |||
content-coding of the response. | content coding of the response. | |||
o Extra Parameters: | Extra Parameters: | |||
* coding: an sf-token containing the specific coding (from the | coding: A Token containing the specific coding (from the "HTTP | |||
HTTP Content Coding Registry) that caused the error. | Content Coding Registry") that caused the error. | |||
o Recommended HTTP status code: 502 | Recommended HTTP Status Code: 502 | |||
o Response only generated by intermediaries: false | Response Only Generated by Intermediaries: false | |||
o Reference: [this document] | Reference: RFC 9209 | |||
2.3.26. HTTP Response Timeout | 2.3.26. HTTP Response Timeout | |||
o Name: http_response_timeout | Name: http_response_timeout | |||
o Description: The intermediary reached a configured time limit | Description: The intermediary reached a configured time limit | |||
waiting for the complete response. | waiting for the complete response. | |||
o Extra Parameters: None. | Extra Parameters: None | |||
o Recommended HTTP status code: 504 | Recommended HTTP Status Code: 504 | |||
o Response only generated by intermediaries: false | Response Only Generated by Intermediaries: false | |||
o Reference: [this document] | Reference: RFC 9209 | |||
2.3.27. HTTP Upgrade Failed | 2.3.27. HTTP Upgrade Failed | |||
o Name: http_upgrade_failed | Name: http_upgrade_failed | |||
o Description: The HTTP Upgrade between the intermediary and the | Description: The process of negotiating an upgrade of the HTTP | |||
next hop failed. | version between the intermediary and the next hop failed. | |||
o Extra Parameters: None. | Extra Parameters: None | |||
o Recommended HTTP status code: 502 | Recommended HTTP Status Code: 502 | |||
o Response only generated by intermediaries: true | Response Only Generated by Intermediaries: true | |||
o Reference: [this document] | Reference: RFC 9209 | |||
2.3.28. HTTP Protocol Error | 2.3.28. HTTP Protocol Error | |||
o Name: http_protocol_error | Name: http_protocol_error | |||
o Description: The intermediary encountered a HTTP protocol error | Description: The intermediary encountered an HTTP protocol error | |||
when communicating with the next hop. This error should only be | when communicating with the next hop. This error should only be | |||
used when a more specific one is not defined. | used when a more specific one is not defined. | |||
o Extra Parameters: None. | Extra Parameters: None | |||
Recommended HTTP Status Code: 502 | ||||
o Recommended HTTP status code: 502 | ||||
o Response only generated by intermediaries: false | Response Only Generated by Intermediaries: false | |||
o Reference: [this document] | Reference: RFC 9209 | |||
2.3.29. Proxy Internal Response | 2.3.29. Proxy Internal Response | |||
o Name: proxy_internal_response | Name: proxy_internal_response | |||
o Description: The intermediary generated the response locally, | Description: The intermediary generated the response itself without | |||
without attempting to connect to the next hop (e.g. in response to | attempting to connect to the next hop. | |||
a request to a debug endpoint terminated at the intermediary). | ||||
o Extra Parameters: None. | Extra Parameters: None | |||
o Recommended HTTP status code: The most appropriate status code for | Recommended HTTP Status Code: The most appropriate status code for | |||
the response | the response | |||
o Response only generated by intermediaries: true | Response Only Generated by Intermediaries: true | |||
o Reference: [this document] | Reference: RFC 9209 | |||
2.3.30. Proxy Internal Error | 2.3.30. Proxy Internal Error | |||
o Name: proxy_internal_error | Name: proxy_internal_error | |||
o Description: The intermediary encountered an internal error | Description: The intermediary encountered an internal error | |||
unrelated to the origin. | unrelated to the origin. | |||
o Extra Parameters: None | Extra Parameters: None | |||
o Recommended HTTP status code: 500 | Recommended HTTP Status Code: 500 | |||
o Response only generated by intermediaries: true | Response Only Generated by Intermediaries: true | |||
o Reference: [this document] | Reference: RFC 9209 | |||
2.3.31. Proxy Configuration Error | 2.3.31. Proxy Configuration Error | |||
o Name: proxy_configuration_error | Name: proxy_configuration_error | |||
o Description: The intermediary encountered an error regarding its | Description: The intermediary encountered an error regarding its | |||
configuration. | configuration. | |||
o Extra Parameters: None | Extra Parameters: None | |||
o Recommended HTTP status code: 500 | ||||
o Response only generated by intermediaries: true | Recommended HTTP Status Code: 500 | |||
Response Only Generated by Intermediaries: true | ||||
o Reference: [this document] | Reference: RFC 9209 | |||
2.3.32. Proxy Loop Detected | 2.3.32. Proxy Loop Detected | |||
o Name: proxy_loop_detected | Name: proxy_loop_detected | |||
o Description: The intermediary tried to forward the request to | Description: The intermediary tried to forward the request to | |||
itself, or a loop has been detected using different means (e.g. | itself, or a loop has been detected using different means (e.g., | |||
[RFC8586]). | [RFC8586]). | |||
o Extra Parameters: None. | Extra Parameters: None | |||
o Recommended HTTP status code: 502 | Recommended HTTP Status Code: 502 | |||
o Response only generated by intermediaries: true | Response Only Generated by Intermediaries: true | |||
o Reference: [this document] | Reference: RFC 9209 | |||
2.4. Defining New Proxy Error Types | 2.4. Defining New Proxy Error Types | |||
New Proxy Error Types can be defined by registering them in the HTTP | New proxy error types can be defined by registering them in the "HTTP | |||
Proxy Error Types registry. | Proxy Error Types" registry. | |||
Registration requests are reviewed and approved by Expert Review, as | Registration requests are reviewed and approved by Expert Review, per | |||
per [RFC8126], Section 4.5. A specification document is appreciated, | [RFC8126], Section 4.5. A specification document is appreciated but | |||
but not required. | not required. | |||
The Expert(s) should consider the following factors when evaluating | The expert(s) should consider the following factors when evaluating | |||
requests: | requests: | |||
o Community feedback | o Community feedback | |||
o If the value is sufficiently well-defined | o If the value is sufficiently well-defined | |||
o Generic types are preferred over vendor-specific, application- | o Generic types are preferred over vendor-specific, application- | |||
specific or deployment-specific values. If a generic value cannot | specific, or deployment-specific values. If a generic value | |||
be agreed upon in the community, the types's name should be | cannot be agreed upon in the community, the type's name should be | |||
correspondingly specific (e.g., with a prefix that identifies the | correspondingly specific (e.g., with a prefix that identifies the | |||
vendor, application or deployment). | vendor, application, or deployment). | |||
o Extra Parameters should not conflict with registered Proxy-Status | o Extra parameters should not conflict with registered Proxy-Status | |||
parameters. | parameters. | |||
Registration requests should use the following template: | Registration requests should use the following template: | |||
o Name: [a name for the Proxy Error Type that matches sf-token] | Name: [a name for the proxy error type that is of type Token ] | |||
Description: [a description of the conditions that generate the | ||||
o Description: [a description of the conditions that generate the | proxy error type] | |||
Proxy Error Type] | ||||
o Extra Parameters: [zero or more optional parameters, along with | Extra Parameters: [zero or more optional parameters, along with | |||
their allowable type(s)] | their allowable Structured Type(s)] | |||
o Recommended HTTP status code: [the appropriate HTTP status code | Recommended HTTP Status Code: [the appropriate HTTP status code for | |||
for this entry] | this entry] | |||
o Response only generated by intermediaries: ['true' or 'false'] | Response Only Generated by Intermediaries: ['true' or 'false'] | |||
o Reference: [to a specification defining this error type; optional] | Reference: [to a specification defining this error type; optional] | |||
o Notes: [optional] | Notes: [optional] | |||
If the Proxy Error Type might occur in responses that are not | If the proxy error type might occur in responses that are not | |||
generated by the intermediary -- for example, when an error is | generated by the intermediary -- for example, when an error is | |||
detected as the response is streamed from a forward connection, | detected as the response is streamed from a forward connection, | |||
causing a Proxy-Status trailer field to be appended -- the 'Response | causing a Proxy-Status trailer field to be appended -- the 'Response | |||
only generated by intermediaries' should be 'false'. If the Proxy | only generated by intermediaries' should be 'false'. If the proxy | |||
Error Type only occurs in responses that are generated by the | error type only occurs in responses that are generated by the | |||
intermediary, it should be 'true'. | intermediary, it should be 'true'. | |||
See the registry at https://iana.org/assignments/http-proxy-status | See the registry at <https://www.iana.org/assignments/http-proxy- | |||
[6] for details on where to send registration requests. | status> for details on where to send registration requests. | |||
3. IANA Considerations | 3. IANA Considerations | |||
Upon publication, please create the HTTP Proxy-Status Parameters | IANA has created the "HTTP Proxy-Status Parameters" registry and the | |||
registry and the HTTP Proxy Error Types registry at | "HTTP Proxy Error Types" registry at | |||
https://iana.org/assignments/http-proxy-status [7] and populate them | <https://www.iana.org/assignments/http-proxy-status> and has | |||
with the types defined in Section 2.1 and Section 2.3 respectively; | populated them with the types defined in Sections 2.1 and 2.3 | |||
see Section 2.2 and Section 2.4 for its associated procedures. | respectively; see Sections 2.2 and 2.4 for their associated | |||
procedures. | ||||
Additionally, please register the following entry in the Hypertext | ||||
Transfer Protocol (HTTP) Field Name Registry: | ||||
o Field name: Proxy-Status | Additionally, the following entry has been added to the "Hypertext | |||
Transfer Protocol (HTTP) Field Name Registry": | ||||
o Status: permanent | Field name: Proxy-Status | |||
o Specification document(s): [this document] | Status: permanent | |||
o Comments: | Specification document(s): RFC 9209 | |||
4. Security Considerations | 4. Security Considerations | |||
One of the primary security concerns when using Proxy-Status is | One of the primary security concerns when using Proxy-Status is | |||
leaking information that might aid an attacker. For example, | leaking information that might aid an attacker. For example, | |||
information about the intermediary's configuration and back-end | information about the intermediary's configuration and backend | |||
topology can be exposed, allowing attackers to directly target back- | topology can be exposed, allowing attackers to directly target | |||
end services that are not prepared for high traffic volume or | backend services that are not prepared for high traffic volume or | |||
malformed inputs. Some information might only be suitable to reveal | malformed inputs. Some information might only be suitable to reveal | |||
to authorized parties. | to authorized parties. | |||
As a result, care needs to be taken when deciding to generate a | As a result, care needs to be taken when deciding to generate a | |||
Proxy-Status field and what information to include in it. Note that | Proxy-Status field and what information to include in it. Note that | |||
intermediaries are not required to generate a Proxy-Status field in | intermediaries are not required to generate a Proxy-Status field in | |||
any response, and can conditionally generate them based upon request | any response and can conditionally generate them based upon request | |||
attributes (e.g., authentication tokens, IP address). | attributes (e.g., authentication tokens, IP address). | |||
Likewise, generation of all parameters is optional, as is generation | Likewise, generation of all parameters is optional, as is the | |||
of the field itself. Also, the field's content is not verified; an | generation of the field itself. Also, the field's content is not | |||
intermediary can claim certain actions (e.g., sending a request over | verified; an intermediary can claim certain actions (e.g., sending a | |||
an encrypted channel) but fail to actually do that. | request over an encrypted channel) but fail to actually do that. | |||
5. References | 5. References | |||
5.1. Normative References | 5.1. Normative References | |||
[HTTP] Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP | [HTTP] Fielding, R., Nottingham, M., and J. Reschke, "HTTP | |||
Semantics", draft-ietf-httpbis-semantics-19 (work in | Semantics", draft-ietf-httpbis-semantics-19 (work in | |||
progress), September 2021. | progress), September 2021. | |||
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate | [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate | |||
Requirement Levels", BCP 14, RFC 2119, | Requirement Levels", BCP 14, RFC 2119, | |||
DOI 10.17487/RFC2119, March 1997, | DOI 10.17487/RFC2119, March 1997, | |||
<https://www.rfc-editor.org/info/rfc2119>. | <https://www.rfc-editor.org/info/rfc2119>. | |||
[RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, | [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, | |||
"Transport Layer Security (TLS) Application-Layer Protocol | "Transport Layer Security (TLS) Application-Layer Protocol | |||
skipping to change at page 23, line 46 ¶ | skipping to change at page 23, line 19 ¶ | |||
[RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS | [RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS | |||
Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, | Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, | |||
January 2019, <https://www.rfc-editor.org/info/rfc8499>. | January 2019, <https://www.rfc-editor.org/info/rfc8499>. | |||
[RFC8914] Kumari, W., Hunt, E., Arends, R., Hardaker, W., and D. | [RFC8914] Kumari, W., Hunt, E., Arends, R., Hardaker, W., and D. | |||
Lawrence, "Extended DNS Errors", RFC 8914, | Lawrence, "Extended DNS Errors", RFC 8914, | |||
DOI 10.17487/RFC8914, October 2020, | DOI 10.17487/RFC8914, October 2020, | |||
<https://www.rfc-editor.org/info/rfc8914>. | <https://www.rfc-editor.org/info/rfc8914>. | |||
[STRUCTURED-FIELDS] | [STRUCTURED-FIELDS] | |||
Nottingham, M. and P-H. Kamp, "Structured Field Values for | Nottingham, M. and P. Kamp, "Structured Field Values for | |||
HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, | HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, | |||
<https://www.rfc-editor.org/info/rfc8941>. | <https://www.rfc-editor.org/info/rfc8941>. | |||
5.2. Informative References | 5.2. Informative References | |||
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax | ||||
Specifications: ABNF", STD 68, RFC 5234, | ||||
DOI 10.17487/RFC5234, January 2008, | ||||
<https://www.rfc-editor.org/info/rfc5234>. | ||||
[RFC8586] Ludin, S., Nottingham, M., and N. Sullivan, "Loop | [RFC8586] Ludin, S., Nottingham, M., and N. Sullivan, "Loop | |||
Detection in Content Delivery Networks (CDNs)", RFC 8586, | Detection in Content Delivery Networks (CDNs)", RFC 8586, | |||
DOI 10.17487/RFC8586, April 2019, | DOI 10.17487/RFC8586, April 2019, | |||
<https://www.rfc-editor.org/info/rfc8586>. | <https://www.rfc-editor.org/info/rfc8586>. | |||
5.3. URIs | ||||
[1] https://lists.w3.org/Archives/Public/ietf-http-wg/ | ||||
[2] https://httpwg.org/ | ||||
[3] https://github.com/httpwg/http-extensions/labels/proxy-status | ||||
[4] https://www.iana.org/assignments/tls-extensiontype-values/tls- | ||||
extensiontype-values.xhtml#alpn-protocol-ids | ||||
[5] https://iana.org/assignments/http-proxy-status | ||||
[6] https://iana.org/assignments/http-proxy-status | ||||
[7] https://iana.org/assignments/http-proxy-status | ||||
Authors' Addresses | Authors' Addresses | |||
Mark Nottingham | Mark Nottingham | |||
Fastly | Fastly | |||
Prahran | Prahran | |||
Australia | Australia | |||
Email: mnot@mnot.net | Email: mnot@mnot.net | |||
URI: https://www.mnot.net/ | URI: https://www.mnot.net/ | |||
End of changes. 294 change blocks. | ||||
451 lines changed or deleted | 418 lines changed or added | |||
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/ |