[#56] object: Introduce Patch method

* Introduce rpc `Patch` and corresponding types;
* Generate docs.

Signed-off-by: Airat Arifullin <aarifullin@yadro.com>

object/service.proto

@@ -283,6 +283,51 @@ service ObjectService {
   // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
   //   provided session token has expired.
   rpc PutSingle(PutSingleRequest) returns (PutSingleResponse);
+
+  // Patch the object. Request uses gRPC stream. First message must set
+  // the address of the object that is going to get patched. If the object's attributes
+  // are patched, then these attrubutes must be set only within the first stream message.
+  //
+  // If the patch request is performed by NOT the object's owner but if the actor has the permission
+  // to perform the patch, then `OwnerID` of the object is changed. In this case the object's owner
+  // loses the object's ownership after the patch request is successfully done.
+  //
+  // As objects are content-addressable the patching causes new object ID generation for the patched object.
+  // This object id is set witihn `PatchResponse`. But the object id may remain unchanged in such cases: 
+  // 1. The chunk of the applying patch contains the same value as the object's payload within the same range;
+  // 2. The patch that reverts the changes applied by preceding patch;
+  // 3. The application of the same patches for the object a few times.
+  //
+  // Extended headers can change `Patch` behaviour:
+  // * [ __SYSTEM__NETMAP_EPOCH \
+  //   (`__NEOFS__NETMAP_EPOCH` is deprecated) \
+  //   Will use the requsted version of Network Map for object placement
+  //   calculation.
+  //
+  // Please refer to detailed `XHeader` description.
+  //
+  // Statuses:
+  // - **OK** (0, SECTION_SUCCESS): \
+  //   object has been successfully patched and saved in the container;
+  // - Common failures (SECTION_FAILURE_COMMON);
+  // - **ACCESS_DENIED** (2048, SECTION_OBJECT): \
+  //   write access to the container is denied;
+  // - **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT): \
+  //   object not found in container;
+  // - **OBJECT_ALREADY_REMOVED** (2052, SECTION_OBJECT): \
+  //   the requested object has been marked as deleted.
+  // - **OUT_OF_RANGE** (2053, SECTION_OBJECT): \
+  //   the requested range is out of bounds;
+  // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
+  //   object storage container not found;
+  // - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
+  //   access to container is denied;
+  // - **TOKEN_NOT_FOUND** (4096, SECTION_SESSION): \
+  //   (for trusted object preparation) session private key does not exist or
+  //   has been deleted;
+  // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
+  //   provided session token has expired.
+  rpc Patch(stream PatchRequest) returns (PatchResponse);
 }
 
 // GET object request
@@ -817,3 +862,69 @@ message PutSingleResponse {
   // transmission.
   neo.fs.v2.session.ResponseVerificationHeader verify_header = 3;
 }
+
+// Object PATCH request
+message PatchRequest {
+  // PATCH request body
+  message Body {
+    // The address of the object that is requested to get patched.
+    neo.fs.v2.refs.Address address = 1;
+
+    // New attributes for the object. See `replace_attributes` flag usage to define how
+    // new attributes should be set.
+    repeated neo.fs.v2.object.Header.Attribute new_attributes = 2;
+
+    // If this flag is set, then the object's attributes will be entirely replaced by `new_attributes` list.
+    // The empty `new_attributes` list with `replace_attributes = true` just resets attributes list for the object.
+    //
+    // Default `false` value for this flag means the attributes will be just merged. If the incoming `new_attributes`
+    // list contains already existing key, then it just replaces it while merging the lists. 
+    bool replace_attributes = 3;
+
+    // The patch for the object's payload. 
+    message Patch {
+      // The range of the source object for which the payload is replaced by the patch's chunk.
+      // If the range's `length = 0`, then the patch's chunk is just appended to the original payload
+      // starting from the `offest` without any replace.
+      Range source_range = 1;
+
+      // The chunk that is being appended to or that replaces the original payload on the given range.
+      bytes chunk = 2;
+    }
+
+    // The patch that is applied for the object.
+    Patch patch = 4;
+  }
+
+  // Body for patch request message.
+  Body body = 1;
+
+  // Carries request meta information. Header data is used only to regulate
+  // message transport and does not affect request execution.
+  neo.fs.v2.session.RequestMetaHeader meta_header = 2;
+
+  // Carries request verification information. This header is used to
+  // authenticate the nodes of the message route and check the correctness of
+  // transmission.
+  neo.fs.v2.session.RequestVerificationHeader verify_header = 3;
+}
+
+// Object PATCH response
+message PatchResponse {
+  // PATCH response body
+  message Body {
+      // The object ID of the saved patched object.
+      neo.fs.v2.refs.ObjectID object_id = 1;
+  }
+
+  // Body for patch response message.
+  Body body = 1;
+
+  // Carries response meta information. Header data is used only to regulate
+  // message transport and does not affect request execution.
+  neo.fs.v2.session.ResponseMetaHeader meta_header = 2;
+
+  // Carries response verification information. This header is used to authenticate
+  // the nodes of the message route and check the correctness of transmission.
+  neo.fs.v2.session.ResponseVerificationHeader verify_header = 3;
+}

proto-docs/object.md

@@ -30,6 +30,11 @@
       - [HeadResponse](#neo.fs.v2.object.HeadResponse)
       - [HeadResponse.Body](#neo.fs.v2.object.HeadResponse.Body)
       - [HeaderWithSignature](#neo.fs.v2.object.HeaderWithSignature)
+      - [PatchRequest](#neo.fs.v2.object.PatchRequest)
+      - [PatchRequest.Body](#neo.fs.v2.object.PatchRequest.Body)
+      - [PatchRequest.Body.Patch](#neo.fs.v2.object.PatchRequest.Body.Patch)
+      - [PatchResponse](#neo.fs.v2.object.PatchResponse)
+      - [PatchResponse.Body](#neo.fs.v2.object.PatchResponse.Body)
       - [PutRequest](#neo.fs.v2.object.PutRequest)
       - [PutRequest.Body](#neo.fs.v2.object.PutRequest.Body)
       - [PutRequest.Body.Init](#neo.fs.v2.object.PutRequest.Body.Init)
@@ -88,6 +93,7 @@ rpc Search(SearchRequest) returns (stream SearchResponse);
 rpc GetRange(GetRangeRequest) returns (stream GetRangeResponse);
 rpc GetRangeHash(GetRangeHashRequest) returns (GetRangeHashResponse);
 rpc PutSingle(PutSingleRequest) returns (PutSingleResponse);
+rpc Patch(stream PatchRequest) returns (PatchResponse);
 
 ```
 
@@ -395,6 +401,55 @@ been deleted;
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | PutSingle | [PutSingleRequest](#neo.fs.v2.object.PutSingleRequest) | [PutSingleResponse](#neo.fs.v2.object.PutSingleResponse) |
+#### Method Patch
+
+Patch the object. Request uses gRPC stream. First message must set
+the address of the object that is going to get patched. If the object's attributes
+are patched, then these attrubutes must be set only within the first stream message.
+
+If the patch request is performed by NOT the object's owner but if the actor has the permission
+to perform the patch, then `OwnerID` of the object is changed. In this case the object's owner
+loses the object's ownership after the patch request is successfully done.
+
+As objects are content-addressable the patching causes new object ID generation for the patched object.
+This object id is set witihn `PatchResponse`. But the object id may remain unchanged in such cases: 
+1. The chunk of the applying patch contains the same value as the object's payload within the same range;
+2. The patch that reverts the changes applied by preceding patch;
+3. The application of the same patches for the object a few times.
+
+Extended headers can change `Patch` behaviour:
+* [ __SYSTEM__NETMAP_EPOCH \
+  (`__NEOFS__NETMAP_EPOCH` is deprecated) \
+  Will use the requsted version of Network Map for object placement
+  calculation.
+
+Please refer to detailed `XHeader` description.
+
+Statuses:
+- **OK** (0, SECTION_SUCCESS): \
+  object has been successfully patched and saved in the container;
+- Common failures (SECTION_FAILURE_COMMON);
+- **ACCESS_DENIED** (2048, SECTION_OBJECT): \
+  write access to the container is denied;
+- **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT): \
+  object not found in container;
+- **OBJECT_ALREADY_REMOVED** (2052, SECTION_OBJECT): \
+  the requested object has been marked as deleted.
+- **OUT_OF_RANGE** (2053, SECTION_OBJECT): \
+  the requested range is out of bounds;
+- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
+  object storage container not found;
+- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
+  access to container is denied;
+- **TOKEN_NOT_FOUND** (4096, SECTION_SESSION): \
+  (for trusted object preparation) session private key does not exist or
+  has been deleted;
+- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
+  provided session token has expired.
+
+| Name | Input | Output |
+| ---- | ----- | ------ |
+| Patch | [PatchRequest](#neo.fs.v2.object.PatchRequest) | [PatchResponse](#neo.fs.v2.object.PatchResponse) |
  <!-- end services -->
 
 
@@ -691,6 +746,71 @@ following steps:
 | signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | Signed `ObjectID` to verify full header's authenticity |
 
 
+<a name="neo.fs.v2.object.PatchRequest"></a>
+
+### Message PatchRequest
+Object PATCH request
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| body | [PatchRequest.Body](#neo.fs.v2.object.PatchRequest.Body) |  | Body for patch request message. |
+| meta_header | [neo.fs.v2.session.RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) |  | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. |
+| verify_header | [neo.fs.v2.session.RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) |  | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
+
+
+<a name="neo.fs.v2.object.PatchRequest.Body"></a>
+
+### Message PatchRequest.Body
+PATCH request body
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) |  | The address of the object that is requested to get patched. |
+| new_attributes | [Header.Attribute](#neo.fs.v2.object.Header.Attribute) | repeated | New attributes for the object. See `replace_attributes` flag usage to define how new attributes should be set. |
+| replace_attributes | [bool](#bool) |  | If this flag is set, then the object's attributes will be entirely replaced by `new_attributes` list. The empty `new_attributes` list with `replace_attributes = true` just resets attributes list for the object.
+
+Default `false` value for this flag means the attributes will be just merged. If the incoming `new_attributes` list contains already existing key, then it just replaces it while merging the lists. |
+| patch | [PatchRequest.Body.Patch](#neo.fs.v2.object.PatchRequest.Body.Patch) |  | The patch that is applied for the object. |
+
+
+<a name="neo.fs.v2.object.PatchRequest.Body.Patch"></a>
+
+### Message PatchRequest.Body.Patch
+The patch for the object's payload.
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| source_range | [Range](#neo.fs.v2.object.Range) |  | The range of the source object for which the payload is replaced by the patch's chunk. If the range's `length = 0`, then the patch's chunk is just appended to the original payload starting from the `offest` without any replace. |
+| chunk | [bytes](#bytes) |  | The chunk that is being appended to or that replaces the original payload on the given range. |
+
+
+<a name="neo.fs.v2.object.PatchResponse"></a>
+
+### Message PatchResponse
+Object PATCH response
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| body | [PatchResponse.Body](#neo.fs.v2.object.PatchResponse.Body) |  | Body for patch response message. |
+| meta_header | [neo.fs.v2.session.ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) |  | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. |
+| verify_header | [neo.fs.v2.session.ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) |  | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
+
+
+<a name="neo.fs.v2.object.PatchResponse.Body"></a>
+
+### Message PatchResponse.Body
+PATCH response body
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| object_id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) |  | The object ID of the saved patched object. |
+
+
 <a name="neo.fs.v2.object.PutRequest"></a>
 
 ### Message PutRequest