Subject: 209 No Content vs. application/empty

From: James M Snell <[email-masked]>
Date: Mon, 01 Oct 2007 08:00:13 -0700

Mark Nottingham has suggested that rather than inventing a new Accept
header and 209 No Content response type, it might be better to create a
new media type that indicates the absense of content and use Accept to
indicate the preference.  For instance:

In the request:

  Accept: application/empty, application/atom+xml;q=0.5

In the response:

  HTTP 200 OK
  Content-Type: application/empty
  ...

Seems to address the problem quite nicely.  I still think that there is
benefit to the Prefer header but in this particular case, Marks
suggestion seems to be a whole lot easier :-).

- James

---

From: Andreas Sewe <[email-masked]>
Date: Mon, 01 Oct 2007 19:07:50 +0200

> suggestion seems to be a whole lot easier :-).

I like the idea in general but would prefer the media type to be called
"message/empty" instead. That "application/atom+xml" is of type
"application" doesn't mean that "*/empty" has be as well.

FWIW, there is already a media type called "message/partial";
"message/empty" thus fits into the "message" type quite nicely.

Regards,

Andreas Sewe

---

From: Henrik Nordstrom <[email-masked]>
Date: Tue, 02 Oct 2007 01:12:55 +0200

On mån, 2007-10-01 at 08:00 -0700, James M Snell wrote:
> indicate the preference.

Now I am confused.. wasn't 209 supposed to return the entity as such?
There is alread "204 No Content" for empty responses if you only want to
return meta data (relevant headers)..

Regards
Henrik

---

From: James M Snell <[email-masked]>
Date: Mon, 01 Oct 2007 16:18:45 -0700

Sorry, yes, I managed to confuse myself. My only excuse is insanity :-)
... I any case, the question is more regarding the use of the Prefer
header to request no-content and not the 209 response.

- James

---

From: Henrik Nordstrom <[email-masked]>
Date: Tue, 02 Oct 2007 01:24:12 +0200

> header to request no-content and not the 209 response.

Hmm.. from the discussions I got the impression that the default should
be 204 No Content / 200 Status message (as is for PUT today), with the
client being able to indicate a preference of actually having the
modified resource entity returned as a 209..

I think some context of the discussion has gone missing here.. what use
case are we talking about?

Regards
Henrik

---

From: Adrien de Croy <[email-masked]>
Date: Wed, 03 Oct 2007 17:25:23 +1300

hello all

I've just submitted a revised draft, covering the issues (hopefully) 
Julian raised regarding parsing and internationalisation (for which I 
adopted the method used by the Warning header).

Regards

Adrien de Croy

-- 
Adrien de Croy - WinGate Proxy Server - http://www.wingate.com

Network Working Group                                            de Croy
Internet-Draft                                                      QBIK
Intended status: Standards Track                         October 3, 2007
Expires: April 3, 2008

                      Progress notifications for HTTP
                       draft-decroy-http-progress-03

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 April 3, 2008.

Copyright Notice

   Copyright (C) The Internet Society (2007).

de Croy                   Expires April 3, 2008                 [Page 1]

Internet-Draft                http-progress                 October 2007

Abstract

   This document specifies extenions to HTTP to allow progress messages
   for user-agents during lengthy transactions.

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 April 3, 2008                 [Page 2]

Internet-Draft                http-progress                 October 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 April 3, 2008                 [Page 3]

Internet-Draft                http-progress                 October 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 problem by providing a defined 
   mechanism whereby intermediaries or server agents can provide 
   progress notifications back to the client agent (and the human user),
   thereby avoiding inappropriate timeouts, and retries.

de Croy                   Expires April 3, 2008                 [Page 4]

Internet-Draft                http-progress                 October 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" ":" interval

   interval = 1*4DIGIT
              ; the time (s) within which the client expects a response

   Example:
   
   Progress: 10

de Croy                   Expires April 3, 2008                 [Page 5]

Internet-Draft                http-progress                 October 2007

3.1.2 1xx Responses

   Progress         = "Progress" ":" prog-num [SP prog-text] 

   prog-text        = quoted-string

   prog-num         = percent | (bytes-processed "/" bytes-total)

   percent          = "%" %d0-100
                      ; integer percentage complete, 0 - 100 

   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 prog-text SHOULD be in a natural language and character set that
   is most likely to be intelligible to the human user receiving the
   response. This decision MAY be based on any available knowledge. The 
   default language is English and the default character set is 
   ISO-8859-1. If a character set other than ISO-8859-1 is used, it MUST
   be encoded in the prog-text using the method described in [RFC2047].
   
   Examples:

      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.

de Croy                   Expires April 3, 2008                 [Page 6]

Internet-Draft                http-progress                 October 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 April 3, 2008                 [Page 7]

Internet-Draft                http-progress                 October 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 April 3, 2008                 [Page 8]

Internet-Draft                http-progress                 October 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 April 3, 2008                 [Page 9]

Internet-Draft                http-progress                 October 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 April 3, 2008                [Page 10]

Internet-Draft                http-progress                 October 2007

8.  Security Considerations

   No security issues identified with use of this proposal.

de Croy                   Expires April 3, 2008                [Page 11]

Internet-Draft                http-progress                 October 2007

9.  Notes & TODO

   * modified from version 00 to remove sections on flow control issues.

   * modified from version 01 to allow for internationalisation of 
     strings, slight modification to syntax.  Minor editorial changes.

de Croy                   Expires April 3, 2008                [Page 12]

Internet-Draft                http-progress                 October 2007

10. IANA Considerations

   None.

de Croy                   Expires April 3, 2008                [Page 13]

Internet-Draft                http-progress                 October 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.

   [RFC4559]  Brezak, J. "SPNEGO-based Kerberos and NTLM HTTP 
              authentication in Microsoft Windows", RFC 4559, June 2006

   [RFC2047]  Moore, K., "MIME (Multipurpose Internet Mail Extensions) 
              Part Three: Message Header Extensions for Non-ASCII Text",
              RFC 2047, November 1996.

de Croy                   Expires April 3, 2008                [Page 14]

Internet-Draft                http-progress                 October 2007

Author's Address

   Adrien de Croy
   Qbik New Zealand Limited
   PO Box 3548
   Shortland St
   Auckland
   New Zealand

   Email: [email-masked]
   URI:   http://www.wingate.com/

de Croy                   Expires April 3, 2008                [Page 15]

Internet-Draft                http-progress                 October 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
   [email-masked].

Acknowledgment

   Funding for the RFC Editor function is provided by the IETF
   Administrative Support Activity (IASA).

de Croy                   Expires April 3, 2008                [Page 16]