idnits 2.17.1 draft-nottingham-http-patch-status-00.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 draft header indicates that this document updates RFC5789, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: o The value of the Content-Length header field MUST be adjusted to reflect the length of the patched response body. o The ETag header field MUST be replaced (or inserted, if not present) with the value of the Patched header field in the 2NN response (if present). o Other header fields in the 2NN response MUST update the stored response, in the same manner as described in [I-D.ietf-httpbis-p6-cache], Section 4.3.4. However, the following fields MUST not be updated: Content-Type, Patched. (Using the creation date from RFC5789, updated by this document, for RFC5378 checks: 2003-11-18) -- 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 14, 2014) is 3693 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) == Outdated reference: A later version (-17) exists of draft-ietf-httpbis-http2-10 Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 3 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 14, 2014 4 Updates: 5789 (if approved) 5 Intended status: Informational 6 Expires: September 15, 2014 8 The 2NN Patch HTTP Status Code 9 draft-nottingham-http-patch-status-00 11 Abstract 13 This document specifies the 2NN Patch HTTP status code to allow 14 servers to perform partial updates of stored responses in client 15 caches. 17 Status of this Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on September 15, 2014. 34 Copyright Notice 36 Copyright (c) 2014 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 52 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 53 2. The 2NN Patch Status Code . . . . . . . . . . . . . . . . . . . 3 54 2.1. The Patched Header Field . . . . . . . . . . . . . . . . . 5 55 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 5 56 3.1. 2NN Patch HTTP Status Code . . . . . . . . . . . . . . . . 5 57 3.2. Accept-Patch Header Field . . . . . . . . . . . . . . . . . 5 58 3.3. Patched Header Field . . . . . . . . . . . . . . . . . . . 5 59 4. Security Considerations . . . . . . . . . . . . . . . . . . . . 5 60 5. References . . . . . . . . . . . . . . . . . . . . . . . . . . 6 61 5.1. Normative References . . . . . . . . . . . . . . . . . . . 6 62 5.2. Informative References . . . . . . . . . . . . . . . . . . 6 63 Appendix A. 2NN Patch and HTTP/2 Server Push . . . . . . . . . . . 6 64 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 8 66 1. Introduction 68 [RFC5246] defines the HTTP PATCH method as a means of selectively 69 updating the state of a resource on a server. This document 70 complements that specification by specifying a means for a server to 71 selectively update a stored response on a client - usually, in a 72 cache [I-D.ietf-httpbis-p6-cache]. 74 1.1. Notational Conventions 76 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 77 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 78 document are to be interpreted as described in [RFC2119]. 80 This document uses the Augmented BNF defined by [RFC5246], and 81 additionally uses the entity-tag rule defined in 82 [I-D.ietf-httpbis-p4-conditional]. 84 2. The 2NN Patch Status Code 86 The 2NN (Patch) status code allows a response to patch a stored 87 response in a cache, by reusing the patch formats of [RFC5789]. In 88 some sense, it is the complement of the HTTP PATCH request method. 90 TODO: is this a 2NN or 3xx? 92 Clients can advertise support for 2NN (Patch), along with the patch 93 formats supported in it, by using the Accept-Patch header field in 94 requests. For example: 96 GET /foo HTTP/1.1 97 Host: api.example.com 98 Accept-Patch: application/patch+json 99 If-None-Match: "abcdef", "ghijkl" 100 User-Agent: Example/1.0 102 If the server can generate a patch for one of the entity tags 103 provided in If-None-Match, in one of the accepted patch formats, it 104 can generate a 2NN (Patch) response: 106 HTTP/1.1 2NN Patch 107 Content-Type: application/patch+json 108 Patched: "ghijkl" 109 ETag: "mnopqrs" 111 The entity tag carried by the ETag header field is associated with 112 the selected representation - i.e., the stored response after the 113 patch is applied. 115 The Patched header field identifies the representation to apply the 116 patch to, as indicated by the entity-tag provided in If-None-Match 117 request header field; see Section 2.1. 119 Therefore, in the example above, the stored response "ghijkl" is 120 being patched, with the resulting stored response having the entity 121 tag "mnopqrs". 123 Application of a 2NN (Patch) response happens in a manner very 124 similar to the process for freshening a stored response by applying a 125 304 (Not Modified), as described in [I-D.ietf-httpbis-p6-cache], 126 Section 4.3.4. 128 In particular, the stored response to apply a 2NN (Patch) response to 129 is the same; if none is selected, the patch fails, and the client MAY 130 resubmit the request without an Accept-Patch header field, in order 131 to get a full response. 133 If a stored response is selected, clients MUST update it in the 134 following manner: 136 o The value of the Content-Length header field MUST be adjusted to 137 reflect the length of the patched response body. 138 o The ETag header field MUST be replaced (or inserted, if not 139 present) with the value of the Patched header field in the 2NN 140 response (if present). 141 o Other header fields in the 2NN response MUST update the stored 142 response, in the same manner as described in 143 [I-D.ietf-httpbis-p6-cache], Section 4.3.4. However, the 144 following fields MUST not be updated: Content-Type, Patched. 146 The 2NN (Patch) status code SHOULD NOT be generated if the request 147 did not include If-None-Match, unless conflicts are handled by the 148 patch format itself (e.g., allowing a patch to append to an array), 149 or externally. 151 Intermediaries MAY append the Accept-Patch header field to requests, 152 or append new values to it, if they will process 2NN responses for 153 the patch format(s) they add. Likewise, intermediaries MAY generate 154 2NN (Patch) responses under the conditions specified here. 156 The 2NN status code is not cacheable by default, and is not a 157 representation of any identified resource. 159 2.1. The Patched Header Field 161 The Patched header field identifies the stored representation that a 162 patch is to be applied to in a 2NN (Patch) response. 164 Patched = entity-tag 166 3. IANA Considerations 168 3.1. 2NN Patch HTTP Status Code 170 This document defines the 2NN (Patch) HTTP status code, as per 171 [I-D.ietf-httpbis-p2-semantics]. 173 o Status Code (3 digits): TBD 174 o Short Description: Patch 175 o Pointer to specification text: Section 2 177 3.2. Accept-Patch Header Field 179 This document updates [RFC5789] to allow the Accept-Patch HTTP header 180 field to be used in requests, which ought to be reflected in the 181 registry. 183 3.3. Patched Header Field 185 This document defines a new HTTP header, field, "Patched", to be 186 registered in the Permanent Message Header Registry, as per 187 [RFC3864]. 189 o Header field name: Patched 190 o Applicable protocol: http 191 o Status: standard 192 o Author/Change controller: IETF 193 o Specification document(s): [this document] 194 o Related information: 196 4. Security Considerations 198 2NN (Patch) can be brittle when the application of a patch fails, 199 because the client has no way to report the failure of a patch to the 200 server. This assymetry might be exploited by an attacker, but can be 201 mitigated by judicious use of strong ETags. 203 Some patch formats might have additional security considerations. 205 5. References 207 5.1. Normative References 209 [I-D.ietf-httpbis-p4-conditional] 210 Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 211 (HTTP/1.1): Conditional Requests", 212 draft-ietf-httpbis-p4-conditional-26 (work in progress), 213 February 2014. 215 [I-D.ietf-httpbis-p6-cache] 216 Fielding, R., Nottingham, M., and J. Reschke, "Hypertext 217 Transfer Protocol (HTTP/1.1): Caching", 218 draft-ietf-httpbis-p6-cache-26 (work in progress), 219 February 2014. 221 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 222 Requirement Levels", BCP 14, RFC 2119, March 1997. 224 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 225 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 227 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 228 RFC 5789, March 2010. 230 5.2. Informative References 232 [I-D.ietf-httpbis-http2] 233 Belshe, M., Peon, R., and M. Thomson, "Hypertext Transfer 234 Protocol version 2", draft-ietf-httpbis-http2-10 (work in 235 progress), February 2014. 237 [I-D.ietf-httpbis-p2-semantics] 238 Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 239 (HTTP/1.1): Semantics and Content", 240 draft-ietf-httpbis-p2-semantics-26 (work in progress), 241 February 2014. 243 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 244 Procedures for Message Header Fields", BCP 90, RFC 3864, 245 September 2004. 247 Appendix A. 2NN Patch and HTTP/2 Server Push 249 In HTTP/2 [I-D.ietf-httpbis-http2], it is possible to "push" a 250 request/response pair into a client's cache. 2NN (Patch) can be used 251 with this mechanism to perform partial updates on stored responses. 253 For example, if a cache has this response stored for 254 "http://example.com/list": 256 200 OK 257 Content-Type: application/json 258 Cache-Control: max-age=3600 259 ETag: "aaa" 261 { "items": ["a"]} 263 A HTTP/2 server could partially update it by sending the request/ 264 response pair (using pseudo-HTTP/1 syntax for purposes of 265 illustration): 267 GET /list 268 Host: example.com 269 If-None-Match: "aaa" 270 Accept-Patch: application/patch+json 272 2NN Patch 273 Content-Type: application/patch+json 274 ETag: "aab" 275 Patched: "aaa" 277 [ 278 { "op": "add", "path": "/items/1", "value": "b" } 279 ] 281 Once the patch is applied, the stored response is now: 283 200 OK 284 Content-Type: application/json 285 Cache-Control: max-age=3600 286 ETag: "aab" 288 { "items": ["a", "b"]} 290 Note that this approach requires a server pushing partial responses 291 to know the stored response's ETag, since the client cache will 292 silently ignore the push if it does not match that provided in 293 "Patched". Likewise, clients that are not conformant to this 294 specification will silently drop such pushes, since the status code 295 is not recognised (as per [I-D.ietf-httpbis-p6-cache]). 297 However, it is possible to do some partial updates without strong 298 consistency. For example, if the stored response is as above, and 299 the server simply wishes to append an value to an array, without 300 regard for the current content of the array (because, presumably, 301 ordering of its content is not important), it can push: 303 GET /list 304 Host: example.com 305 Accept-Patch: application/patch+json 307 2NN Patch 308 Content-Type: application/patch+json 310 [ 311 { "op": "add", "path": "/items/-", "value": "b" } 312 ] 314 Here, the resulting document would be as above, but since entity tags 315 are not provided, the operation will succeed as long as the patch 316 application succeeds. 318 Author's Address 320 Mark Nottingham 322 Email: mnot@mnot.net 323 URI: http://www.mnot.net/