idnits 2.17.1 draft-ietf-httpbis-proxy-status-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (13 October 2021) is 925 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Normative reference to a draft: ref. 'HTTP' ** Obsolete normative reference: RFC 8499 (Obsoleted by RFC 9499) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP M. Nottingham 3 Internet-Draft Fastly 4 Intended status: Standards Track P. Sikora 5 Expires: 16 April 2022 Google 6 13 October 2021 8 The Proxy-Status HTTP Response Header Field 9 draft-ietf-httpbis-proxy-status-08 11 Abstract 13 This document defines the Proxy-Status HTTP field to convey the 14 details of intermediary response handling, including generated 15 errors. 17 Note to Readers 19 _RFC EDITOR: please remove this section before publication_ 21 Discussion of this draft takes place on the HTTP working group 22 mailing list (ietf-http-wg@w3.org), which is archived at 23 https://lists.w3.org/Archives/Public/ietf-http-wg/ 24 (https://lists.w3.org/Archives/Public/ietf-http-wg/). 26 Working Group information can be found at https://httpwg.org/ 27 (https://httpwg.org/); source code and issues list for this draft can 28 be found at https://github.com/httpwg/http-extensions/labels/proxy- 29 status (https://github.com/httpwg/http-extensions/labels/proxy- 30 status). 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at https://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on 16 April 2022. 49 Copyright Notice 51 Copyright (c) 2021 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 56 license-info) in effect on the date of publication of this document. 57 Please review these documents carefully, as they describe your rights 58 and restrictions with respect to this document. Code Components 59 extracted from this document must include Simplified BSD License text 60 as described in Section 4.e of the Trust Legal Provisions and are 61 provided without warranty as described in the Simplified BSD License. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 66 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 67 2. The Proxy-Status HTTP Field . . . . . . . . . . . . . . . . . 4 68 2.1. Proxy-Status Parameters . . . . . . . . . . . . . . . . . 6 69 2.1.1. error . . . . . . . . . . . . . . . . . . . . . . . . 6 70 2.1.2. next-hop . . . . . . . . . . . . . . . . . . . . . . 8 71 2.1.3. next-protocol . . . . . . . . . . . . . . . . . . . . 8 72 2.1.4. received-status . . . . . . . . . . . . . . . . . . . 8 73 2.1.5. details . . . . . . . . . . . . . . . . . . . . . . . 9 74 2.2. Defining New Proxy-Status Parameters . . . . . . . . . . 9 75 2.3. Proxy Error Types . . . . . . . . . . . . . . . . . . . . 10 76 2.3.1. DNS Timeout . . . . . . . . . . . . . . . . . . . . . 10 77 2.3.2. DNS Error . . . . . . . . . . . . . . . . . . . . . . 10 78 2.3.3. Destination Not Found . . . . . . . . . . . . . . . . 11 79 2.3.4. Destination Unavailable . . . . . . . . . . . . . . . 11 80 2.3.5. Destination IP Prohibited . . . . . . . . . . . . . . 11 81 2.3.6. Destination IP Unroutable . . . . . . . . . . . . . . 12 82 2.3.7. Connection Refused . . . . . . . . . . . . . . . . . 12 83 2.3.8. Connection Terminated . . . . . . . . . . . . . . . . 12 84 2.3.9. Connection Timeout . . . . . . . . . . . . . . . . . 13 85 2.3.10. Connection Read Timeout . . . . . . . . . . . . . . . 13 86 2.3.11. Connection Write Timeout . . . . . . . . . . . . . . 13 87 2.3.12. Connection Limit Reached . . . . . . . . . . . . . . 14 88 2.3.13. TLS Protocol Error . . . . . . . . . . . . . . . . . 14 89 2.3.14. TLS Certificate Error . . . . . . . . . . . . . . . . 14 90 2.3.15. TLS Alert Received . . . . . . . . . . . . . . . . . 15 91 2.3.16. HTTP Request Error . . . . . . . . . . . . . . . . . 15 92 2.3.17. HTTP Request Denied . . . . . . . . . . . . . . . . . 16 93 2.3.18. HTTP Incomplete Response . . . . . . . . . . . . . . 16 94 2.3.19. HTTP Response Header Section Too Large . . . . . . . 16 95 2.3.20. HTTP Response Header Field Line Too Large . . . . . . 17 96 2.3.21. HTTP Response Body Too Large . . . . . . . . . . . . 17 97 2.3.22. HTTP Response Trailer Section Too Large . . . . . . . 18 98 2.3.23. HTTP Response Trailer Field Line Too Large . . . . . 18 99 2.3.24. HTTP Response Transfer-Coding Error . . . . . . . . . 18 100 2.3.25. HTTP Response Content-Coding Error . . . . . . . . . 19 101 2.3.26. HTTP Response Timeout . . . . . . . . . . . . . . . . 19 102 2.3.27. HTTP Upgrade Failed . . . . . . . . . . . . . . . . . 19 103 2.3.28. HTTP Protocol Error . . . . . . . . . . . . . . . . . 20 104 2.3.29. Proxy Internal Response . . . . . . . . . . . . . . . 20 105 2.3.30. Proxy Internal Error . . . . . . . . . . . . . . . . 20 106 2.3.31. Proxy Configuration Error . . . . . . . . . . . . . . 21 107 2.3.32. Proxy Loop Detected . . . . . . . . . . . . . . . . . 21 108 2.4. Defining New Proxy Error Types . . . . . . . . . . . . . 21 109 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 110 4. Security Considerations . . . . . . . . . . . . . . . . . . . 23 111 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 23 112 5.1. Normative References . . . . . . . . . . . . . . . . . . 23 113 5.2. Informative References . . . . . . . . . . . . . . . . . 24 114 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 25 116 1. Introduction 118 HTTP intermediaries (see Section 3.7 of [HTTP]) -- including both 119 forward proxies and gateways (also known as "reverse proxies") -- 120 have become an increasingly significant part of HTTP deployments. In 121 particular, reverse proxies and Content Delivery Networks (CDNs) form 122 part of the critical infrastructure of many Web sites. 124 Typically, HTTP intermediaries forward requests towards the origin 125 server (inbound) and then forward their responses back to clients 126 (outbound). However, if an error occurs before a response is 127 obtained from an inbound server, the response is often generated by 128 the intermediary itself. 130 HTTP accommodates these types of errors with a few status codes; for 131 example, 502 Bad Gateway and 504 Gateway Timeout. However, 132 experience has shown that more information is necessary to aid 133 debugging and communicate what's happened to the client. 134 Additionally, intermediaries sometimes want to convey additional 135 information about their handling of a response, even if they did not 136 generate it. 138 To enable these uses, Section 2 defines a new HTTP response field to 139 allow intermediaries to convey details of their handling of a 140 response. Section 2.1 enumerates the information that can be added 141 to the field by intermediaries, which can be extended as per 142 Section 2.2. Section 2.3 defines a set of error types for use when a 143 proxy encounters an issue when obtaining a response for the request; 144 these can likewise be extended as per Section 2.4. 146 1.1. Notational Conventions 148 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 149 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 150 "OPTIONAL" in this document are to be interpreted as described in BCP 151 14 [RFC2119] [RFC8174] when, and only when, they appear in all 152 capitals, as shown here. 154 This specification uses Structured Fields [STRUCTURED-FIELDS] to 155 specify syntax and parsing, and ABNF [RFC5234] as a shorthand for 156 that syntax. The terms sf-list, sf-item, sf-string, sf-token, sf- 157 integer and key refer to the structured types defined therein. 159 Note that in this specification, "proxy" is used to indicate both 160 forward and reverse proxies, otherwise known as gateways. "Next hop" 161 indicates the connection in the direction leading to the origin 162 server for the request. 164 2. The Proxy-Status HTTP Field 166 The Proxy-Status HTTP response field allows an intermediary to convey 167 additional information about its handling of a response and its 168 associated request. The syntax of this header field conforms to 169 [STRUCTURED-FIELDS]. 171 It is a List ([STRUCTURED-FIELDS], Section 3.1): 173 Proxy-Status = sf-list 175 Each member of the list represents an intermediary that has handled 176 the response. The first member of the list represents the 177 intermediary closest to the origin server, and the last member of the 178 list represents the intermediary closest to the user agent. 180 For example: 182 Proxy-Status: revproxy1.example.net, ExampleCDN 184 indicates that this response was handled first by 185 revproxy1.example.net (a reverse proxy adjacent to the origin server) 186 and then ExampleCDN. 188 Intermediaries determine when it is appropriate to add the Proxy- 189 Status field to a response. Some might decide to append to it to all 190 responses, whereas others might only do so when specifically 191 configured to, or when the request contains a header field that 192 activates a debugging mode. 194 Each member of the list identifies the intermediary that inserted the 195 value, and MUST have a type of either sf-string or sf-token. 196 Depending on the deployment, this might be a service name (but not a 197 software or hardware product name; e.g., "Example CDN"is appropriate, 198 but "ExampleProxy" is not, because it doesn't identify the 199 deployment), a hostname ("proxy-3.example.com"), an IP address, or a 200 generated string. 202 Parameters on each member (as per Section 3.1.2 of 203 [STRUCTURED-FIELDS]) convey additional information about that 204 intermediary's handling of the response and its associated request; 205 see Section 2.1. While all of these parameters are OPTIONAL, 206 intermediaries are encouraged to provide as much information as 207 possible (but see Section 4 for security considerations in doing so). 209 When adding a value to the Proxy-Status field, intermediaries SHOULD 210 preserve the existing members of the field to allow debugging of the 211 entire chain of intermediaries handling the request, unless 212 explicitly configured to remove them (e.g., to prevent internal 213 network details from leaking; see Section 4). 215 Origin servers MUST NOT generate the Proxy-Status field. 217 Proxy-Status MAY be sent as a HTTP trailer field. For example, if an 218 intermediary is streaming a response and the inbound connection 219 suddenly terminates, Proxy-Status can only be appended to the trailer 220 section of the outbound message, since the header section has already 221 been sent. However, because it might be silently discarded along the 222 path to the user agent (as is the case for all trailer fields; see 223 Section 6.5 of [HTTP]), Proxy-Status SHOULD NOT be sent as a trailer 224 field unless it is not possible to send it in the header section. 226 To allow recipients to reconstruct the relative ordering of Proxy- 227 Status members conveyed in trailer fields with those conveyed in 228 header fields, an intermediary MUST NOT send Proxy-Status as a 229 trailer field unless it has also generated a Proxy-Status header 230 field with the same member (although potentially different 231 parameters) in that message. 233 For example, a proxy identified as 'ThisProxy' that receives a 234 response bearing a header field: 236 Proxy-Status: SomeOtherProxy 238 would add its own entry to the header field: 240 Proxy-Status: SomeOtherProxy, ThisProxy 241 thus allowing it to append a trailer field: 243 Proxy-Status: ThisProxy; error=read_timeout 245 ... which would thereby allow a downstream recipient to understand 246 that processing by 'SomeOtherProxy' occurred before 'ThisProxy'. 248 A client MAY promote the Proxy-Status trailer field into a header 249 field by following these steps: 251 1. For each member trailer_member of the Proxy-Status trailer field 252 value: 254 1. Let header_member be the first (left-most) value of the 255 Proxy-Status header field value, comparing the sf-token or 256 sf-string character-by-character and without consideration of 257 parameters. 259 2. If no matching header_member is found, continue processing 260 the next trailer_member. 262 3. Replace header_member with trailer_member in its entirety, 263 including any parameters. 265 2. Remove the Proxy-Status trailer field, if empty. 267 2.1. Proxy-Status Parameters 269 This section lists parameters that can be used on the members of the 270 Proxy-Status field. Unrecognised parameters MUST be ignored. 272 2.1.1. error 274 The error parameter's value is an sf-token that is a Proxy Error 275 Type. When present, it indicates that the intermediary encountered 276 an issue when obtaining this response. 278 The presence of some Proxy Error Types indicates that the response 279 was generated by the intermediary itself, rather than being forwarded 280 from the origin server. This is the case when, for example, the 281 origin server can't be contacted, so the proxy has to create its own 282 response. 284 Other Proxy Error Types can be added to (potentially partial) 285 responses that were generated by the origin server or some other 286 inbound server. For example, if the forward connection abruptly 287 closes, an intermediary might add Proxy-Status with an appropriate 288 error as a trailer field. 290 Proxy Error Types that are registered with a 'Response only generated 291 by intermediaries' value of 'true' indicate that they can only occur 292 on responses generated by the intermediary. If the value is 'false', 293 the response might be generated by the intermediary or an inbound 294 server. 296 Section 2.3 lists the Proxy Error Types defined in this document; new 297 ones can be defined using the procedure outlined in Section 2.4. 299 For example: 301 HTTP/1.1 504 Gateway Timeout 302 Proxy-Status: ExampleCDN; error=connection_timeout 304 indicates that this 504 response was generated by ExampleCDN, due to 305 a connection timeout when going forward. 307 Or: 309 HTTP/1.1 429 Too Many Requests 310 Proxy-Status: r34.example.net; error=http_request_error, ExampleCDN 312 indicates that this 429 Too Many Requests response was generated by 313 r34.example.net, not the CDN or the origin. 315 When sending the error parameter, the most specific Proxy Error Type 316 SHOULD be sent, provided that it accurately represents the error 317 condition. If an appropriate Proxy Error Type is not defined, there 318 are a number of generic error types (e.g., proxy_internal_error, 319 http_protocol_error) that can be used. If they are not suitable, 320 consider registering a new Proxy Error Type (see Section 2.4). 322 Each Proxy Error Type has a Recommended HTTP Status Code. When 323 generating a HTTP response containing error, its HTTP status code 324 SHOULD be set to the Recommended HTTP Status Code. However, there 325 may be circumstances (e.g., for backwards compatibility with previous 326 behaviours, a status code has already been sent) when another status 327 code might be used. 329 Proxy Error Types can also define any number of extra parameters for 330 use with that type. Their use, like all parameters, is optional. As 331 a result, if an extra parameter is used with a Proxy Error Type for 332 which it is not defined, it will be ignored. 334 2.1.2. next-hop 336 The next-hop parameter's value is an sf-string or sf-token that 337 identifies the intermediary or origin server selected (and used, if 338 contacted) to obtain this response. It might be a hostname, IP 339 address, or alias. 341 For example: 343 Proxy-Status: cdn.example.org; next-hop=backend.example.org:8001 345 indicates that cdn.example.org used backend.example.org:8001 as the 346 next hop for this request. 348 2.1.3. next-protocol 350 The next-protocol parameter's value indicates the ALPN protocol 351 identifier [RFC7301] of the protocol used by the intermediary to 352 connect to the next hop when obtaining this response. 354 The value MUST be either an sf-token or sf-binary, representing a TLS 355 Application-Layer Protocol Negotiation (ALPN) Protocol ID (see 356 https://www.iana.org/assignments/tls-extensiontype-values/tls- 357 extensiontype-values.xhtml#alpn-protocol-ids 358 (https://www.iana.org/assignments/tls-extensiontype-values/tls- 359 extensiontype-values.xhtml#alpn-protocol-ids)). If the protocol 360 identifier is able to be expressed as an sf-token using ASCII 361 encoding, that form MUST be used. 363 For example: 365 Proxy-Status: "proxy.example.org"; next-protocol=h2 367 Note that the APLN identifier is being used here to identify the 368 protocol in use; it may or may not have been actually used in the 369 protocol negotiation. 371 2.1.4. received-status 373 The received-status parameter's value indicates the HTTP status code 374 that the intermediary received from the next hop server when 375 obtaining this response. 377 The value MUST be an sf-integer. 379 For example: 381 Proxy-Status: ExampleCDN; received-status=200 383 2.1.5. details 385 The details parameter's value is an sf-string containing additional 386 information not captured anywhere else. This can include 387 implementation-specific or deployment-specific information. 389 For example: 391 Proxy-Status: proxy.example.net; error="http_protocol_error"; 392 details="Malformed response header: space before colon" 394 2.2. Defining New Proxy-Status Parameters 396 New Proxy-Status Parameters can be defined by registering them in the 397 HTTP Proxy-Status Parameters registry. 399 Registration requests are reviewed and approved by Expert Review, as 400 per [RFC8126], Section 4.5. A specification document is appreciated, 401 but not required. 403 The Expert(s) should consider the following factors when evaluating 404 requests: 406 * Community feedback 408 * If the value is sufficiently well-defined 410 * Generic parameters are preferred over vendor-specific, 411 application-specific or deployment-specific values. If a generic 412 value cannot be agreed upon in the community, the parameter's name 413 should be correspondingly specific (e.g., with a prefix that 414 identifies the vendor, application or deployment). 416 * Parameter names should not conflict with registered extra 417 parameters in the Proxy Error Type Registry. 419 Registration requests should use the following template: 421 * Name: [a name for the Proxy-Status Parameter that matches key] 423 * Description: [a description of the parameter semantics and value] 425 * Reference: [to a specification defining this parameter; optional] 427 See the registry at https://iana.org/assignments/http-proxy-status 428 (https://iana.org/assignments/http-proxy-status) for details on where 429 to send registration requests. 431 2.3. Proxy Error Types 433 This section lists the Proxy Error Types defined by this document. 434 See Section 2.4 for information about defining new Proxy Error Types. 436 Note that implementations might not produce all Proxy Error Types. 437 The set of types below is designed to map to existing states in 438 implementations, and so may not be applicable to some. 440 2.3.1. DNS Timeout 442 * Name: dns_timeout 444 * Description: The intermediary encountered a timeout when trying to 445 find an IP address for the next hop hostname. 447 * Extra Parameters: None. 449 * Recommended HTTP status code: 504 451 * Response only generated by intermediaries: true 453 * Reference: [this document] 455 2.3.2. DNS Error 457 * Name: dns_error 459 * Description: The intermediary encountered a DNS error when trying 460 to find an IP address for the next hop hostname. 462 * Extra Parameters: 464 - rcode: A sf-string conveying the DNS RCODE that indicates the 465 error type. See [RFC8499], Section 3. 467 - info-code: A sf-integer conveying the Extended DNS Error Code 468 info-code. See [RFC8914]. 470 * Recommended HTTP status code: 502 472 * Response only generated by intermediaries: true 474 * Reference: [this document] 476 2.3.3. Destination Not Found 478 * Name: destination_not_found 480 * Description: The intermediary cannot determine the appropriate 481 next hop to use for this request; for example, it may not be 482 configured. Note that this error is specific to gateways, which 483 typically require specific configuration to identify the "backend" 484 server; forward proxies use in-band information to identify the 485 origin server. 487 * Extra Parameters: None. 489 * Recommended HTTP status code: 500 491 * Response only generated by intermediaries: true 493 * Reference: [this document] 495 2.3.4. Destination Unavailable 497 * Name: destination_unavailable 499 * Description: The intermediary considers the next hop to be 500 unavailable; e.g., recent attempts to communicate with it may have 501 failed, or a health check may indicate that it is down. 503 * Extra Parameters: None. 505 * Recommended HTTP status code: 503 507 * Response only generated by intermediaries: true 509 * Reference: [this document] 511 2.3.5. Destination IP Prohibited 513 * Name: destination_ip_prohibited 515 * Description: The intermediary is configured to prohibit 516 connections to the next hop IP address. 518 * Extra Parameters: None. 520 * Recommended HTTP status code: 502 522 * Response only generated by intermediaries: true 523 * Reference: [this document] 525 2.3.6. Destination IP Unroutable 527 * Name: destination_ip_unroutable 529 * Description: The intermediary cannot find a route to the next hop 530 IP address. 532 * Extra Parameters: None. 534 * Recommended HTTP status code: 502 536 * Response only generated by intermediaries: true 538 * Reference: [this document] 540 2.3.7. Connection Refused 542 * Name: connection_refused 544 * Description: The intermediary's connection to the next hop was 545 refused. 547 * Extra Parameters: None. 549 * Recommended HTTP status code: 502 551 * Response only generated by intermediaries: true 553 * Reference: [this document] 555 2.3.8. Connection Terminated 557 * Name: connection_terminated 559 * Description: The intermediary's connection to the next hop was 560 closed before complete response was received. 562 * Extra Parameters: None. 564 * Recommended HTTP status code: 502 566 * Response only generated by intermediaries: false 568 * Reference: [this document] 570 2.3.9. Connection Timeout 572 * Name: connection_timeout 574 * Description: The intermediary's attempt to open a connection to 575 the next hop timed out. 577 * Extra Parameters: None. 579 * Recommended HTTP status code: 504 581 * Response only generated by intermediaries: true 583 * Reference: [this document] 585 2.3.10. Connection Read Timeout 587 * Name: connection_read_timeout 589 * Description: The intermediary was expecting data on a connection 590 (e.g., part of a response), but did not receive any new data in a 591 configured time limit. 593 * Extra Parameters: None. 595 * Recommended HTTP status code: 504 597 * Response only generated by intermediaries: false 599 * Reference: [this document] 601 2.3.11. Connection Write Timeout 603 * Name: connection_write_timeout 605 * Description: The intermediary was attempting to write data to a 606 connection, but was not able to (e.g., because its buffers were 607 full). 609 * Extra Parameters: None. 611 * Recommended HTTP status code: 504 613 * Response only generated by intermediaries: false 615 * Reference: [this document] 617 2.3.12. Connection Limit Reached 619 * Name: connection_limit_reached 621 * Description: The intermediary is configured to limit the number of 622 connections it has to the next hop, and that limit has been 623 passed. 625 * Extra Parameters: None. 627 * Recommended HTTP status code: 503 629 * Response only generated by intermediaries: true 631 * Reference: [this document] 633 2.3.13. TLS Protocol Error 635 * Name: tls_protocol_error 637 * Description: The intermediary encountered a TLS error when 638 communicating with the next hop, either during handshake or 639 afterwards. 641 * Extra Parameters: None. 643 * Recommended HTTP status code: 502 645 * Response only generated by intermediaries: false 647 * Reference: [this document] 649 * Notes: Not appropriate when a TLS alert is received; see 650 tls_alert_received 652 2.3.14. TLS Certificate Error 654 * Name: tls_certificate_error 656 * Description: The intermediary encountered an error when verifying 657 the certificate presented by the next hop. 659 * Extra Parameters: None. 661 * Recommended HTTP status code: 502 663 * Response only generated by intermediaries: true 664 * Reference: [this document] 666 2.3.15. TLS Alert Received 668 * Name: tls_alert_received 670 * Description: The intermediary received a TLS alert from the next 671 hop. 673 * Extra Parameters: 675 - alert-id: an sf-integer containing the applicable value from 676 the TLS Alerts registry. See {!RFC8446}}. 678 - alert-message: an sf-token or sf-string containing the 679 applicable description string from the TLS Alerts registry. 680 See [RFC8446]. 682 * Recommended HTTP status code: 502 684 * Response only generated by intermediaries: false 686 * Reference: [this document] 688 2.3.16. HTTP Request Error 690 * Name: http_request_error 692 * Description: The intermediary is generating a client (4xx) 693 response on the origin's behalf. Applicable status codes include 694 (but are not limited to) 400, 403, 405, 406, 408, 411, 413, 414, 695 415, 416, 417, 429. 697 * Extra Parameters: 699 - status-code: an sf-integer containing the generated status 700 code. 702 - status-phrase: an sf-string containing the generated status 703 phrase. 705 * Recommended HTTP status code: The applicable 4xx status code 707 * Response only generated by intermediaries: true 709 * Reference: [this document] 710 * Notes: This type helps distinguish between responses generated by 711 intermediaries from those generated by the origin. 713 2.3.17. HTTP Request Denied 715 * Name: http_request_denied 717 * Description: The intermediary rejected the HTTP request based on 718 its configuration and/or policy settings. The request wasn't 719 forwarded to the next hop. 721 * Extra Parameters: None. 723 * Recommended HTTP status code: 403 725 * Response only generated by intermediaries: true 727 * Reference: [this document] 729 2.3.18. HTTP Incomplete Response 731 * Name: http_response_incomplete 733 * Description: The intermediary received an incomplete response to 734 the request from the next hop. 736 * Extra Parameters: None. 738 * Recommended HTTP status code: 502 740 * Response only generated by intermediaries: false 742 * Reference: [this document] 744 2.3.19. HTTP Response Header Section Too Large 746 * Name: http_response_header_section_size 748 * Description: The intermediary received a response to the request 749 whose header section was considered too large. 751 * Extra Parameters: 753 - header-section-size: an sf-integer indicating how large the 754 headers received were. Note that they might not be complete; 755 i.e., the intermediary may have discarded or refused additional 756 data. 758 * Recommended HTTP status code: 502 760 * Response only generated by intermediaries: false 762 * Reference: [this document] 764 2.3.20. HTTP Response Header Field Line Too Large 766 * Name: http_response_header_size 768 * Description: The intermediary received a response to the request 769 containing an individual header field line that was considered too 770 large. 772 * Extra Parameters: 774 - header-name: an sf-string indicating the name of the header 775 field that triggered the error. 777 - header-size: an sf-integer indicating the size of the header 778 field that triggered the error. 780 * Recommended HTTP status code: 502 782 * Response only generated by intermediaries: false 784 * Reference: [this document] 786 2.3.21. HTTP Response Body Too Large 788 * Name: http_response_body_size 790 * Description: The intermediary received a response to the request 791 whose body was considered too large. 793 * Extra Parameters: 795 - body-size: an sf-integer indicating how large the body received 796 was. Note that it may not have been complete; i.e., the 797 intermediary may have discarded or refused additional data. 799 * Recommended HTTP status code: 502 801 * Response only generated by intermediaries: false 803 * Reference: [this document] 805 2.3.22. HTTP Response Trailer Section Too Large 807 * Name: http_response_trailer_section_size 809 * Description: The intermediary received a response to the request 810 whose trailer section was considered too large. 812 * Extra Parameters: 814 - trailer-section-size: an sf-integer indicating how large the 815 trailers received were. Note that they might not be complete; 816 i.e., the intermediary may have discarded or refused additional 817 data. 819 * Recommended HTTP status code: 502 821 * Response only generated by intermediaries: false 823 * Reference: [this document] 825 2.3.23. HTTP Response Trailer Field Line Too Large 827 * Name: http_response_trailer_size 829 * Description: The intermediary received a response to the request 830 containing an individual trailer field line that was considered 831 too large. 833 * Extra Parameters: 835 - trailer-name: an sf-string indicating the name of the trailer 836 field that triggered the error. 838 - trailer-size: an sf-integer indicating the size of the trailer 839 field that triggered the error. 841 * Recommended HTTP status code: 502 843 * Response only generated by intermediaries: false 845 * Reference: [this document] 847 2.3.24. HTTP Response Transfer-Coding Error 849 * Name: http_response_transfer_coding 851 * Description: The intermediary encountered an error decoding the 852 transfer-coding of the response. 854 * Extra Parameters: 856 - coding: an sf-token containing the specific coding (from the 857 HTTP Transfer Coding Registry) that caused the error. 859 * Recommended HTTP status code: 502 861 * Response only generated by intermediaries: false 863 * Reference: [this document] 865 2.3.25. HTTP Response Content-Coding Error 867 * Name: http_response_content_coding 869 * Description: The intermediary encountered an error decoding the 870 content-coding of the response. 872 * Extra Parameters: 874 - coding: an sf-token containing the specific coding (from the 875 HTTP Content Coding Registry) that caused the error. 877 * Recommended HTTP status code: 502 879 * Response only generated by intermediaries: false 881 * Reference: [this document] 883 2.3.26. HTTP Response Timeout 885 * Name: http_response_timeout 887 * Description: The intermediary reached a configured time limit 888 waiting for the complete response. 890 * Extra Parameters: None. 892 * Recommended HTTP status code: 504 894 * Response only generated by intermediaries: false 896 * Reference: [this document] 898 2.3.27. HTTP Upgrade Failed 900 * Name: http_upgrade_failed 901 * Description: The HTTP Upgrade between the intermediary and the 902 next hop failed. 904 * Extra Parameters: None. 906 * Recommended HTTP status code: 502 908 * Response only generated by intermediaries: true 910 * Reference: [this document] 912 2.3.28. HTTP Protocol Error 914 * Name: http_protocol_error 916 * Description: The intermediary encountered a HTTP protocol error 917 when communicating with the next hop. This error should only be 918 used when a more specific one is not defined. 920 * Extra Parameters: None. 922 * Recommended HTTP status code: 502 924 * Response only generated by intermediaries: false 926 * Reference: [this document] 928 2.3.29. Proxy Internal Response 930 * Name: proxy_internal_response 932 * Description: The intermediary generated the response locally, 933 without attempting to connect to the next hop (e.g. in response to 934 a request to a debug endpoint terminated at the intermediary). 936 * Extra Parameters: None. 938 * Recommended HTTP status code: The most appropriate status code for 939 the response 941 * Response only generated by intermediaries: true 943 * Reference: [this document] 945 2.3.30. Proxy Internal Error 947 * Name: proxy_internal_error 948 * Description: The intermediary encountered an internal error 949 unrelated to the origin. 951 * Extra Parameters: None 953 * Recommended HTTP status code: 500 955 * Response only generated by intermediaries: true 957 * Reference: [this document] 959 2.3.31. Proxy Configuration Error 961 * Name: proxy_configuration_error 963 * Description: The intermediary encountered an error regarding its 964 configuration. 966 * Extra Parameters: None 968 * Recommended HTTP status code: 500 970 * Response only generated by intermediaries: true 972 * Reference: [this document] 974 2.3.32. Proxy Loop Detected 976 * Name: proxy_loop_detected 978 * Description: The intermediary tried to forward the request to 979 itself, or a loop has been detected using different means (e.g. 980 [RFC8586]). 982 * Extra Parameters: None. 984 * Recommended HTTP status code: 502 986 * Response only generated by intermediaries: true 988 * Reference: [this document] 990 2.4. Defining New Proxy Error Types 992 New Proxy Error Types can be defined by registering them in the HTTP 993 Proxy Error Types registry. 995 Registration requests are reviewed and approved by Expert Review, as 996 per [RFC8126], Section 4.5. A specification document is appreciated, 997 but not required. 999 The Expert(s) should consider the following factors when evaluating 1000 requests: 1002 * Community feedback 1004 * If the value is sufficiently well-defined 1006 * Generic types are preferred over vendor-specific, application- 1007 specific or deployment-specific values. If a generic value cannot 1008 be agreed upon in the community, the types's name should be 1009 correspondingly specific (e.g., with a prefix that identifies the 1010 vendor, application or deployment). 1012 * Extra Parameters should not conflict with registered Proxy-Status 1013 parameters. 1015 Registration requests should use the following template: 1017 * Name: [a name for the Proxy Error Type that matches sf-token] 1019 * Description: [a description of the conditions that generate the 1020 Proxy Error Type] 1022 * Extra Parameters: [zero or more optional parameters, along with 1023 their allowable type(s)] 1025 * Recommended HTTP status code: [the appropriate HTTP status code 1026 for this entry] 1028 * Response only generated by intermediaries: ['true' or 'false'] 1030 * Reference: [to a specification defining this error type; optional] 1032 * Notes: [optional] 1034 If the Proxy Error Type might occur in responses that are not 1035 generated by the intermediary -- for example, when an error is 1036 detected as the response is streamed from a forward connection, 1037 causing a Proxy-Status trailer field to be appended -- the 'Response 1038 only generated by intermediaries' should be 'false'. If the Proxy 1039 Error Type only occurs in responses that are generated by the 1040 intermediary, it should be 'true'. 1042 See the registry at https://iana.org/assignments/http-proxy-status 1043 (https://iana.org/assignments/http-proxy-status) for details on where 1044 to send registration requests. 1046 3. IANA Considerations 1048 Upon publication, please create the HTTP Proxy-Status Parameters 1049 registry and the HTTP Proxy Error Types registry at 1050 https://iana.org/assignments/http-proxy-status 1051 (https://iana.org/assignments/http-proxy-status) and populate them 1052 with the types defined in Section 2.1 and Section 2.3 respectively; 1053 see Section 2.2 and Section 2.4 for its associated procedures. 1055 Additionally, please register the following entry in the Hypertext 1056 Transfer Protocol (HTTP) Field Name Registry: 1058 * Field name: Proxy-Status 1060 * Status: permanent 1062 * Specification document(s): [this document] 1064 * Comments: 1066 4. Security Considerations 1068 One of the primary security concerns when using Proxy-Status is 1069 leaking information that might aid an attacker. For example, 1070 information about the intermediary's configuration and back-end 1071 topology can be exposed, allowing attackers to directly target back- 1072 end services that are not prepared for high traffic volume or 1073 malformed inputs. Some information might only be suitable to reveal 1074 to authorized parties. 1076 As a result, care needs to be taken when deciding to generate a 1077 Proxy-Status field and what information to include in it. Note that 1078 intermediaries are not required to generate a Proxy-Status field in 1079 any response, and can conditionally generate them based upon request 1080 attributes (e.g., authentication tokens, IP address). 1082 Likewise, generation of all parameters is optional, as is generation 1083 of the field itself. Also, the field's content is not verified; an 1084 intermediary can claim certain actions (e.g., sending a request over 1085 an encrypted channel) but fail to actually do that. 1087 5. References 1089 5.1. Normative References 1091 [HTTP] Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 1092 Semantics", Work in Progress, Internet-Draft, draft-ietf- 1093 httpbis-semantics-19, 12 September 2021, 1094 . 1097 [STRUCTURED-FIELDS] 1098 Nottingham, M. and P-H. Kamp, "Structured Field Values for 1099 HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, 1100 . 1102 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1103 Requirement Levels", BCP 14, RFC 2119, 1104 DOI 10.17487/RFC2119, March 1997, 1105 . 1107 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 1108 Writing an IANA Considerations Section in RFCs", BCP 26, 1109 RFC 8126, DOI 10.17487/RFC8126, June 2017, 1110 . 1112 [RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS 1113 Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, 1114 January 2019, . 1116 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1117 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1118 May 2017, . 1120 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 1121 "Transport Layer Security (TLS) Application-Layer Protocol 1122 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 1123 July 2014, . 1125 [RFC8914] Kumari, W., Hunt, E., Arends, R., Hardaker, W., and D. 1126 Lawrence, "Extended DNS Errors", RFC 8914, 1127 DOI 10.17487/RFC8914, October 2020, 1128 . 1130 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1131 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1132 . 1134 5.2. Informative References 1136 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1137 Specifications: ABNF", STD 68, RFC 5234, 1138 DOI 10.17487/RFC5234, January 2008, 1139 . 1141 [RFC8586] Ludin, S., Nottingham, M., and N. Sullivan, "Loop 1142 Detection in Content Delivery Networks (CDNs)", RFC 8586, 1143 DOI 10.17487/RFC8586, April 2019, 1144 . 1146 Authors' Addresses 1148 Mark Nottingham 1149 Fastly 1150 Prahran 1151 Australia 1153 Email: mnot@mnot.net 1154 URI: https://www.mnot.net/ 1156 Piotr Sikora 1157 Google 1159 Email: piotrsikora@google.com