diff --git a/docs/extensions.md b/docs/extensions.md index 72cc93aa..fa8cf1db 100644 --- a/docs/extensions.md +++ b/docs/extensions.md @@ -50,3 +50,172 @@ HTTP/1.1 204 No Content Connection: close Server: AmazonS3 ``` + +## Object operations management + +### Action to patch object (PatchObject) + +Allows to partially change and add data to an existing object. + +> **Note**: patch is not supported for objects that were uploaded using SSE. + +#### Path parameters + +- **Bucket** + + Bucket name. + + _Required: Yes_ + +- **Key** + + Object name. + + _Required: Yes_ + +#### Query parameters + +- **versionId** + + Version of the original object to patch. + + _Required: No_ + +#### Request headers + +- **Content-Range** + + The byte range of the object (or its version) to patch. + + The value is formed as follows: `bytes {start byte}-{end byte}/*`. + + Range boundaries are included. + + The maximum range length is 5GB. + + To write additional data to the object, the end byte must be greater than the object size. + + The start byte cannot be greater than the object size. + + The range length must be equal to the value of the **_Content-Length_** header. + + The format corresponds to the [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110#name-content-range) specification with the following + exceptions: + + - **_complete-length_** parameter is ignored. + - **_last-pos_** parameter is optional (if not specified, the value is assumed to be equal to the end byte of the object). + + _Required: Yes_ + +- **Content-Length** + + Number of bytes sent in the request body. + + _Required: Yes_ + +- **If-Match** + + Patch is performed if ETag of the object (or its version) is equal to specified in the header. + + _Required: No_ + +- **If-Unmodified-Since** + + Patch is performed if the object (or its version) has not changed since the time specified in the header. + + _Required: No_ + +- **x-amz-expected-bucket-owner** + + ID of the intended owner of the bucket. + + _Required: No_ + +#### Request body + +Contains new data for the passed byte range of the object. + +#### Response + +The request returns the following data in XML format. + +- **PatchObjectResult** + + Root level tag for parameters. + +- **Object** + + Parent tag for patch results. + +- **LastModified** + + Time when the object was last modified. Applying patch does not change this value. + +- **ETag** + + Patched object tag. Always in SHA-256 format. + +If the bucket is versioned, the **_x-amz-version-id_** header is returned with the version of the created object. + +#### Errors + +- **MissingContentRange** + + The required **_Content-Range_** header was not sent. + + HTTP Status Code: 400 + +- **NoSuchBucket** + + The specified bucket does not exist. + + HTTP Status Code: 404 + +- **NoSuchKey** + + The specified object does not exist. + + HTTP Status Code: 404 + +- **MissingContentLength** + + The required **_Content-Length_** header was not sent. + + HTTP Status Code: 411 + +- **PreconditionFailed** + + At least one of the preconditions is not satisfied. + + HTTP Status Code: 412 + +- **InvalidRange** + + Incorrect value in **_Content-Range_** header. + + HTTP Status Code: 416 + +#### Example + +Sample Request + +```text +PATCH /example-bucket/example-key HTTP/1.1 +Host: data.s3..frostfs-s3-gw.com +Content-Range: bytes 0-3/* +Content-Length: 4 +&AUTHPARAMS + +Body +``` + +Sample Response + +```xml + + + 2024-07-24T14:54:54Z + "e8b53b75afaf3ce898f048c663b11cf4c71f5f13456673dd5b422a247c9e627f" + + +```