draft-ietf-httpbis-proxy-status-06.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: February 17, 2022 Google Expires: March 26, 2022 Google
August 16, 2021 September 22, 2021
The Proxy-Status HTTP Response Header Field The Proxy-Status HTTP Response Header Field
draft-ietf-httpbis-proxy-status-06 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 field to convey the
details of intermediary response handling, including generated details of intermediary response handling, including generated
errors. errors.
Note to Readers Note to Readers
_RFC EDITOR: please remove this section before publication_ _RFC EDITOR: please remove this section before publication_
skipping to change at page 1, line 45 skipping to change at page 1, line 45
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 February 17, 2022. This Internet-Draft will expire on March 26, 2022.
Copyright Notice Copyright Notice
Copyright (c) 2021 IETF Trust and the persons identified as the Copyright (c) 2021 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 -- including both forward proxies and gateways HTTP intermediaries (see Section 3.7 of [HTTP]) -- including both
(also known as "reverse proxies") -- have become an increasingly forward proxies and gateways (also known as "reverse proxies") --
significant part of HTTP deployments. In particular, reverse proxies have become an increasingly significant part of HTTP deployments. In
and Content Delivery Networks (CDNs) form part of the critical particular, reverse proxies and Content Delivery Networks (CDNs) form
infrastructure of many Web sites. part of the critical infrastructure of many Web sites.
Typically, HTTP intermediaries forward requests towards the origin Typically, HTTP intermediaries forward requests towards the origin
server and then forward their responses back to clients. However, if server (inbound) and then forward their responses back to clients
an error occurs before a response is obtained from upstream, the (outbound). However, if an error occurs before a response is
response is often generated by the intermediary itself. obtained from an inbound server, the response is often generated by
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; for
example, 502 Bad Gateway and 504 Gateway Timeout. However, 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
skipping to change at page 3, line 13 skipping to change at page 3, line 13
these can likewise be extended as per Section 2.4. these can likewise be extended as 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 BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
This specification uses Structured Fields [RFC8941] to specify syntax This specification uses Structured Fields [STRUCTURED-FIELDS] to
and parsing, and ABNF [RFC5234] as a shorthand for that syntax. The specify syntax and parsing, and ABNF [RFC5234] as a shorthand for
terms sf-list, sf-item, sf-string, sf-token, sf-integer and key refer that syntax. The terms sf-list, sf-item, sf-string, sf-token, sf-
to the structured types defined therein. 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. associated request. The syntax of this header field conforms to
[STRUCTURED-FIELDS].
It is a List ([RFC8941], Section 3.1): It is a List ([STRUCTURED-FIELDS], Section 3.1):
Proxy-Status = sf-list Proxy-Status = sf-list
Each member of the list represents an intermediary that has handled Each member of the list represents an intermediary that has handled
the response. The first member of the list represents the the response. The first member of the list represents the
intermediary closest to the origin server, and the last member of the intermediary closest to the origin server, and the last member of the
list represents the intermediary closest to the user agent. list represents the intermediary closest to the user agent.
For example: For example:
Proxy-Status: FooProxy, ExampleCDN Proxy-Status: revproxy1.example.net, ExampleCDN
indicates that this response was handled first by FooProxy (a reverse indicates that this response was handled first by
proxy adjacent to the origin server) and then ExampleCDN. revproxy1.example.net (a reverse proxy adjacent to the origin server)
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 to 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 that activates a configured to, or when the request contains a header field that
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 sf-string or sf-token.
Depending on the deployment, this might be a service name (but not a
software or hardware product name; e.g., "Example CDN"is appropriate,
but "ExampleProxy" is not, because it doesn't identify the
deployment), a hostname ("proxy-3.example.com"), an IP address, or a
generated string.
Depending on the deployment, this might be a product or service name Parameters on each member (as per Section 3.1.2 of
(e.g., ExampleProxy or "Example CDN"), a hostname ("proxy- [STRUCTURED-FIELDS]) convey additional information about that
3.example.com"), an IP address, or a generated string.
Parameters on each member convey additional information about that
intermediary's handling of the response and its associated request; intermediary's handling of the response and its associated request;
see Section 2.1. While all of these parameters are OPTIONAL, see Section 2.1. While all of these parameters are OPTIONAL,
intermediaries are encouraged to provide as much information as intermediaries are encouraged to provide as much information as
possible (but see Section 4 for security considerations in doing so). possible (but see Section 4 for 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. entire chain of intermediaries handling the request, unless
explicitly configured to remove them (e.g., to prevent internal
Proxy-Status MAY be sent in HTTP trailers. For example, if an network details from leaking; see Section 4).
intermediary is streaming a response and the upstream connection
suddenly terminates, Proxy-Status can only be appended to the
trailers of the outgoing message, since the headers have already been
sent. As with all trailers, it might be silently discarded along the
path to the user agent, so this SHOULD NOT be done unless it is not
possible to send it in headers, and an intermediary MUST NOT send
Proxy-Status as a trailer field unless it has also sent a
corresponding Proxy-Status header field in the same message, so that
the trailer value's ordering relative to other intermediaries is
preserved.
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
intermediary is streaming a response and the inbound connection
suddenly terminates, Proxy-Status can only be appended to the trailer
section of the outbound message, since the header section has already
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
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.
To allow recipients to reconstruct the relative ordering of Proxy-
Status members conveyed in trailer fields with those conveyed in
header fields, an intermediary MUST NOT send Proxy-Status as a
trailer field unless it has also generated a Proxy-Status header
field with the same member (although potentially different
parameters) in that message.
For example, a proxy identified as 'ThisProxy' that receives a
response bearing a header field:
Proxy-Status: SomeOtherProxy
would add its own entry to the header field:
Proxy-Status: SomeOtherProxy, ThisProxy
thus allowing it to append a trailer field:
Proxy-Status: ThisProxy; error=read_timeout
... which would thereby allow a downstream recipient to understand
that processing by 'SomeOtherProxy' occurred before 'ThisProxy'.
A client MAY promote the Proxy-Status trailer field into a header
field by following these steps:
1. For each member trailer_member of the Proxy-Status trailer field
value:
1. Let header_member be the first (left-most) value of the
Proxy-Status header field value, comparing the sf-token or
sf-string character-by-character and without consideration of
parameters.
2. If no matching header_member is found, continue processing
the next trailer_member.
3. Replace header_member with trailer_member in its entirety,
including any parameters.
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 an sf-token that is a Proxy Error
Type. When present, it indicates that the proxy encountered an issue Type. When present, it indicates that the intermediary encountered
when obtaining a response. an issue when obtaining a response.
Unless a Proxy Error Type specifies otherwise, the presences of error The presence of some Proxy Error Types indicates that the response
often, but not always, indicates that response was generated by the was generated by the intermediary itself, rather than being forwarded
proxy, not the origin server or any other upstream server. For from the origin server. This is the case when, for example, the
example, a proxy might attempt to correct an error, or part of a origin server can't be contacted, so the proxy has to create its own
response might be forwarded before the error is encountered. response.
Other Proxy Error Types can be added to (potentially partial)
responses that were generated by the origin server or some other
inbound server. For example, if the forward connection abruptly
closes, an intermediary might add Proxy-Status with an appropriate
error as a trailer field.
Proxy Error Types that are registered with a 'Only generated by
intermediaries' value of 'true' indicate that they can only occur on
responses generated by the intermediary. If the value is 'false',
the response might be generated by the intermediary or an inbound
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: SomeCDN; error=connection_timeout Proxy-Status: ExampleCDN; error=connection_timeout
indicates that this 504 response was generated by SomeCDN, due to a indicates that this 504 response was generated by ExampleCDN, due to
connection timeout when going forward. a connection timeout when going forward.
Or: Or:
HTTP/1.1 429 Too Many Requests HTTP/1.1 429 Too Many Requests
Proxy-Status: SomeReverseProxy; error=http_request_error 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
the intermediary, not the origin. the reverse proxy, 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 a HTTP response containing "error", its HTTP status code
skipping to change at page 5, line 49 skipping to change at page 7, line 14
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 an sf-string or sf-token that
identifies the intermediary or origin server selected (and used, if identifies the intermediary or origin server selected (and used, if
contacted) for this response. It might be a hostname, IP address, or contacted) for this response. It might be a hostname, IP address, or
alias. alias.
For example: For example:
Proxy-Status: cdn.example.org; next-hop=backend.example.org Proxy-Status: cdn.example.org; next-hop=backend.example.org:8001
indicates that cdn.example.org used backend.example.org:8001 as the
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 ALPN protocol
identifier [RFC7301] used by the intermediary to connect to the next identifier [RFC7301] of the protocol used by the intermediary to
hop. This is only applicable when that connection was actually connect to the next hop. This is only applicable when that
established. connection was actually established.
The value MUST be either an sf-token or sf-binary, representing a TLS The value MUST be either an sf-token or sf-binary, representing a TLS
Application-Layer Protocol Negotiation (ALPN) Protocol ID (see Application-Layer Protocol Negotiation (ALPN) Protocol ID (see
https://www.iana.org/assignments/tls-extensiontype-values/tls- https://www.iana.org/assignments/tls-extensiontype-values/tls-
extensiontype-values.xhtml#alpn-protocol-ids [4]). If the protocol extensiontype-values.xhtml#alpn-protocol-ids [4]). If the protocol
identifier is able to be expressed as an sf-token using ASCII identifier is able to be expressed as an sf-token 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
protocol in use; it may or may not have been actually used in the
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. code that the intermediary received from the next hop server.
The value MUST be an sf-integer. The value MUST be an sf-integer.
For example: For example:
Proxy-Status: ExampleProxy; 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 an sf-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: ExampleProxy; 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, as
per [RFC8126], Section 4.5. A specification document is appreciated, per [RFC8126], Section 4.5. A specification document is appreciated,
but not required. but not required.
skipping to change at page 7, line 52 skipping to change at page 9, line 25
o Name: dns_timeout o Name: dns_timeout
o Description: The intermediary encountered a timeout when trying to o 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. o Extra Parameters: None.
o Recommended HTTP status code: 504 o Recommended HTTP status code: 504
o Only generated by intermediaries: true
o Reference: [this document] o Reference: [this document]
2.3.2. DNS Error 2.3.2. DNS Error
o Name: dns_error o Name: dns_error
o Description: The intermediary encountered a DNS error when trying o Description: The intermediary encountered a DNS error when trying
to find an IP address for the next hop hostname. to find an IP address for the next hop hostname.
o Extra Parameters: o Extra Parameters:
* rcode: A sf-string conveying the DNS RCODE that indicates the * rcode: A sf-string conveying the DNS RCODE that indicates the
error type. See [RFC8499], Section 3. error type. See [RFC8499], Section 3.
* info-code: A sf-integer conveying the Extended DNS Error Code * info-code: A sf-integer conveying the Extended DNS Error Code
info-code. See [RFC8914]. info-code. See [RFC8914].
o Recommended HTTP status code: 502 o Recommended HTTP status code: 502
o Only generated by intermediaries: true
o Reference: [this document] o Reference: [this document]
2.3.3. Destination Not Found 2.3.3. Destination Not Found
o Name: destination_not_found o Name: destination_not_found
o Description: The intermediary cannot determine the appropriate o Description: The intermediary cannot determine the appropriate
next hop to use for this request; for example, it may not be next 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. o Extra Parameters: None.
o Recommended HTTP status code: 500 o Recommended HTTP status code: 500
o Only generated by intermediaries: true
o Reference: [this document] o Reference: [this document]
2.3.4. Destination Unavailable 2.3.4. Destination Unavailable
o Name: destination_unavailable o Name: destination_unavailable
o Description: The intermediary considers the next hop to be o 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. o Extra Parameters: None.
o Recommended HTTP status code: 503 o Recommended HTTP status code: 503
o Only generated by intermediaries: true
o Reference: [this document] o Reference: [this document]
2.3.5. Destination IP Prohibited 2.3.5. Destination IP Prohibited
o Name: destination_ip_prohibited o Name: destination_ip_prohibited
o Description: The intermediary is configured to prohibit o Description: The intermediary is configured to prohibit
connections to the next hop IP address. connections to the next hop IP address.
o Extra Parameters: None. o Extra Parameters: None.
o Recommended HTTP status code: 502 o Recommended HTTP status code: 502
o Only generated by intermediaries: true
o Reference: [this document] o Reference: [this document]
2.3.6. Destination IP Unroutable 2.3.6. Destination IP Unroutable
o Name: destination_ip_unroutable o Name: destination_ip_unroutable
o Description: The intermediary cannot find a route to the next hop o Description: The intermediary cannot find a route to the next hop
IP address. IP address.
o Extra Parameters: None. o Extra Parameters: None.
o Recommended HTTP status code: 502 o Recommended HTTP status code: 502
o Only generated by intermediaries: true
o Reference: [this document] o Reference: [this document]
2.3.7. Connection Refused 2.3.7. Connection Refused
o Name: connection_refused o Name: connection_refused
o Description: The intermediary's connection to the next hop was o Description: The intermediary's connection to the next hop was
refused. refused.
o Extra Parameters: None. o Extra Parameters: None.
o Recommended HTTP status code: 502 o Recommended HTTP status code: 502
o Only generated by intermediaries: true
o Reference: [this document] o Reference: [this document]
2.3.8. Connection Terminated 2.3.8. Connection Terminated
o Name: connection_terminated o Name: connection_terminated
o Description: The intermediary's connection to the next hop was o Description: The intermediary's connection to the next hop was
closed before complete response was received. closed before complete response was received.
o Extra Parameters: None. o Extra Parameters: None.
o Recommended HTTP status code: 502 o Recommended HTTP status code: 502
o Reference: [this document] o Only generated by intermediaries: false
o Notes: Responses with this error type might not have been o Reference: [this document]
generated by the intermediary.
2.3.9. Connection Timeout 2.3.9. Connection Timeout
o Name: connection_timeout o Name: connection_timeout
o Description: The intermediary's attempt to open a connection to o Description: The intermediary's attempt to open a connection to
the next hop timed out. the next hop timed out.
o Extra Parameters: None. o Extra Parameters: None.
o Recommended HTTP status code: 504 o Recommended HTTP status code: 504
o Only generated by intermediaries: true
o Reference: [this document] o Reference: [this document]
2.3.10. Connection Read Timeout 2.3.10. Connection Read Timeout
o Name: connection_read_timeout o Name: connection_read_timeout
o Description: The intermediary was expecting data on a connection o 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. o Extra Parameters: None.
o Recommended HTTP status code: 504 o Recommended HTTP status code: 504
o Reference: [this document] o Only generated by intermediaries: false
o Notes: Responses with this error type might not have been o Reference: [this document]
generated by the intermediary.
2.3.11. Connection Write Timeout 2.3.11. Connection Write Timeout
o Name: connection_write_timeout o Name: connection_write_timeout
o Description: The intermediary was attempting to write data to a o 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. o Extra Parameters: None.
o Recommended HTTP status code: 504 o Recommended HTTP status code: 504
o Reference: [this document] o Only generated by intermediaries: false
o Notes: Responses with this error type might not have been o Reference: [this document]
generated by the intermediary.
2.3.12. Connection Limit Reached 2.3.12. Connection Limit Reached
o Name: connection_limit_reached o Name: connection_limit_reached
o Description: The intermediary is configured to limit the number of o 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. passed.
o Extra Parameters: None. o Extra Parameters: None.
o Recommended HTTP status code: 503 o Recommended HTTP status code: 503
o Only generated by intermediaries: true
o Reference: [this document] o Reference: [this document]
2.3.13. TLS Protocol Error 2.3.13. TLS Protocol Error
o Name: tls_protocol_error o Name: tls_protocol_error
o Description: The intermediary encountered a TLS error when o Description: The intermediary encountered a TLS error when
communicating with the next hop, either during handshake or communicating with the next hop, either during handshake or
afterwards. afterwards.
o Extra Parameters: None. o Extra Parameters: None.
o Recommended HTTP status code: 502 o Recommended HTTP status code: 502
o Reference: [this document] o Only generated by intermediaries: false
o Notes: Responses with this error type might not have been o Reference: [this document]
generated by the intermediary.
Note that additional information about the error can be recorded in o Notes: Not appropriate when a TLS alert is received; see
the details parameter (as is the case for all errors). tls_alert_received
2.3.14. TLS Certificate Error 2.3.14. TLS Certificate Error
o Name: tls_certificate_error o Name: tls_certificate_error
o Description: The intermediary encountered an error when verifying o 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. o Extra Parameters: None.
o Recommended HTTP status code: 502 o Recommended HTTP status code: 502
o Only generated by intermediaries: true
o Reference: [this document] o Reference: [this document]
Note that additional information about the error can be recorded in
the details parameter (as is the case for all errors).
2.3.15. TLS Alert Received 2.3.15. TLS Alert Received
o Name: tls_alert_received o Name: tls_alert_received
o Description: The intermediary received a TLS alert from the next o Description: The intermediary received a TLS alert from the next
hop. hop.
o Extra Parameters: o Extra Parameters:
* alert-id: an sf-integer containing the applicable value from * alert-id: an sf-integer containing the applicable value from
the TLS Alerts registry. See {!RFC8446}}. the TLS Alerts registry. See {!RFC8446}}.
* alert-message: an sf-token containing the applicable * alert-message: an sf-token or sf-string containing the
description string from the TLS Alerts registry. See applicable description string from the TLS Alerts registry.
[RFC8446]. See [RFC8446].
o Recommended HTTP status code: 502 o Recommended HTTP status code: 502
o Reference: [this document] o Only generated by intermediaries: false
o Notes: Responses with this error type might not have been o Reference: [this document]
generated by the intermediary.
2.3.16. HTTP Request Error 2.3.16. HTTP Request Error
o Name: http_request_error o Name: http_request_error
o Description: The intermediary is generating a client (4xx) o Description: The intermediary is generating a client (4xx)
response on the origin's behalf. Applicable status codes include response on the origin's behalf. Applicable status codes include
(but are not limited to) 400, 403, 405, 406, 408, 411, 413, 414, (but are not limited to) 400, 403, 405, 406, 408, 411, 413, 414,
415, 416, 417, 429. 415, 416, 417, 429.
o Extra Parameters: o Extra Parameters:
* status-code: an sf-integer containing the generated status * status-code: an sf-integer containing the generated status
code. code.
* status-phrase: an sf-string containing the generated status * status-phrase: an sf-string containing the generated status
phrase. phrase.
o Recommended HTTP status code: The applicable 4xx status code o Recommended HTTP status code: The applicable 4xx status code
o Reference: [this document] o Only generated by intermediaries: true
o Reference: [this document]
o Notes: This type helps distinguish between responses generated by o 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 o Name: http_request_denied
o Description: The intermediary rejected the HTTP request based on o Description: The intermediary rejected the HTTP request based on
its configuration and/or policy settings. The request wasn't its configuration and/or policy settings. The request wasn't
forwarded to the next hop. forwarded to the next hop.
o Extra Parameters: None. o Extra Parameters: None.
o Recommended HTTP status code: 403 o Recommended HTTP status code: 403
o Only generated by intermediaries: true
o Reference: [this document] o Reference: [this document]
2.3.18. HTTP Incomplete Response 2.3.18. HTTP Incomplete Response
o Name: http_response_incomplete o Name: http_response_incomplete
o Description: The intermediary received an incomplete response to o Description: The intermediary received an incomplete response to
the request from the next hop. the request from the next hop.
o Extra Parameters: None. o Extra Parameters: None.
o Recommended HTTP status code: 502 o Recommended HTTP status code: 502
o Reference: [this document] o Only generated by intermediaries: false
o Notes: Responses with this error type might not have been o Reference: [this document]
generated by the intermediary.
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 o Name: http_response_header_section_size
o Description: The intermediary received a response to the request o 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: o Extra Parameters:
* header-section-size: an sf-integer indicating how large the * header-section-size: an sf-integer indicating how large the
headers received were. Note that they might not be complete; headers received 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 o Recommended HTTP status code: 502
o Reference: [this document] o Only generated by intermediaries: false
o Notes: Responses with this error type might not have been o Reference: [this document]
generated by the intermediary.
2.3.20. HTTP Response Header Too Large 2.3.20. HTTP Response Header Field Line Too Large
o Name: http_response_header_size o Name: http_response_header_size
o Description: The intermediary received a response to the request o Description: The intermediary received a response to the request
containing an individual header line that was considered too containing an individual header field line that was considered too
large. large.
o Extra Parameters: o Extra Parameters:
* header-name: an sf-string indicating the name of the header * header-name: an sf-string indicating the name of the header
that triggered the error. field that triggered the error.
* header-size: an sf-integer indicating the size of the header * header-size: an sf-integer indicating the size of the header
that triggered the error. field that triggered the error.
o Recommended HTTP status code: 502 o Recommended HTTP status code: 502
o Reference: [this document] o Only generated by intermediaries: false
o Notes: Responses with this error type might not have been o Reference: [this document]
generated by the intermediary.
2.3.21. HTTP Response Body Too Large 2.3.21. HTTP Response Body Too Large
o Name: http_response_body_size o Name: http_response_body_size
o Description: The intermediary received a response to the request o Description: The intermediary received a response to the request
whose body was considered too large. whose body was considered too large.
o Extra Parameters: o Extra Parameters:
* body-size: an sf-integer indicating how large the body received * body-size: an sf-integer indicating how large the body received
was. Note that it may not have been complete; i.e., the was. Note that it may not have been complete; i.e., the
intermediary may have discarded or refused additional data. intermediary may have discarded or refused additional data.
o Recommended HTTP status code: 502 o Recommended HTTP status code: 502
o Reference: [this document]
o Notes: Responses with this error type might not have been o Only generated by intermediaries: false
generated by the intermediary.
o Reference: [this document]
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 o Name: http_response_trailer_section_size
o Description: The intermediary received a response to the request o 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: o Extra Parameters:
* trailer-section-size: an sf-integer indicating how large the * trailer-section-size: an sf-integer indicating how large the
trailers received were. Note that they might not be complete; trailers received 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 o Recommended HTTP status code: 502
o Reference: [this document] o Only generated by intermediaries: false
o Notes: Responses with this error type might not have been o Reference: [this document]
generated by the intermediary.
2.3.23. HTTP Response Trailer Too Large 2.3.23. HTTP Response Trailer Field Line Too Large
o Name: http_response_trailer_size o Name: http_response_trailer_size
o Description: The intermediary received a response to the request o Description: The intermediary received a response to the request
containing an individual trailer line that was considered too containing an individual trailer field line that was considered
large. too large.
o Extra Parameters: o Extra Parameters:
* trailer-name: an sf-string indicating the name of the trailer * trailer-name: an sf-string indicating the name of the trailer
that triggered the error. field that triggered the error.
* trailer-size: an sf-integer indicating the size of the trailer * trailer-size: an sf-integer indicating the size of the trailer
that triggered the error. field that triggered the error.
o Recommended HTTP status code: 502 o Recommended HTTP status code: 502
o Reference: [this document] o Only generated by intermediaries: false
o Notes: Responses with this error type might not have been o Reference: [this document]
generated by the intermediary.
2.3.24. HTTP Response Transfer-Coding Error 2.3.24. HTTP Response Transfer-Coding Error
o Name: http_response_transfer_coding o Name: http_response_transfer_coding
o Description: The intermediary encountered an error decoding the o Description: The intermediary encountered an error decoding the
transfer-coding of the response. transfer-coding of the response.
o Extra Parameters: o Extra Parameters:
* coding: an sf-token containing the specific coding that caused * coding: an sf-token containing the specific coding (from the
the error. HTTP Transfer Coding Registry) that caused the error.
o Recommended HTTP status code: 502 o Recommended HTTP status code: 502
o Reference: [this document] o Only generated by intermediaries: false
o Notes: Responses with this error type might not have been o Reference: [this document]
generated by the intermediary.
2.3.25. HTTP Response Content-Coding Error 2.3.25. HTTP Response Content-Coding Error
o Name: http_response_content_coding o Name: http_response_content_coding
o Description: The intermediary encountered an error decoding the o Description: The intermediary encountered an error decoding the
content-coding of the response. content-coding of the response.
o Extra Parameters: o Extra Parameters:
* coding: an sf-token containing the specific coding that caused * coding: an sf-token containing the specific coding (from the
the error. HTTP Content Coding Registry) that caused the error.
o Recommended HTTP status code: 502 o Recommended HTTP status code: 502
o Reference: [this document] o Only generated by intermediaries: false
o Notes: Responses with this error type might not have been o Reference: [this document]
generated by the intermediary.
2.3.26. HTTP Response Timeout 2.3.26. HTTP Response Timeout
o Name: http_response_timeout o Name: http_response_timeout
o Description: The intermediary reached a configured time limit o Description: The intermediary reached a configured time limit
waiting for the complete response. waiting for the complete response.
o Extra Parameters: None. o Extra Parameters: None.
o Recommended HTTP status code: 504 o Recommended HTTP status code: 504
o Reference: [this document]
o Notes: Responses with this error type might not have been o Only generated by intermediaries: false
generated by the intermediary.
o Reference: [this document]
2.3.27. HTTP Upgrade Failed 2.3.27. HTTP Upgrade Failed
o Name: http_upgrade_failed o Name: http_upgrade_failed
o Description: The HTTP Upgrade between the intermediary and the o Description: The HTTP Upgrade between the intermediary and the
next hop failed. next hop failed.
o Extra Parameters: None. o Extra Parameters: None.
o Recommended HTTP status code: 502 o Recommended HTTP status code: 502
o Only generated by intermediaries: true
o Reference: [this document] o Reference: [this document]
2.3.28. HTTP Protocol Error 2.3.28. HTTP Protocol Error
o Name: http_protocol_error o Name: http_protocol_error
o Description: The intermediary encountered a HTTP protocol error o Description: The intermediary encountered a 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. o Extra Parameters: None.
o Recommended HTTP status code: 502 o Recommended HTTP status code: 502
o Reference: [this document] o Only generated by intermediaries: false
o Notes: Responses with this error type might not have been
generated by the intermediary.
Note that additional information about the error can be recorded in o Reference: [this document]
the details parameter (as is the case for all errors).
2.3.29. Proxy Internal Response 2.3.29. Proxy Internal Response
o Name: proxy_internal_response o Name: proxy_internal_response
o Description: The intermediary generated the response locally, o Description: The intermediary generated the response locally,
without attempting to connect to the next hop (e.g. in response to without attempting to connect to the next hop (e.g. in response to
a request to a debug endpoint terminated at the intermediary). a request to a debug endpoint terminated at the intermediary).
o Extra Parameters: None. o Extra Parameters: None.
o Recommended HTTP status code: The most appropriate status code for o Recommended HTTP status code: The most appropriate status code for
the response the response
o Only generated by intermediaries: true
o Reference: [this document] o Reference: [this document]
2.3.30. Proxy Internal Error 2.3.30. Proxy Internal Error
o Name: proxy_internal_error o Name: proxy_internal_error
o Description: The intermediary encountered an internal error o Description: The intermediary encountered an internal error
unrelated to the origin. unrelated to the origin.
o Extra Parameters: None o Extra Parameters: None
o Recommended HTTP status code: 500 o Recommended HTTP status code: 500
o Reference: [this document] o Only generated by intermediaries: true
Note that additional information about the error can be recorded in o Reference: [this document]
the details parameter (as is the case for all errors).
2.3.31. Proxy Configuration Error 2.3.31. Proxy Configuration Error
o Name: proxy_configuration_error o Name: proxy_configuration_error
o Description: The intermediary encountered an error regarding its o Description: The intermediary encountered an error regarding its
configuration. configuration.
o Extra Parameters: None o Extra Parameters: None
o Recommended HTTP status code: 500 o Recommended HTTP status code: 500
o Reference: [this document] o Only generated by intermediaries: true
Note that additional information about the error can be recorded in o Reference: [this document]
the details parameter (as is the case for all errors).
2.3.32. Proxy Loop Detected 2.3.32. Proxy Loop Detected
o Name: proxy_loop_detected o Name: proxy_loop_detected
o Description: The intermediary tried to forward the request to o 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. o Extra Parameters: None.
o Recommended HTTP status code: 502 o Recommended HTTP status code: 502
o Only generated by intermediaries: true
o Reference: [this document] o Reference: [this document]
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, as
per [RFC8126], Section 4.5. A specification document is appreciated, per [RFC8126], Section 4.5. A specification document is appreciated,
but not required. but not required.
skipping to change at page 19, line 44 skipping to change at page 21, line 43
o 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 o Extra Parameters: [zero or more optional parameters, along with
their allowable type(s)] their allowable type(s)]
o Recommended HTTP status code: [the appropriate HTTP status code o Recommended HTTP status code: [the appropriate HTTP status code
for this entry] for this entry]
o Only generated by intermediaries: ['true' or 'false']
o Reference: [to a specification defining this error type; optional] o Reference: [to a specification defining this error type; optional]
o Notes: [optional] o 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 the error is generated by the intermediary -- for example, when an error is
detected during response content processing and a Proxy-Status detected as the response is streamed from a forward connection,
trailer field is appended -- that SHOULD be explained in the Notes. causing a Proxy-Status trailer field to be appended -- the 'Only
generated by intermediaries' should be 'false'. If the Proxy Error
Type only occurs in responses that are generated by the intermediary,
it should be 'true'.
See the registry at https://iana.org/assignments/http-proxy-status See the registry at https://iana.org/assignments/http-proxy-status
[6] for details on where to send registration requests. [6] for details on where to send registration requests.
3. IANA Considerations 3. IANA Considerations
Upon publication, please create the HTTP Proxy-Status Parameters Upon publication, please create the HTTP Proxy-Status Parameters
registry and the HTTP Proxy Error Types registry at registry and the HTTP Proxy Error Types registry at
https://iana.org/assignments/http-proxy-status [7] and populate them https://iana.org/assignments/http-proxy-status [7] and populate them
with the types defined in Section 2.1 and Section 2.3 respectively; with the types defined in Section 2.1 and Section 2.3 respectively;
see Section 2.2 and Section 2.4 for its associated procedures. see Section 2.2 and Section 2.4 for its associated procedures.
Additionally, please register the following entry in the Hypertext
Transfer Protocol (HTTP) Field Name Registry:
o Field name: Proxy-Status
o Status: permanent
o Specification document(s): [this document]
o Comments:
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 back-end
topology can be exposed. topology can be exposed, allowing attackers to directly target back-
end services that are not prepared for high traffic volume or
malformed inputs. Some information might only be suitable to reveal
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. Note that intermediaries are not required to Proxy-Status field and what information to include in it. Note that
generate a Proxy-Status field in any response, and can conditionally intermediaries are not required to generate a Proxy-Status field in
generate them based upon request attributes (e.g., authentication any response, and can conditionally generate them based upon request
tokens, IP address). attributes (e.g., authentication tokens, IP address).
Likewise, generation of all parameters is optional. Likewise, generation of all parameters is optional, as is generation
of the field itself. Also, the field's content is not verified; an
intermediary can claim certain actions (e.g., sending a 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
Semantics", draft-ietf-httpbis-semantics-19 (work in
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
Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301,
July 2014, <https://www.rfc-editor.org/info/rfc7301>. July 2014, <https://www.rfc-editor.org/info/rfc7301>.
skipping to change at page 21, line 18 skipping to change at page 23, line 45
[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>.
[RFC8941] Nottingham, M. and P-H. Kamp, "Structured Field Values for [STRUCTURED-FIELDS]
Nottingham, M. and P-H. 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 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, Specifications: ABNF", STD 68, RFC 5234,
DOI 10.17487/RFC5234, January 2008, DOI 10.17487/RFC5234, January 2008,
<https://www.rfc-editor.org/info/rfc5234>. <https://www.rfc-editor.org/info/rfc5234>.
skipping to change at page 22, line 9 skipping to change at page 24, line 38
[5] https://iana.org/assignments/http-proxy-status [5] https://iana.org/assignments/http-proxy-status
[6] https://iana.org/assignments/http-proxy-status [6] https://iana.org/assignments/http-proxy-status
[7] 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, VIC Prahran
Australia Australia
Email: mnot@mnot.net Email: mnot@mnot.net
URI: https://www.mnot.net/ URI: https://www.mnot.net/
Piotr Sikora Piotr Sikora
Google Google
Email: piotrsikora@google.com Email: piotrsikora@google.com
 End of changes. 98 change blocks. 
148 lines changed or deleted 247 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/