doc: Add RFC documents

1 files changed, 563 insertions, 0 deletions

diff --git a/doc/rfc/rfc5789.txt b/doc/rfc/rfc5789.txt
new file mode 100644
index 0000000..7a2c061
--- /dev/null
+++ b/doc/rfc/rfc5789.txt
@@ -0,0 +1,563 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF)                      L. Dusseault
+Request for Comments: 5789                                    Linden Lab
+Category: Standards Track                                       J. Snell
+ISSN: 2070-1721                                               March 2010
+
+
+                         PATCH Method for HTTP
+
+Abstract
+
+   Several applications extending the Hypertext Transfer Protocol (HTTP)
+   require a feature to do partial resource modification.  The existing
+   HTTP PUT method only allows a complete replacement of a document.
+   This proposal adds a new HTTP method, PATCH, to modify an existing
+   HTTP resource.
+
+Status of This Memo
+
+   This is an Internet Standards Track document.
+
+   This document is a product of the Internet Engineering Task Force
+   (IETF).  It represents the consensus of the IETF community.  It has
+   received public review and has been approved for publication by the
+   Internet Engineering Steering Group (IESG).  Further information on
+   Internet Standards is available in Section 2 of RFC 5741.
+
+   Information about the current status of this document, any errata,
+   and how to provide feedback on it may be obtained at
+   http://www.rfc-editor.org/info/rfc5789.
+
+Copyright Notice
+
+   Copyright (c) 2010 IETF Trust and the persons identified as the
+   document authors.  All rights reserved.
+
+   This document is subject to BCP 78 and the IETF Trust's Legal
+   Provisions Relating to IETF Documents
+   (http://trustee.ietf.org/license-info) in effect on the date of
+   publication of this document.  Please review these documents
+   carefully, as they describe your rights and restrictions with respect
+   to this document.  Code Components extracted from this document must
+   include Simplified BSD License text as described in Section 4.e of
+   the Trust Legal Provisions and are provided without warranty as
+   described in the Simplified BSD License.
+
+
+
+
+
+
+
+Dusseault & Snell            Standards Track                    [Page 1]
+
+RFC 5789                       HTTP PATCH                     March 2010
+
+
+Table of Contents
+
+   1. Introduction ....................................................2
+   2. The PATCH Method ................................................2
+      2.1. A Simple PATCH Example .....................................4
+      2.2. Error Handling .............................................5
+   3. Advertising Support in OPTIONS ..................................7
+      3.1. The Accept-Patch Header ....................................7
+      3.2. Example OPTIONS Request and Response .......................7
+   4. IANA Considerations .............................................8
+      4.1. The Accept-Patch Response Header ...........................8
+   5. Security Considerations .........................................8
+   6. References ......................................................9
+      6.1. Normative References .......................................9
+      6.2. Informative References .....................................9
+   Appendix A.  Acknowledgements .....................................10
+
+1.  Introduction
+
+   This specification defines the new HTTP/1.1 [RFC2616] method, PATCH,
+   which is used to apply partial modifications to a resource.
+
+   A new method is necessary to improve interoperability and prevent
+   errors.  The PUT method is already defined to overwrite a resource
+   with a complete new body, and cannot be reused to do partial changes.
+   Otherwise, proxies and caches, and even clients and servers, may get
+   confused as to the result of the operation.  POST is already used but
+   without broad interoperability (for one, there is no standard way to
+   discover patch format support).  PATCH was mentioned in earlier HTTP
+   specifications, but not completely defined.
+
+   In this document, the key words "MUST", "MUST NOT", "REQUIRED",
+   "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
+   and "OPTIONAL" are to be interpreted as described in [RFC2119].
+
+   Furthermore, this document uses the ABNF syntax defined in Section
+   2.1 of [RFC2616].
+
+2.  The PATCH Method
+
+   The PATCH method requests that a set of changes described in the
+   request entity be applied to the resource identified by the Request-
+   URI.  The set of changes is represented in a format called a "patch
+   document" identified by a media type.  If the Request-URI does not
+   point to an existing resource, the server MAY create a new resource,
+   depending on the patch document type (whether it can logically modify
+   a null resource) and permissions, etc.
+
+
+
+
+Dusseault & Snell            Standards Track                    [Page 2]
+
+RFC 5789                       HTTP PATCH                     March 2010
+
+
+   The difference between the PUT and PATCH requests is reflected in the
+   way the server processes the enclosed entity to modify the resource
+   identified by the Request-URI.  In a PUT request, the enclosed entity
+   is considered to be a modified version of the resource stored on the
+   origin server, and the client is requesting that the stored version
+   be replaced.  With PATCH, however, the enclosed entity contains a set
+   of instructions describing how a resource currently residing on the
+   origin server should be modified to produce a new version.  The PATCH
+   method affects the resource identified by the Request-URI, and it
+   also MAY have side effects on other resources; i.e., new resources
+   may be created, or existing ones modified, by the application of a
+   PATCH.
+
+   PATCH is neither safe nor idempotent as defined by [RFC2616], Section
+   9.1.
+
+   A PATCH request can be issued in such a way as to be idempotent,
+   which also helps prevent bad outcomes from collisions between two
+   PATCH requests on the same resource in a similar time frame.
+   Collisions from multiple PATCH requests may be more dangerous than
+   PUT collisions because some patch formats need to operate from a
+   known base-point or else they will corrupt the resource.  Clients
+   using this kind of patch application SHOULD use a conditional request
+   such that the request will fail if the resource has been updated
+   since the client last accessed the resource.  For example, the client
+   can use a strong ETag [RFC2616] in an If-Match header on the PATCH
+   request.
+
+   There are also cases where patch formats do not need to operate from
+   a known base-point (e.g., appending text lines to log files, or non-
+   colliding rows to database tables), in which case the same care in
+   client requests is not needed.
+
+   The server MUST apply the entire set of changes atomically and never
+   provide (e.g., in response to a GET during this operation) a
+   partially modified representation.  If the entire patch document
+   cannot be successfully applied, then the server MUST NOT apply any of
+   the changes.  The determination of what constitutes a successful
+   PATCH can vary depending on the patch document and the type of
+   resource(s) being modified.  For example, the common 'diff' utility
+   can generate a patch document that applies to multiple files in a
+   directory hierarchy.  The atomicity requirement holds for all
+   directly affected files.  See "Error Handling", Section 2.2, for
+   details on status codes and possible error conditions.
+
+   If the request passes through a cache and the Request-URI identifies
+   one or more currently cached entities, those entries SHOULD be
+   treated as stale.  A response to this method is only cacheable if it
+
+
+
+Dusseault & Snell            Standards Track                    [Page 3]
+
+RFC 5789                       HTTP PATCH                     March 2010
+
+
+   contains explicit freshness information (such as an Expires header or
+   "Cache-Control: max-age" directive) as well as the Content-Location
+   header matching the Request-URI, indicating that the PATCH response
+   body is a resource representation.  A cached PATCH response can only
+   be used to respond to subsequent GET and HEAD requests; it MUST NOT
+   be used to respond to other methods (in particular, PATCH).
+
+   Note that entity-headers contained in the request apply only to the
+   contained patch document and MUST NOT be applied to the resource
+   being modified.  Thus, a Content-Language header could be present on
+   the request, but it would only mean (for whatever that's worth) that
+   the patch document had a language.  Servers SHOULD NOT store such
+   headers except as trace information, and SHOULD NOT use such header
+   values the same way they might be used on PUT requests.  Therefore,
+   this document does not specify a way to modify a document's Content-
+   Type or Content-Language value through headers, though a mechanism
+   could well be designed to achieve this goal through a patch document.
+
+   There is no guarantee that a resource can be modified with PATCH.
+   Further, it is expected that different patch document formats will be
+   appropriate for different types of resources and that no single
+   format will be appropriate for all types of resources.  Therefore,
+   there is no single default patch document format that implementations
+   are required to support.  Servers MUST ensure that a received patch
+   document is appropriate for the type of resource identified by the
+   Request-URI.
+
+   Clients need to choose when to use PATCH rather than PUT.  For
+   example, if the patch document size is larger than the size of the
+   new resource data that would be used in a PUT, then it might make
+   sense to use PUT instead of PATCH.  A comparison to POST is even more
+   difficult, because POST is used in widely varying ways and can
+   encompass PUT and PATCH-like operations if the server chooses.  If
+   the operation does not modify the resource identified by the Request-
+   URI in a predictable way, POST should be considered instead of PATCH
+   or PUT.
+
+2.1.  A Simple PATCH Example
+
+   PATCH /file.txt HTTP/1.1
+   Host: www.example.com
+   Content-Type: application/example
+   If-Match: "e0023aa4e"
+   Content-Length: 100
+
+   [description of changes]
+
+
+
+
+
+Dusseault & Snell            Standards Track                    [Page 4]
+
+RFC 5789                       HTTP PATCH                     March 2010
+
+
+   This example illustrates use of a hypothetical patch document on an
+   existing resource.
+
+   Successful PATCH response to existing text file:
+
+   HTTP/1.1 204 No Content
+   Content-Location: /file.txt
+   ETag: "e0023aa4f"
+
+   The 204 response code is used because the response does not carry a
+   message body (which a response with the 200 code would have).  Note
+   that other success codes could be used as well.
+
+   Furthermore, the ETag response header field contains the ETag for the
+   entity created by applying the PATCH, available at
+   http://www.example.com/file.txt, as indicated by the Content-Location
+   response header field.
+
+2.2.  Error Handling
+
+   There are several known conditions under which a PATCH request can
+   fail.
+
+   Malformed patch document:  When the server determines that the patch
+      document provided by the client is not properly formatted, it
+      SHOULD return a 400 (Bad Request) response.  The definition of
+      badly formatted depends on the patch document chosen.
+
+   Unsupported patch document:  Can be specified using a 415
+      (Unsupported Media Type) response when the client sends a patch
+      document format that the server does not support for the resource
+      identified by the Request-URI.  Such a response SHOULD include an
+      Accept-Patch response header as described in Section 3.1 to notify
+      the client what patch document media types are supported.
+
+   Unprocessable request:  Can be specified with a 422 (Unprocessable
+      Entity) response ([RFC4918], Section 11.2) when the server
+      understands the patch document and the syntax of the patch
+      document appears to be valid, but the server is incapable of
+      processing the request.  This might include attempts to modify a
+      resource in a way that would cause the resource to become invalid;
+      for instance, a modification to a well-formed XML document that
+      would cause it to no longer be well-formed.  There may also be
+      more specific errors like "Conflicting State" that could be
+      signaled with this status code, but the more specific error would
+      generally be more helpful.
+
+
+
+
+
+Dusseault & Snell            Standards Track                    [Page 5]
+
+RFC 5789                       HTTP PATCH                     March 2010
+
+
+   Resource not found:  Can be specified with a 404 (Not Found) status
+      code when the client attempted to apply a patch document to a non-
+      existent resource, but the patch document chosen cannot be applied
+      to a non-existent resource.
+
+   Conflicting state:  Can be specified with a 409 (Conflict) status
+      code when the request cannot be applied given the state of the
+      resource.  For example, if the client attempted to apply a
+      structural modification and the structures assumed to exist did
+      not exist (with XML, a patch might specify changing element 'foo'
+      to element 'bar' but element 'foo' might not exist).
+
+   Conflicting modification:  When a client uses either the If-Match or
+      If-Unmodified-Since header to define a precondition, and that
+      precondition failed, then the 412 (Precondition Failed) error is
+      most helpful to the client.  However, that response makes no sense
+      if there was no precondition on the request.  In cases when the
+      server detects a possible conflicting modification and no
+      precondition was defined in the request, the server can return a
+      409 (Conflict) response.
+
+   Concurrent modification:  Some applications of PATCH might require
+      the server to process requests in the order in which they are
+      received.  If a server is operating under those restrictions, and
+      it receives concurrent requests to modify the same resource, but
+      is unable to queue those requests, the server can usefully
+      indicate this error by using a 409 (Conflict) response.
+
+   Note that the 409 Conflict response gives reasonably consistent
+   information to clients.  Depending on the application and the nature
+   of the patch format, the client might be able to reissue the request
+   as is (e.g., an instruction to append a line to a log file), have to
+   retrieve the resource content to recalculate a patch, or have to fail
+   the operation.
+
+   Other HTTP status codes can also be used under the appropriate
+   circumstances.
+
+   The entity body of error responses SHOULD contain enough information
+   to communicate the nature of the error to the client.  The content-
+   type of the response entity can vary across implementations.
+
+
+
+
+
+
+
+
+
+
+Dusseault & Snell            Standards Track                    [Page 6]
+
+RFC 5789                       HTTP PATCH                     March 2010
+
+
+3.  Advertising Support in OPTIONS
+
+   A server can advertise its support for the PATCH method by adding it
+   to the listing of allowed methods in the "Allow" OPTIONS response
+   header defined in HTTP/1.1.  The PATCH method MAY appear in the
+   "Allow" header even if the Accept-Patch header is absent, in which
+   case the list of allowed patch documents is not advertised.
+
+3.1.  The Accept-Patch Header
+
+   This specification introduces a new response header Accept-Patch used
+   to specify the patch document formats accepted by the server.
+   Accept-Patch SHOULD appear in the OPTIONS response for any resource
+   that supports the use of the PATCH method.  The presence of the
+   Accept-Patch header in response to any method is an implicit
+   indication that PATCH is allowed on the resource identified by the
+   Request-URI.  The presence of a specific patch document format in
+   this header indicates that that specific format is allowed on the
+   resource identified by the Request-URI.
+
+   Accept-Patch = "Accept-Patch" ":" 1#media-type
+
+   The Accept-Patch header specifies a comma-separated listing of media-
+   types (with optional parameters) as defined by [RFC2616], Section
+   3.7.
+
+   Example:
+
+   Accept-Patch: text/example;charset=utf-8
+
+3.2.  Example OPTIONS Request and Response
+
+   [request]
+
+   OPTIONS /example/buddies.xml HTTP/1.1
+   Host: www.example.com
+
+   [response]
+
+   HTTP/1.1 200 OK
+   Allow: GET, PUT, POST, OPTIONS, HEAD, DELETE, PATCH
+   Accept-Patch: application/example, text/example
+
+   The examples show a server that supports PATCH generally using two
+   hypothetical patch document formats.
+
+
+
+
+
+
+Dusseault & Snell            Standards Track                    [Page 7]
+
+RFC 5789                       HTTP PATCH                     March 2010
+
+
+4.  IANA Considerations
+
+4.1.  The Accept-Patch Response Header
+
+   The Accept-Patch response header has been added to the permanent
+   registry (see [RFC3864]).
+
+   Header field name:  Accept-Patch
+
+   Applicable Protocol:  HTTP
+
+   Author/Change controller:  IETF
+
+   Specification document:  this specification
+
+5.  Security Considerations
+
+   The security considerations for PATCH are nearly identical to the
+   security considerations for PUT ([RFC2616], Section 9.6).  These
+   include authorizing requests (possibly through access control and/or
+   authentication) and ensuring that data is not corrupted through
+   transport errors or through accidental overwrites.  Whatever
+   mechanisms are used for PUT can be used for PATCH as well.  The
+   following considerations apply especially to PATCH.
+
+   A document that is patched might be more likely to be corrupted than
+   a document that is overridden in entirety, but that concern can be
+   addressed through the use of mechanisms such as conditional requests
+   using ETags and the If-Match request header as described in
+   Section 2.  If a PATCH request fails, the client can issue a GET
+   request to the resource to see what state it is in.  In some cases,
+   the client might be able to check the contents of the resource to see
+   if the PATCH request can be resent, but in other cases, the attempt
+   will just fail and/or a user will have to verify intent.  In the case
+   of a failure of the underlying transport channel, where a PATCH
+   response is not received before the channel fails or some other
+   timeout happens, the client might have to issue a GET request to see
+   whether the request was applied.  The client might want to ensure
+   that the GET request bypasses caches using mechanisms described in
+   HTTP specifications (see, for example, Section 13.1.6 of [RFC2616]).
+
+   Sometimes an HTTP intermediary might try to detect viruses being sent
+   via HTTP by checking the body of the PUT/POST request or GET
+   response.  The PATCH method complicates such watch-keeping because
+   neither the source document nor the patch document might be a virus,
+   yet the result could be.  This security consideration is not
+
+
+
+
+
+Dusseault & Snell            Standards Track                    [Page 8]
+
+RFC 5789                       HTTP PATCH                     March 2010
+
+
+   materially different from those already introduced by byte-range
+   downloads, downloading patch documents, uploading zipped (compressed)
+   files, and so on.
+
+   Individual patch documents will have their own specific security
+   considerations that will likely vary depending on the types of
+   resources being patched.  The considerations for patched binary
+   resources, for instance, will be different than those for patched XML
+   documents.  Servers MUST take adequate precautions to ensure that
+   malicious clients cannot consume excessive server resources (e.g.,
+   CPU, disk I/O) through the client's use of PATCH.
+
+6.  References
+
+6.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.
+
+   [RFC3864]  Klyne, G., Nottingham, M., and J. Mogul, "Registration
+              Procedures for Message Header Fields", BCP 90, RFC 3864,
+              September 2004.
+
+6.2.  Informative References
+
+   [RFC4918]  Dusseault, L., "HTTP Extensions for Web Distributed
+              Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault & Snell            Standards Track                    [Page 9]
+
+RFC 5789                       HTTP PATCH                     March 2010
+
+
+Appendix A.  Acknowledgements
+
+   PATCH is not a new concept, it first appeared in HTTP in drafts of
+   version 1.1 written by Roy Fielding and Henrik Frystyk and also
+   appears in Section 19.6.1.1 of RFC 2068.
+
+   Thanks to Adam Roach, Chris Sharp, Julian Reschke, Geoff Clemm, Scott
+   Lawrence, Jeffrey Mogul, Roy Fielding, Greg Stein, Jim Luther, Alex
+   Rousskov, Jamie Lokier, Joe Hildebrand, Mark Nottingham, Michael
+   Balloni, Cyrus Daboo, Brian Carpenter, John Klensin, Eliot Lear, SM,
+   and Bernie Hoeneisen for review and advice on this document.  In
+   particular, Julian Reschke did repeated reviews, made many useful
+   suggestions, and was critical to the publication of this document.
+
+Authors' Addresses
+
+   Lisa Dusseault
+   Linden Lab
+   945 Battery Street
+   San Francisco, CA  94111
+   USA
+
+   EMail: lisa.dusseault@gmail.com
+
+
+   James M. Snell
+
+   EMail: jasnell@gmail.com
+   URI:   http://www.snellspace.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault & Snell            Standards Track                   [Page 10]
+