idnits 2.17.1 draft-thomson-hybi-http-timeout-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 seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (July 17, 2012) is 4272 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) == Unused Reference: 'RFC2068' is defined on line 415, but no explicit reference was found in the text == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-20 ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) -- Obsolete informational reference (is this intentional?): RFC 2068 (Obsoleted by RFC 2616) Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HYBI M. Thomson 3 Internet-Draft Microsoft 4 Intended status: Standards Track S. Loreto 5 Expires: January 18, 2013 Ericsson 6 G. Wilkins 7 Intalio 8 July 17, 2012 10 Hypertext Transfer Protocol (HTTP) Keep-Alive Header 11 draft-thomson-hybi-http-timeout-03 13 Abstract 15 A Keep-Alive header is defined for HTTP. This hop-by-hop header 16 informs hosts about connection management policies. A parameters is 17 defined for idle connection timeout. 19 Status of this Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on January 18, 2013. 36 Copyright Notice 38 Copyright (c) 2012 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 1.1. Idle Connection Timeouts and Connection Reuse . . . . . . 3 55 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 56 2. Keep-Alive Header . . . . . . . . . . . . . . . . . . . . . . 4 57 2.1. 'timeout' Parameter . . . . . . . . . . . . . . . . . . . 4 58 2.2. Other Header Parameters . . . . . . . . . . . . . . . . . 5 59 2.2.1. 'max' Parameter . . . . . . . . . . . . . . . . . . . 5 60 3. Existing Intermediaries . . . . . . . . . . . . . . . . . . . 5 61 4. Upgraded HTTP Connections . . . . . . . . . . . . . . . . . . 6 62 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 63 6. Security Considerations . . . . . . . . . . . . . . . . . . . 7 64 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 65 7.1. Registration for Keep-Alive Header . . . . . . . . . . . . 8 66 7.2. Registry for Keep-Alive Information . . . . . . . . . . . 8 67 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 9 68 9. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . 9 69 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 70 10.1. Normative References . . . . . . . . . . . . . . . . . . . 9 71 10.2. Informative References . . . . . . . . . . . . . . . . . . 10 72 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10 74 1. Introduction 76 This document describes the "Keep-Alive" header. The "Keep-Alive" 77 header provides Hypertext Transfer Protocol (HTTP) 78 [I-D.ietf-httpbis-p1-messaging] clients, servers and intermediaries 79 with information about the connection use policies of their peers. 81 The "timeout" Keep-Alive parameter indicates the time that a 82 connection will be allowed to remain idle before it is closed. 84 Some HTTP implementations already provide an implementation for this 85 header. Not all of those implementations are interoperable due to 86 significant differences in the header format. This draft defines a 87 single format for the header and ascribes specific semantics to the 88 header parameters. 90 1.1. Idle Connection Timeouts and Connection Reuse 92 Management of idle HTTP connections has an impact on long-lived 93 communications between hosts. Hosts are able to close idle 94 connections in order to reduce resource consumption. 96 Many clients choose not to send non-idempotent requests on idle 97 connections. If the intermediary or server holding the other end of 98 the connection chooses to close the connection while a non-idempotent 99 request is in transit, the client has no way to tell if the request 100 has succeeded. For this reason, many clients establish a new 101 connection for every non-idempotent request. This is inefficient if 102 the existing connection is a usable connection: establishing a new 103 connection adds significantly to the latency of the request. 105 Connection resources can be more efficiently used when an idle 106 connection timeout is known. A client that only periodically sends 107 request can learn about the possibility of a connection timeout and 108 can act to create a new connection for requests or send requests that 109 keep the connection from timing out. Alternatively, a client that 110 knows that more requests on a connection are unlikely within the 111 discovered timeout interval can close the connection immediately 112 after a poll, releasing resources. 114 1.2. Terminology 116 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 117 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT 118 RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as 119 described in BCP 14, RFC 2119 [RFC2119] and indicate requirement 120 levels for compliant implementations. 122 2. Keep-Alive Header 124 The "Keep-Alive" header is a hop-by-hop header that provides 125 information about a persistent connection. Both client and server 126 are able to provide information independently. 128 Keep-Alive = "Keep-Alive" ":" 1#keep-alive-info 129 keep-alive-info = "timeout" "=" delta-seconds 130 / keep-alive-extension 131 keep-alive-extension = token [ "=" ( token / quoted-string ) ] 133 This header is sent by either host participating in a persistent 134 connection. The values might be set based on policy implemented by 135 servers, clients and intermediaries. Values might also be set based 136 on knowledge that a host has about lower layer intermediaries in the 137 path of the request, such as a TCP middlebox. Such middleboxes, in 138 particular network address translators (NATs), frequently discard 139 mappings for idle connections, causing the connection to fail after a 140 certain duration of inactivity. 142 The value of Keep-Alive parameters can change on each request or 143 response sent on a connection. Absence of the header or any 144 parameter implies that any previously provided value still applies. 146 As a hop-by-hop header, this header only applies to a single 147 transport-level connection. If a Keep-Alive header is added to a 148 request or response, the Connection header MUST include the tag 149 "Keep-Alive". This ensures that compliant intermediaries that do not 150 recognize this header remove it before forwarding a request. 152 2.1. 'timeout' Parameter 154 A host sets the value of the "timeout" parameter to the time that the 155 host will allow an idle connection to remain open before it is 156 closed. A connection is idle if no data is sent or received by a 157 host. 159 The value of the "timeout" parameter is a single integer in seconds. 161 A host MAY keep an idle connection open for longer than the time that 162 it indicates, but it SHOULD attempt to retain a connection for at 163 least as long as indicated. 165 Each peer, client or server, has a different view of the time that a 166 connection becomes idle. Packet transmission at one peer necessarily 167 occurs before receipt, meaning that the sending peer perceives the 168 connection as being idle earlier to the receiving peer. Similarly, 169 the buffering or retransmission of data by lower layers of the stack, 170 which is unlikely to be visible to the HTTP implementation, compounds 171 this effect. Clients are advised to make allowances for delays in 172 determining whether to reuse an idle connection. 174 2.2. Other Header Parameters 176 The Keep-Alive header can be extended by adding any number of keep- 177 alive-extension values to the header. Any extension that is not 178 understood MUST be ignored. 180 The HTTP Keep-Alive Information Registry defines the namespace for 181 Keep-Alive extensions. Section 7.2 describes this registry. 183 2.2.1. 'max' Parameter 185 The "max" parameter has been used to indicate the maximum number of 186 requests that would be made on the connection. This parameter is 187 deprecated. Any limit on requests can be enforced by sending 188 "Connection: close" and closing the connection. 190 3. Existing Intermediaries 192 The exact impact of an intermediary on an HTTP request with a Keep- 193 Alive header depends on the type of intermediary. 195 An intermediary that is compliant with HTTP/1.1, but does not 196 implement Keep-Alive, ignores and discards this header before 197 forwarding a request. Since it is unaware of the semantics of the 198 header it could drop an idle connection at any time (see Section 199 7.1.4 of [I-D.ietf-httpbis-p1-messaging]). 201 A non-compliant "transparent" intermediary could pass this header on 202 to the next hop. This results in errors of the sort that are 203 described in Section A.1.2 of [I-D.ietf-httpbis-p1-messaging]. 204 Clients that send this header to HTTP/1.0 servers or proxies SHOULD 205 monitor for "hung" connections and avoid sending the header if a 206 connection appears to hang. 208 A network address translation (NAT) device or other middlebox might 209 cause a connection to become unavailable prior to the advertised 210 timeout. 212 A client or intermediary can revise or remove the Keep-Alive header 213 for subsequent requests to the same resource or origin server if it 214 detects non-compliant intermediaries or middleboxes that have shorter 215 timeout periods. 217 4. Upgraded HTTP Connections 219 A connection timeout can apply to a connection that is subsequently 220 upgraded to another protocol [RFC2817], such as the websocket 221 protocol [RFC6455]. 223 The idle connection timeout applies to the upgraded connection, 224 unless the upgraded protocol provides another method for indicating 225 idle timeouts. 227 A server, client or intermediary might apply different policies to an 228 upgraded protocol. 230 Upgraded protocols might establish an end-to-end connection. As a 231 hop-by-hop header, the values in the "Keep-Alive" on each hop apply 232 to every hop equally. For "timeout", this means that the lowest 233 value from any hop applies to the connection. 235 Intermediaries that support this header SHOULD determine the impact 236 of a header parameter on dependent hops and reflect that in the 237 values they set. For "timeout", this means that the lowest value 238 from the values seen and the local value is provided in outgoing 239 messages. 241 5. Examples 243 The example in Figure 1 shows how a Keep-Alive header could be used. 244 All connections are independently negotiated. In this example, the 245 client indicates a timeout of 600 seconds (10 minutes), but the proxy 246 is prepared to retain the connection for up to 3600 seconds (1 hour). 247 On the link between proxy and server, the proxy requests a timeout of 248 1200 seconds and the server indicates a lower limit of 300 seconds. 250 Client Proxy Server 251 | | | 252 +- Keep-Alive: timeout=600 -->| | 253 | Connection: Keep-Alive | | 254 | +- Keep-Alive: timeout=1200 -->| 255 | | Connection: Keep-Alive | 256 | | | 257 | |<-- Keep-Alive: timeout=300 --+ 258 | | Connection: Keep-Alive | 259 |<- Keep-Alive: timeout=3600 -+ | 260 | Connection: Keep-Alive | | 261 | | | 263 Figure 1: Independent HTTP Hops 265 As this example shows, the timeout policies maintained by the proxy 266 are different for each connection. Each connection hop is 267 independent. 269 The example in Figure 2 shows the headers included in an upgrade from 270 HTTP/1.1 to WebSocket [RFC6455]. With a websocket upgrade, the 271 connections on each hop cannot have independent lifecycles on either 272 side of an intermediary. After the upgrade, timeout policies cannot 273 be independent for each hop. The proxy adjusts the timeout value to 274 reflect the lower of the values set by client and the proxy policies 275 so that the server is aware of the connection characteristics; 276 similarly, the value from the server is provided to the client. 278 Client Proxy Server 279 | | | 280 | Upgrade: websocket | | 281 +- Keep-Alive: timeout=600 -->| | 282 | Connection: Keep-Alive, | | 283 | Upgrade | | 284 | | Upgrade: websocket | 285 | +- Keep-Alive: timeout=600 --->| 286 | | Connection: Keep-Alive, | 287 | | Upgrade | 288 | | | 289 | | Upgrade: websocket | 290 | |<-- Keep-Alive: timeout=300 --+ 291 | | Connection: Keep-Alive, | 292 | | Upgrade | 293 | Upgrade: websocket | | 294 |<- Keep-Alive: timeout=300 --+ | 295 | Connection: Keep-Alive, | | 296 | Upgrade | | 297 | | | 299 Figure 2: Interdependent Connections with Upgrade 301 6. Security Considerations 303 Establishing a persistent connection requires a commitment of 304 resources at a host. The Keep-Alive header are used to express host 305 policy that could alter the way that a host allocates connection 306 resources. Since these policies can be enacted without this 307 feedback, these indications have little effect on security other than 308 exposing specifics of policy. 310 A host can close a non-idle connection sooner than the indicated time 311 if necessary or as dictated by local policy (see Section 7.1.4 of 313 [I-D.ietf-httpbis-p1-messaging]). 315 7. IANA Considerations 317 [[Note to IANA/RFC Editor: Please replace instance of RFCXXXX with 318 the number of the published RFC and remove this note.]] 320 7.1. Registration for Keep-Alive Header 322 This document registers the HTTP "Keep-Alive" header in the 323 "Permanent Message Header Fields" registry established by [RFC3864] 325 Header field: Keep-Alive 327 Applicable protocol: HTTP 329 Status: standard 331 Author/change controller: Internet Engineering Task Force, IETF 332 (iesg@ietf.org) 334 Specification document(s): RFCXXXX (this document) 336 7.2. Registry for Keep-Alive Information 338 This document establishes a registry for Keep-Alive Information. 340 Registrations are subject to Specification Required [RFC5226]. The 341 designated expert is advised to review registrations and work with 342 the submitter to ensure that: 344 o the registration name conforms to the HTTP "token" grammar 346 o a stable specification exists that is sufficient for interoperable 347 implementation 349 o the registration does not duplicate an existing entry 351 The registry includes the following initial values: 353 timeout See Section 2.1 of this document. 355 max Deprecated. See Section 2.2.1 of this document. 357 8. Acknowledgments 359 Jamie Lokier provided valuable contributions of experience, insight 360 and text suggestions to this document. Roy Fielding provided 361 information on existing implementations of the poorly documented 362 header. Also provided useful feedback: Patrick McManus, Dave Thaler, 363 Konstantinos Pentikousis. 365 9. Change Log 367 Since -01: 369 o Deprecated 'max' 371 o Corrected badly misleading examples 373 o Loosened the registry policy from IETF Review 375 Since -00: 377 o Removed Request-Timeout in favor of the wait parameter of the 378 Prefer header. 380 o Connection-Timeout has now been replaced with the zombie spawn of 381 Keep-Alive. This means that it picks up the 'max' parameter as 382 baggage. Open question: should 'max' be deprecated? 384 Since draft-loreto-http-timeout: 386 o Changed Timeout to Request-Timeout to avoid a conflict with an 387 existing header definition. 389 o Added note about the application of Connection-Timeout to upgraded 390 protocols. 392 10. References 394 10.1. Normative References 396 [I-D.ietf-httpbis-p1-messaging] 397 Fielding, R., Lafon, Y., and J. Reschke, "HTTP/1.1, part 398 1: Message Routing and Syntax"", 399 draft-ietf-httpbis-p1-messaging-20 (work in progress), 400 July 2012. 402 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 403 Requirement Levels", BCP 14, RFC 2119, March 1997. 405 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 406 Procedures for Message Header Fields", BCP 90, RFC 3864, 407 September 2004. 409 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 410 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 411 May 2008. 413 10.2. Informative References 415 [RFC2068] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., and T. 416 Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", 417 RFC 2068, January 1997. 419 [RFC2817] Khare, R. and S. Lawrence, "Upgrading to TLS Within 420 HTTP/1.1", RFC 2817, May 2000. 422 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", 423 RFC 6455, December 2011. 425 Authors' Addresses 427 Martin Thomson 428 Microsoft 429 3210 Porter Drive 430 Palo Alto, CA 94304 431 US 433 Phone: +1 650-353-1925 434 Email: martin.thomson@skype.net 436 Salvatore Loreto 437 Ericsson 438 Hirsalantie 11 439 Jorvas 02420 440 Finland 442 Email: salvatore.loreto@ericsson.com 443 Greg Wilkins 444 Intalio 445 644 Emerson Street, Suite 200 446 Palo Alto 94301 447 USA 449 Email: gregw@intalio.com