idnits 2.17.1 draft-ietf-httpbis-proxy-status-03.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 (9 February 2021) is 1164 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: 1 error (**), 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: 13 August 2021 Google 6 9 February 2021 8 The Proxy-Status HTTP Response Header Field 9 draft-ietf-httpbis-proxy-status-03 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 13 August 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.2. received-status . . . . . . . . . . . . . . . . . . . . . 7 73 2.2.1. details . . . . . . . . . . . . . . . . . . . . . . . 7 74 2.3. Defining New Proxy-Status Parameters . . . . . . . . . . 7 75 2.4. Proxy Error Types . . . . . . . . . . . . . . . . . . . . 8 76 2.4.1. DNS Timeout . . . . . . . . . . . . . . . . . . . . . 8 77 2.4.2. DNS Error . . . . . . . . . . . . . . . . . . . . . . 8 78 2.4.3. Destination Not Found . . . . . . . . . . . . . . . . 9 79 2.4.4. Destination Unavailable . . . . . . . . . . . . . . . 9 80 2.4.5. Destination IP Prohibited . . . . . . . . . . . . . . 9 81 2.4.6. Destination IP Unroutable . . . . . . . . . . . . . . 10 82 2.4.7. Connection Refused . . . . . . . . . . . . . . . . . 10 83 2.4.8. Connection Terminated . . . . . . . . . . . . . . . . 10 84 2.4.9. Connection Timeout . . . . . . . . . . . . . . . . . 10 85 2.4.10. Connection Read Timeout . . . . . . . . . . . . . . . 11 86 2.4.11. Connection Write Timeout . . . . . . . . . . . . . . 11 87 2.4.12. Connection Limit Reached . . . . . . . . . . . . . . 11 88 2.4.13. TLS Protocol Error . . . . . . . . . . . . . . . . . 11 89 2.4.14. TLS Certificate Error . . . . . . . . . . . . . . . . 12 90 2.4.15. TLS Alert Received . . . . . . . . . . . . . . . . . 12 91 2.4.16. HTTP Request Error . . . . . . . . . . . . . . . . . 13 92 2.4.17. HTTP Request Denied . . . . . . . . . . . . . . . . . 13 93 2.4.18. HTTP Incomplete Response . . . . . . . . . . . . . . 13 94 2.4.19. HTTP Response Header Section Too Large . . . . . . . 14 95 2.4.20. HTTP Response Header Too Large . . . . . . . . . . . 14 96 2.4.21. HTTP Response Body Too Large . . . . . . . . . . . . 14 97 2.4.22. HTTP Response Trailer Section Too Large . . . . . . . 15 98 2.4.23. HTTP Response Trailer Too Large . . . . . . . . . . . 15 99 2.4.24. HTTP Response Transfer-Coding Error . . . . . . . . . 16 100 2.4.25. HTTP Response Content-Coding Error . . . . . . . . . 16 101 2.4.26. HTTP Response Timeout . . . . . . . . . . . . . . . . 16 102 2.4.27. HTTP Upgrade Failed . . . . . . . . . . . . . . . . . 17 103 2.4.28. HTTP Protocol Error . . . . . . . . . . . . . . . . . 17 104 2.4.29. Proxy Internal Response . . . . . . . . . . . . . . . 17 105 2.4.30. Proxy Internal Error . . . . . . . . . . . . . . . . 17 106 2.4.31. Proxy Configuration Error . . . . . . . . . . . . . . 18 107 2.4.32. Proxy Loop Detected . . . . . . . . . . . . . . . . . 18 108 2.5. 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 kind of information that can be 140 conveyed, and Section 2.4 defines a set of error types for use when a 141 proxy encounters an issue when obtaining a response for the request. 143 1.1. Notational Conventions 145 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 146 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 147 "OPTIONAL" in this document are to be interpreted as described in BCP 148 14 [RFC2119] [RFC8174] when, and only when, they appear in all 149 capitals, as shown here. 151 This specification uses Structured Fields 152 [I-D.ietf-httpbis-header-structure] to specify syntax and parsing. 153 The terms sf-list, sf-item, sf-string, sf-token, sf-integer and key 154 refer to the structured types defined therein. 156 Note that in this specification, "proxy" is used to indicate both 157 forward and reverse proxies, otherwise known as gateways. "Next hop" 158 indicates the connection in the direction leading to the origin 159 server for the request. 161 2. The Proxy-Status HTTP Field 163 The Proxy-Status HTTP response field allows an intermediary to convey 164 additional information about its handling of a response and its 165 associated request. 167 It is a List [I-D.ietf-httpbis-header-structure], Section 3.1: 169 Proxy-Status = sf-list 171 Each member of the list represents an intermediary that has handled 172 the response. The first member of the list represents the 173 intermediary closest to the origin server, and the last member of the 174 list represents the intermediary closest to the user agent. 176 For example: 178 Proxy-Status: FooProxy, ExampleCDN 180 indicates that this response was handled first by FooProxy and then 181 ExampleCDN. 183 Intermediaries determine when it is appropriate to add the Proxy- 184 Status field to a response. Some might decide to append to it to all 185 responses, whereas others might only do so when specifically 186 configured to, or when the request contains a header that activates a 187 debugging mode. 189 Each member of the list identifies the intermediary that inserted the 190 value, and MUST have a type of either sf-string or sf-token. 191 Depending on the deployment, this might be a product or service name 192 (e.g., ExampleProxy or "Example CDN"), a hostname ("proxy- 193 3.example.com"), an IP address, or a generated string. 195 Parameters on each member convey additional information about that 196 intermediary's handling of the response and its associated request; 197 see Section 2.1. While all of these parameters are OPTIONAL, 198 intermediaries are encouraged to provide as much information as 199 possible (but see Section 4 for security considerations in doing so). 201 When adding a value to the Proxy-Status field, intermediaries SHOULD 202 preserve the existing members of the field, to allow debugging of the 203 entire chain of intermediaries handling the request. 205 Proxy-Status MAY be sent in HTTP trailers. For example, if an 206 intermediary is streaming a response and the upstream connection 207 suddenly terminates, Proxy-Status can only be appended to the 208 trailers of the outgoing message, since the headers have already been 209 sent. As with all trailers, it might be silently discarded along the 210 path to the user agent, so this SHOULD NOT be done unless it is not 211 possible to send it in headers, and an intermediary MUST NOT send 212 Proxy-Status as a trailer field unless it has also sent a 213 corresponding Proxy-Status header field in the same message, so that 214 the trailer value's ordering relative to other intermediaries is 215 preserved. 217 Origin servers MUST NOT generate the Proxy-Status field. 219 2.1. Proxy-Status Parameters 221 This section lists parameters that can be used on the members of the 222 Proxy-Status field. Unrecognised parameters SHOULD be ignored. 224 2.1.1. error 226 The "error" parameter's value is an sf-token that is a Proxy Error 227 Type. When present, it indicates that the proxy encountered an issue 228 when obtaining a response. 230 Unless a Proxy Error Type specifies otherwise, the presences of error 231 often, but not always, indicates that response was generated by the 232 proxy, not the origin server or any other upstream server. For 233 example, a proxy might attempt to correct an error, or part of a 234 response might be forwarded before the error is encountered. 236 Section 2.4 lists the Proxy Error Types defined in this document; new 237 ones can be defined using the procedure outlined in Section 2.5. 239 For example: 241 HTTP/1.1 504 Gateway Timeout 242 Proxy-Status: SomeCDN; error=connection_timeout 244 indicates that this 504 response was generated by SomeCDN, due to a 245 connection timeout when going forward. 247 Or: 249 HTTP/1.1 429 Too Many Requests 250 Proxy-Status: SomeReverseProxy; error=http_request_error 252 indicates that this 429 Too Many Requests response was generated by 253 the intermediary, not the origin. 255 When sending the error parameter, the most specific Proxy Error Type 256 SHOULD be sent, provided that it accurately represents the error 257 condition. If an appropriate Proxy Error Type is not defined, there 258 are a number of generic error types (e.g., proxy_internal_error, 259 http_protocol_error) that can be used. If they are not suitable, 260 consider registering a new Proxy Error Type (see Section 2.5). 262 Each Proxy Error Type has a Recommended HTTP Status Code. When 263 generating a HTTP response containing "error", its HTTP status code 264 SHOULD be set to the Recommended HTTP Status Code. However, there 265 may be circumstances (e.g., for backwards compatibility with previous 266 behaviours, a status code has already been sent) when another status 267 code might be used. 269 Proxy Error Types can also define any number of extra parameters for 270 use with that type. Their use, like all parameters, is optional. As 271 a result, if an extra parameter is used with a Proxy Error Type for 272 which it is not defined, it will be ignored. 274 2.1.2. next-hop 276 The "next-hop" parameter's value is an sf-string or sf-token that 277 identifies the intermediary or origin server selected (and used, if 278 contacted) for this response. It might be a hostname, IP address, or 279 alias. 281 For example: 283 Proxy-Status: cdn.example.org; next-hop=backend.example.org 285 2.1.3. next-protocol 287 The "next-protocol" parameter's value indicates the ALPN protocol 288 identifier [RFC7301] used by the intermediary to connect to the next 289 hop. This is only applicable when that connection was actually 290 established. 292 The value MUST be either an sf-token or sf-binary. If the protocol 293 identifier is able to be expressed as an sf-token using UTF-8 294 encoding, that form MUST be used. 296 For example: 298 Proxy-Status: "proxy.example.org"; next-protocol=h2 300 2.2. received-status 302 The "received-status" parameter's value indicates the HTTP status 303 code that the intermediary received from the next hop server. 305 The value MUST be an sf-integer. 307 For example: 309 Proxy-Status: ExampleProxy; received-status=200 311 2.2.1. details 313 The "details" parameter's value is an sf-string containing additional 314 information not captured anywhere else. This can include 315 implementation-specific or deployment-specific information. 317 For example: 319 Proxy-Status: ExampleProxy; error="http_protocol_error"; 320 details="Malformed response header - space before colon" 322 2.3. Defining New Proxy-Status Parameters 324 New Proxy-Status Parameters can be defined by registering them in the 325 HTTP Proxy-Status Parameters registry. 327 Registration requests are reviewed and approved by a Designated 328 Expert, as per [RFC8126], Section 4.5. A specification document is 329 appreciated, but not required. 331 The Expert(s) should consider the following factors when evaluating 332 requests: 334 * Community feedback 336 * If the value is sufficiently well-defined 338 * Generic parameters are preferred over vendor-specific, 339 application-specific or deployment-specific values. If a generic 340 value cannot be agreed upon in the community, the parameter's name 341 should be correspondingly specific (e.g., with a prefix that 342 identifies the vendor, application or deployment). 344 * Parameter names should not conflict with registered extra 345 parameters in the Proxy Error Type Registry. 347 Registration requests should use the following template: 349 * Name: [a name for the Proxy-Status Parameter that matches key] 351 * Description: [a description of the parameter semantics and value] 353 * Reference: [to a specification defining this parameter] 355 See the registry at https://iana.org/assignments/http-proxy-status 356 (https://iana.org/assignments/http-proxy-status) for details on where 357 to send registration requests. 359 2.4. Proxy Error Types 361 This section lists the Proxy Error Types defined by this document. 362 See Section 2.5 for information about defining new Proxy Error Types. 364 2.4.1. DNS Timeout 366 * Name: dns_timeout 368 * Description: The intermediary encountered a timeout when trying to 369 find an IP address for the next hop hostname. 371 * Extra Parameters: None. 373 * Recommended HTTP status code: 504 375 2.4.2. DNS Error 377 * Name: dns_error 379 * Description: The intermediary encountered a DNS error when trying 380 to find an IP address for the next hop hostname. 382 * Extra Parameters: 384 - rcode: A sf-string conveying the DNS RCODE that indicates the 385 error type. See [RFC8499], Section 3. 387 * Recommended HTTP status code: 502 389 2.4.3. Destination Not Found 391 * Name: destination_not_found 393 * Description: The intermediary cannot determine the appropriate 394 next hop to use for this request; for example, it may not be 395 configured. Note that this error is specific to gateways, which 396 typically require specific configuration to identify the "backend" 397 server; forward proxies use in-band information to identify the 398 origin server. 400 * Extra Parameters: None. 402 * Recommended HTTP status code: 500 404 2.4.4. Destination Unavailable 406 * Name: destination_unavailable 408 * Description: The intermediary considers the next hop to be 409 unavailable; e.g., recent attempts to communicate with it may have 410 failed, or a health check may indicate that it is down. 412 * Extra Parameters: None. 414 * Recommended HTTP status code: 503 416 2.4.5. Destination IP Prohibited 418 * Name: destination_ip_prohibited 420 * Description: The intermediary is configured to prohibit 421 connections to the next hop IP address. 423 * Extra Parameters: None. 425 * Recommended HTTP status code: 502 427 2.4.6. Destination IP Unroutable 429 * Name: destination_ip_unroutable 431 * Description: The intermediary cannot find a route to the next hop 432 IP address. 434 * Extra Parameters: None. 436 * Recommended HTTP status code: 502 438 2.4.7. Connection Refused 440 * Name: connection_refused 442 * Description: The intermediary's connection to the next hop was 443 refused. 445 * Extra Parameters: None. 447 * Recommended HTTP status code: 502 449 2.4.8. Connection Terminated 451 * Name: connection_terminated 453 * Description: The intermediary's connection to the next hop was 454 closed before complete response was received. 456 * Extra Parameters: None. 458 * Recommended HTTP status code: 502 460 * Notes: Responses with this error type might not have been 461 generated by the intermediary. 463 2.4.9. Connection Timeout 465 * Name: connection_timeout 467 * Description: The intermediary's attempt to open a connection to 468 the next hop timed out. 470 * Extra Parameters: None. 472 * Recommended HTTP status code: 504 474 2.4.10. Connection Read Timeout 476 * Name: connection_read_timeout 478 * Description: The intermediary was expecting data on a connection 479 (e.g., part of a response), but did not receive any new data in a 480 configured time limit. 482 * Extra Parameters: None. 484 * Recommended HTTP status code: 504 486 * Notes: Responses with this error type might not have been 487 generated by the intermediary. 489 2.4.11. Connection Write Timeout 491 * Name: connection_write_timeout 493 * Description: The intermediary was attempting to write data to a 494 connection, but was not able to (e.g., because its buffers were 495 full). 497 * Extra Parameters: None. 499 * Recommended HTTP status code: 504 501 * Notes: Responses with this error type might not have been 502 generated by the intermediary. 504 2.4.12. Connection Limit Reached 506 * Name: connection_limit_reached 508 * Description: The intermediary is configured to limit the number of 509 connections it has to the next hop, and that limit has been 510 passed. 512 * Extra Parameters: None. 514 * Recommended HTTP status code: 503 516 2.4.13. TLS Protocol Error 518 * Name: tls_protocol_error 519 * Description: The intermediary encountered a TLS error when 520 communicating with the next hop, either during handshake or 521 afterwards. 523 * Extra Parameters: None. 525 * Recommended HTTP status code: 502 527 * Notes: Responses with this error type might not have been 528 generated by the intermediary. 530 Note that additional information about the error can be recorded in 531 the details parameter (as is the case for all errors). 533 2.4.14. TLS Certificate Error 535 * Name: tls_certificate_error 537 * Description: The intermediary encountered an error when verifying 538 the certificate presented by the next hop. 540 * Extra Parameters: None. 542 * Recommended HTTP status code: 502 544 Note that additional information about the error can be recorded in 545 the details parameter (as is the case for all errors). 547 2.4.15. TLS Alert Received 549 * Name: tls_alert_received 551 * Description: The intermediary received a TLS alert from the next 552 hop. 554 * Extra Parameters: 556 - alert-message: an sf-token containing the applicable 557 description string from the TLS Alerts registry. 559 * Recommended HTTP status code: 502 561 * Notes: Responses with this error type might not have been 562 generated by the intermediary. 564 2.4.16. HTTP Request Error 566 * Name: http_request_error 568 * Description: The intermediary is generating a client (4xx) 569 response on the origin's behalf. Applicable status codes include 570 (but are not limited to) 400, 403, 405, 406, 408, 411, 413, 414, 571 415, 416, 417, 429. 573 * Extra Parameters: 575 - status-code: an sf-integer containing the generated status 576 code. 578 - status-phrase: an sf-string containing the generated status 579 phrase. 581 * Recommended HTTP status code: The applicable 4xx status code 583 * Notes: This type helps distinguish between responses generated by 584 intermediaries from those generated by the origin. 586 2.4.17. HTTP Request Denied 588 * Name: http_request_denied 590 * Description: The intermediary rejected the HTTP request based on 591 its configuration and/or policy settings. The request wasn't 592 forwarded to the next hop. 594 * Extra Parameters: None. 596 * Recommended HTTP status code: 403 598 2.4.18. HTTP Incomplete Response 600 * Name: http_response_incomplete 602 * Description: The intermediary received an incomplete response to 603 the request from the next hop. 605 * Extra Parameters: None. 607 * Recommended HTTP status code: 502 609 * Notes: Responses with this error type might not have been 610 generated by the intermediary. 612 2.4.19. HTTP Response Header Section Too Large 614 * Name: http_response_header_section_size 616 * Description: The intermediary received a response to the request 617 whose header section was considered too large. 619 * Extra Parameters: 621 - header-section-size: an sf-integer indicating how large the 622 headers received were. Note that they might not be complete; 623 i.e., the intermediary may have discarded or refused additional 624 data. 626 * Recommended HTTP status code: 502 628 * Notes: Responses with this error type might not have been 629 generated by the intermediary. 631 2.4.20. HTTP Response Header Too Large 633 * Name: http_response_header_size 635 * Description: The intermediary received a response to the request 636 containing an individual header line that was considered too 637 large. 639 * Extra Parameters: 641 - header-name: an sf-string indicating the name of the header 642 that triggered the error. 644 - header-size: an sf-integer indicating the size of the header 645 that triggered the error. 647 * Recommended HTTP status code: 502 649 * Notes: Responses with this error type might not have been 650 generated by the intermediary. 652 2.4.21. HTTP Response Body Too Large 654 * Name: http_response_body_size 656 * Description: The intermediary received a response to the request 657 whose body was considered too large. 659 * Extra Parameters: 661 - body-size: an sf-integer indicating how large the body received 662 was. Note that it may not have been complete; i.e., the 663 intermediary may have discarded or refused additional data. 665 * Recommended HTTP status code: 502 667 * Notes: Responses with this error type might not have been 668 generated by the intermediary. 670 2.4.22. HTTP Response Trailer Section Too Large 672 * Name: http_response_trailer_section_size 674 * Description: The intermediary received a response to the request 675 whose trailer section was considered too large. 677 * Extra Parameters: 679 - trailer-section-size: an sf-integer indicating how large the 680 trailers received were. Note that they might not be complete; 681 i.e., the intermediary may have discarded or refused additional 682 data. 684 * Recommended HTTP status code: 502 686 * Notes: Responses with this error type might not have been 687 generated by the intermediary. 689 2.4.23. HTTP Response Trailer Too Large 691 * Name: http_response_trailer_size 693 * Description: The intermediary received a response to the request 694 containing an individual trailer line that was considered too 695 large. 697 * Extra Parameters: 699 - trailer-name: an sf-string indicating the name of the trailer 700 that triggered the error. 702 - trailer-size: an sf-integer indicating the size of the trailer 703 that triggered the error. 705 * Recommended HTTP status code: 502 707 * Notes: Responses with this error type might not have been 708 generated by the intermediary. 710 2.4.24. HTTP Response Transfer-Coding Error 712 * Name: http_response_transfer_coding 714 * Description: The intermediary encountered an error decoding the 715 transfer-coding of the response. 717 * Extra Parameters: 719 - coding: an sf-token containing the specific coding that caused 720 the error. 722 * Recommended HTTP status code: 502 724 * Notes: Responses with this error type might not have been 725 generated by the intermediary. 727 2.4.25. HTTP Response Content-Coding Error 729 * Name: http_response_content_coding 731 * Description: The intermediary encountered an error decoding the 732 content-coding of the response. 734 * Extra Parameters: 736 - coding: an sf-token containing the specific coding that caused 737 the error. 739 * Recommended HTTP status code: 502 741 * Notes: Responses with this error type might not have been 742 generated by the intermediary. 744 2.4.26. HTTP Response Timeout 746 * Name: http_response_timeout 748 * Description: The intermediary reached a configured time limit 749 waiting for the complete response. 751 * Extra Parameters: None. 753 * Recommended HTTP status code: 504 755 * Notes: Responses with this error type might not have been 756 generated by the intermediary. 758 2.4.27. HTTP Upgrade Failed 760 * Name: http_upgrade_failed 762 * Description: The HTTP Upgrade between the intermediary and the 763 next hop failed. 765 * Extra Parameters: None. 767 * Recommended HTTP status code: 502 769 2.4.28. HTTP Protocol Error 771 * Name: http_protocol_error 773 * Description: The intermediary encountered a HTTP protocol error 774 when communicating with the next hop. This error should only be 775 used when a more specific one is not defined. 777 * Extra Parameters: None. 779 * Recommended HTTP status code: 502 781 * Notes: Responses with this error type might not have been 782 generated by the intermediary. 784 Note that additional information about the error can be recorded in 785 the details parameter (as is the case for all errors). 787 2.4.29. Proxy Internal Response 789 * Name: proxy_internal_response 791 * Description: The intermediary generated the response locally, 792 without attempting to connect to the next hop (e.g. in response to 793 a request to a debug endpoint terminated at the intermediary). 795 * Extra Parameters: None. 797 * Recommended HTTP status code: 799 2.4.30. Proxy Internal Error 801 * Name: proxy_internal_error 803 * Description: The intermediary encountered an internal error 804 unrelated to the origin. 806 * Extra Parameters: None 808 * Recommended HTTP status code: 500 810 Note that additional information about the error can be recorded in 811 the details parameter (as is the case for all errors). 813 2.4.31. Proxy Configuration Error 815 * Name: proxy_configuration_error 817 * Description: The intermediary encountered an error regarding its 818 configuration. 820 * Extra Parameters: None 822 * Recommended HTTP status code: 500 824 Note that additional information about the error can be recorded in 825 the details parameter (as is the case for all errors). 827 2.4.32. Proxy Loop Detected 829 * Name: proxy_loop_detected 831 * Description: The intermediary tried to forward the request to 832 itself, or a loop has been detected using different means (e.g. 833 [RFC8586]). 835 * Extra Parameters: None. 837 * Recommended HTTP status code: 502 839 2.5. Defining New Proxy Error Types 841 New Proxy Error Types can be defined by registering them in the HTTP 842 Proxy Error Types registry. 844 Registration requests are reviewed and approved by a Designated 845 Expert, as per [RFC8126], Section 4.5. A specification document is 846 appreciated, but not required. 848 The Expert(s) should consider the following factors when evaluating 849 requests: 851 * Community feedback 853 * If the value is sufficiently well-defined 854 * Generic types are preferred over vendor-specific, application- 855 specific or deployment-specific values. If a generic value cannot 856 be agreed upon in the community, the types's name should be 857 correspondingly specific (e.g., with a prefix that identifies the 858 vendor, application or deployment). 860 * Extra Parameters should not conflict with registered Proxy-Status 861 parameters. 863 Registration requests should use the following template: 865 * Name: [a name for the Proxy Error Type that matches sf-token] 867 * Description: [a description of the conditions that generate the 868 Proxy Error Type] 870 * Extra Parameters: [zero or more optional parameters, along with 871 their allowable type(s)] 873 * Recommended HTTP status code: [the appropriate HTTP status code 874 for this entry] 876 * Notes: [optional] 878 If the Proxy Error Type might occur in responses that are not 879 generated by the intermediary -- for example, when the error is 880 detected during response content processing and a Proxy-Status 881 trailer field is appended -- that SHOULD be explained in the Notes. 883 See the registry at https://iana.org/assignments/http-proxy-status 884 (https://iana.org/assignments/http-proxy-status) for details on where 885 to send registration requests. 887 3. IANA Considerations 889 Upon publication, please create the HTTP Proxy-Status Parameters 890 registry and the HTTP Proxy Error Types registry at 891 https://iana.org/assignments/http-proxy-statuses 892 (https://iana.org/assignments/http-proxy-statuses) and populate them 893 with the types defined in Section 2.1 and Section 2.4 respectively; 894 see Section 2.3 and Section 2.5 for its associated procedures. 896 4. Security Considerations 898 One of the primary security concerns when using Proxy-Status is 899 leaking information that might aid an attacker. For example, 900 information about the intermediary's configuration and back-end 901 topology can be exposed. 903 As a result, care needs to be taken when deciding to generate a 904 Proxy-Status field. Note that intermediaries are not required to 905 generate a Proxy-Status field in any response, and can conditionally 906 generate them based upon request attributes (e.g., authentication 907 tokens, IP address). 909 Likewise, generation of all parameters is optional. 911 5. References 913 5.1. Normative References 915 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 916 Requirement Levels", BCP 14, RFC 2119, 917 DOI 10.17487/RFC2119, March 1997, 918 . 920 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 921 Writing an IANA Considerations Section in RFCs", BCP 26, 922 RFC 8126, DOI 10.17487/RFC8126, June 2017, 923 . 925 [RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS 926 Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, 927 January 2019, . 929 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 930 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 931 May 2017, . 933 [I-D.ietf-httpbis-header-structure] 934 Nottingham, M. and P. Kamp, "Structured Field Values for 935 HTTP", Work in Progress, Internet-Draft, draft-ietf- 936 httpbis-header-structure-19, 3 June 2020, 937 . 940 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 941 "Transport Layer Security (TLS) Application-Layer Protocol 942 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 943 July 2014, . 945 5.2. Informative References 947 [RFC8586] Ludin, S., Nottingham, M., and N. Sullivan, "Loop 948 Detection in Content Delivery Networks (CDNs)", RFC 8586, 949 DOI 10.17487/RFC8586, April 2019, 950 . 952 Authors' Addresses 954 Mark Nottingham 955 Fastly 956 Prahran VIC 957 Australia 959 Email: mnot@mnot.net 960 URI: https://www.mnot.net/ 962 Piotr Sikora 963 Google 965 Email: piotrsikora@google.com