# HTTP PATCH support

This is a markdown translation of the document at
[http://sabre.io/dav/http-patch/](http://sabre.io/dav/http-patch/)
[© 2018 fruux GmbH](https://fruux.com/)

The `Sabre\\DAV\\PartialUpdate\\Plugin` from the Sabre DAV library provides
support for the HTTP PATCH method [RFC5789](http://tools.ietf.org/html/rfc5789).
This allows you to update just a portion of a file, or append to a file.

This document can be used as a spec for other implementors. There is some
DAV-specific stuff in this document, but only in relation to the OPTIONS
request.

## A sample request

```
PATCH /file.txt
Content-Length: 4
Content-Type: application/x-sabredav-partialupdate
X-Update-Range: bytes=3-6

ABCD
```

This request updates 'file.txt', specifically the bytes 3-6 (inclusive) to
`ABCD`.

If you just want to append to an existing file, use the following syntax:

```
PATCH /file.txt
Content-Length: 4
Content-Type: application/x-sabredav-partialupdate
X-Update-Range: append

1234
```

The last request adds 4 bytes to the bottom of the file.

## The rules

- The `Content-Length` header is required.
- `X-Update-Range` is also required.
- The `bytes` value is the exact same as the HTTP Range header. The two numbers
  are inclusive (so `3-6` means that bytes 3,4,5 and 6 will be updated).
- Just like the HTTP Range header, the specified bytes is a 0-based index.
- The `application/x-sabredav-partialupdate` must also be specified.
- The end-byte is optional.
- The start-byte cannot be omitted.
- If the start byte is negative, it's calculated from the end of the file. So
  `-1` will update the last byte in the file.
- Use `X-Update-Range: append` to add to the end of the file.
- Neither the start, nor the end-byte have to be within the file's current size.
- If the start-byte is beyond the file's current length, the space in between
  will be filled with NULL bytes (`0x00`).
- The specification currently does not support multiple ranges.
- If both start and end offsets are given, than both must be non-negative, and
  the end offset must be greater or equal to the start offset.

## More examples

The following table illustrates most types of requests and what the end-result
of them will be.

It is assumed that the input file contains `1234567890`, and the request body
always contains 4 dashes (`----`).

X-Update-Range header | Result
--------------------- | -------
`bytes=0-3`           | `----567890`
`bytes=1-4`           | `1----67890`
`bytes=0-`            | `----567890`
`bytes=-4`            | `123456----`
`bytes=-2`            | `12345678----`
`bytes=2-`            | `12----7890`
`bytes=12-`           | `1234567890..----`
`append`              | `1234567890----`

Please note that in the `bytes=12-` example, we used dots (`.`) to represent
what are actually `NULL` bytes (so `0x00`). The null byte is not printable.

## Status codes

### The following status codes should be used:

Status code | Reason
----------- | ------
200 or 204  | When the operation was successful
400         | Invalid `X-Update-Range` header
411         | `Content-Length` header was not provided
415         | Unrecognized content-type, should be `application/x-sabredav-partialupdate`
416         | If there was something wrong with the bytes, such as a `Content-Length` not matching with what was sent as the start and end bytes, or an end byte being lower than the start byte.

## OPTIONS

If you want to be compliant with SabreDAV's implementation of PATCH, you must
also return 'sabredav-partialupdate' in the 'DAV:' header:

```
HTTP/1.1 204 No Content
DAV: 1, 2, 3, sabredav-partialupdate, extended-mkcol
```

This is only required if you are adding this feature to a DAV server. For
non-webdav implementations such as REST services this is optional.