One document matched: draft-thomson-hybi-http-timeout-03.xml
<?xml version="1.0"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
<?rfc strict="yes" ?>
<?rfc toc="yes"?>
<?rfc tocdepth="4"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes" ?>
<?rfc compact="yes" ?>
<?rfc subcompact="no" ?>
<rfc category="std" ipr="trust200902">
<front>
<title abbrev="HTTP Keep-Alive">
Hypertext Transfer Protocol (HTTP) Keep-Alive Header
</title>
<author initials="M" surname="Thomson" fullname="Martin Thomson">
<organization>Microsoft</organization>
<address>
<postal>
<street>3210 Porter Drive</street>
<city>Palo Alto</city>
<region>CA</region>
<code>94304</code>
<country>US</country>
</postal>
<phone>+1 650-353-1925</phone>
<email>martin.thomson@skype.net</email>
</address>
</author>
<author fullname="Salvatore Loreto" initials="S" surname="Loreto">
<organization>Ericsson</organization>
<address>
<postal>
<street>Hirsalantie 11</street>
<code>02420</code>
<city>Jorvas</city>
<country>Finland</country>
</postal>
<email>salvatore.loreto@ericsson.com</email>
</address>
</author>
<author initials="G" surname="Wilkins" fullname="Greg Wilkins">
<organization>Intalio</organization>
<address>
<postal>
<street>644 Emerson Street, Suite 200</street>
<code>94301</code>
<city>Palo Alto</city>
<country>USA</country>
</postal>
<email>gregw@intalio.com</email>
</address>
</author>
<!--
<author initials="J" surname="Lokier" fullname="Jamie Lokier">
<organization></organization>
<address>
<postal>
<street></street>
<code></code>
<city></city>
<country></country>
</postal>
<email></email>
</address>
</author>
-->
<date month="July" year="2012"/>
<area>APP</area>
<workgroup>HYBI</workgroup>
<keyword>HTTP</keyword>
<keyword>Timeout</keyword>
<keyword>Request-Timeout</keyword>
<keyword>Connection-Timeout</keyword>
<keyword>Connection</keyword>
<keyword>Keep-Alive</keyword>
<abstract>
<t>A Keep-Alive header is defined for HTTP. This hop-by-hop header informs hosts about connection management policies. A parameters is defined for idle connection timeout.
</t>
</abstract>
</front>
<middle>
<section title="Introduction">
<t>This document describes the <spanx style="verb">Keep-Alive</spanx> header. The <spanx style="verb">Keep-Alive</spanx> header provides <xref target="I-D.ietf-httpbis-p1-messaging">Hypertext Transfer Protocol (HTTP)</xref> clients, servers and intermediaries with information about the connection use policies of their peers.
</t>
<t>The <spanx style="verb">timeout</spanx> Keep-Alive parameter indicates the time that a connection will be allowed to remain idle before it is closed.
</t>
<t>Some HTTP implementations already provide an implementation for this header. Not all of those implementations are interoperable due to significant differences in the header format. This draft defines a single format for the header and ascribes specific semantics to the header parameters.
</t>
<section title="Idle Connection Timeouts and Connection Reuse">
<t>Management of idle HTTP connections has an impact on long-lived communications between hosts. Hosts are able to close idle connections in order to reduce resource consumption.
</t>
<t>Many clients choose not to send non-idempotent requests on idle connections. If the intermediary or server holding the other end of the connection chooses to close the connection while a non-idempotent request is in transit, the client has no way to tell if the request has succeeded. For this reason, many clients establish a new connection for every non-idempotent request. This is inefficient if the existing connection is a usable connection: establishing a new connection adds significantly to the latency of the request.
</t>
<t>Connection resources can be more efficiently used when an idle connection timeout is known. A client that only periodically sends request can learn about the possibility of a connection timeout and can act to create a new connection for requests or send requests that keep the connection from timing out. Alternatively, a client that knows that more requests on a connection are unlikely within the discovered timeout interval can close the connection immediately after a poll, releasing resources.
</t>
</section>
<section title="Terminology">
<t>In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in BCP 14, <xref target="RFC2119">RFC 2119</xref> and indicate requirement levels for compliant implementations.
</t>
</section>
</section>
<section anchor="keep-alive" title="Keep-Alive Header">
<t>The <spanx style="verb">Keep-Alive</spanx> header is a hop-by-hop header that provides information about a persistent connection. Both client and server are able to provide information independently.
</t>
<figure>
<artwork><!-- type="abnf" doesn't work...fuck you HTTP --><![CDATA[
Keep-Alive = "Keep-Alive" ":" 1#keep-alive-info
keep-alive-info = "timeout" "=" delta-seconds
/ keep-alive-extension
keep-alive-extension = token [ "=" ( token / quoted-string ) ]
]]></artwork>
</figure>
<t>This header is sent by either host participating in a persistent connection. The values might be set based on policy implemented by servers, clients and intermediaries. Values might also be set based on knowledge that a host has about lower layer intermediaries in the path of the request, such as a TCP middlebox. Such middleboxes, in particular network address translators (NATs), frequently discard mappings for idle connections, causing the connection to fail after a certain duration of inactivity.
</t>
<t>The value of Keep-Alive parameters can change on each request or response sent on a connection. Absence of the header or any parameter implies that any previously provided value still applies.
</t>
<t>As a hop-by-hop header, this header only applies to a single transport-level connection. If a Keep-Alive header is added to a request or response, the Connection header MUST include the tag <spanx style="verb">Keep-Alive</spanx>. This ensures that compliant intermediaries that do not recognize this header remove it before forwarding a request.
</t>
<section anchor="p-timeout" title="'timeout' Parameter">
<t>A host sets the value of the <spanx style="verb">timeout</spanx> parameter to the time that the host will allow an idle connection to remain open before it is closed. A connection is idle if no data is sent or received by a host.
</t>
<t>The value of the <spanx style="verb">timeout</spanx> parameter is a single integer in seconds.
</t>
<t>A host MAY keep an idle connection open for longer than the time that it indicates, but it SHOULD attempt to retain a connection for at least as long as indicated.
</t>
<t>Each peer, client or server, has a different view of the time that a connection becomes idle. Packet transmission at one peer necessarily occurs before receipt, meaning that the sending peer perceives the connection as being idle earlier to the receiving peer. Similarly, the buffering or retransmission of data by lower layers of the stack, which is unlikely to be visible to the HTTP implementation, compounds this effect. Clients are advised to make allowances for delays in determining whether to reuse an idle connection.
</t>
</section>
<section title="Other Header Parameters">
<t>The Keep-Alive header can be extended by adding any number of keep-alive-extension values to the header. Any extension that is not understood MUST be ignored.
</t>
<t>The HTTP Keep-Alive Information Registry defines the namespace for Keep-Alive extensions. <xref target="registry"/> describes this registry.
</t>
<section anchor="p-max" title="'max' Parameter">
<t>The <spanx style="verb">max</spanx> parameter has been used to indicate the maximum number of requests that would be made on the connection. This parameter is deprecated. Any limit on requests can be enforced by sending <spanx style="verb">Connection: close</spanx> and closing the connection.
</t>
</section>
</section>
</section>
<section anchor="keep-alive-intermediary" title="Existing Intermediaries">
<t>The exact impact of an intermediary on an HTTP request with a Keep-Alive header depends on the type of intermediary.
</t>
<t>An intermediary that is compliant with HTTP/1.1, but does not implement Keep-Alive, ignores and discards this header before forwarding a request. Since it is unaware of the semantics of the header it could drop an idle connection at any time (see Section 7.1.4 of <xref target="I-D.ietf-httpbis-p1-messaging"/>).
</t>
<t>A non-compliant "transparent" intermediary could pass this header on to the next hop. This results in errors of the sort that are described in Section A.1.2 of <xref target="I-D.ietf-httpbis-p1-messaging"/>. Clients that send this header to HTTP/1.0 servers or proxies SHOULD monitor for "hung" connections and avoid sending the header if a connection appears to hang.
</t>
<t>A network address translation (NAT) device or other middlebox might cause a connection to become unavailable prior to the advertised timeout.
</t>
<t>A client or intermediary can revise or remove the Keep-Alive header for subsequent requests to the same resource or origin server if it detects non-compliant intermediaries or middleboxes that have shorter timeout periods.
</t>
</section>
<section title="Upgraded HTTP Connections">
<t>A connection timeout can apply to a connection that is subsequently upgraded to another protocol <xref target="RFC2817"/>, such as <xref target="RFC6455">the websocket protocol</xref>.
</t>
<t>The idle connection timeout applies to the upgraded connection, unless the upgraded protocol provides another method for indicating idle timeouts.
</t>
<t>A server, client or intermediary might apply different policies to an upgraded protocol.</t>
<t>Upgraded protocols might establish an end-to-end connection. As a hop-by-hop header, the values in the <spanx style="verb">Keep-Alive</spanx> on each hop apply to every hop equally. For <spanx style="verb">timeout</spanx>, this means that the lowest value from any hop applies to the connection.
</t>
<t>Intermediaries that support this header SHOULD determine the impact of a header parameter on dependent hops and reflect that in the values they set. For <spanx style="verb">timeout</spanx>, this means that the lowest value from the values seen and the local value is provided in outgoing messages.
</t>
</section>
<section title="Examples">
<t>The example in <xref target="ex-http"/> shows how a Keep-Alive header could be used. All connections are independently negotiated. In this example, the client indicates a timeout of 600 seconds (10 minutes), but the proxy is prepared to retain the connection for up to 3600 seconds (1 hour). On the link between proxy and server, the proxy requests a timeout of 1200 seconds and the server indicates a lower limit of 300 seconds.
</t>
<figure anchor="ex-http" title="Independent HTTP Hops"><artwork><![CDATA[
Client Proxy Server
| | |
+- Keep-Alive: timeout=600 -->| |
| Connection: Keep-Alive | |
| +- Keep-Alive: timeout=1200 -->|
| | Connection: Keep-Alive |
| | |
| |<-- Keep-Alive: timeout=300 --+
| | Connection: Keep-Alive |
|<- Keep-Alive: timeout=3600 -+ |
| Connection: Keep-Alive | |
| | |
]]></artwork>
</figure>
<t>As this example shows, the timeout policies maintained by the proxy are different for each connection. Each connection hop is independent.
</t>
<t>The example in <xref target="ex-ws"/> shows the headers included in an upgrade from HTTP/1.1 to <xref target="RFC6455">WebSocket</xref>. With a websocket upgrade, the connections on each hop cannot have independent lifecycles on either side of an intermediary. After the upgrade, timeout policies cannot be independent for each hop. The proxy adjusts the timeout value to reflect the lower of the values set by client and the proxy policies so that the server is aware of the connection characteristics; similarly, the value from the server is provided to the client.
</t>
<figure anchor="ex-ws" title="Interdependent Connections with Upgrade"><artwork><![CDATA[
Client Proxy Server
| | |
| Upgrade: websocket | |
+- Keep-Alive: timeout=600 -->| |
| Connection: Keep-Alive, | |
| Upgrade | |
| | Upgrade: websocket |
| +- Keep-Alive: timeout=600 --->|
| | Connection: Keep-Alive, |
| | Upgrade |
| | |
| | Upgrade: websocket |
| |<-- Keep-Alive: timeout=300 --+
| | Connection: Keep-Alive, |
| | Upgrade |
| Upgrade: websocket | |
|<- Keep-Alive: timeout=300 --+ |
| Connection: Keep-Alive, | |
| Upgrade | |
| | |
]]></artwork>
</figure>
</section>
<section anchor="security" title="Security Considerations">
<t>Establishing a persistent connection requires a commitment of resources at a host. The Keep-Alive header are used to express host policy that could alter the way that a host allocates connection resources. Since these policies can be enacted without this feedback, these indications have little effect on security other than exposing specifics of policy.
</t>
<t>A host can close a non-idle connection sooner than the indicated time if necessary or as dictated by local policy (see Section 7.1.4 of <xref target="I-D.ietf-httpbis-p1-messaging"/>).
</t>
</section>
<section title="IANA Considerations">
<t>[[Note to IANA/RFC Editor: Please replace instance of RFCXXXX with the number of the published RFC and remove this note.]]
</t>
<section title="Registration for Keep-Alive Header">
<t>This document registers the HTTP <spanx style="verb">Keep-Alive</spanx> header in the "Permanent Message Header Fields" registry established by <xref target="RFC3864"/>
<list style="hanging">
<t hangText="Header field:">Keep-Alive</t>
<t hangText="Applicable protocol:">HTTP</t>
<t hangText="Status:">standard</t>
<t hangText="Author/change controller:">Internet Engineering Task Force, IETF (iesg@ietf.org)</t>
<t hangText="Specification document(s):">RFCXXXX (this document)</t>
</list>
</t>
<t></t>
</section>
<section anchor="registry" title="Registry for Keep-Alive Information">
<t>This document establishes a registry for Keep-Alive Information.
</t>
<t>Registrations are subject to <xref target="RFC5226">Specification Required</xref>. The designated expert is advised to review registrations and work with the submitter to ensure that:
<list style="symbols">
<t>the registration name conforms to the HTTP <spanx style="verb">token</spanx> grammar
</t>
<t>a stable specification exists that is sufficient for interoperable implementation
</t>
<t>the registration does not duplicate an existing entry
</t>
</list>
</t>
<t>The registry includes the following initial values:
<list style="hanging">
<t hangText="timeout">See <xref target="p-timeout"/> of this document.</t>
<t hangText="max">Deprecated. See <xref target="p-max"/> of this document.</t>
</list>
</t>
</section>
</section>
<section title="Acknowledgments">
<t>Jamie Lokier provided valuable contributions of experience, insight and text suggestions to this document. Roy Fielding provided information on existing implementations of the poorly documented header. Also provided useful feedback: Patrick McManus, Dave Thaler, Konstantinos Pentikousis.</t>
</section>
<section title="Change Log">
<t>Since -01:
<list style="symbols">
<t>Deprecated 'max'</t>
<t>Corrected badly misleading examples</t>
<t>Loosened the registry policy from IETF Review</t>
</list>
</t>
<t>Since -00:
<list style="symbols">
<t>Removed Request-Timeout in favor of the wait parameter of the Prefer header.</t>
<t>Connection-Timeout has now been replaced with the zombie spawn of Keep-Alive. This means that it picks up the 'max' parameter as baggage. Open question: should 'max' be deprecated?</t>
</list>
</t>
<t>Since draft-loreto-http-timeout:
<list style="symbols">
<t>Changed Timeout to Request-Timeout to avoid a conflict with an existing header definition.</t>
<t>Added note about the application of Connection-Timeout to upgraded protocols.</t>
</list>
</t>
</section>
</middle>
<back>
<references title="Normative References">
<?rfc include="reference.RFC.2119"?>
<?rfc include="reference.RFC.3864"?>
<?rfc include="reference.RFC.5226"?>
<?rfc include="reference.I-D.ietf-httpbis-p1-messaging"?>
</references>
<references title="Informative References">
<?rfc include="reference.RFC.2068"?>
<?rfc include="reference.RFC.2817"?>
<?rfc include="reference.RFC.6455"?>
</references>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 19:29:04 |