< draft-ietf-httpbis-proxy-status-04.txt		draft-ietf-httpbis-proxy-status-05.txt >
	HTTP M. Nottingham		HTTP M. Nottingham
	Internet-Draft Fastly		Internet-Draft Fastly
	Intended status: Standards Track P. Sikora		Intended status: Standards Track P. Sikora
	Expires: 13 August 2021 Google		Expires: 29 October 2021 Google
	9 February 2021		27 April 2021
	The Proxy-Status HTTP Response Header Field		The Proxy-Status HTTP Response Header Field
	draft-ietf-httpbis-proxy-status-04		draft-ietf-httpbis-proxy-status-05
	Abstract		Abstract
	This document defines the Proxy-Status HTTP field to convey the		This document defines the Proxy-Status HTTP field to convey the
	details of intermediary response handling, including generated		details of intermediary response handling, including generated
	errors.		errors.
	Note to Readers		Note to Readers
	_RFC EDITOR: please remove this section before publication_		_RFC EDITOR: please remove this section before publication_
	skipping to change at page 1, line 48 ¶		skipping to change at page 1, line 48 ¶
	Internet-Drafts are working documents of the Internet Engineering		Internet-Drafts are working documents of the Internet Engineering
	Task Force (IETF). Note that other groups may also distribute		Task Force (IETF). Note that other groups may also distribute
	working documents as Internet-Drafts. The list of current Internet-		working documents as Internet-Drafts. The list of current Internet-
	Drafts is at https://datatracker.ietf.org/drafts/current/.		Drafts is at https://datatracker.ietf.org/drafts/current/.
	Internet-Drafts are draft documents valid for a maximum of six months		Internet-Drafts are draft documents valid for a maximum of six months
	and may be updated, replaced, or obsoleted by other documents at any		and may be updated, replaced, or obsoleted by other documents at any
	time. It is inappropriate to use Internet-Drafts as reference		time. It is inappropriate to use Internet-Drafts as reference
	material or to cite them other than as "work in progress."		material or to cite them other than as "work in progress."
	This Internet-Draft will expire on 13 August 2021.		This Internet-Draft will expire on 29 October 2021.
	Copyright Notice		Copyright Notice
	Copyright (c) 2021 IETF Trust and the persons identified as the		Copyright (c) 2021 IETF Trust and the persons identified as the
	document authors. All rights reserved.		document authors. All rights reserved.
	This document is subject to BCP 78 and the IETF Trust's Legal		This document is subject to BCP 78 and the IETF Trust's Legal
	Provisions Relating to IETF Documents (https://trustee.ietf.org/		Provisions Relating to IETF Documents (https://trustee.ietf.org/
	license-info) in effect on the date of publication of this document.		license-info) in effect on the date of publication of this document.
	Please review these documents carefully, as they describe your rights		Please review these documents carefully, as they describe your rights
	skipping to change at page 3, line 46 ¶		skipping to change at page 3, line 46 ¶
	HTTP accommodates these types of errors with a few status codes; for		HTTP accommodates these types of errors with a few status codes; for
	example, 502 Bad Gateway and 504 Gateway Timeout. However,		example, 502 Bad Gateway and 504 Gateway Timeout. However,
	experience has shown that more information is necessary to aid		experience has shown that more information is necessary to aid
	debugging and communicate what's happened to the client.		debugging and communicate what's happened to the client.
	Additionally, intermediaries sometimes want to convey additional		Additionally, intermediaries sometimes want to convey additional
	information about their handling of a response, even if they did not		information about their handling of a response, even if they did not
	generate it.		generate it.
	To enable these uses, Section 2 defines a new HTTP response field to		To enable these uses, Section 2 defines a new HTTP response field to
	allow intermediaries to convey details of their handling of a		allow intermediaries to convey details of their handling of a
	response, Section 2.1 enumerates the kind of information that can be		response. Section 2.1 enumerates the information that can be added
	conveyed, and Section 2.3 defines a set of error types for use when a		to the field by intermediaries, which can be extended as per
	proxy encounters an issue when obtaining a response for the request.		Section 2.2. Section 2.3 defines a set of error types for use when a
			proxy encounters an issue when obtaining a response for the request;
			these can likewise be extended as per Section 2.4.
	1.1. Notational Conventions		1.1. Notational Conventions
	The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",		The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
	"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and		"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
	"OPTIONAL" in this document are to be interpreted as described in BCP		"OPTIONAL" in this document are to be interpreted as described in BCP
	14 [RFC2119] [RFC8174] when, and only when, they appear in all		14 [RFC2119] [RFC8174] when, and only when, they appear in all
	capitals, as shown here.		capitals, as shown here.
	This specification uses Structured Fields		This specification uses Structured Fields [RFC8941] to specify syntax
	[I-D.ietf-httpbis-header-structure] to specify syntax and parsing.		and parsing, and ABNF [RFC5234] as a shorthand for that syntax. The
	The terms sf-list, sf-item, sf-string, sf-token, sf-integer and key		terms sf-list, sf-item, sf-string, sf-token, sf-integer and key refer
	refer to the structured types defined therein.		to the structured types defined therein.
	Note that in this specification, "proxy" is used to indicate both		Note that in this specification, "proxy" is used to indicate both
	forward and reverse proxies, otherwise known as gateways. "Next hop"		forward and reverse proxies, otherwise known as gateways. "Next hop"
	indicates the connection in the direction leading to the origin		indicates the connection in the direction leading to the origin
	server for the request.		server for the request.
	2. The Proxy-Status HTTP Field		2. The Proxy-Status HTTP Field
	The Proxy-Status HTTP response field allows an intermediary to convey		The Proxy-Status HTTP response field allows an intermediary to convey
	additional information about its handling of a response and its		additional information about its handling of a response and its
	associated request.		associated request.
	It is a List [I-D.ietf-httpbis-header-structure], Section 3.1:		It is a List ([RFC8941], Section 3.1):
	Proxy-Status = sf-list		Proxy-Status = sf-list
	Each member of the list represents an intermediary that has handled		Each member of the list represents an intermediary that has handled
	the response. The first member of the list represents the		the response. The first member of the list represents the
	intermediary closest to the origin server, and the last member of the		intermediary closest to the origin server, and the last member of the
	list represents the intermediary closest to the user agent.		list represents the intermediary closest to the user agent.
	For example:		For example:
	skipping to change at page 5, line 38 ¶		skipping to change at page 5, line 38 ¶
	Proxy-Status as a trailer field unless it has also sent a		Proxy-Status as a trailer field unless it has also sent a
	corresponding Proxy-Status header field in the same message, so that		corresponding Proxy-Status header field in the same message, so that
	the trailer value's ordering relative to other intermediaries is		the trailer value's ordering relative to other intermediaries is
	preserved.		preserved.
	Origin servers MUST NOT generate the Proxy-Status field.		Origin servers MUST NOT generate the Proxy-Status field.
	2.1. Proxy-Status Parameters		2.1. Proxy-Status Parameters
	This section lists parameters that can be used on the members of the		This section lists parameters that can be used on the members of the
	Proxy-Status field. Unrecognised parameters SHOULD be ignored.		Proxy-Status field. Unrecognised parameters MUST be ignored.
	2.1.1. error		2.1.1. error
	The "error" parameter's value is an sf-token that is a Proxy Error		The "error" parameter's value is an sf-token that is a Proxy Error
	Type. When present, it indicates that the proxy encountered an issue		Type. When present, it indicates that the proxy encountered an issue
	when obtaining a response.		when obtaining a response.
	Unless a Proxy Error Type specifies otherwise, the presences of error		Unless a Proxy Error Type specifies otherwise, the presences of error
	often, but not always, indicates that response was generated by the		often, but not always, indicates that response was generated by the
	proxy, not the origin server or any other upstream server. For		proxy, not the origin server or any other upstream server. For
	skipping to change at page 7, line 39 ¶		skipping to change at page 7, line 39 ¶
	Proxy-Status: ExampleProxy; received-status=200		Proxy-Status: ExampleProxy; received-status=200
	2.1.5. details		2.1.5. details
	The "details" parameter's value is an sf-string containing additional		The "details" parameter's value is an sf-string containing additional
	information not captured anywhere else. This can include		information not captured anywhere else. This can include
	implementation-specific or deployment-specific information.		implementation-specific or deployment-specific information.
	For example:		For example:
	Proxy-Status: ExampleProxy; error="http_protocol_error";		Proxy-Status: ExampleProxy; error="http_protocol_error";
	details="Malformed response header - space before colon"		details="Malformed response header - space before colon"
	2.2. Defining New Proxy-Status Parameters		2.2. Defining New Proxy-Status Parameters
	New Proxy-Status Parameters can be defined by registering them in the		New Proxy-Status Parameters can be defined by registering them in the
	HTTP Proxy-Status Parameters registry.		HTTP Proxy-Status Parameters registry.
	Registration requests are reviewed and approved by a Designated		Registration requests are reviewed and approved by a Designated
	Expert, as per [RFC8126], Section 4.5. A specification document is		Expert, as per [RFC8126], Section 4.5. A specification document is
	appreciated, but not required.		appreciated, but not required.
	skipping to change at page 9, line 10 ¶		skipping to change at page 9, line 10 ¶
	* Name: dns_error		* Name: dns_error
	* Description: The intermediary encountered a DNS error when trying		* Description: The intermediary encountered a DNS error when trying
	to find an IP address for the next hop hostname.		to find an IP address for the next hop hostname.
	* Extra Parameters:		* Extra Parameters:
	- rcode: A sf-string conveying the DNS RCODE that indicates the		- rcode: A sf-string conveying the DNS RCODE that indicates the
	error type. See [RFC8499], Section 3.		error type. See [RFC8499], Section 3.
			- info-code: A sf-integer conveying the Extended DNS Error Code
			info-code. See [RFC8914].
	* Recommended HTTP status code: 502		* Recommended HTTP status code: 502
	2.3.3. Destination Not Found		2.3.3. Destination Not Found
	* Name: destination_not_found		* Name: destination_not_found
	* Description: The intermediary cannot determine the appropriate		* Description: The intermediary cannot determine the appropriate
	next hop to use for this request; for example, it may not be		next hop to use for this request; for example, it may not be
	configured. Note that this error is specific to gateways, which		configured. Note that this error is specific to gateways, which
	typically require specific configuration to identify the "backend"		typically require specific configuration to identify the "backend"
	skipping to change at page 20, line 20 ¶		skipping to change at page 20, line 20 ¶
	Likewise, generation of all parameters is optional.		Likewise, generation of all parameters is optional.
	5. References		5. References
	5.1. Normative References		5.1. Normative References
	[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate		[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
	Requirement Levels", BCP 14, RFC 2119,		Requirement Levels", BCP 14, RFC 2119,
	DOI 10.17487/RFC2119, March 1997,		DOI 10.17487/RFC2119, March 1997,
	<https://www.rfc-editor.org/info/rfc2119>.		<https://www.rfc-editor.org/rfc/rfc2119>.
	[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for		[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
	Writing an IANA Considerations Section in RFCs", BCP 26,		Writing an IANA Considerations Section in RFCs", BCP 26,
	RFC 8126, DOI 10.17487/RFC8126, June 2017,		RFC 8126, DOI 10.17487/RFC8126, June 2017,
	<https://www.rfc-editor.org/info/rfc8126>.		<https://www.rfc-editor.org/rfc/rfc8126>.
	[RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS		[RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS
	Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499,		Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499,
	January 2019, <https://www.rfc-editor.org/info/rfc8499>.		January 2019, <https://www.rfc-editor.org/rfc/rfc8499>.
	[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC		[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
	2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,		2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
	May 2017, <https://www.rfc-editor.org/info/rfc8174>.		May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.
	[I-D.ietf-httpbis-header-structure]		[RFC8941] Nottingham, M. and P-H. Kamp, "Structured Field Values for
	Nottingham, M. and P. Kamp, "Structured Field Values for		HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021,
	HTTP", Work in Progress, Internet-Draft, draft-ietf-		<https://www.rfc-editor.org/rfc/rfc8941>.
	httpbis-header-structure-19, 3 June 2020,
	<http://www.ietf.org/internet-drafts/draft-ietf-httpbis-
	header-structure-19.txt>.
	[RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan,		[RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan,
	"Transport Layer Security (TLS) Application-Layer Protocol		"Transport Layer Security (TLS) Application-Layer Protocol
	Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301,		Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301,
	July 2014, <https://www.rfc-editor.org/info/rfc7301>.		July 2014, <https://www.rfc-editor.org/rfc/rfc7301>.
			[RFC8914] Kumari, W., Hunt, E., Arends, R., Hardaker, W., and D.
			Lawrence, "Extended DNS Errors", RFC 8914,
			DOI 10.17487/RFC8914, October 2020,
			<https://www.rfc-editor.org/rfc/rfc8914>.
	5.2. Informative References		5.2. Informative References
			[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
			Specifications: ABNF", STD 68, RFC 5234,
			DOI 10.17487/RFC5234, January 2008,
			<https://www.rfc-editor.org/rfc/rfc5234>.
	[RFC8586] Ludin, S., Nottingham, M., and N. Sullivan, "Loop		[RFC8586] Ludin, S., Nottingham, M., and N. Sullivan, "Loop
	Detection in Content Delivery Networks (CDNs)", RFC 8586,		Detection in Content Delivery Networks (CDNs)", RFC 8586,
	DOI 10.17487/RFC8586, April 2019,		DOI 10.17487/RFC8586, April 2019,
	<https://www.rfc-editor.org/info/rfc8586>.		<https://www.rfc-editor.org/rfc/rfc8586>.
	Authors' Addresses		Authors' Addresses
	Mark Nottingham		Mark Nottingham
	Fastly		Fastly
	Prahran VIC		Prahran VIC
	Australia		Australia
	Email: mnot@mnot.net		Email: mnot@mnot.net
	URI: https://www.mnot.net/		URI: https://www.mnot.net/
End of changes. 17 change blocks.
	27 lines changed or deleted		39 lines changed or added
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/