idnits 2.17.1 draft-decroy-http-progress-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 14. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 355. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 366. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 373. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 379. 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 : ---------------------------------------------------------------------------- == There are 2 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust 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). == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The Progress field MAY appear in any request message sent by a client or in any server or proxy-generated 1xx series of response messages. The Progress field MUST not appear in any other series of response messages. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (July 23, 2008) is 5756 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: 'RFC2616' is defined on line 321, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 2 errors (**), 0 flaws (~~), 5 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group de Croy 2 Internet-Draft QBIK 3 Intended status: Standards Track July 23, 2008 4 Expires: January 23, 2009 6 Progress notifications for HTTP 7 draft-decroy-http-progress-04 9 Status of this Memo 11 By submitting this Internet-Draft, each author represents that any 12 applicable patent or other IPR claims of which he or she is aware 13 have been or will be disclosed, and any of which he or she becomes 14 aware will be disclosed, in accordance with Section 6 of BCP 79. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that 18 other groups may also distribute working documents as Internet- 19 Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six months 22 and may be updated, replaced, or obsoleted by other documents at any 23 time. It is inappropriate to use Internet-Drafts as reference 24 material or to cite them other than as "work in progress." 26 The list of current Internet-Drafts can be accessed at 27 http://www.ietf.org/ietf/1id-abstracts.txt. 29 The list of Internet-Draft Shadow Directories can be accessed at 30 http://www.ietf.org/shadow.html. 32 This Internet-Draft will expire on January 23, 2009. 34 Copyright Notice 36 Copyright (C) The IETF Trust (2008). 38 Abstract 40 This document specifies an extension to HTTP to allow the sending of 41 progress messages to user-agents during lengthy processing which 42 could otherwise cause users or user-agents to abandon requests. 44 Table of Contents 46 1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 47 2. Introduction and motivation . . . . . . . . . . . . . . . . . 4 48 2.1 The need for progress information. . . . . . . . . . . . . . 4 49 2.2 Aim of this document . . . . . . . . . . . . . . . . . . . . 4 50 3. Header Field Definitions . . . . . . . . . . . . . . . . . . . 5 51 3.1 Progress . . . . . . . . . . . . . . . . . . . . . . . . . . 5 52 3.1.1 Client request . . . . . . . . . . . . . . . . . . . . . 5 53 3.1.2 1xx Responses. . . . . . . . . . . . . . . . . . . . . . 6 54 4. Timing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 55 4.1 Progress Intervals . . . . . . . . . . . . . . . . . . . . . 7 56 5. Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 57 6. Compatibilty issues. . . . . . . . . . . . . . . . . . . . . . 9 58 7. Implementation Notes . . . . . . . . . . . . . . . . . . . . . 10 59 8. Security Considerations . . . . . . . . . . . . . . . . . . . 11 60 9. Notes & TODO . . . . . . . . . . . . . . . . . . . . . . . . . 12 61 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 62 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 14 63 11.1. Normative References . . . . . . . . . . . . . . . . . . . 14 64 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 15 65 Intellectual Property and Copyright Statements . . . . . . . . . . 16 67 1. Terminology 69 The keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT" 70 and "MAY" that appear in this document are to be interpreted as 71 described in [RFC2119] 73 2. Introduction and motivation 75 2.1 The need for progress information 77 Resource transfers using HTTP are increasingly subject to ever- 78 more complex processing, particularly by proxy servers. Processing 79 such as scanning resources for virii at an HTTP proxy creates 80 special problems that cannot be resolved cleanly with the current 81 specification of HTTP. 83 Many types of processing require access to an entire message body. 84 This can take considerable time to accumulate depending on upstream 85 link bandwidth and/or other factors. It may not be safe to send 86 any part of the resource to the client until processing is complete. 88 Frequently problems occur where human users of client agents give up 89 waiting for visible progress, typically resulting in retries wasting 90 time, network and other resources. 92 Furthermore, some automated clients will give up waiting when no 93 resource data is received within a certain timeframe. 95 There is a clear need for upstream agents to be able to provide 96 timely progress notifications to downstream agents to enable them to 97 make proper decisions about whether it is appropriate to keep 98 waiting. 100 2.3 Aim of this document 102 This document aims to solve this problem by providing a defined 103 mechanism whereby intermediaries or server agents can provide 104 progress notifications back to the client agent (and the human user), 105 thereby avoiding inappropriate timeouts, and retries. 107 3 Header field definitions 109 This document defines a new header field to indicate progress. 110 This field allows optional textual state indication as well as 111 requiring numeric indication of completeness. 113 3.1 Progress 115 The Progress field MAY appear in any request message sent by a client 116 or in any server or proxy-generated 1xx series of response messages. 117 The Progress field MUST not appear in any other series of response 118 messages. 120 A server that complies with this document upon receiving a request 121 containing a Progress field MUST provide an interim response message 122 (1XX) within a reasonable time period AND provide further periodic 123 updates until the final response to the request is sent. 125 A proxy that complies with this document upon receiving a request 126 containing a Progress field MUST forward the tag unchanged to any 127 upstream agent. The proxy however is responsible for providing 128 progress messages to the client, and in the event that no upstream 129 notifications are available, it MUST satisfy the client progress 130 notifications whilst it is still prepared to process the request. 132 The proxy SHOULD pass any 1XX messages back through to the 133 client unchanged. 135 Progress indication is worthless if it is not timely. A discussion 136 of timing is in section 4 138 The form of the field is defined below 140 3.1.1 Client request 142 Progress = "Progress" ":" interval 144 interval = 1*4DIGIT 145 ; the time (s) within which the client expects a response 147 Example: 149 Progress: 10 151 3.1.2 1xx Responses 153 Progress = "Progress" ":" prog-num [SP prog-text] 155 prog-text = quoted-string 157 prog-num = percent | (bytes-processed "/" bytes-total) 159 percent = "%" %d0-100 160 ; integer percentage complete, 0 - 100 162 bytes-processed = number 164 bytes-total = number | "UNKNOWN" 166 The textual information is intended to be displayed verbatim to a 167 user in an area usually associated with progress indication. The 168 numeric-progress field can be used to display a progress bar and/or 169 show how much data has been received by an upstream proxy. 171 The prog-text SHOULD be in a natural language and character set that 172 is most likely to be intelligible to the human user receiving the 173 response. This decision MAY be based on any available knowledge. The 174 default language is English and the default character set is 175 ISO-8859-1. If a character set other than ISO-8859-1 is used, it MUST 176 be encoded in the prog-text using the method described in [RFC2047]. 178 Examples: 180 Progress: 20480/UNKNOWN "Generating content" 182 This could be sent by a server to indicate progress of generation of 183 content. 185 Progress: 20480/UNKNOWN "Download in progress" 187 Could be sent by an upstream proxy that is retrieving a message body, 188 has received 20480 bytes, and doesn't know the content length. 190 Progress: 1200000/1200000 "Download complete, scanning" 192 Could be sent by an upstream proxy that has just completed retrieving 193 a message body, has received 1200000 of 1200000 bytes, and is about 194 to scan the content before sending it on to the client. 196 Progress: %25 "Scanning content for virii" 198 Could be sent by an upstream proxy that is currently 25% through 199 virus scanning of a message body. 201 4. Timing 203 4.1 Progress intervals 205 The client Progress header indicates a time in seconds which is the 206 time within which it expects a response (either final or interim 207 containing progress information). The server or proxy SHOULD use 208 this specified time as the initial time and periodic time for 209 updates, or choose another time. If the server chooses to use 210 another periodic interval, this should be one chosen with regard to 211 the usefulness of the interval to a waiting human, and it is 212 suggested that an interval of about 5 - 10 seconds would be 213 appropriate. 215 Agents generating progress notifications MAY choose to send a 216 notification whenever any significant change in state occurs. 218 However in the interests of bandwidth, agents SHOULD NOT send 219 progress notifications more frequently than once per second. 220 This includes an intermediary which may be generating notifications 221 and relaying notifications from upstream. 223 It is left up to the implementor of intermediaries to choose which 224 notifications they may choose to relay or generate themselves, 225 remembering that this is intended for a human user, but will be 226 useful to automated agents as well. 228 5. Example 230 +-------------------+------------------------+--------------------+ 231 | Client | Intermediary | Server | 232 +-------------------+------------------------+--------------------+ 234 Connects to intermediary 236 -> 237 GET http://www.wingate.com/bigfile.zip HTTP/1.1 238 Host: www.wingate.com 239 Progress: 10 241 -> 242 GET /bigfile.zip HTTP/1.1 243 Host: www.wingate.com 244 Progress: 10 246 <- 247 HTTP/1.1 200 OK 248 Content-Length: 20000000 249 ... 251 time elapses 252 <- 253 HTTP/1,1 102 Processing 254 Progress: 1000000/20000000 "Downloading" 256 time elapses 257 <- 258 HTTP/1,1 102 Processing 259 Progress: 20000000/20000000 "Downloaded, Scanning" 261 time elapses 262 <- 263 HTTP/1,1 102 Processing 264 Progress: %25 "Scanning" 266 time elapses 267 <- 268 HTTP/1,1 102 Processing 269 Progress: %75 "Scanning" 271 <- 272 HTTP/1.1 200 OK 273 Content-Length: 20000000 274 ... 275 Transfers resource to client. 277 6. Compatibilty issues. 279 None identified. RFC2616 already requires that any agent must be 280 able to cope with multiple interim responses. 282 A server not understanding the Progress header in a request will 283 not generate progress notifications. 285 A client unaware of this document will not generate requests with 286 the Progress header. 288 A proxy not understanding the Progress header already should be 289 passing unknown headers through to upstream, and also passing back 290 1XX responses. 292 7. Implementation Notes 294 Most user agents provide screen real-estate to display progress, 295 often in the "status bar" of the window. It is envisaged that the 296 progress notifications outlined in this document would be shown in 297 there. 299 8. Security Considerations 301 No security issues identified with use of this proposal. 303 9. Notes & TODO 305 * modified from version 00 to remove sections on flow control issues. 307 * modified from version 01 to allow for internationalisation of 308 strings, slight modification to syntax. Minor editorial changes. 310 10. IANA Considerations 312 None. 314 11. References 316 11.1. Normative References 318 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 319 Requirement Levels", BCP 14, RFC 2119, March 1997. 321 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 322 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 323 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 325 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) 326 Part Three: Message Header Extensions for Non-ASCII Text", 327 RFC 2047, November 1996. 329 Author's Address 331 Adrien de Croy 332 Qbik New Zealand Limited 333 PO Box 3548 334 Shortland St 335 Auckland 336 New Zealand 338 Email: adrien@qbik.com 339 URI: http://www.wingate.com/ 341 Full Copyright Statement 343 Copyright (C) The IETF Trust (2008). 345 This document is subject to the rights, licenses and restrictions 346 contained in BCP 78, and except as set forth therein, the authors 347 retain all their rights. 349 This document and the information contained herein are provided on an 350 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 351 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 352 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 353 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 354 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 355 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 357 Intellectual Property 359 The IETF takes no position regarding the validity or scope of any 360 Intellectual Property Rights or other rights that might be claimed to 361 pertain to the implementation or use of the technology described in 362 this document or the extent to which any license under such rights 363 might or might not be available; nor does it represent that it has 364 made any independent effort to identify any such rights. Information 365 on the procedures with respect to rights in RFC documents can be 366 found in BCP 78 and BCP 79. 368 Copies of IPR disclosures made to the IETF Secretariat and any 369 assurances of licenses to be made available, or the result of an 370 attempt made to obtain a general license or permission for the use of 371 such proprietary rights by implementers or users of this 372 specification can be obtained from the IETF on-line IPR repository at 373 http://www.ietf.org/ipr. 375 The IETF invites any interested party to bring to its attention any 376 copyrights, patents or patent applications, or other proprietary 377 rights that may cover technology that may be required to implement 378 this standard. Please address the information to the IETF at 379 ietf-ipr@ietf.org. 381 Acknowledgment 383 Funding for the RFC Editor function is provided by the IETF 384 Administrative Support Activity (IASA).