idnits 2.17.1 draft-wright-http-progress-02.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 : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 21, 2019) is 1615 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 2518 (Obsoleted by RFC 4918) Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP A. Wright 3 Internet-Draft November 21, 2019 4 Intended status: Experimental 5 Expires: May 24, 2020 7 Reporting Progress of Long-Running Operations in HTTP 8 draft-wright-http-progress-02 10 Abstract 12 This document defines a mechanism for following the real-time 13 progress of long-running operations over HTTP. 15 Status of This Memo 17 This Internet-Draft is submitted in full conformance with the 18 provisions of BCP 78 and BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF). Note that other groups may also distribute 22 working documents as Internet-Drafts. The list of current Internet- 23 Drafts is at https://datatracker.ietf.org/drafts/current/. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 This Internet-Draft will expire on May 24, 2020. 32 Copyright Notice 34 Copyright (c) 2019 IETF Trust and the persons identified as the 35 document authors. All rights reserved. 37 This document is subject to BCP 78 and the IETF Trust's Legal 38 Provisions Relating to IETF Documents 39 (https://trustee.ietf.org/license-info) in effect on the date of 40 publication of this document. Please review these documents 41 carefully, as they describe your rights and restrictions with respect 42 to this document. Code Components extracted from this document must 43 include Simplified BSD License text as described in Section 4.e of 44 the Trust Legal Provisions and are provided without warranty as 45 described in the Simplified BSD License. 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 50 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 51 1.2. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . 3 52 2. Status Document Workflow . . . . . . . . . . . . . . . . . . 3 53 2.1. Initial Request . . . . . . . . . . . . . . . . . . . . . 3 54 2.2. Status Document Request . . . . . . . . . . . . . . . . . 4 55 2.3. Closing the Operation . . . . . . . . . . . . . . . . . . 4 56 2.4. Example . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 6 58 3.1. The "102 Processing" status code . . . . . . . . . . . . 6 59 3.1.1. Use of the "Location" header in 102 Processing . . . 7 60 3.2. The "Progress" header . . . . . . . . . . . . . . . . . . 7 61 3.3. The "Status-URI" header . . . . . . . . . . . . . . . . . 8 62 3.4. The "processing" preference . . . . . . . . . . . . . . . 9 63 4. Security Considerations . . . . . . . . . . . . . . . . . . . 9 64 4.1. Status URIs . . . . . . . . . . . . . . . . . . . . . . . 9 65 4.2. Denial of Service . . . . . . . . . . . . . . . . . . . . 9 66 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 67 5.1. Normative References . . . . . . . . . . . . . . . . . . 9 68 5.2. Informative References . . . . . . . . . . . . . . . . . 10 69 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10 71 1. Introduction 73 HTTP is often used for making and observing the progress of long- 74 running operations, including: 76 o Copying, patching, or deleting large sets of files 78 o Waiting on a task to be started at a specific time 80 o Adding an operation to a lengthy queue 82 o Working through a multi-step operation, e.g. provisioning a server 84 o Receiving updates to a long running task, e.g. construction of a 85 building 87 This document specifies a way to receive updates from the server on 88 progress of such an operation, by defining a "progress" HTTP 89 preference indicating the client would prefer to receive regular 90 progress updates, a header for describing the current progress, and a 91 1xx interim response to convey this progress information. 93 1.1. Notational Conventions 95 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 96 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 97 "OPTIONAL" in this document are to be interpreted as described in BCP 98 14 [RFC2119] [RFC8174] when, and only when, they appear in all 99 capitals, as shown here. 101 This document uses ABNF as defined in [RFC5234] and imports grammar 102 rules from [RFC7230] and [RFC8187]. 104 Examples in this document may add whitespace for clarity, or omit 105 some HTTP headers for brevity; requests and responses may require 106 additional Host, Connection, and/or Content-Length headers to be 107 properly received. 109 1.2. Scope 111 This document is only intended to provide a mechanism for relaying 112 the progress of a long-running operation, it does not intend to be a 113 mechanism for subscribing to updates on a resource in general. 115 2. Status Document Workflow 117 The Status Document Workflow uses a status document that is related 118 to a single request. This status document is updated with the status 119 of the operation, until the operation completes, finalizing the 120 status document with the result of the operation. No format is 121 defined for the status document, any suitable information may be 122 included, and the contents MAY be content-negotiated. 124 The server SHOULD keep the status document available for a period of 125 time after the operation finishes. 127 2.1. Initial Request 129 To begin, the client makes the initial request with an unsafe method. 130 For example, "POST http://example.com/resource". 132 o If the operation finishes quickly, the server can issue the final 133 response with a non-1xx, non-202 status code. The server may 134 respond with any response allowed by HTTP, including a document 135 describing the result of the operation, a representation of the 136 new state of the resource, or a minimal representation. 138 o If the client sent a "Prefer: processing" preference, the server 139 SHOULD issue a "102 Processing" interim response upon receipt of 140 the request, and every time there is an update to the operation 141 progress. The first interim response SHOULD include a "Location" 142 header identifying the status document created for this request. 143 When the request finishes, respond normally with the final non- 144 1xx, non-202 status code. 146 o If the request includes "Prefer: respond-async, wait=n", and has 147 been running longer than the preferred wait time, then background 148 the operation and emit "202 Accepted", with a "Location" header. 149 If the server emitted a 102 Processing interim response, this will 150 be the same header as before. 152 If the server responds with the result of the operation, or a 153 representation of the new state of the resource, the "Content- 154 Location" header identifies where this document can be requested in 155 the future. 157 Note that clients may make requests with all of the above 158 preferences; they can all be honored at the same time, see below for 159 an example. 161 2.2. Status Document Request 163 If the client received an operation status document from the initial 164 unsafe request, it may make a GET request to this document to re- 165 download the result of the request. 167 The client may do this for any reason, including: 169 o The operation resulted in a 202 Accepted response and the client 170 wants to know if the operation finished. 172 o The user wants to review the outcome of the request after having 173 discarded the initial 2xx (non-202) response. 175 o The connection was reset before the initial request could respond 176 with a non-1xx status code. 178 If the client makes this request with the "Prefer: processing" 179 preference, the server SHOULD send an initial "102 Processing" 180 header, and "102 Processing" responses for every progress update 181 until the operation completes. 183 2.3. Closing the Operation 185 The client MAY acknowledge it has reacted to the completed operation 186 by issuing a "DELETE" request on the status document. Servers SHOULD 187 limit requests on the status document to the user that issued the 188 initial request. 190 Servers MAY delete the status document any time after the operation 191 finishes, but SHOULD wait a period of time long enough for clients to 192 check back on the operation on another business day. 194 2.4. Example 196 Clients may send any combination of preferences in a request. In 197 this example, the client issues a POST request to capture a 198 photograph of a scenic landscape by issuing a POST request to 199 "http://example.com/capture", and the server generates a status 200 document for this request at "http://example.com/capture?request=42". 202 POST http://example.com/capture HTTP/1.1 203 Prefer: processing, respond-async, wait=20 205 To which the server might reply: 207 HTTP/1.1 102 Processing 208 Location: 209 Progress: 0/3 "Herding cats" 211 HTTP/1.1 102 Processing 212 Progress: 1/3 "Knitting sweaters" 214 HTTP/1.1 102 Processing 215 Progress: 2/3 "Slaying dragons" 217 HTTP/1.1 201 Created 218 Progress: 3/3 "Available" 219 Location: 220 Content-Location: 221 Content-Type: text/plain 223 The photographer uploaded your image to: 224 226 If this same request took significantly longer (more than 20 227 seconds), then due to the respond-async preference, the response 228 might look like this instead: 230 HTTP/1.1 102 Processing 231 Progress: 0/3 "Herding cats" 232 Location: 234 HTTP/1.1 102 Processing 235 Progress: 1/3 "Knitting sweaters" 237 HTTP/1.1 202 Accepted 238 Location: 239 Content-Location: 240 Content-Type: text/plain 242 The photographer is on step 2: Knitting sweaters 244 The client can re-subscribe to updates by making a GET request to the 245 status document with "Prefer: processing": 247 GET http://example.com/capture?request=42 HTTP/1.1 248 Prefer: processing, respond-async, wait=20 250 HTTP/1.1 102 Processing 251 Progress: 1/3 "Knitting sweaters" 253 HTTP/1.1 102 Processing 254 Progress: 2/3 "Slaying dragons" 256 HTTP/1.1 200 OK 257 Progress: 3/3 "Available" 258 Status-URI: 201 259 Content-Type: text/plain 261 The photographer uploaded your image to: 262 264 3. Definitions 266 3.1. The "102 Processing" status code 268 The 102 (Processing) status code is an interim response used to 269 inform the client that the server has accepted the request, but has 270 not yet completed it. This status code SHOULD send this status when 271 the request could potentially take long enough to time out 272 connections due to inactivity, or when there is new progress to 273 report via a "Progress" or "Status-URI" header. 275 The "102 Processing" status was first described by WebDAV in 276 [RFC2518], but was not included in subsequent revisions of WebDAV for 277 lack of implementations. This document updates the semantics of the 278 "102 Processing" status code first defined there. 280 3.1.1. Use of the "Location" header in 102 Processing 282 The meaning of a Location header [RFC7231] is the same as in a "202 283 Accepted" response: It identifies a document that will be updated 284 with the progress, current status, and result of the operation. 286 A Location header SHOULD be sent in the first "102 Processing" 287 response, as well as the "202 Accepted" response to the same request. 289 3.2. The "Progress" header 291 The "Progress" header is used to indicate the current progress on an 292 operation being run by the origin server. Use of this header implies 293 the server supports "102 Processing" responses and the "processing" 294 preference. 296 Progress = fraction *( WS progress-remark ) 297 progress-remark = fraction / comment / quoted-string / ext-value 298 fraction = 1*DIGIT "/" [ 1*DIGIT ] 299 comment = 300 quoted-string = 301 ext-value = 303 The Progress header lists data about the current operation and 304 summarizes operations that have finished. It contains a fraction, 305 and any number of remarks. 307 The fraction numerator specifies the number of operations that have 308 completed. It may also represent the zero-indexed identifier of the 309 current operation. The numerator MUST NOT decrease in value. 311 The fraction denominator specifies the total expected operations to 312 be completed before a final status code can be delivered. If 313 specified, the denominator MUST NOT be smaller than the numerator. 314 The denominator MAY be omitted when the length of the operation is 315 unknown. If additional tasks need to be performed, the denominator 316 MAY increase. The numerator MUST NOT decrease in value and MUST NOT 317 disappear once introduced. 319 The remark is some sort of indication of the current task being 320 carried out. For example, if multiple files are being operated on, 321 it might refer to the most recent file to be opened. Four forms are 322 provided: 324 o Use of additional "fraction" productions are permitted to indicate 325 progress on a subordinate operation. For example, a data transfer 326 in progress as part of a multi-step operation. 328 o Use of the "comment" production implies the text is not intended 329 for end users. 331 o The "ext-value" provides a label for users. If the HTTP server 332 supports localization, the server SHOULD negotiate a language 333 using "Accept-Language", if it exists in the request. This 334 language does not necessarily have to be the same as the "Content- 335 Language". 337 o The "quoted-string" is also supported if the text is entirely 338 7-bit ASCII. This is suitable for reporting filenames or similar 339 data not in any particular language. 341 Multiple remarks MAY be used. Remarks MUST be listed in descending 342 significance; if multiple fractions are presented, remarks describe 343 the operation identified by the previous fraction. 345 Example usage: 347 Progress: 0/1 348 Progress: 66/ (tries) utf-8'en'Generating%20prime%20number 349 Progress: 5/16 UTF-8'ja-JP'%e9%a3%9f%e3%81%b9%e3%81%a6 350 Progress: 3/20 "POST http://example.com/item/3" 8020/8591489 (bytes) 352 3.3. The "Status-URI" header 354 The Status-URI header reports the status of an operation performed on 355 a resource by another request. 357 The Status-URI header MAY be used any number of times in a "101 358 Processing" response to report the result of a subordinate operation 359 for the request. 361 Status-URI = #status-pair 362 status-pair = status-code OWS "<" URI-Reference ">" 363 status-code = 364 URI-Reference = 366 Example usage: 368 Status-URI: 507 369 Status-URI: 200 371 3.4. The "processing" preference 373 The "processing" HTTP preference [RFC7240] specifies if the server 374 should emit "102 Processing" status responses. 376 When performing a unsafe action, the server should emit interim "102 377 Processing" responses until the action finishes. 379 In a GET or HEAD request to a status document, it means the client is 380 only interested in the result of the operation that the status 381 document is about, and the server should send "102 Processing" 382 updates until then. The "respond-async" and "wait" preferences are 383 ignored here as the request is not performing an action. 385 4. Security Considerations 387 4.1. Status URIs 389 The fact that this operation produces a URI for each operation means 390 that third parties can look at the requests being made by a user. 391 Servers SHOULD ensure that only the user who made the request has 392 access to the status document. Servers SHOULD generate URIs with 393 sufficient entropy, although URIs supposed to be considered public 394 knowledge (see HTTP). 396 4.2. Denial of Service 398 This may expose information about load, which may allow attackers to 399 better exploit weak points already under stress. Servers with this 400 functionality may make it cheap for server operators to accept work- 401 intensive tasks. Usual precautions about mitigating denial-of- 402 service attacks should be exercised. 404 5. References 406 5.1. Normative References 408 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 409 Requirement Levels", BCP 14, RFC 2119, 410 DOI 10.17487/RFC2119, March 1997, 411 . 413 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 414 Specifications: ABNF", STD 68, RFC 5234, 415 DOI 10.17487/RFC5234, January 2008, 416 . 418 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 419 Protocol (HTTP/1.1): Message Syntax and Routing", 420 RFC 7230, DOI 10.17487/RFC7230, June 2014, 421 . 423 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 424 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 425 DOI 10.17487/RFC7231, June 2014, 426 . 428 [RFC7240] Snell, J., "Prefer Header for HTTP", RFC 7240, 429 DOI 10.17487/RFC7240, June 2014, 430 . 432 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 433 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 434 May 2017, . 436 [RFC8187] Reschke, J., "Indicating Character Encoding and Language 437 for HTTP Header Field Parameters", RFC 8187, 438 DOI 10.17487/RFC8187, September 2017, 439 . 441 5.2. Informative References 443 [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D. 444 Jensen, "HTTP Extensions for Distributed Authoring -- 445 WEBDAV", RFC 2518, DOI 10.17487/RFC2518, February 1999, 446 . 448 Author's Address 450 Austin Wright 452 Email: aaa@bzfx.net