idnits 2.17.1 draft-ietf-httpbis-proxy-status-05.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 (27 April 2021) is 1089 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: 29 October 2021 Google 6 27 April 2021 8 The Proxy-Status HTTP Response Header Field 9 draft-ietf-httpbis-proxy-status-05 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 29 October 2021. 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 . . . . . . . . . . . . . . . . . . . . . . 8 78 2.3.3. Destination Not Found . . . . . . . . . . . . . . . . 9 79 2.3.4. Destination Unavailable . . . . . . . . . . . . . . . 9 80 2.3.5. Destination IP Prohibited . . . . . . . . . . . . . . 9 81 2.3.6. Destination IP Unroutable . . . . . . . . . . . . . . 10 82 2.3.7. Connection Refused . . . . . . . . . . . . . . . . . 10 83 2.3.8. Connection Terminated . . . . . . . . . . . . . . . . 10 84 2.3.9. Connection Timeout . . . . . . . . . . . . . . . . . 10 85 2.3.10. Connection Read Timeout . . . . . . . . . . . . . . . 11 86 2.3.11. Connection Write Timeout . . . . . . . . . . . . . . 11 87 2.3.12. Connection Limit Reached . . . . . . . . . . . . . . 11 88 2.3.13. TLS Protocol Error . . . . . . . . . . . . . . . . . 11 89 2.3.14. TLS Certificate Error . . . . . . . . . . . . . . . . 12 90 2.3.15. TLS Alert Received . . . . . . . . . . . . . . . . . 12 91 2.3.16. HTTP Request Error . . . . . . . . . . . . . . . . . 13 92 2.3.17. HTTP Request Denied . . . . . . . . . . . . . . . . . 13 93 2.3.18. HTTP Incomplete Response . . . . . . . . . . . . . . 13 94 2.3.19. HTTP Response Header Section Too Large . . . . . . . 14 95 2.3.20. HTTP Response Header Too Large . . . . . . . . . . . 14 96 2.3.21. HTTP Response Body Too Large . . . . . . . . . . . . 14 97 2.3.22. HTTP Response Trailer Section Too Large . . . . . . . 15 98 2.3.23. HTTP Response Trailer Too Large . . . . . . . . . . . 15 99 2.3.24. HTTP Response Transfer-Coding Error . . . . . . . . . 16 100 2.3.25. HTTP Response Content-Coding Error . . . . . . . . . 16 101 2.3.26. HTTP Response Timeout . . . . . . . . . . . . . . . . 16 102 2.3.27. HTTP Upgrade Failed . . . . . . . . . . . . . . . . . 17 103 2.3.28. HTTP Protocol Error . . . . . . . . . . . . . . . . . 17 104 2.3.29. Proxy Internal Response . . . . . . . . . . . . . . . 17 105 2.3.30. Proxy Internal Error . . . . . . . . . . . . . . . . 17 106 2.3.31. Proxy Configuration Error . . . . . . . . . . . . . . 18 107 2.3.32. Proxy Loop Detected . . . . . . . . . . . . . . . . . 18 108 2.4. Defining New Proxy Error Types . . . . . . . . . . . . . 18 109 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 110 4. Security Considerations . . . . . . . . . . . . . . . . . . . 19 111 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 112 5.1. Normative References . . . . . . . . . . . . . . . . . . 20 113 5.2. Informative References . . . . . . . . . . . . . . . . . 20 114 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 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 and then 183 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. If the protocol 295 identifier is able to be expressed as an sf-token using UTF-8 296 encoding, that form MUST be used. 298 For example: 300 Proxy-Status: "proxy.example.org"; next-protocol=h2 302 2.1.4. received-status 304 The "received-status" parameter's value indicates the HTTP status 305 code that the intermediary received from the next hop server. 307 The value MUST be an sf-integer. 309 For example: 311 Proxy-Status: ExampleProxy; received-status=200 313 2.1.5. details 315 The "details" parameter's value is an sf-string containing additional 316 information not captured anywhere else. This can include 317 implementation-specific or deployment-specific information. 319 For example: 321 Proxy-Status: ExampleProxy; error="http_protocol_error"; 322 details="Malformed response header - space before colon" 324 2.2. Defining New Proxy-Status Parameters 326 New Proxy-Status Parameters can be defined by registering them in the 327 HTTP Proxy-Status Parameters registry. 329 Registration requests are reviewed and approved by a Designated 330 Expert, as per [RFC8126], Section 4.5. A specification document is 331 appreciated, but not required. 333 The Expert(s) should consider the following factors when evaluating 334 requests: 336 * Community feedback 338 * If the value is sufficiently well-defined 340 * Generic parameters are preferred over vendor-specific, 341 application-specific or deployment-specific values. If a generic 342 value cannot be agreed upon in the community, the parameter's name 343 should be correspondingly specific (e.g., with a prefix that 344 identifies the vendor, application or deployment). 346 * Parameter names should not conflict with registered extra 347 parameters in the Proxy Error Type Registry. 349 Registration requests should use the following template: 351 * Name: [a name for the Proxy-Status Parameter that matches key] 353 * Description: [a description of the parameter semantics and value] 355 * Reference: [to a specification defining this parameter] 357 See the registry at https://iana.org/assignments/http-proxy-status 358 (https://iana.org/assignments/http-proxy-status) for details on where 359 to send registration requests. 361 2.3. Proxy Error Types 363 This section lists the Proxy Error Types defined by this document. 364 See Section 2.4 for information about defining new Proxy Error Types. 366 2.3.1. DNS Timeout 368 * Name: dns_timeout 370 * Description: The intermediary encountered a timeout when trying to 371 find an IP address for the next hop hostname. 373 * Extra Parameters: None. 375 * Recommended HTTP status code: 504 377 2.3.2. DNS Error 379 * Name: dns_error 381 * Description: The intermediary encountered a DNS error when trying 382 to find an IP address for the next hop hostname. 384 * Extra Parameters: 386 - rcode: A sf-string conveying the DNS RCODE that indicates the 387 error type. See [RFC8499], Section 3. 389 - info-code: A sf-integer conveying the Extended DNS Error Code 390 info-code. See [RFC8914]. 392 * Recommended HTTP status code: 502 394 2.3.3. Destination Not Found 396 * Name: destination_not_found 398 * Description: The intermediary cannot determine the appropriate 399 next hop to use for this request; for example, it may not be 400 configured. Note that this error is specific to gateways, which 401 typically require specific configuration to identify the "backend" 402 server; forward proxies use in-band information to identify the 403 origin server. 405 * Extra Parameters: None. 407 * Recommended HTTP status code: 500 409 2.3.4. Destination Unavailable 411 * Name: destination_unavailable 413 * Description: The intermediary considers the next hop to be 414 unavailable; e.g., recent attempts to communicate with it may have 415 failed, or a health check may indicate that it is down. 417 * Extra Parameters: None. 419 * Recommended HTTP status code: 503 421 2.3.5. Destination IP Prohibited 423 * Name: destination_ip_prohibited 425 * Description: The intermediary is configured to prohibit 426 connections to the next hop IP address. 428 * Extra Parameters: None. 430 * Recommended HTTP status code: 502 432 2.3.6. Destination IP Unroutable 434 * Name: destination_ip_unroutable 436 * Description: The intermediary cannot find a route to the next hop 437 IP address. 439 * Extra Parameters: None. 441 * Recommended HTTP status code: 502 443 2.3.7. Connection Refused 445 * Name: connection_refused 447 * Description: The intermediary's connection to the next hop was 448 refused. 450 * Extra Parameters: None. 452 * Recommended HTTP status code: 502 454 2.3.8. Connection Terminated 456 * Name: connection_terminated 458 * Description: The intermediary's connection to the next hop was 459 closed before complete response was received. 461 * Extra Parameters: None. 463 * Recommended HTTP status code: 502 465 * Notes: Responses with this error type might not have been 466 generated by the intermediary. 468 2.3.9. Connection Timeout 470 * Name: connection_timeout 472 * Description: The intermediary's attempt to open a connection to 473 the next hop timed out. 475 * Extra Parameters: None. 477 * Recommended HTTP status code: 504 479 2.3.10. Connection Read Timeout 481 * Name: connection_read_timeout 483 * Description: The intermediary was expecting data on a connection 484 (e.g., part of a response), but did not receive any new data in a 485 configured time limit. 487 * Extra Parameters: None. 489 * Recommended HTTP status code: 504 491 * Notes: Responses with this error type might not have been 492 generated by the intermediary. 494 2.3.11. Connection Write Timeout 496 * Name: connection_write_timeout 498 * Description: The intermediary was attempting to write data to a 499 connection, but was not able to (e.g., because its buffers were 500 full). 502 * Extra Parameters: None. 504 * Recommended HTTP status code: 504 506 * Notes: Responses with this error type might not have been 507 generated by the intermediary. 509 2.3.12. Connection Limit Reached 511 * Name: connection_limit_reached 513 * Description: The intermediary is configured to limit the number of 514 connections it has to the next hop, and that limit has been 515 passed. 517 * Extra Parameters: None. 519 * Recommended HTTP status code: 503 521 2.3.13. TLS Protocol Error 523 * Name: tls_protocol_error 524 * Description: The intermediary encountered a TLS error when 525 communicating with the next hop, either during handshake or 526 afterwards. 528 * Extra Parameters: None. 530 * Recommended HTTP status code: 502 532 * Notes: Responses with this error type might not have been 533 generated by the intermediary. 535 Note that additional information about the error can be recorded in 536 the details parameter (as is the case for all errors). 538 2.3.14. TLS Certificate Error 540 * Name: tls_certificate_error 542 * Description: The intermediary encountered an error when verifying 543 the certificate presented by the next hop. 545 * Extra Parameters: None. 547 * Recommended HTTP status code: 502 549 Note that additional information about the error can be recorded in 550 the details parameter (as is the case for all errors). 552 2.3.15. TLS Alert Received 554 * Name: tls_alert_received 556 * Description: The intermediary received a TLS alert from the next 557 hop. 559 * Extra Parameters: 561 - alert-message: an sf-token containing the applicable 562 description string from the TLS Alerts registry. 564 * Recommended HTTP status code: 502 566 * Notes: Responses with this error type might not have been 567 generated by the intermediary. 569 2.3.16. HTTP Request Error 571 * Name: http_request_error 573 * Description: The intermediary is generating a client (4xx) 574 response on the origin's behalf. Applicable status codes include 575 (but are not limited to) 400, 403, 405, 406, 408, 411, 413, 414, 576 415, 416, 417, 429. 578 * Extra Parameters: 580 - status-code: an sf-integer containing the generated status 581 code. 583 - status-phrase: an sf-string containing the generated status 584 phrase. 586 * Recommended HTTP status code: The applicable 4xx status code 588 * Notes: This type helps distinguish between responses generated by 589 intermediaries from those generated by the origin. 591 2.3.17. HTTP Request Denied 593 * Name: http_request_denied 595 * Description: The intermediary rejected the HTTP request based on 596 its configuration and/or policy settings. The request wasn't 597 forwarded to the next hop. 599 * Extra Parameters: None. 601 * Recommended HTTP status code: 403 603 2.3.18. HTTP Incomplete Response 605 * Name: http_response_incomplete 607 * Description: The intermediary received an incomplete response to 608 the request from the next hop. 610 * Extra Parameters: None. 612 * Recommended HTTP status code: 502 614 * Notes: Responses with this error type might not have been 615 generated by the intermediary. 617 2.3.19. HTTP Response Header Section Too Large 619 * Name: http_response_header_section_size 621 * Description: The intermediary received a response to the request 622 whose header section was considered too large. 624 * Extra Parameters: 626 - header-section-size: an sf-integer indicating how large the 627 headers received were. Note that they might not be complete; 628 i.e., the intermediary may have discarded or refused additional 629 data. 631 * Recommended HTTP status code: 502 633 * Notes: Responses with this error type might not have been 634 generated by the intermediary. 636 2.3.20. HTTP Response Header Too Large 638 * Name: http_response_header_size 640 * Description: The intermediary received a response to the request 641 containing an individual header line that was considered too 642 large. 644 * Extra Parameters: 646 - header-name: an sf-string indicating the name of the header 647 that triggered the error. 649 - header-size: an sf-integer indicating the size of the header 650 that triggered the error. 652 * Recommended HTTP status code: 502 654 * Notes: Responses with this error type might not have been 655 generated by the intermediary. 657 2.3.21. HTTP Response Body Too Large 659 * Name: http_response_body_size 661 * Description: The intermediary received a response to the request 662 whose body was considered too large. 664 * Extra Parameters: 666 - body-size: an sf-integer indicating how large the body received 667 was. Note that it may not have been complete; i.e., the 668 intermediary may have discarded or refused additional data. 670 * Recommended HTTP status code: 502 672 * Notes: Responses with this error type might not have been 673 generated by the intermediary. 675 2.3.22. HTTP Response Trailer Section Too Large 677 * Name: http_response_trailer_section_size 679 * Description: The intermediary received a response to the request 680 whose trailer section was considered too large. 682 * Extra Parameters: 684 - trailer-section-size: an sf-integer indicating how large the 685 trailers received were. Note that they might not be complete; 686 i.e., the intermediary may have discarded or refused additional 687 data. 689 * Recommended HTTP status code: 502 691 * Notes: Responses with this error type might not have been 692 generated by the intermediary. 694 2.3.23. HTTP Response Trailer Too Large 696 * Name: http_response_trailer_size 698 * Description: The intermediary received a response to the request 699 containing an individual trailer line that was considered too 700 large. 702 * Extra Parameters: 704 - trailer-name: an sf-string indicating the name of the trailer 705 that triggered the error. 707 - trailer-size: an sf-integer indicating the size of the trailer 708 that triggered the error. 710 * Recommended HTTP status code: 502 712 * Notes: Responses with this error type might not have been 713 generated by the intermediary. 715 2.3.24. HTTP Response Transfer-Coding Error 717 * Name: http_response_transfer_coding 719 * Description: The intermediary encountered an error decoding the 720 transfer-coding of the response. 722 * Extra Parameters: 724 - coding: an sf-token containing the specific coding that caused 725 the error. 727 * Recommended HTTP status code: 502 729 * Notes: Responses with this error type might not have been 730 generated by the intermediary. 732 2.3.25. HTTP Response Content-Coding Error 734 * Name: http_response_content_coding 736 * Description: The intermediary encountered an error decoding the 737 content-coding of the response. 739 * Extra Parameters: 741 - coding: an sf-token containing the specific coding that caused 742 the error. 744 * Recommended HTTP status code: 502 746 * Notes: Responses with this error type might not have been 747 generated by the intermediary. 749 2.3.26. HTTP Response Timeout 751 * Name: http_response_timeout 753 * Description: The intermediary reached a configured time limit 754 waiting for the complete response. 756 * Extra Parameters: None. 758 * Recommended HTTP status code: 504 760 * Notes: Responses with this error type might not have been 761 generated by the intermediary. 763 2.3.27. HTTP Upgrade Failed 765 * Name: http_upgrade_failed 767 * Description: The HTTP Upgrade between the intermediary and the 768 next hop failed. 770 * Extra Parameters: None. 772 * Recommended HTTP status code: 502 774 2.3.28. HTTP Protocol Error 776 * Name: http_protocol_error 778 * Description: The intermediary encountered a HTTP protocol error 779 when communicating with the next hop. This error should only be 780 used when a more specific one is not defined. 782 * Extra Parameters: None. 784 * Recommended HTTP status code: 502 786 * Notes: Responses with this error type might not have been 787 generated by the intermediary. 789 Note that additional information about the error can be recorded in 790 the details parameter (as is the case for all errors). 792 2.3.29. Proxy Internal Response 794 * Name: proxy_internal_response 796 * Description: The intermediary generated the response locally, 797 without attempting to connect to the next hop (e.g. in response to 798 a request to a debug endpoint terminated at the intermediary). 800 * Extra Parameters: None. 802 * Recommended HTTP status code: 804 2.3.30. Proxy Internal Error 806 * Name: proxy_internal_error 808 * Description: The intermediary encountered an internal error 809 unrelated to the origin. 811 * Extra Parameters: None 813 * Recommended HTTP status code: 500 815 Note that additional information about the error can be recorded in 816 the details parameter (as is the case for all errors). 818 2.3.31. Proxy Configuration Error 820 * Name: proxy_configuration_error 822 * Description: The intermediary encountered an error regarding its 823 configuration. 825 * Extra Parameters: None 827 * Recommended HTTP status code: 500 829 Note that additional information about the error can be recorded in 830 the details parameter (as is the case for all errors). 832 2.3.32. Proxy Loop Detected 834 * Name: proxy_loop_detected 836 * Description: The intermediary tried to forward the request to 837 itself, or a loop has been detected using different means (e.g. 838 [RFC8586]). 840 * Extra Parameters: None. 842 * Recommended HTTP status code: 502 844 2.4. Defining New Proxy Error Types 846 New Proxy Error Types can be defined by registering them in the HTTP 847 Proxy Error Types registry. 849 Registration requests are reviewed and approved by a Designated 850 Expert, as per [RFC8126], Section 4.5. A specification document is 851 appreciated, but not required. 853 The Expert(s) should consider the following factors when evaluating 854 requests: 856 * Community feedback 858 * If the value is sufficiently well-defined 859 * Generic types are preferred over vendor-specific, application- 860 specific or deployment-specific values. If a generic value cannot 861 be agreed upon in the community, the types's name should be 862 correspondingly specific (e.g., with a prefix that identifies the 863 vendor, application or deployment). 865 * Extra Parameters should not conflict with registered Proxy-Status 866 parameters. 868 Registration requests should use the following template: 870 * Name: [a name for the Proxy Error Type that matches sf-token] 872 * Description: [a description of the conditions that generate the 873 Proxy Error Type] 875 * Extra Parameters: [zero or more optional parameters, along with 876 their allowable type(s)] 878 * Recommended HTTP status code: [the appropriate HTTP status code 879 for this entry] 881 * Notes: [optional] 883 If the Proxy Error Type might occur in responses that are not 884 generated by the intermediary -- for example, when the error is 885 detected during response content processing and a Proxy-Status 886 trailer field is appended -- that SHOULD be explained in the Notes. 888 See the registry at https://iana.org/assignments/http-proxy-status 889 (https://iana.org/assignments/http-proxy-status) for details on where 890 to send registration requests. 892 3. IANA Considerations 894 Upon publication, please create the HTTP Proxy-Status Parameters 895 registry and the HTTP Proxy Error Types registry at 896 https://iana.org/assignments/http-proxy-statuses 897 (https://iana.org/assignments/http-proxy-statuses) and populate them 898 with the types defined in Section 2.1 and Section 2.3 respectively; 899 see Section 2.2 and Section 2.4 for its associated procedures. 901 4. Security Considerations 903 One of the primary security concerns when using Proxy-Status is 904 leaking information that might aid an attacker. For example, 905 information about the intermediary's configuration and back-end 906 topology can be exposed. 908 As a result, care needs to be taken when deciding to generate a 909 Proxy-Status field. Note that intermediaries are not required to 910 generate a Proxy-Status field in any response, and can conditionally 911 generate them based upon request attributes (e.g., authentication 912 tokens, IP address). 914 Likewise, generation of all parameters is optional. 916 5. References 918 5.1. Normative References 920 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 921 Requirement Levels", BCP 14, RFC 2119, 922 DOI 10.17487/RFC2119, March 1997, 923 . 925 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 926 Writing an IANA Considerations Section in RFCs", BCP 26, 927 RFC 8126, DOI 10.17487/RFC8126, June 2017, 928 . 930 [RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS 931 Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, 932 January 2019, . 934 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 935 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 936 May 2017, . 938 [RFC8941] Nottingham, M. and P-H. Kamp, "Structured Field Values for 939 HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, 940 . 942 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 943 "Transport Layer Security (TLS) Application-Layer Protocol 944 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 945 July 2014, . 947 [RFC8914] Kumari, W., Hunt, E., Arends, R., Hardaker, W., and D. 948 Lawrence, "Extended DNS Errors", RFC 8914, 949 DOI 10.17487/RFC8914, October 2020, 950 . 952 5.2. Informative References 954 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 955 Specifications: ABNF", STD 68, RFC 5234, 956 DOI 10.17487/RFC5234, January 2008, 957 . 959 [RFC8586] Ludin, S., Nottingham, M., and N. Sullivan, "Loop 960 Detection in Content Delivery Networks (CDNs)", RFC 8586, 961 DOI 10.17487/RFC8586, April 2019, 962 . 964 Authors' Addresses 966 Mark Nottingham 967 Fastly 968 Prahran VIC 969 Australia 971 Email: mnot@mnot.net 972 URI: https://www.mnot.net/ 974 Piotr Sikora 975 Google 977 Email: piotrsikora@google.com