Network Working Group de Croy Internet-Draft QBIK Intended status: Standards Track August 1, 2007 Expires: January 3, 2008 Progress notifications for HTTP draft-decroy-http-progress-01 Status of this Memo By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on January 3, 2008. Copyright Notice Copyright (C) The Internet Society (2007). de Croy Expires January 3, 2008 [Page 1] Internet-Draft http-progress August 2007 Abstract This document specifies extenions to HTTP to allow progress messages for user-agents during lengthy transactions, and to allow better flow-control of large message body submission in cases where HTTP authentication is required by servers and/or intermediaries. Table of Contents 1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Introduction and motivation . . . . . . . . . . . . . . . . . 4 2.1 The need for progress information. . . . . . . . . . . . . . 4 2.2 Aim of this document . . . . . . . . . . . . . . . . . . . . 4 3. Header Field Definitions . . . . . . . . . . . . . . . . . . . 5 3.1 Progress . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.1.1 Client request . . . . . . . . . . . . . . . . . . . . . 5 3.1.2 1xx Responses. . . . . . . . . . . . . . . . . . . . . . 6 4. Timing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 4.1 Progress Intervals . . . . . . . . . . . . . . . . . . . . . 7 5. Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 6. Compatibilty issues. . . . . . . . . . . . . . . . . . . . . . 9 7. Implementation Notes . . . . . . . . . . . . . . . . . . . . . 10 8. Security Considerations . . . . . . . . . . . . . . . . . . . 11 9. Notes & TODO . . . . . . . . . . . . . . . . . . . . . . . . . 12 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 14 11.1. Normative References . . . . . . . . . . . . . . . . . . . 14 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 15 Intellectual Property and Copyright Statements . . . . . . . . . . 16 de Croy Expires January 3, 2008 [Page 2] Internet-Draft http-progress August 2007 1. Terminology The keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT" and "MAY" that appear in this document are to be interpreted as described in [RFC2119] de Croy Expires January 3, 2008 [Page 3] Internet-Draft http-progress August 2007 2. Introduction and motivation 2.1 The need for progress information Increasingly, resource transfers using HTTP are subject to ever- more complex processing, particularly by proxy servers. Processing such as scanning resources for viruses at an HTTP proxy creates special problems that cannot be resolved cleanly with the current specification of HTTP. Many types of processing require access to an entire message body. This can take considerable time to accumulate depending on upstream link bandwidth and/or other factors. It may not be safe to send any part of the resource to the client until processing is complete. Frequently problems occur where human users of client agents give up waiting for visible progress, typically resulting in retries wasting time and network resources. Furthermore, some automated clients will give up waiting when no resource data is received within a certain timeframe. There is a clear need for upstream agents to be able to provide timely progress notifications to downstream agents to enable them to make proper decisions about whether it is appropriate to keep waiting. 2.3 Aim of this document This document aims to solve this problems by providing a defined mechanism whereby intermediaries or server agents can provide visible progress notifications back to the client agent (and the human user), thereby avoiding inappropriate timeouts, and retries; de Croy Expires January 3, 2008 [Page 4] Internet-Draft http-progress August 2007 3 Header field definitions This document defines a new header field to indicate progress. This field allows optional textual state indication as well as requiring numeric indication of completeness. 3.1 Progress 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. A server that complies with this document upon receiving a request containing a Progress field MUST provide an interim response message (1XX) within a reasonable time period AND provide further periodic updates until the final response to the request is sent. A proxy that complies with this document upon receiving a request containing a Progress field MUST forward the tag unchanged to any upstream agent. The proxy however is responsible for providing progress messages to the client, and in the event that no upstream notifications are available, it MUST satisfy the client progress notifications whilst it is still prepared to process the request. The proxy SHOULD pass any 1XX messages back through to the client unchanged. Progress indication is worthless if it is not timely. A discussion of timing is in section 4 The form of the field is defined below 3.1.1 Client request Progress = "Progress" ":" SP interval interval = the time in seconds in which the client expects a response Example: Progress: 10 de Croy Expires January 3, 2008 [Page 5] Internet-Draft http-progress August 2007 3.1.2 1xx Responses Progress = "Progress" ":" SP numeric [";" SP textual] textual = any text valid in a header numeric = (percent | bytes-processed "/" bytes-total) percent = "%" number bytes-processed = number bytes-total = number | "UNKNOWN" The textual information is intended to be displayed verbatim to a user in an area usually associated with progress indication. The numeric-progress field can be used to display a progress bar and/or show how much data has been received by an upstream proxy. the language of the text information SHOULD be the same language as indicated as preferred by the client in its original request, e.g. by using the values from the Accept-Language: header in the request Examples of its use are: Progress: 20480/UNKNOWN; Generating content This could be sent by a server to indicate progress of generation of content. Progress: 20480/UNKNOWN; Download in progress Could be sent by an upstream proxy that is retrieving a message body, has received 20480 bytes, and doesn't know the content length. Progress: 1200000/1200000; Download complete, scanning Could be sent by an upstream proxy that has just completed retrieving a message body, has received 1200000 of 1200000 bytes, and is about to scan the content before sending it on to the client. Progress: %25; Scanning content for viruses Could be sent by an upstream proxy that is currently 25% through virus scanning of a message body. Progress: %45; Enumerating mail folders could be sent by a webmail server opening a user mailbox de Croy Expires January 3, 2008 [Page 6] Internet-Draft http-progress August 2007 4. Timing 4.1 Progress intervals The client Progress header indicates a time in seconds which is the time within which it expects a response (either final or interim containing progress information). The server or proxy SHOULD use this specified time as the initial time and periodic time for updates, or choose another time. If the server chooses to use another periodic interval, this should be one chosen with regard to the usefulness of the interval to a waiting human, and it is suggested that an interval of about 5 - 10 seconds would be appropriate. Agents generating progress notifications MAY choose to send a notification whenever any significant change in state occurs. However in the interests of bandwidth, agents SHOULD NOT send progress notifications more frequently than once per second. This includes an intermediary which may be generating notifications and relaying notifications from upstream. It is left up to the implementor of intermediaries to choose which notifications they may choose to relay or generate themselves, remembering that this is intended for a human user, but will be useful to automated agents as well. de Croy Expires January 3, 2008 [Page 7] Internet-Draft http-progress August 2007 5. Example +-------------------+------------------------+--------------------+ | Client | Intermediary | Server | +-------------------+------------------------+--------------------+ Connects to intermediary -> GET http://www.wingate.com/bigfile.zip HTTP/1.1 Host: www.wingate.com Progress: 10 -> GET /bigfile.zip HTTP/1.1 Host: www.wingate.com Progress: 10 <- HTTP/1.1 200 OK Content-Length: 20000000 ... time elapses <- HTTP/1,1 102 Processing Progress: 1000000/20000000; Downloading time elapses <- HTTP/1,1 102 Processing Progress: 20000000/20000000; Downloaded, Scanning time elapses <- HTTP/1,1 102 Processing Progress: %25; Scanning time elapses <- HTTP/1,1 102 Processing Progress: %75; Scanning <- HTTP/1.1 200 OK Content-Length: 20000000 ... Transfers resource to client. de Croy Expires January 3, 2008 [Page 8] Internet-Draft http-progress August 2007 6. Compatibilty issues. None identified. RFC2616 already mandates that any agent must be able to cope with multiple interim responses. A server not understanding the Progress header in a request will not generate progress notifications. A client unaware of this document will not generate requests with the Progress header. A proxy not understanding the Progress header already should be passing unknown headers through to upstream, and also passing back 1XX responses. de Croy Expires January 3, 2008 [Page 9] Internet-Draft http-progress August 2007 7. Implementation Notes Most user agents provide screen real-estate to display progress, often in the "status bar" of the window. It is envisaged that the progress notifications outlined in this document would be shown in there. de Croy Expires January 3, 2008 [Page 10] Internet-Draft http-progress August 2007 8. Security Considerations No security issues identified with use of this proposal. de Croy Expires January 3, 2008 [Page 11] Internet-Draft http-progress August 2007 9. Notes & TODO * modified from version 00 to remove sections on flow control issues. de Croy Expires January 3, 2008 [Page 12] Internet-Draft http-progress August 2007 10. IANA Considerations None. de Croy Expires January 3, 2008 [Page 13] Internet-Draft http-progress August 2007 11. References 11.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. [RFC4234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 4234, October 2005. [RFC4559] Brezak, J. "SPNEGO-based Kerberos and NTLM HTTP authentication in Microsoft Windows", RFC 4559, June 2006 de Croy Expires January 3, 2008 [Page 14] Internet-Draft http-progress August 2007 Author's Address Adrien de Croy Qbik New Zealand Limited PO Box 3548 Shortland St Auckland New Zealand Email: adrien@qbik.com URI: http://www.wingate.com/ de Croy Expires January 3, 2008 [Page 15] Internet-Draft http-progress August 2007 Full Copyright Statement Copyright (C) The Internet Society (2007). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Intellectual Property The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org. Acknowledgment Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). de Croy Expires January 3, 2008 [Page 16]