provide a definition for partial PUT

draft-ietf-httpbis-semantics-latest.xml

@@ -4772,16 +4772,9 @@ Content-Encoding: gzip
    between the related resources.
 </t>
 <t>
-   An origin server that allows PUT on a given target resource &MUST; send a
-   <x:ref>400 (Bad Request)</x:ref> response to a PUT request that contains a
-   <x:ref>Content-Range</x:ref> header field (<xref target="field.content-range"/>), since
-   the content is likely to be a partial representation mistakenly PUT as
-   a full representation.
-   Partial content updates are possible by targeting a separately identified
-   resource with state that overlaps a portion of the larger resource, or by
-   using a different method that has been specifically defined for partial
-   updates (for example, the PATCH method defined in
-   <xref target="RFC5789"/>).
+   Some origin servers support use of the <x:ref>Content-Range</x:ref> header
+   field (<xref target="field.content-range"/>) as a request modifier to
+   perform a partial PUT, as described in <xref target="partial-PUT"/>.
 </t>
 <t>
    Responses to the PUT method are not cacheable. If a successful PUT request
@@ -7790,9 +7783,11 @@ bytes=500-700,601-999
    A proxy that receives such a message &SHOULD; forward it downstream.
 </t>
 <t>
+   Content-Range might also be sent as a request modifier to request a
+   partial PUT, as described in <xref target="partial-PUT"/>, based on private
+   agreements between client and origin server.
    A server &MUST; ignore a Content-Range header field received in a request
-   with a method for which Content-Range support is not defined. No request
-   method in this specification is defined to support Content-Range in a request.
+   with a method for which Content-Range support is not defined.
 </t>
 <t>
    For byte ranges, a sender &SHOULD; indicate the complete length of the
@@ -7870,6 +7865,38 @@ Content-Range: bytes 734-1233/1234
 </ul>
 </section>
 
+<section title="Partial PUT" anchor="partial-PUT">
+  <x:anchor-alias value="partial PUT"/>
+  <iref primary="false" item="Fields" subitem="Content-Range"/><iref primary="false" item="Header Fields" subitem="Content-Range"/><iref primary="false" item="Content-Range header field"/>
+<t>
+   Some origin servers support <x:ref>PUT</x:ref> of a partial representation
+   when a <x:ref>Content-Range</x:ref> header field
+   (<xref target="field.content-range"/>) is sent in the request, though
+   such support is inconsistent and depends on private agreements with
+   user agents. In general, it requests that the state of the
+   <x:ref>target resource</x:ref> be partly replaced with the enclosed content
+   at an offset and length indicated by the Content-Range value, where the
+   offset is relative to the current selected representation.
+</t>
+<t>
+   An origin server &SHOULD; respond with a <x:ref>400 (Bad Request)</x:ref>
+   status code if it receives <x:ref>Content-Range</x:ref> on a PUT for a
+   target resource that does not support partial PUT requests.
+</t>
+<t>
+   Partial PUT is not backwards compatible with the original definition of PUT.
+   It may result in the content being written as a complete replacement for the
+   current representation.
+</t>
+<t>
+   Partial resource updates are also possible by targeting a separately
+   identified resource with state that overlaps or extends a portion of the
+   larger resource, or by using a different method that has been specifically
+   defined for partial updates (for example, the PATCH method defined in
+   <xref target="RFC5789"/>).
+</t>
+</section>
+
 <section title="Media Type multipart/byteranges" anchor="multipart.byteranges">
 <iref item="Media Type" subitem="multipart/byteranges" primary="true"/>
 <iref item="multipart/byteranges Media Type" primary="true"/>
@@ -12914,6 +12941,11 @@ Content-Type: text/plain
    applicability.
    (<xref target="status.422"/>)
 </t>
+<t>
+   Allowed use of the <x:ref>Content-Range</x:ref> header field
+   (<xref target="field.content-range"/>) as a request modifier on PUT.
+   (<xref target="PUT"/>)
+</t>
 </section>
 
 <section title="Changes from RFC 7232" anchor="changes.from.rfc.7232">
@@ -12961,6 +12993,12 @@ Content-Type: text/plain
    It is now possible to define Range handling on extension methods.
    (<xref target="field.range"/>)
 </t>
+<t>
+   Described use of the <x:ref>Content-Range</x:ref> header field
+   (<xref target="field.content-range"/>) as a request modifier to perform a
+   partial PUT.
+   (<xref target="partial-PUT"/>)
+</t>
 </section>
 
 <section title="Changes from RFC 7235" anchor="changes.from.rfc.7235">
@@ -13272,7 +13310,7 @@ Content-Type: text/plain
 <ul x:when-empty="None yet.">
   <li>In <xref target="field.accept"/>, remove the unused "accept parameters" (<eref target="https://github.com/httpwg/http-core/issues/568"/>)</li>
   <li>In <xref target="history.and.evolution"/>, mention that RFC 1945 describes HTTP/0.9 as well (<eref target="https://github.com/httpwg/http-core/issues/614"/>)</li>
-  <li>In <xref target="field.content-range"/>, clarify that Content-Range is to be ignored in requests (<eref target="https://github.com/httpwg/http-core/issues/618"/>)</li>
+  <li>In <xref target="partial-PUT"/>, describe non-standard use of the <x:ref>Content-Range</x:ref> header field (<xref target="field.content-range"/>) as a request modifier to perform a partial PUT (<eref target="https://github.com/httpwg/http-core/issues/618"/>)</li>
   <li>In <xref target="status.421"/>, import the 421 (Misdirected Request) status code from <xref target="RFC7540"/> (<eref target="https://github.com/httpwg/http-core/issues/622"/>)</li>
   <li>In <xref target="length-requirements"/>, rephrase the actual recipient parsing requirements (<eref target="https://github.com/httpwg/http-core/issues/634"/>)</li>
   <li>In <xref target="considerations.for.new.methods"/>, mention request target forms in considerations for new methods (<eref target="https://github.com/httpwg/http-core/issues/636"/>)</li>