idnits 2.17.1 draft-nottingham-http-poe-00.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 3667, Section 5.1 on line 14. -- Found old boilerplate from RFC 3978, Section 5.5 on line 403. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 380. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 387. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 393. ** Found boilerplate matching RFC 3978, Section 5.4, paragraph 1 (on line 409), which is fine, but *also* found old RFC 2026, Section 10.4C, paragraph 1 text on line 36. ** The document seems to lack an RFC 3978 Section 5.1 IPR Disclosure Acknowledgement -- however, there's a paragraph with a matching beginning. Boilerplate error? ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. ** The document uses RFC 3667 boilerplate or RFC 3978-like boilerplate instead of verbatim RFC 3978 boilerplate. After 6 May 2005, submission of drafts without verbatim RFC 3978 boilerplate is not accepted. The following non-3978 patterns matched text found in the document. That text should be removed or replaced: By submitting this Internet-Draft, I certify that any applicable patent or other IPR claims of which I am aware have been disclosed, or will be disclosed, and any of which I become aware will be disclosed, in accordance with RFC 3668. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year -- 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 (March 19, 2005) is 6971 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) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 7 errors (**), 0 flaws (~~), 2 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Nottingham 3 Internet-Draft March 19, 2005 4 Expires: September 17, 2005 6 POST Once Exactly (POE) 7 draft-nottingham-http-poe-00 9 Status of this Memo 11 By submitting this Internet-Draft, I certify that any applicable 12 patent or other IPR claims of which I am aware have been disclosed, 13 and any of which I become aware will be disclosed, in accordance with 14 RFC 3668. 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 19 Internet-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 September 17, 2005. 34 Copyright Notice 36 Copyright (C) The Internet Society (2005). All Rights Reserved. 38 Abstract 40 This specification describes a pattern of use that allows HTTP 41 clients to automatically retry POST requests in a manner that assures 42 no unintended side effects will take place, and defines mechanisms to 43 allow implementations to automatically determine when such patterns 44 are supported. 46 Table of Contents 48 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 49 1.1 Notational Conventions . . . . . . . . . . . . . . . . . . 4 50 1.2 Relationships to Other Specifications . . . . . . . . . . 4 51 2. POE Resources . . . . . . . . . . . . . . . . . . . . . . . . 4 52 3. The POE-Links HTTP Response Header . . . . . . . . . . . . . . 5 53 4. The POE HTTP Request Header . . . . . . . . . . . . . . . . . 6 54 5. Example: Hyperlinking to a POE Resource . . . . . . . . . . . 6 55 6. Example: Manual Retry . . . . . . . . . . . . . . . . . . . . 7 56 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 57 8. Security Considerations . . . . . . . . . . . . . . . . . . . 8 58 9. Normative References . . . . . . . . . . . . . . . . . . . . . 8 59 Author's Address . . . . . . . . . . . . . . . . . . . . . . . 8 60 A. Implementation Notes . . . . . . . . . . . . . . . . . . . . . 8 61 B. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 9 62 Intellectual Property and Copyright Statements . . . . . . . . 10 64 1. Introduction 66 A very common sight on the Web is an admonishment to only "click 67 submit once." This is because there are some cases where an HTTP 68 request's status on the server is not known to the client; in some 69 instances, a delay in a response might be due to a temporary load on 70 the server that doesn't interfere with the request's processing, if 71 given enough time. In other cases, it could be caused by a server 72 failing, or a network problem; in these cases, the request may need 73 to be retried. 75 As a result, users (as well as automated agents) are placed in a 76 quandary; without a response, they don't know whether their request 77 has been successfully processed or not. 79 This isn't a problem for those HTTP requests that use idempotent 80 methods (e.g., GET and PUT); by definition, if the same request is 81 repeated (either by an impatient user pressing "reload" or an 82 automated agent timing out), there will be no additional side 83 effects. 85 However, non-idempotent HTTP methods, namely POST, may have 86 additional side effects when the same request is sent more than once. 87 To give a common example, POST is used by Web shopping baskets; when 88 the user wishes to finalise their purchase, a POST request is sent to 89 the server which processes the credit card transaction and fills the 90 order. 92 If the POST is sent twice, there is the danger of a duplicate order 93 being made. 95 RFC 2616, Section 8.1.4, states: 97 Non-idempotent methods or sequences MUST NOT be automatically 98 retried, although user agents MAY offer a human operator the 99 choice of retrying the request(s). Confirmation by user-agent 100 software with semantic understanding of the application MAY 101 substitute for user confirmation. 103 This specification provides applications with one means for gaining 104 such semantic understanding. Specifically, it describes a pattern of 105 use that allows clients to automatically retry POST requests in a 106 manner that assures no unintended side effects will take place. 108 It also defines HTTP header-fields to allow implementations to 109 automatically determine when such patterns are supported. These are 110 not an exclusive mechanism; other means for identifying POE resources 111 (e.g., format-specific markup on links in the entity body) may be 112 used. 114 Note that the pattern described here can also be used in situations 115 where user intervention is required. 117 1.1 Notational Conventions 119 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 120 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 121 document are to be interpreted as described in BCP 14, [RFC2119], as 122 scoped to those conformance targets. 124 This specification defines extensions to the HTTP/1.1 [RFC2616] 125 specification. It uses the augmented BNF of that document, and 126 relies on both the non-terminals defined in that document and other 127 aspects of the HTTP/1.1 specification. 129 1.2 Relationships to Other Specifications 131 There are a number of "reliable" application protocols layered on top 132 of HTTP. Generally, these operate by treating HTTP as a transport 133 protocol, rather than a transfer protocol; i.e., they seek to make 134 any message delivered by HTTP reliable. 136 This specification is more focused; it only attempts to provide 137 reliable POST semantics, because most other HTTP methods, being 138 idempotent, do not require reliable delivery of either the request or 139 the response, in an application-to-application sense. 141 This specification does not address methods other than POST; however, 142 similar techniques might be applied to other non-idempotent methods. 143 Likewise, it does not address non-idempotent sequences of requests, 144 or guaranteed ordered delivery of requests. 146 2. POE Resources 148 A POE resource is an HTTP [RFC2616] resource with particular 149 properties that clients can take advantage of to assure that POST 150 requests are made once exactly, without requiring user intervention. 152 A POE resource will respond to a POST request successfully exactly 153 once; that is, a server MUST NOT respond to a POST with a 2xx-series 154 status code if it has been successfully POSTed to at some point in 155 the past. 157 If a POE resource is subsequently POSTed to, it SHOULD respond with a 158 405 Method Not Allowed status code. Such a response MUST NOT include 159 POST in the content of the Allow header. 161 If the response to a POST to a POE resource contains an entity body, 162 that entity body SHOULD be available by GETting it from the resource, 163 to allow the client to retrieve the state of the response in the case 164 that a POST was successful, but the client did not receive the 165 response. 167 For example, if the POST response is cacheable, the same entity body 168 should be available through a subsequent GET; or, if the response has 169 a 303 See Other status code, subsequent GETs should redirect to the 170 indicated resource. 172 Note that a POE resource MAY require HTTP authentication, employ some 173 forms of HTTP redirection, etc. 175 When a client sends a POST request to a POE resource, it MAY 176 automatically (i.e., without user intervention) retry the request if 177 the response is indeterminate (e.g., the connection is lost or times 178 out). However, clients MUST NOT retry requests indefinitely. 180 User-agents SHOULD inform users that they are retrying a request 181 automatically, and MUST inform users if they stop retrying. 183 3. The POE-Links HTTP Response Header 185 The POE-Links HTTP header is an entity-header field whose field-value 186 is a comma-separated list of quoted URI-references [RFC3986] (without 187 fragment identifiers) that the origin server asserts to be POE 188 resources. 190 POE-Links = "POE-Links" ":" 1#( <"> POE-URI <"> ) 191 POE-URI = absolute-URI | ( relative-part [ "?" query ] ) 193 The contents of the POE-Links response header SHOULD correspond to 194 links found in the content of the response body. 196 [[ Some reviewers have suggested using the "Link" HTTP header with a 197 "rel" attribute instead of a special-purpose HTTP header, thereby 198 allowing link mechanisms in HTML to be used without further 199 specification. 201 Whilst this is attractive, it would require the Link header to be 202 standardized (it never was) and would introduce the potential need 203 for implementations to scan body content, whereas this is not 204 necessary in the current design (which does not preclude in-body 205 identification of POE resources, but does not encourage it). 206 Feedback on this design decision is sought.]] 208 4. The POE HTTP Request Header 210 The POE HTTP header is a request-header field whose field-value 211 indicates the version of POE that a client supports. 213 POE = "POE" ":" POE-version 214 POE-version = 1*DIGIT 216 The POE-version that identifies this specification is "1". 218 Clients SHOULD send the POE request header on all requests to inform 219 the decisions of the server. Servers MAY vary their content based 220 upon the presence of the POE header (e.g., changing the operation of 221 submit buttons, changing user instructions), and MAY use the POE 222 header to determine when to send a POE-Links response header. 224 5. Example: Hyperlinking to a POE Resource 226 A typical use case for POE is assuring that an order to a Web 227 shopping basket is only POSTed once, so that only one order is made. 228 Here, the client retrieves the state of the shopping basket to allow 229 the user to review it prior to checking out; 231 C: GET /accounts/bob/shopping_basket HTTP/1.1 232 Host: www.example.com 233 POE: 1 234 ... 236 The server returns a summary of the shopping basket in HTML, along 237 with a form that allows the user to check out. 239 S: 200 OK HTTP/1.1 240 POE-Links: "/accounts/bob/orders/12345" 241 ... 242
243 244
245 ... 247 When the user activates 'Submit Order 12345', it sends a POST request 248 to what has been identified as a POE resource; 250 C: POST /accounts/bob/orders/12345 HTTP/1.1 251 Host: www.example.com 252 POE: 1 253 ... 255 If the request is processed successfully, the server will respond 256 with 258 S: 200 OK HTTP/1.1 259 ... 261 If the client does not receive that response, it can retry the POST 262 request automatically; 264 C: POST /accounts/bob/orders/12345 265 Host: www.example.com 266 POE: 1 268 If the server had received and accepted the first request, it will 269 respond with 271 S: 405 Method Not Allowed HTTP/1.1 272 Allow: GET 273 ... 275 If the response status is "405 Method Not Allowed" the client can 276 infer that the earlier POST succeeded. A 2xx response indicates that 277 earlier POST did not succeed, but that this one has. When the client 278 receives either of these responses, it knows that the request has 279 been accepted, and it can stop retrying. 281 6. Example: Manual Retry 283 As noted, it is not necessary to use POE-specific HTTP headers in 284 conjunction with this pattern. As such, it is possible to assure 285 exactly one POST without special accommodation on the User-Agent, 286 because the user can retry requests as needed. 288 Operation is the same as in the previous example, with the caveat 289 that POE-specific HTTP headers are optional. If the user is unsure 290 whether the POST has succeeded (e.g., the browser "hangs"), they can 291 be instructed to do one of two things; 293 1. submit a GET to the POE resource to determine its state 294 2. re-submit their POST to the resource 296 Many implementations support one or both of these actions through 297 "reloading" the page, or re-requesting the page manually (through an 298 "address bar" UI widget or similar). 300 In either case, the server can return an unambiguous response as to 301 the success of the POST, along with a user-friendly message in the 302 entity body. 304 7. IANA Considerations 306 [[ TBD: header registration templates ]] 308 8. Security Considerations 310 Clients that indiscriminately retry requests may be used to 311 manufacture a denial-of-service attack on third party Web sites; 312 i.e., if a particular implementation retries aggressively or 313 indefinitely, an attack can be engineered whereby a number of clients 314 send a large number of requests to a particular site. This risk can 315 be mitigated by reasonable retry periods, backoff algorithms, a 316 reasonable maximum count for retries before manual intervention, and 317 selective treatment of links across administrative domains (e.g., 318 those with different authorities). 320 9 Normative References 322 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 323 Requirement Levels", BCP 14, RFC 2119, March 1997. 325 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 326 Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext 327 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 329 [RFC3986] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform 330 Resource Identifier (URI): Generic Syntax", STD 66, RFC 331 3986, January 2005. 333 Author's Address 335 Mark Nottingham 337 EMail: mnot@pobox.com 338 URI: http://www.mnot.net/ 340 Appendix A. Implementation Notes 342 Implementations of POE resources need to carefully consider how to 343 guarantee that only one POST request is allowed, whilst still 344 assuring that the desired side effects take place. In practice, this 345 means that the information needed to enact the side effects needs to 346 be stored durably and that the state of the resource needs to be 347 updated, all in an atomic fashion. 349 Careful consideration needs to be given to the generation of URIs for 350 POE resources, since they should never be reused. Long-lived, unique 351 identifiers can be generated by combining a date with one or more 352 other sources of context. For example, 354 http://www.example.com/users/bob/orders/2005/03/15/no2 356 encodes the date ("2005/03/15") along with a system-unique userid 357 ("bob") and an order number for that day (no2"), allowing the system 358 to generate unique identifiers without storing more information than 359 the userid and how many orders have been made in the current day. 361 Note that this is an example only; the structure of POE URIs, like 362 other URIs, is opaque to consumers in the absence of authoritative 363 information. 365 Appendix B. Acknowledgements 367 The author would like to thank Yves Lafon, Roy Fielding and Rohit 368 Khare for their feedback. None of the flaws in this specification 369 are theirs. 371 Intellectual Property Statement 373 The IETF takes no position regarding the validity or scope of any 374 Intellectual Property Rights or other rights that might be claimed to 375 pertain to the implementation or use of the technology described in 376 this document or the extent to which any license under such rights 377 might or might not be available; nor does it represent that it has 378 made any independent effort to identify any such rights. Information 379 on the procedures with respect to rights in RFC documents can be 380 found in BCP 78 and BCP 79. 382 Copies of IPR disclosures made to the IETF Secretariat and any 383 assurances of licenses to be made available, or the result of an 384 attempt made to obtain a general license or permission for the use of 385 such proprietary rights by implementers or users of this 386 specification can be obtained from the IETF on-line IPR repository at 387 http://www.ietf.org/ipr. 389 The IETF invites any interested party to bring to its attention any 390 copyrights, patents or patent applications, or other proprietary 391 rights that may cover technology that may be required to implement 392 this standard. Please address the information to the IETF at 393 ietf-ipr@ietf.org. 395 Disclaimer of Validity 397 This document and the information contained herein are provided on an 398 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 399 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 400 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 401 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 402 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 403 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 405 Copyright Statement 407 Copyright (C) The Internet Society (2005). This document is subject 408 to the rights, licenses and restrictions contained in BCP 78, and 409 except as set forth therein, the authors retain all their rights. 411 Acknowledgment 413 Funding for the RFC Editor function is currently provided by the 414 Internet Society.