idnits 2.17.1 draft-ietf-httpbis-proxy-status-06.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 : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 1 character in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (16 August 2021) is 956 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) ** Obsolete normative reference: RFC 8499 (Obsoleted by RFC 9499) Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). 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: 17 February 2022 Google 6 16 August 2021 8 The Proxy-Status HTTP Response Header Field 9 draft-ietf-httpbis-proxy-status-06 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 17 February 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 . . . . . . . . . . . . . . . . . 5 69 2.1.1. error . . . . . . . . . . . . . . . . . . . . . . . . 5 70 2.1.2. next-hop . . . . . . . . . . . . . . . . . . . . . . 6 71 2.1.3. next-protocol . . . . . . . . . . . . . . . . . . . . 7 72 2.1.4. received-status . . . . . . . . . . . . . . . . . . . 7 73 2.1.5. details . . . . . . . . . . . . . . . . . . . . . . . 7 74 2.2. Defining New Proxy-Status Parameters . . . . . . . . . . 7 75 2.3. Proxy Error Types . . . . . . . . . . . . . . . . . . . . 8 76 2.3.1. DNS Timeout . . . . . . . . . . . . . . . . . . . . . 8 77 2.3.2. DNS Error . . . . . . . . . . . . . . . . . . . . . . 9 78 2.3.3. Destination Not Found . . . . . . . . . . . . . . . . 9 79 2.3.4. Destination Unavailable . . . . . . . . . . . . . . . 9 80 2.3.5. Destination IP Prohibited . . . . . . . . . . . . . . 10 81 2.3.6. Destination IP Unroutable . . . . . . . . . . . . . . 10 82 2.3.7. Connection Refused . . . . . . . . . . . . . . . . . 10 83 2.3.8. Connection Terminated . . . . . . . . . . . . . . . . 11 84 2.3.9. Connection Timeout . . . . . . . . . . . . . . . . . 11 85 2.3.10. Connection Read Timeout . . . . . . . . . . . . . . . 11 86 2.3.11. Connection Write Timeout . . . . . . . . . . . . . . 11 87 2.3.12. Connection Limit Reached . . . . . . . . . . . . . . 12 88 2.3.13. TLS Protocol Error . . . . . . . . . . . . . . . . . 12 89 2.3.14. TLS Certificate Error . . . . . . . . . . . . . . . . 13 90 2.3.15. TLS Alert Received . . . . . . . . . . . . . . . . . 13 91 2.3.16. HTTP Request Error . . . . . . . . . . . . . . . . . 13 92 2.3.17. HTTP Request Denied . . . . . . . . . . . . . . . . . 14 93 2.3.18. HTTP Incomplete Response . . . . . . . . . . . . . . 14 94 2.3.19. HTTP Response Header Section Too Large . . . . . . . 15 95 2.3.20. HTTP Response Header Too Large . . . . . . . . . . . 15 96 2.3.21. HTTP Response Body Too Large . . . . . . . . . . . . 15 97 2.3.22. HTTP Response Trailer Section Too Large . . . . . . . 16 98 2.3.23. HTTP Response Trailer Too Large . . . . . . . . . . . 16 99 2.3.24. HTTP Response Transfer-Coding Error . . . . . . . . . 17 100 2.3.25. HTTP Response Content-Coding Error . . . . . . . . . 17 101 2.3.26. HTTP Response Timeout . . . . . . . . . . . . . . . . 18 102 2.3.27. HTTP Upgrade Failed . . . . . . . . . . . . . . . . . 18 103 2.3.28. HTTP Protocol Error . . . . . . . . . . . . . . . . . 18 104 2.3.29. Proxy Internal Response . . . . . . . . . . . . . . . 19 105 2.3.30. Proxy Internal Error . . . . . . . . . . . . . . . . 19 106 2.3.31. Proxy Configuration Error . . . . . . . . . . . . . . 19 107 2.3.32. Proxy Loop Detected . . . . . . . . . . . . . . . . . 20 108 2.4. Defining New Proxy Error Types . . . . . . . . . . . . . 20 109 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 110 4. Security Considerations . . . . . . . . . . . . . . . . . . . 21 111 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 112 5.1. Normative References . . . . . . . . . . . . . . . . . . 21 113 5.2. Informative References . . . . . . . . . . . . . . . . . 22 114 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 116 1. Introduction 118 HTTP intermediaries -- including both forward proxies and gateways 119 (also known as "reverse proxies") -- have become an increasingly 120 significant part of HTTP deployments. In particular, reverse proxies 121 and Content Delivery Networks (CDNs) form part of the critical 122 infrastructure of many Web sites. 124 Typically, HTTP intermediaries forward requests towards the origin 125 server and then forward their responses back to clients. However, if 126 an error occurs before a response is obtained from upstream, the 127 response is often generated by the intermediary itself. 129 HTTP accommodates these types of errors with a few status codes; for 130 example, 502 Bad Gateway and 504 Gateway Timeout. However, 131 experience has shown that more information is necessary to aid 132 debugging and communicate what's happened to the client. 133 Additionally, intermediaries sometimes want to convey additional 134 information about their handling of a response, even if they did not 135 generate it. 137 To enable these uses, Section 2 defines a new HTTP response field to 138 allow intermediaries to convey details of their handling of a 139 response. Section 2.1 enumerates the information that can be added 140 to the field by intermediaries, which can be extended as per 141 Section 2.2. Section 2.3 defines a set of error types for use when a 142 proxy encounters an issue when obtaining a response for the request; 143 these can likewise be extended as per Section 2.4. 145 1.1. Notational Conventions 147 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 148 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 149 "OPTIONAL" in this document are to be interpreted as described in BCP 150 14 [RFC2119] [RFC8174] when, and only when, they appear in all 151 capitals, as shown here. 153 This specification uses Structured Fields [RFC8941] to specify syntax 154 and parsing, and ABNF [RFC5234] as a shorthand for that syntax. The 155 terms sf-list, sf-item, sf-string, sf-token, sf-integer and key refer 156 to the structured types defined therein. 158 Note that in this specification, "proxy" is used to indicate both 159 forward and reverse proxies, otherwise known as gateways. "Next hop" 160 indicates the connection in the direction leading to the origin 161 server for the request. 163 2. The Proxy-Status HTTP Field 165 The Proxy-Status HTTP response field allows an intermediary to convey 166 additional information about its handling of a response and its 167 associated request. 169 It is a List ([RFC8941], Section 3.1): 171 Proxy-Status = sf-list 173 Each member of the list represents an intermediary that has handled 174 the response. The first member of the list represents the 175 intermediary closest to the origin server, and the last member of the 176 list represents the intermediary closest to the user agent. 178 For example: 180 Proxy-Status: FooProxy, ExampleCDN 182 indicates that this response was handled first by FooProxy (a reverse 183 proxy adjacent to the origin server) and then ExampleCDN. 185 Intermediaries determine when it is appropriate to add the Proxy- 186 Status field to a response. Some might decide to append to it to all 187 responses, whereas others might only do so when specifically 188 configured to, or when the request contains a header that activates a 189 debugging mode. 191 Each member of the list identifies the intermediary that inserted the 192 value, and MUST have a type of either sf-string or sf-token. 193 Depending on the deployment, this might be a product or service name 194 (e.g., ExampleProxy or "Example CDN"), a hostname ("proxy- 195 3.example.com"), an IP address, or a generated string. 197 Parameters on each member convey additional information about that 198 intermediary's handling of the response and its associated request; 199 see Section 2.1. While all of these parameters are OPTIONAL, 200 intermediaries are encouraged to provide as much information as 201 possible (but see Section 4 for security considerations in doing so). 203 When adding a value to the Proxy-Status field, intermediaries SHOULD 204 preserve the existing members of the field, to allow debugging of the 205 entire chain of intermediaries handling the request. 207 Proxy-Status MAY be sent in HTTP trailers. For example, if an 208 intermediary is streaming a response and the upstream connection 209 suddenly terminates, Proxy-Status can only be appended to the 210 trailers of the outgoing message, since the headers have already been 211 sent. As with all trailers, it might be silently discarded along the 212 path to the user agent, so this SHOULD NOT be done unless it is not 213 possible to send it in headers, and an intermediary MUST NOT send 214 Proxy-Status as a trailer field unless it has also sent a 215 corresponding Proxy-Status header field in the same message, so that 216 the trailer value's ordering relative to other intermediaries is 217 preserved. 219 Origin servers MUST NOT generate the Proxy-Status field. 221 2.1. Proxy-Status Parameters 223 This section lists parameters that can be used on the members of the 224 Proxy-Status field. Unrecognised parameters MUST be ignored. 226 2.1.1. error 228 The "error" parameter's value is an sf-token that is a Proxy Error 229 Type. When present, it indicates that the proxy encountered an issue 230 when obtaining a response. 232 Unless a Proxy Error Type specifies otherwise, the presences of error 233 often, but not always, indicates that response was generated by the 234 proxy, not the origin server or any other upstream server. For 235 example, a proxy might attempt to correct an error, or part of a 236 response might be forwarded before the error is encountered. 238 Section 2.3 lists the Proxy Error Types defined in this document; new 239 ones can be defined using the procedure outlined in Section 2.4. 241 For example: 243 HTTP/1.1 504 Gateway Timeout 244 Proxy-Status: SomeCDN; error=connection_timeout 246 indicates that this 504 response was generated by SomeCDN, due to a 247 connection timeout when going forward. 249 Or: 251 HTTP/1.1 429 Too Many Requests 252 Proxy-Status: SomeReverseProxy; error=http_request_error 254 indicates that this 429 Too Many Requests response was generated by 255 the intermediary, not the origin. 257 When sending the error parameter, the most specific Proxy Error Type 258 SHOULD be sent, provided that it accurately represents the error 259 condition. If an appropriate Proxy Error Type is not defined, there 260 are a number of generic error types (e.g., proxy_internal_error, 261 http_protocol_error) that can be used. If they are not suitable, 262 consider registering a new Proxy Error Type (see Section 2.4). 264 Each Proxy Error Type has a Recommended HTTP Status Code. When 265 generating a HTTP response containing "error", its HTTP status code 266 SHOULD be set to the Recommended HTTP Status Code. However, there 267 may be circumstances (e.g., for backwards compatibility with previous 268 behaviours, a status code has already been sent) when another status 269 code might be used. 271 Proxy Error Types can also define any number of extra parameters for 272 use with that type. Their use, like all parameters, is optional. As 273 a result, if an extra parameter is used with a Proxy Error Type for 274 which it is not defined, it will be ignored. 276 2.1.2. next-hop 278 The "next-hop" parameter's value is an sf-string or sf-token that 279 identifies the intermediary or origin server selected (and used, if 280 contacted) for this response. It might be a hostname, IP address, or 281 alias. 283 For example: 285 Proxy-Status: cdn.example.org; next-hop=backend.example.org 287 2.1.3. next-protocol 289 The "next-protocol" parameter's value indicates the ALPN protocol 290 identifier [RFC7301] used by the intermediary to connect to the next 291 hop. This is only applicable when that connection was actually 292 established. 294 The value MUST be either an sf-token or sf-binary, representing a TLS 295 Application-Layer Protocol Negotiation (ALPN) Protocol ID (see 296 https://www.iana.org/assignments/tls-extensiontype-values/tls- 297 extensiontype-values.xhtml#alpn-protocol-ids 298 (https://www.iana.org/assignments/tls-extensiontype-values/tls- 299 extensiontype-values.xhtml#alpn-protocol-ids)). If the protocol 300 identifier is able to be expressed as an sf-token using ASCII 301 encoding, that form MUST be used. 303 For example: 305 Proxy-Status: "proxy.example.org"; next-protocol=h2 307 2.1.4. received-status 309 The "received-status" parameter's value indicates the HTTP status 310 code that the intermediary received from the next hop server. 312 The value MUST be an sf-integer. 314 For example: 316 Proxy-Status: ExampleProxy; received-status=200 318 2.1.5. details 320 The "details" parameter's value is an sf-string containing additional 321 information not captured anywhere else. This can include 322 implementation-specific or deployment-specific information. 324 For example: 326 Proxy-Status: ExampleProxy; error="http_protocol_error"; 327 details="Malformed response header - space before colon" 329 2.2. Defining New Proxy-Status Parameters 331 New Proxy-Status Parameters can be defined by registering them in the 332 HTTP Proxy-Status Parameters registry. 334 Registration requests are reviewed and approved by Expert Review, as 335 per [RFC8126], Section 4.5. A specification document is appreciated, 336 but not required. 338 The Expert(s) should consider the following factors when evaluating 339 requests: 341 * Community feedback 343 * If the value is sufficiently well-defined 345 * Generic parameters are preferred over vendor-specific, 346 application-specific or deployment-specific values. If a generic 347 value cannot be agreed upon in the community, the parameter's name 348 should be correspondingly specific (e.g., with a prefix that 349 identifies the vendor, application or deployment). 351 * Parameter names should not conflict with registered extra 352 parameters in the Proxy Error Type Registry. 354 Registration requests should use the following template: 356 * Name: [a name for the Proxy-Status Parameter that matches key] 358 * Description: [a description of the parameter semantics and value] 360 * Reference: [to a specification defining this parameter; optional] 362 See the registry at https://iana.org/assignments/http-proxy-status 363 (https://iana.org/assignments/http-proxy-status) for details on where 364 to send registration requests. 366 2.3. Proxy Error Types 368 This section lists the Proxy Error Types defined by this document. 369 See Section 2.4 for information about defining new Proxy Error Types. 371 Note that implementations might not produce all Proxy Error Types. 372 The set of types below is designed to map to existing states in 373 implementations, and so may not be applicable to some. 375 2.3.1. DNS Timeout 377 * Name: dns_timeout 379 * Description: The intermediary encountered a timeout when trying to 380 find an IP address for the next hop hostname. 382 * Extra Parameters: None. 384 * Recommended HTTP status code: 504 386 * Reference: [this document] 388 2.3.2. DNS Error 390 * Name: dns_error 392 * Description: The intermediary encountered a DNS error when trying 393 to find an IP address for the next hop hostname. 395 * Extra Parameters: 397 - rcode: A sf-string conveying the DNS RCODE that indicates the 398 error type. See [RFC8499], Section 3. 400 - info-code: A sf-integer conveying the Extended DNS Error Code 401 info-code. See [RFC8914]. 403 * Recommended HTTP status code: 502 405 * Reference: [this document] 407 2.3.3. Destination Not Found 409 * Name: destination_not_found 411 * Description: The intermediary cannot determine the appropriate 412 next hop to use for this request; for example, it may not be 413 configured. Note that this error is specific to gateways, which 414 typically require specific configuration to identify the "backend" 415 server; forward proxies use in-band information to identify the 416 origin server. 418 * Extra Parameters: None. 420 * Recommended HTTP status code: 500 422 * Reference: [this document] 424 2.3.4. Destination Unavailable 426 * Name: destination_unavailable 427 * Description: The intermediary considers the next hop to be 428 unavailable; e.g., recent attempts to communicate with it may have 429 failed, or a health check may indicate that it is down. 431 * Extra Parameters: None. 433 * Recommended HTTP status code: 503 435 * Reference: [this document] 437 2.3.5. Destination IP Prohibited 439 * Name: destination_ip_prohibited 441 * Description: The intermediary is configured to prohibit 442 connections to the next hop IP address. 444 * Extra Parameters: None. 446 * Recommended HTTP status code: 502 448 * Reference: [this document] 450 2.3.6. Destination IP Unroutable 452 * Name: destination_ip_unroutable 454 * Description: The intermediary cannot find a route to the next hop 455 IP address. 457 * Extra Parameters: None. 459 * Recommended HTTP status code: 502 461 * Reference: [this document] 463 2.3.7. Connection Refused 465 * Name: connection_refused 467 * Description: The intermediary's connection to the next hop was 468 refused. 470 * Extra Parameters: None. 472 * Recommended HTTP status code: 502 474 * Reference: [this document] 476 2.3.8. Connection Terminated 478 * Name: connection_terminated 480 * Description: The intermediary's connection to the next hop was 481 closed before complete response was received. 483 * Extra Parameters: None. 485 * Recommended HTTP status code: 502 487 * Reference: [this document] 489 * Notes: Responses with this error type might not have been 490 generated by the intermediary. 492 2.3.9. Connection Timeout 494 * Name: connection_timeout 496 * Description: The intermediary's attempt to open a connection to 497 the next hop timed out. 499 * Extra Parameters: None. 501 * Recommended HTTP status code: 504 503 * Reference: [this document] 505 2.3.10. Connection Read Timeout 507 * Name: connection_read_timeout 509 * Description: The intermediary was expecting data on a connection 510 (e.g., part of a response), but did not receive any new data in a 511 configured time limit. 513 * Extra Parameters: None. 515 * Recommended HTTP status code: 504 517 * Reference: [this document] 519 * Notes: Responses with this error type might not have been 520 generated by the intermediary. 522 2.3.11. Connection Write Timeout 523 * Name: connection_write_timeout 525 * Description: The intermediary was attempting to write data to a 526 connection, but was not able to (e.g., because its buffers were 527 full). 529 * Extra Parameters: None. 531 * Recommended HTTP status code: 504 533 * Reference: [this document] 535 * Notes: Responses with this error type might not have been 536 generated by the intermediary. 538 2.3.12. Connection Limit Reached 540 * Name: connection_limit_reached 542 * Description: The intermediary is configured to limit the number of 543 connections it has to the next hop, and that limit has been 544 passed. 546 * Extra Parameters: None. 548 * Recommended HTTP status code: 503 550 * Reference: [this document] 552 2.3.13. TLS Protocol Error 554 * Name: tls_protocol_error 556 * Description: The intermediary encountered a TLS error when 557 communicating with the next hop, either during handshake or 558 afterwards. 560 * Extra Parameters: None. 562 * Recommended HTTP status code: 502 564 * Reference: [this document] 566 * Notes: Responses with this error type might not have been 567 generated by the intermediary. 569 Note that additional information about the error can be recorded in 570 the details parameter (as is the case for all errors). 572 2.3.14. TLS Certificate Error 574 * Name: tls_certificate_error 576 * Description: The intermediary encountered an error when verifying 577 the certificate presented by the next hop. 579 * Extra Parameters: None. 581 * Recommended HTTP status code: 502 583 * Reference: [this document] 585 Note that additional information about the error can be recorded in 586 the details parameter (as is the case for all errors). 588 2.3.15. TLS Alert Received 590 * Name: tls_alert_received 592 * Description: The intermediary received a TLS alert from the next 593 hop. 595 * Extra Parameters: 597 - alert-id: an sf-integer containing the applicable value from 598 the TLS Alerts registry. See {!RFC8446}}. 600 - alert-message: an sf-token containing the applicable 601 description string from the TLS Alerts registry. See 602 [RFC8446]. 604 * Recommended HTTP status code: 502 606 * Reference: [this document] 608 * Notes: Responses with this error type might not have been 609 generated by the intermediary. 611 2.3.16. HTTP Request Error 613 * Name: http_request_error 615 * Description: The intermediary is generating a client (4xx) 616 response on the origin's behalf. Applicable status codes include 617 (but are not limited to) 400, 403, 405, 406, 408, 411, 413, 414, 618 415, 416, 417, 429. 620 * Extra Parameters: 622 - status-code: an sf-integer containing the generated status 623 code. 625 - status-phrase: an sf-string containing the generated status 626 phrase. 628 * Recommended HTTP status code: The applicable 4xx status code 630 * Reference: [this document] 632 * Notes: This type helps distinguish between responses generated by 633 intermediaries from those generated by the origin. 635 2.3.17. HTTP Request Denied 637 * Name: http_request_denied 639 * Description: The intermediary rejected the HTTP request based on 640 its configuration and/or policy settings. The request wasn't 641 forwarded to the next hop. 643 * Extra Parameters: None. 645 * Recommended HTTP status code: 403 647 * Reference: [this document] 649 2.3.18. HTTP Incomplete Response 651 * Name: http_response_incomplete 653 * Description: The intermediary received an incomplete response to 654 the request from the next hop. 656 * Extra Parameters: None. 658 * Recommended HTTP status code: 502 660 * Reference: [this document] 662 * Notes: Responses with this error type might not have been 663 generated by the intermediary. 665 2.3.19. HTTP Response Header Section Too Large 667 * Name: http_response_header_section_size 669 * Description: The intermediary received a response to the request 670 whose header section was considered too large. 672 * Extra Parameters: 674 - header-section-size: an sf-integer indicating how large the 675 headers received were. Note that they might not be complete; 676 i.e., the intermediary may have discarded or refused additional 677 data. 679 * Recommended HTTP status code: 502 681 * Reference: [this document] 683 * Notes: Responses with this error type might not have been 684 generated by the intermediary. 686 2.3.20. HTTP Response Header Too Large 688 * Name: http_response_header_size 690 * Description: The intermediary received a response to the request 691 containing an individual header line that was considered too 692 large. 694 * Extra Parameters: 696 - header-name: an sf-string indicating the name of the header 697 that triggered the error. 699 - header-size: an sf-integer indicating the size of the header 700 that triggered the error. 702 * Recommended HTTP status code: 502 704 * Reference: [this document] 706 * Notes: Responses with this error type might not have been 707 generated by the intermediary. 709 2.3.21. HTTP Response Body Too Large 711 * Name: http_response_body_size 712 * Description: The intermediary received a response to the request 713 whose body was considered too large. 715 * Extra Parameters: 717 - body-size: an sf-integer indicating how large the body received 718 was. Note that it may not have been complete; i.e., the 719 intermediary may have discarded or refused additional data. 721 * Recommended HTTP status code: 502 723 * Reference: [this document] 725 * Notes: Responses with this error type might not have been 726 generated by the intermediary. 728 2.3.22. HTTP Response Trailer Section Too Large 730 * Name: http_response_trailer_section_size 732 * Description: The intermediary received a response to the request 733 whose trailer section was considered too large. 735 * Extra Parameters: 737 - trailer-section-size: an sf-integer indicating how large the 738 trailers received were. Note that they might not be complete; 739 i.e., the intermediary may have discarded or refused additional 740 data. 742 * Recommended HTTP status code: 502 744 * Reference: [this document] 746 * Notes: Responses with this error type might not have been 747 generated by the intermediary. 749 2.3.23. HTTP Response Trailer Too Large 751 * Name: http_response_trailer_size 753 * Description: The intermediary received a response to the request 754 containing an individual trailer line that was considered too 755 large. 757 * Extra Parameters: 759 - trailer-name: an sf-string indicating the name of the trailer 760 that triggered the error. 762 - trailer-size: an sf-integer indicating the size of the trailer 763 that triggered the error. 765 * Recommended HTTP status code: 502 767 * Reference: [this document] 769 * Notes: Responses with this error type might not have been 770 generated by the intermediary. 772 2.3.24. HTTP Response Transfer-Coding Error 774 * Name: http_response_transfer_coding 776 * Description: The intermediary encountered an error decoding the 777 transfer-coding of the response. 779 * Extra Parameters: 781 - coding: an sf-token containing the specific coding that caused 782 the error. 784 * Recommended HTTP status code: 502 786 * Reference: [this document] 788 * Notes: Responses with this error type might not have been 789 generated by the intermediary. 791 2.3.25. HTTP Response Content-Coding Error 793 * Name: http_response_content_coding 795 * Description: The intermediary encountered an error decoding the 796 content-coding of the response. 798 * Extra Parameters: 800 - coding: an sf-token containing the specific coding that caused 801 the error. 803 * Recommended HTTP status code: 502 805 * Reference: [this document] 806 * Notes: Responses with this error type might not have been 807 generated by the intermediary. 809 2.3.26. HTTP Response Timeout 811 * Name: http_response_timeout 813 * Description: The intermediary reached a configured time limit 814 waiting for the complete response. 816 * Extra Parameters: None. 818 * Recommended HTTP status code: 504 820 * Reference: [this document] 822 * Notes: Responses with this error type might not have been 823 generated by the intermediary. 825 2.3.27. HTTP Upgrade Failed 827 * Name: http_upgrade_failed 829 * Description: The HTTP Upgrade between the intermediary and the 830 next hop failed. 832 * Extra Parameters: None. 834 * Recommended HTTP status code: 502 836 * Reference: [this document] 838 2.3.28. HTTP Protocol Error 840 * Name: http_protocol_error 842 * Description: The intermediary encountered a HTTP protocol error 843 when communicating with the next hop. This error should only be 844 used when a more specific one is not defined. 846 * Extra Parameters: None. 848 * Recommended HTTP status code: 502 850 * Reference: [this document] 852 * Notes: Responses with this error type might not have been 853 generated by the intermediary. 855 Note that additional information about the error can be recorded in 856 the details parameter (as is the case for all errors). 858 2.3.29. Proxy Internal Response 860 * Name: proxy_internal_response 862 * Description: The intermediary generated the response locally, 863 without attempting to connect to the next hop (e.g. in response to 864 a request to a debug endpoint terminated at the intermediary). 866 * Extra Parameters: None. 868 * Recommended HTTP status code: The most appropriate status code for 869 the response 871 * Reference: [this document] 873 2.3.30. Proxy Internal Error 875 * Name: proxy_internal_error 877 * Description: The intermediary encountered an internal error 878 unrelated to the origin. 880 * Extra Parameters: None 882 * Recommended HTTP status code: 500 884 * Reference: [this document] 886 Note that additional information about the error can be recorded in 887 the details parameter (as is the case for all errors). 889 2.3.31. Proxy Configuration Error 891 * Name: proxy_configuration_error 893 * Description: The intermediary encountered an error regarding its 894 configuration. 896 * Extra Parameters: None 898 * Recommended HTTP status code: 500 900 * Reference: [this document] 901 Note that additional information about the error can be recorded in 902 the details parameter (as is the case for all errors). 904 2.3.32. Proxy Loop Detected 906 * Name: proxy_loop_detected 908 * Description: The intermediary tried to forward the request to 909 itself, or a loop has been detected using different means (e.g. 910 [RFC8586]). 912 * Extra Parameters: None. 914 * Recommended HTTP status code: 502 916 * Reference: [this document] 918 2.4. Defining New Proxy Error Types 920 New Proxy Error Types can be defined by registering them in the HTTP 921 Proxy Error Types registry. 923 Registration requests are reviewed and approved by Expert Review, as 924 per [RFC8126], Section 4.5. A specification document is appreciated, 925 but not required. 927 The Expert(s) should consider the following factors when evaluating 928 requests: 930 * Community feedback 932 * If the value is sufficiently well-defined 934 * Generic types are preferred over vendor-specific, application- 935 specific or deployment-specific values. If a generic value cannot 936 be agreed upon in the community, the types's name should be 937 correspondingly specific (e.g., with a prefix that identifies the 938 vendor, application or deployment). 940 * Extra Parameters should not conflict with registered Proxy-Status 941 parameters. 943 Registration requests should use the following template: 945 * Name: [a name for the Proxy Error Type that matches sf-token] 947 * Description: [a description of the conditions that generate the 948 Proxy Error Type] 950 * Extra Parameters: [zero or more optional parameters, along with 951 their allowable type(s)] 953 * Recommended HTTP status code: [the appropriate HTTP status code 954 for this entry] 956 * Reference: [to a specification defining this error type; optional] 958 * Notes: [optional] 960 If the Proxy Error Type might occur in responses that are not 961 generated by the intermediary -- for example, when the error is 962 detected during response content processing and a Proxy-Status 963 trailer field is appended -- that SHOULD be explained in the Notes. 965 See the registry at https://iana.org/assignments/http-proxy-status 966 (https://iana.org/assignments/http-proxy-status) for details on where 967 to send registration requests. 969 3. IANA Considerations 971 Upon publication, please create the HTTP Proxy-Status Parameters 972 registry and the HTTP Proxy Error Types registry at 973 https://iana.org/assignments/http-proxy-status 974 (https://iana.org/assignments/http-proxy-status) and populate them 975 with the types defined in Section 2.1 and Section 2.3 respectively; 976 see Section 2.2 and Section 2.4 for its associated procedures. 978 4. Security Considerations 980 One of the primary security concerns when using Proxy-Status is 981 leaking information that might aid an attacker. For example, 982 information about the intermediary's configuration and back-end 983 topology can be exposed. 985 As a result, care needs to be taken when deciding to generate a 986 Proxy-Status field. Note that intermediaries are not required to 987 generate a Proxy-Status field in any response, and can conditionally 988 generate them based upon request attributes (e.g., authentication 989 tokens, IP address). 991 Likewise, generation of all parameters is optional. 993 5. References 995 5.1. Normative References 997 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 998 Requirement Levels", BCP 14, RFC 2119, 999 DOI 10.17487/RFC2119, March 1997, 1000 . 1002 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 1003 Writing an IANA Considerations Section in RFCs", BCP 26, 1004 RFC 8126, DOI 10.17487/RFC8126, June 2017, 1005 . 1007 [RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS 1008 Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, 1009 January 2019, . 1011 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1012 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1013 May 2017, . 1015 [RFC8941] Nottingham, M. and P-H. Kamp, "Structured Field Values for 1016 HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, 1017 . 1019 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 1020 "Transport Layer Security (TLS) Application-Layer Protocol 1021 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 1022 July 2014, . 1024 [RFC8914] Kumari, W., Hunt, E., Arends, R., Hardaker, W., and D. 1025 Lawrence, "Extended DNS Errors", RFC 8914, 1026 DOI 10.17487/RFC8914, October 2020, 1027 . 1029 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1030 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1031 . 1033 5.2. Informative References 1035 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1036 Specifications: ABNF", STD 68, RFC 5234, 1037 DOI 10.17487/RFC5234, January 2008, 1038 . 1040 [RFC8586] Ludin, S., Nottingham, M., and N. Sullivan, "Loop 1041 Detection in Content Delivery Networks (CDNs)", RFC 8586, 1042 DOI 10.17487/RFC8586, April 2019, 1043 . 1045 Authors' Addresses 1047 Mark Nottingham 1048 Fastly 1049 Prahran VIC 1050 Australia 1052 Email: mnot@mnot.net 1053 URI: https://www.mnot.net/ 1055 Piotr Sikora 1056 Google 1058 Email: piotrsikora@google.com