idnits 2.17.1 draft-thomson-hybi-http-timeout-00.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 (March 7, 2011) is 4798 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 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-12 -- Obsolete informational reference (is this intentional?): RFC 2068 (Obsoleted by RFC 2616) Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HYBI M. Thomson 3 Internet-Draft Andrew Corporation 4 Intended status: Standards Track S. Loreto 5 Expires: September 8, 2011 Ericsson 6 G. Wilkins 7 Intalio 8 March 7, 2011 10 Hypertext Transfer Protocol (HTTP) Timeouts 11 draft-thomson-hybi-http-timeout-00 13 Abstract 15 A Request-Timeout header is defined for Hypertext Transfer Protocol 16 (HTTP). This end-to-end header informs an origin server and any 17 intermediaries of the maximum time that a client will await a 18 response to its request. A server can use this header to ensure that 19 a timely response is generated. This also identifies requests as 20 being potentially long-lived, and allows for better resource 21 allocation for these requests. 23 A Connection-Timeout header is defined for HTTP. This hop-by-hop 24 header informs the entity at the other end of a connection of the 25 maximum time that an idle connection is kept open. This header 26 improves reliability by providing better information about the idle 27 connection management policy of HTTP hosts. 29 Status of this Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at http://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on September 8, 2011. 46 Copyright Notice 48 Copyright (c) 2011 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 64 1.1. Request Timeouts . . . . . . . . . . . . . . . . . . . . . 3 65 1.2. Idle Connection Timeouts . . . . . . . . . . . . . . . . . 4 66 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 67 3. Request-Timeout Header . . . . . . . . . . . . . . . . . . . . 5 68 3.1. Existing Intermediaries . . . . . . . . . . . . . . . . . 5 69 3.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 6 70 4. Connection-Timeout Header . . . . . . . . . . . . . . . . . . 7 71 4.1. Existing Intermediaries . . . . . . . . . . . . . . . . . 8 72 4.2. Upgraded HTTP Connections . . . . . . . . . . . . . . . . 8 73 4.3. Example . . . . . . . . . . . . . . . . . . . . . . . . . 8 74 5. Security Considerations . . . . . . . . . . . . . . . . . . . 9 75 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 76 6.1. Request-Timeout HTTP header Registration . . . . . . . . . 10 77 6.2. Connection-Timeout HTTP header Registration . . . . . . . 10 78 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 10 79 8. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . 10 80 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 81 9.1. Normative References . . . . . . . . . . . . . . . . . . . 11 82 9.2. Informative References . . . . . . . . . . . . . . . . . . 11 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 11 85 1. Introduction 87 This document describes two headers that provide Hypertext Transfer 88 Protocol (HTTP) [RFC2616] hosts with timing information. 90 The "Request-Timeout" header describes the time available for a 91 single HTTP request. 93 The "Connection-Timeout" header describes the time that an idle 94 connection is retained. 96 1.1. Request Timeouts 98 HTTP is a client-driven protocol. As such, a server is only able to 99 provide information to a client when that client requests it. To 100 address the need for servers to provide low-latency notifications to 101 clients, a practice of long-polling [I-D.loreto-http-bidirectional] 102 is commonplace. 104 Long-polling requires that a client maintain an open request to a 105 server. The server withholds responses to this request until the 106 event of interest occurs. The open request provides the server with 107 a way to send a message immediately after the event occurs. After 108 the response containing the notification is received, the client 109 immediately opens another open request. 111 Long-polling differs significantly to many HTTP requests, which do 112 not have significant delay between request and response. Long- 113 polling requests monopolize a connection for the time that they are 114 outstanding. For this reason, it is useful for a server or 115 intermediary to identify a long-polling request. Identifying a long- 116 polling request would enable specialized resource management for 117 long-polling requests; for instance, separate connection allocations 118 and management, longer timeout periods and long-poll optimizations. 120 A connection that is used for long-polling also appears to be idle 121 for a significant period. Management of idle connections can 122 interfere with the operation of a long-poll. Many intermediaries 123 legitimately use timeouts to avoid clients from monopolizing the use 124 of outgoing connections. If an intermediary times out a request, the 125 server is unable to send a response. 127 Knowing the time available to provide a response can avoid problems 128 with timeouts. Current implementations select times between 30 and 129 120 seconds, times that have been empirically determined to be safe. 130 A server provides a null response before this time to ensure that the 131 connection appears to be active to intermediaries. Such low values 132 are potentially wasteful, since each null response and subsequent 133 request generates traffic. A null response can also increase the 134 latency of notifications, since the response removes the channel that 135 the server would use for notifications. 137 The Request-Timeout header defined in Section 3 describes the maximum 138 time available to a server in providing a response to any particular 139 request. 141 For the Request-Timeout header, Section 3.1 includes a discussion of 142 the interaction with existing HTTP intermediaries and other 143 intermediaries like network address translation (NAT) device. 145 1.2. Idle Connection Timeouts 147 Management of idle HTTP connections has an impact on long-lived 148 communications between hosts. Hosts are able to close idle 149 connections in order to reduce resource consumption. 151 Many clients choose not to send non-idempotent requests on idle 152 connections. If the intermediary or server holding the other end of 153 the connection chooses to close the connection while a non-idempotent 154 request is in transit, the client has no way to tell if the request 155 has succeeded. For this reason, many clients establish a new 156 connection for every non-idempotent request. This is inefficient if 157 the existing connection is usable connection: establishing a new 158 connection adds significantly to the latency of the request. 160 Polling of resource state can more efficiently use connection 161 resources when an idle connection timeout is known. A client that 162 polls on an interval that is close to the connection timeout can 163 ensure that polling requests are made before the idle connection is 164 closed, avoiding any need to retry a request due to the 165 aforementioned problem. Alternatively, a client that knows that the 166 connection timeout is less than the polling interval can close the 167 connection immediately after a poll, releasing resources. 169 A Connection-Timeout header is defined in Section 4. This hop-by-hop 170 header informs hosts of the minumum time that a connection remains 171 idle before it is closed. Indicating this time explicitly gives a 172 client the knowledge necessary to reuse an idle connection with a 173 greater assurance that the connection is usable. 175 2. Terminology 177 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 178 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT 179 RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as 180 described in BCP 14, RFC 2119 [RFC2119] and indicate requirement 181 levels for compliant implementations. 183 3. Request-Timeout Header 185 The "Request-Timeout" header is a end-to-end request header that 186 indicates the maximum time that a client is prepared to await a 187 response. 189 Request-Timeout = "Request-Timeout" ":" timeout-value 190 timeout-value = 1*DIGIT 192 A client adds a Request-Timeout header to any request for which they 193 are prepared to await a response. The client sets the header to the 194 maximum time that they are prepared to wait. 196 The value of the Request-Timeout header is a single integer value in 197 seconds. 199 An origin server interprets this header as the time between receipt 200 of a complete request and the time that it generates and begins 201 sending the response. A client will observe a longer time interval 202 between request and response, as network transit and processing by 203 intermediaries add delays. If this time is critical, a client SHOULD 204 allow for delays in setting a value for the header. 206 An origin server MAY apply a lower value to the timeout based on 207 local policy. An origin server MAY choose to take longer to produce 208 a response, at the risk that the client is no longer able to use the 209 response. 211 An HTTP intermediary MAY reduce the value of a Request-Timeout header 212 based on local policy. An intermediary MAY add a Request-Timeout 213 header if none is present. The value in the Request-Timeout header 214 MUST NOT be increased or removed. 216 The client MUST NOT set the value of the Timeout header greater than 217 the value of the Connection-Timeout header. 219 3.1. Existing Intermediaries 221 The exact impact of an intermediary on an HTTP request with a 222 Request-Timeout header depends on the type of intermediary. 224 An intermediary that is compliant with HTTP/1.1 passes this header, 225 but unaware of the header semantics, passes the header on to the 226 origin server without altering it. For an intermediary that does not 227 time out requests, or an intermediary that has a timeout period that 228 is longer than the one specified in the header, this has no impact. 230 An existing intermediary that has a shorter timeout period than the 231 indicated time will time out a request before the server generates a 232 response. The intermediary could send the client a 504 (Gateway 233 Timeout) response when it times out. 235 An intermediary that forwards requests without altering them (a 236 transparent intermediary) is similar to an HTTP/1.1 compliant 237 intermediary. 239 A non-compliant intermediary might remove a Request-Timeout header. 240 This means that the server is unaware of the timeliness requirements 241 of the client. A server that expects a Request-Timeout header might 242 attempt to guess an appropriate value. 244 A network address translation (NAT) device might interact with 245 timeouts. These devices maintain state about TCP connections that 246 are established through them. This state can be discarded or lost if 247 the connection remains idle. A NAT device failure can also cause 248 state loss. Further attempts to use the connection either fail 249 without error, or result in the NAT device sending a TCP "RST" to the 250 entity that attempts to use the connection. 252 A client MAY revise the Request-Timeout header that it sends in 253 subsequent requests to the same resource or origin server if it 254 detects intermediaries or NAT devices that have shorter timeout 255 periods. However, two requests are not guaranteed to follow the same 256 path through a network, especially for different resources. A client 257 that employs a heuristic for setting the Timeout header SHOULD ensure 258 that any knowledge it obtains about timeouts is not retained 259 indefinitely. 261 3.2. Examples 263 The following example shows how a Request-Timeout header could be 264 used. In this case, both intermediaries - proxy and gateway - both 265 reduce the timeout based on their policy. 267 Client Proxy Gateway Server 268 | | | | 269 | Request- | | | 270 +-- Timeout: 300 -->| Request- | | 271 | +-- Timeout: 250 -->| Request- | 272 | | +-- Timeout: 240 -->| 273 | | | ^ | 274 . . . | . 275 . . . up to 240 seconds 276 . . . | . 277 | | | V | 278 | | |<----- 200 OK -----+ 279 | |<----- 200 OK -----+ | 280 |<----- 200 OK -----+ | | 281 | | | | 283 4. Connection-Timeout Header 285 The "Connection-Timeout" header is a hop-by-hop header that indicates 286 the minimum time that an idle connection will be maintained. 288 Connection-Timeout = "Connection-Timeout" ":" timeout-value 289 ; timeout-value from Timeout header 291 This header is sent by either host participating in a persistent 292 connection. A host sets the value to the minimum time that local 293 policy at that host allows for an idle connection to remain open. A 294 connection is idle if no data is sent or received by a host. 296 The value of the Connection-Timeout header is a single integer in 297 seconds. 299 As a hop-by-hop header, this header only applies to a single 300 transport-level connection. If a Connection-Timeout header is added 301 to a request or response, the Connection header MUST include the tag 302 "Connection-Timeout". This ensures that intermediaries that do not 303 recognize this header remove it before forwarding a request. 305 A host MAY keep an idle connection open for longer than the time that 306 it indicates, but it SHOULD attempt to retain a connection for at 307 least as long as indicated. 309 Network transit and processing by intermediaries add additional 310 delays that can skew the subjective perception of whether a 311 connection is idle. A client SHOULD make allowances for any delays 312 in determining whether to reuse an idle connection. 314 An intermediary that provides a Connection-Timeout header value, MUST 315 set the value of the Request-Timeout header in any requests that it 316 forwards to be less than or equal to the Connection-Timeout that it 317 provides. 319 4.1. Existing Intermediaries 321 The exact impact of an intermediary on an HTTP request with a 322 Connection-Timeout header depends on the type of intermediary. 324 An intermediary that is compliant with HTTP/1.1 ignores and discards 325 this header before forwarding a request. Since it is unaware of the 326 semantics of the header it could drop an idle connection at any time 327 (see Section 7.1.4 of [I-D.ietf-httpbis-p1-messaging]). 329 A non-compliant or otherwise transparent intermediary might pass this 330 header on to the next hop. This results in same types of errors that 331 the Keep-Alive header causes, as described in Section 19.7.1 of 332 [RFC2068]. 334 A network address translation (NAT) device might cause a connection 335 to become unavailable prior to the advertised timeout. 337 A host MAY revise the Connection-Timeout header that it sends in 338 subsequent requests to the same resource or origin server if it 339 detects intermediaries or NAT devices that have shorter timeout 340 periods. 342 4.2. Upgraded HTTP Connections 344 A connection timeout can apply to a connection that is subsequently 345 upgraded to another protocol [RFC2817]. Endpoints and intermediaries 346 MAY assume that the connection timeout applies to the upgraded 347 connection, unless the upgraded protocol provides another method for 348 indicating idle timeouts. 350 4.3. Example 352 The following example shows how a Connection-Timeout header could be 353 used. All connections are independently negotiated. In this 354 example, the client indicates a timeout of 600 seconds (10 minutes), 355 but the proxy is only prepared to retain the connection for at least 356 120 seconds (2 minutes). On the link between proxy and server, the 357 proxy requests a timeout of 1200 seconds and the server reduces this 358 to 300 seconds. 360 Client Proxy Server 361 | | | 362 +- Connection-Timeout: 600 -->| | 363 | Connection: | | 364 | Connection-Timeout | | 365 | +- Connection-Timeout: 1200 -->| 366 | | Connection: | 367 | | Connection-Timeout | 368 | | | 369 | |<-- Connection-Timeout: 300 --+ 370 | | Connection: | 371 | | Connection-Timeout | 372 |<-- Connection-Timeout: 120 -+ | 373 | Connection: | | 374 | Connection-Timeout | | 375 | | | 377 5. Security Considerations 379 Establishing a persistent connection requires a commitment of 380 resources at a host. The Timeout and Connection-Timeout headers are 381 used to express host policy that could alter the way that a host 382 allocates connection resources. 384 A host that alters its policies based on the receipt of either header 385 could be exploited by a malicious host to either benefit from 386 increased access to resources or to consume resources in the hopes of 387 depriving another host. 389 An attacker might attempt to keep a connection from becoming idle, to 390 keep the connection open. A client could legitimately do this to 391 benefit from a reduced latency for later requests, but an attacker 392 might exploit this to monopolize server resources. A host that has 393 indicated a Connection-Timeout MAY close a non-idle connection sooner 394 than the indicated time if necessary or dictated by local policy (see 395 Section 7.1.4 of [I-D.ietf-httpbis-p1-messaging]). 397 6. IANA Considerations 399 This section registers the two HTTP headers in the "Permanent Message 400 Header Fields" registry established by [RFC3864]. 402 [[Note to IANA/RFC Editor: Please replace instance of RFCXXXX with 403 the number of the published RFC and remove this note.]] 405 6.1. Request-Timeout HTTP header Registration 407 This document registers the HTTP "Request-Timeout" header in the 408 "Permanent Message Header Fields" registry established by [RFC3864] 410 Header field: Request-Timeout 412 Applicable protocol: HTTP 414 Status: standard 416 Author/change controller: Internet Engineering Task Force, IETF 417 (iesg@ietf.org) 419 Specification document(s): RFCXXXX (this document) 421 6.2. Connection-Timeout HTTP header Registration 423 This document registers the HTTP "Connection-Timeout" header in the 424 "Permanent Message Header Fields" registry established by [RFC3864] 426 Header field: Connection-Timeout 428 Applicable protocol: HTTP 430 Status: standard 432 Author/change controller: Internet Engineering Task Force, IETF 433 (iesg@ietf.org) 435 Specification document(s): RFCXXXX (this document) 437 7. Acknowledgments 439 Jamie Lokier provided valuable contributions of experience, insight 440 and text suggestions to this document. 442 8. Change Log 444 Since draft-loreto-http-timeout: 446 o Changed Timeout to Request-Timeout to avoid a conflict with an 447 existing header definition. 449 o Added note about the application of Connection-Timeout to upgraded 450 protocols. 452 9. References 454 9.1. Normative References 456 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 457 Requirement Levels", BCP 14, RFC 2119, March 1997. 459 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 460 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 461 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 463 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 464 Procedures for Message Header Fields", BCP 90, RFC 3864, 465 September 2004. 467 9.2. Informative References 469 [I-D.ietf-httpbis-p1-messaging] 470 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 471 Masinter, L., Leach, P., Berners-Lee, T., and J. Reschke, 472 "HTTP/1.1, part 1: URIs, Connections, and Message 473 Parsing", draft-ietf-httpbis-p1-messaging-12 (work in 474 progress), October 2010. 476 [I-D.loreto-http-bidirectional] 477 Loreto, S., Saint-Andre, P., Salsano, S., and G. Wilkins, 478 "Known Issues and Best Practices for the Use of Long 479 Polling and Streaming in Bidirectional HTTP", 480 draft-loreto-http-bidirectional-07 (work in progress), 481 January 2011. 483 [RFC2068] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., and T. 484 Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", 485 RFC 2068, January 1997. 487 [RFC2817] Khare, R. and S. Lawrence, "Upgrading to TLS Within 488 HTTP/1.1", RFC 2817, May 2000. 490 Authors' Addresses 492 Martin Thomson 493 Andrew Corporation 494 Andrew Building (39) 495 Wollongong University Campus 496 Northfields Avenue 497 Wollongong, NSW 2522 498 AU 500 Phone: +61 2 4221 2915 501 Email: martin.thomson@andrew.com 503 Salvatore Loreto 504 Ericsson 505 Hirsalantie 11 506 Jorvas 02420 507 Finland 509 Email: salvatore.loreto@ericsson.com 511 Greg Wilkins 512 Intalio 513 644 Emerson Street, Suite 200 514 Palo Alto 94301 515 USA 517 Email: gregw@intalio.com