< draft-wright-http-progress-00.txt   draft-wright-http-progress-01.txt >
HTTP A. Wright HTTP A. Wright
Internet-Draft May 28, 2019 Internet-Draft May 29, 2019
Intended status: Experimental Intended status: Experimental
Expires: November 29, 2019 Expires: November 30, 2019
Reporting Progress of Long-Running Operations in HTTP Reporting Progress of Long-Running Operations in HTTP
draft-wright-http-progress-00 draft-wright-http-progress-01
Abstract Abstract
This document defines a mechanism for following the real-time This document defines a mechanism for following the real-time
progress of long-running operations over HTTP. progress of long-running operations over HTTP.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
skipping to change at page 1, line 31 skipping to change at page 1, line 31
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 29, 2019. This Internet-Draft will expire on November 30, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 24 skipping to change at page 2, line 24
3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 6 3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.1. The "102 Processing" status code . . . . . . . . . . . . 6 3.1. The "102 Processing" status code . . . . . . . . . . . . 6
3.1.1. Use of the "Location" header in 102 Processing . . . 7 3.1.1. Use of the "Location" header in 102 Processing . . . 7
3.2. The "Progress" header . . . . . . . . . . . . . . . . . . 7 3.2. The "Progress" header . . . . . . . . . . . . . . . . . . 7
3.3. The "Status-URI" header . . . . . . . . . . . . . . . . . 8 3.3. The "Status-URI" header . . . . . . . . . . . . . . . . . 8
3.4. The "Status-Location" header . . . . . . . . . . . . . . 8 3.4. The "Status-Location" header . . . . . . . . . . . . . . 8
3.5. The "processing" preference . . . . . . . . . . . . . . . 9 3.5. The "processing" preference . . . . . . . . . . . . . . . 9
4. Security Considerations . . . . . . . . . . . . . . . . . . . 9 4. Security Considerations . . . . . . . . . . . . . . . . . . . 9
4.1. Status URIs . . . . . . . . . . . . . . . . . . . . . . . 9 4.1. Status URIs . . . . . . . . . . . . . . . . . . . . . . . 9
4.2. Denial of Service . . . . . . . . . . . . . . . . . . . . 9 4.2. Denial of Service . . . . . . . . . . . . . . . . . . . . 9
5. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 9
5.1. Normative References . . . . . . . . . . . . . . . . . . 10 5.1. Normative References . . . . . . . . . . . . . . . . . . 10
5.2. Informative References . . . . . . . . . . . . . . . . . 10 5.2. Informative References . . . . . . . . . . . . . . . . . 10
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11
1. Introduction 1. Introduction
HTTP is often used for making and observing the progress of long- HTTP is often used for making and observing the progress of long-
running operations, including: running operations, including:
o Copying, patching, or deleting large sets of files o Copying, patching, or deleting large sets of files
skipping to change at page 3, line 48 skipping to change at page 3, line 48
respond with any response allowed by HTTP, including a document respond with any response allowed by HTTP, including a document
describing the result of the operation, a representation of the describing the result of the operation, a representation of the
new state of the resource, or a minimal representation. new state of the resource, or a minimal representation.
o If the client sent a "Prefer: processing" preference, the server o If the client sent a "Prefer: processing" preference, the server
SHOULD issue a "102 Processing" intermediate response upon receipt SHOULD issue a "102 Processing" intermediate response upon receipt
of the request, and every time there is an update to the operation of the request, and every time there is an update to the operation
progress. The first intermediate response SHOULD include a progress. The first intermediate response SHOULD include a
"Location" header identifying the status document created for this "Location" header identifying the status document created for this
request. When the request finishes, respond normally with the request. When the request finishes, respond normally with the
final non-1xx, non-202 status code. If the client additionally final non-1xx, non-202 status code.
sent a "Prefer: progress" preference, each response SHOULD include
a "Progress" header in each response.
o If the request includes "Prefer: respond-async, wait=n", and has o If the request includes "Prefer: respond-async, wait=n", and has
been running longer than the preferred wait time, then background been running longer than the preferred wait time, then background
the operation and emit "202 Accepted", with a "Location" header. the operation and emit "202 Accepted", with a "Location" header.
If the server emitted a 102 Processing intermediate response, this If the server emitted a 102 Processing intermediate response, this
will be the same header as before. will be the same header as before.
If the server responds with the result of the operation, or a If the server responds with the result of the operation, or a
representation of the new state of the resource, the "Content- representation of the new state of the resource, the "Content-
Location" header identifies where this document can be requested in Location" header identifies where this document can be requested in
the future. the future.
Note that clients may make requests with all of the above Note that clients may make requests with all of the above
preferences; they can all be honored at the same time, see below for preferences; they can all be honored at the same time, see below for
skipping to change at page 5, line 11 skipping to change at page 5, line 11
by issuing a "DELETE" request on the status document. Servers SHOULD by issuing a "DELETE" request on the status document. Servers SHOULD
limit requests on the status document to the user that issued the limit requests on the status document to the user that issued the
initial request. initial request.
Servers MAY delete the status document any time after the operation Servers MAY delete the status document any time after the operation
finishes, but SHOULD wait a period of time long enough for clients to finishes, but SHOULD wait a period of time long enough for clients to
check back on the operation on another business day. check back on the operation on another business day.
2.4. Example 2.4. Example
Clients may send all four preferences in a request. In this example, Clients may send any combination of preferences in a request. In
the client issues a POST request to capture a photograph of a scenic this example, the client issues a POST request to capture a
landscape by issuing a POST request to <"http://example.com/ photograph of a scenic landscape by issuing a POST request to
capture">, and the server generates a status document for this "http://example.com/capture", and the server generates a status
request at <"http://example.com/capture?request=42">. document for this request at "http://example.com/capture?request=42".
POST http://example.com/capture HTTP/1.1 POST http://example.com/capture HTTP/1.1
Prefer: processing, respond-async, wait=20 Prefer: processing, respond-async, wait=20
To which the server might reply: To which the server might reply:
HTTP/1.1 102 Processing HTTP/1.1 102 Processing
Location: <?request=42> Location: <?request=42>
Progress: 0/3 "Herding cats" Progress: 0/3 "Herding cats"
skipping to change at page 6, line 33 skipping to change at page 6, line 33
Prefer: processing, respond-async, wait=20 Prefer: processing, respond-async, wait=20
HTTP/1.1 102 Processing HTTP/1.1 102 Processing
Progress: 1/3 "Knitting sweaters" Progress: 1/3 "Knitting sweaters"
HTTP/1.1 102 Processing HTTP/1.1 102 Processing
Progress: 2/3 "Slaying dragons" Progress: 2/3 "Slaying dragons"
HTTP/1.1 200 OK HTTP/1.1 200 OK
Progress: 3/3 "Available" Progress: 3/3 "Available"
Content-Type: application/json
Status-URI: 201 </capture> Status-URI: 201 </capture>
Status-Location: </photos/42> Status-Location: </photos/42>
Content-Type: text/plain Content-Type: text/plain
The photographer uploaded your image to: The photographer uploaded your image to:
<http://example.com/photos/42> <http://example.com/photos/42>
3. Definitions 3. Definitions
3.1. The "102 Processing" status code 3.1. The "102 Processing" status code
skipping to change at page 7, line 39 skipping to change at page 7, line 36
quoted-string = <quoted-string, see [RFC7230], Section 3.2.6> quoted-string = <quoted-string, see [RFC7230], Section 3.2.6>
ext-value = <ext-value, see [RFC8187]> ext-value = <ext-value, see [RFC8187]>
The Progress header includes three datum: A numerator, a denominator, The Progress header includes three datum: A numerator, a denominator,
and a message. and a message.
The numerator specifies the number of sub-operations that have The numerator specifies the number of sub-operations that have
completed. The numerator MUST NOT decrease in value. completed. The numerator MUST NOT decrease in value.
The denominator specifies the total expected operations to be The denominator specifies the total expected operations to be
completed before a final status code can be delivered. The completed before a final status code can be delivered. If specified,
denominator MUST be larger than the numerator, if specified. If the the denominator MUST NOT be smaller than the numerator. If the
length of the operation is unknown, it may be omitted. If additional length of the operation is unknown, it may be omitted. If additional
tasks need to be performed, the denominator MAY increase. tasks need to be performed, the denominator MAY increase.
The message is some sort of remark indicating the current task being The message is some sort of remark indicating the current task being
carried out. If multiple files are being operated on, this might carried out. If multiple files are being operated on, this might
refer to the most recent file to be opened. Three forms are refer to the most recent file to be opened. Three forms are
provided: provided:
o Use of the "comment" production implies the text is not intended o Use of the "comment" production implies the text is not intended
for end users. for end users.
skipping to change at page 8, line 29 skipping to change at page 8, line 25
Progress: 5/16 UTF-8'ja-JP'%e9%a3%9f%e3%81%b9%e3%81%a6 Progress: 5/16 UTF-8'ja-JP'%e9%a3%9f%e3%81%b9%e3%81%a6
Progress: 3/20 "POST http://example.com/item/3" Progress: 3/20 "POST http://example.com/item/3"
3.3. The "Status-URI" header 3.3. The "Status-URI" header
The Status-URI header reports the status of an operation performed on The Status-URI header reports the status of an operation performed on
a resource by another request. a resource by another request.
The Status-URI header MAY be used any number of times in a "101 The Status-URI header MAY be used any number of times in a "101
Processing" response to report the result of a subordinate operation Processing" response to report the result of a subordinate operation
for the request or the request that the status document is about. for the request.
The Status-URI header SHOULD be used to report the final response The Status-URI header SHOULD be used to report the final response
status that the status document is about. status that the status document is about.
Status-URI = #status-pair Status-URI = #status-pair
status-pair = status-code OWS "<" URI-Reference ">" status-pair = status-code OWS "<" URI-Reference ">"
status-code = <status-code, see [RFC7230], Section 3.1.2> status-code = <status-code, see [RFC7230], Section 3.1.2>
URI-Reference = <URI-reference, see [RFC7230], Section 2.7> URI-Reference = <URI-reference, see [RFC7230], Section 2.7>
Example usage: Example usage:
skipping to change at page 9, line 12 skipping to change at page 9, line 10
URI of the resource that would have been identified by the "Location" URI of the resource that would have been identified by the "Location"
header in the initial request. The meaning of the value of this header in the initial request. The meaning of the value of this
header is dependent on the value of the status code from the "Status- header is dependent on the value of the status code from the "Status-
URI" header. URI" header.
The purpose of this header is to have a field that is semantically The purpose of this header is to have a field that is semantically
the same as the Location header on the initial response. This is the same as the Location header on the initial response. This is
slightly different than the Link header [RFC8288], which conveys a slightly different than the Link header [RFC8288], which conveys a
link relationship between documents. link relationship between documents.
This header is so named as it is the URI from a location header in This header is so named as it is the URI from a Location header in
the final response to an initial request, that has since been copied the final response to an initial request, that has since been copied
to a status document response. to the response headers for the status document.
3.5. The "processing" preference 3.5. The "processing" preference
The "processing" HTTP preference [RFC7240] specifies if the server The "processing" HTTP preference [RFC7240] specifies if the server
should emit "102 Processing" status responses. should emit "102 Processing" status responses.
When performing a unsafe action, the server should emit intermediate When performing a unsafe action, the server should emit intermediate
"102 Processing" responses until the action finishes. "102 Processing" responses until the action finishes.
In a GET or HEAD request to a status document, it means the client is In a GET or HEAD request to a status document, it means the client is
 End of changes. 13 change blocks. 
19 lines changed or deleted 17 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/