Merge pull request #283 from nspcc-dev/fix/child-objects-acl

cthulhu-rider · web-flow · commit 533950f0172c · 2024-02-05T21:08:23.000+04:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,8 +4,12 @@
 
 ### Added
 - Numeric operands for object search queries (#265)
+- Link object payload message (#263)
+- Children sizes index to the link objects (#264)
+- `LINK` split chain object type (#283)
 
 ### Changed
+- Split ID is deprecated, the first child part is used instead and is known to the other parts (#283)
 
 ### Removed
 
diff --git a/link/types.proto b/link/types.proto
@@ -0,0 +1,30 @@
+syntax = "proto3";
+
+package neo.fs.v2.link;
+
+option go_package = "github.com/nspcc-dev/neofs-api-go/v2/link/grpc;link";
+option csharp_namespace = "Neo.FileStorage.API.Link";
+
+import "refs/types.proto";
+
+// Link is a payload of helper objects that contain the full list of the split
+// chain objects' IDs. It is created only after the whole split chain is known
+// and signed. This object is the only object that refers to every "child object"
+// ID. It is NOT required for the original object assembling. It MUST have ALL
+// the "child objects" IDs. Child objects MUST be ordered according to the
+// original payload split, meaning the first payload part holder MUST be placed
+// at the first place in the corresponding link object. Sizes MUST NOT be omitted
+// and MUST be a real object payload size in bytes.
+message Link {
+  // Object ID with its object's payload size.
+  message MeasuredObject {
+    // Object ID.
+    neo.fs.v2.refs.ObjectID id = 1 [json_name = "id"];
+
+    // Object size in bytes.
+    uint32 size = 2 [json_name = "size"];
+  }
+
+  // Full list of the "child" object descriptors.
+  repeated MeasuredObject children = 1 [json_name = "children"];
+}
diff --git a/object/types.proto b/object/types.proto
@@ -17,6 +17,7 @@ import "session/types.proto";
 // * TOMBSTONE
 // * STORAGE_GROUP
 // * LOCK
+// * LINK
 enum ObjectType {
   // Just a normal object
   REGULAR = 0;
@@ -29,6 +30,9 @@ enum ObjectType {
 
   // Object lock
   LOCK = 3;
+
+  // Object that stores child object IDs for the split objects.
+  LINK = 4;
 }
 
 // Type of match expression
@@ -185,14 +189,21 @@ message Header {
     // `header` field of the parent object. Used to reconstruct parent.
     Header parent_header = 4 [json_name = "parentHeader"];
 
+    // DEPRECATED. Was used before creating the separate LINK object type. Keep
+    // child objects list in the LINK object's payload.
     // List of identifiers of the objects generated by splitting current one.
     repeated neo.fs.v2.refs.ObjectID children = 5 [json_name = "children"];
 
+    // DEPRECATED. Was used as an identifier of a split chain. Use the first
+    // part ID instead.
     // 16 byte UUIDv4 used to identify the split object hierarchy parts. Must be
     // unique inside container. All objects participating in the split must have
     // the same `split_id` value.
     bytes split_id = 6 [json_name = "splitID"];
 
+    // Identifier of the first part of the origin object. Known to all the split
+    // parts except the first one. Identifies the split and allows to differ them.
+    neo.fs.v2.refs.ObjectID first = 7 [json_name = "first"];
   }
   // Position of the object in the split hierarchy
   Split split = 11 [json_name = "split"];
@@ -223,6 +234,8 @@ message Object {
 // assemble the original object. With a linking object one can assemble an object
 // right from the object parts.
 message SplitInfo {
+  // DEPRECATED. Was used as an identifier of a split chain. Use the first
+  // part ID instead.
   // 16 byte UUID used to identify the split object hierarchy parts.
   bytes split_id = 1;
 
@@ -234,4 +247,8 @@ message SplitInfo {
   // split header with the original object header and a sorted list of
   // object parts.
   neo.fs.v2.refs.ObjectID link = 3;
+
+  // Identifier of the first part of the origin object. Known to all the split
+  // parts except the first one. Identifies the split and allows to differ them.
+  neo.fs.v2.refs.ObjectID first_part = 4;
 }
diff --git a/proto-docs/link.md b/proto-docs/link.md
@@ -0,0 +1,80 @@
+# Protocol Documentation
+<a name="top"></a>
+
+## Table of Contents
+
+- [link/types.proto](#link/types.proto)
+
+  - Messages
+    - [Link](#neo.fs.v2.link.Link)
+    - [Link.MeasuredObject](#neo.fs.v2.link.Link.MeasuredObject)
+    
+
+- [Scalar Value Types](#scalar-value-types)
+
+
+
+<a name="link/types.proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## link/types.proto
+
+
+ <!-- end services -->
+
+
+<a name="neo.fs.v2.link.Link"></a>
+
+### Message Link
+Link is a payload of helper objects that contain the full list of the split
+chain objects' IDs. It is created only after the whole split chain is known
+and signed. This object is the only object that refers to every "child object"
+ID. It is NOT required for the original object assembling. It MUST have ALL
+the "child objects" IDs. Child objects MUST be ordered according to the
+original payload split, meaning the first payload part holder MUST be placed
+at the first place in the corresponding link object. Sizes MUST NOT be omitted
+and MUST be a real object payload size in bytes.
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| children | [Link.MeasuredObject](#neo.fs.v2.link.Link.MeasuredObject) | repeated | Full list of the "child" object descriptors. |
+
+
+<a name="neo.fs.v2.link.Link.MeasuredObject"></a>
+
+### Message Link.MeasuredObject
+Object ID with its object's payload size.
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) |  | Object ID. |
+| size | [uint32](#uint32) |  | Object size in bytes. |
+
+ <!-- end messages -->
+
+ <!-- end enums -->
+
+
+
+## Scalar Value Types
+
+| .proto Type | Notes | C++ Type | Java Type | Python Type |
+| ----------- | ----- | -------- | --------- | ----------- |
+| <a name="double" /> double |  | double | double | float |
+| <a name="float" /> float |  | float | float | float |
+| <a name="int32" /> int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
+| <a name="int64" /> int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
+| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
+| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
+| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
+| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
+| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
+| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
+| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
+| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
+| <a name="bool" /> bool |  | bool | boolean | boolean |
+| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
+| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
+
diff --git a/proto-docs/object.md b/proto-docs/object.md
@@ -954,8 +954,9 @@ must be within the same container.
 | previous | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) |  | Identifier of the left split neighbor |
 | parent_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | `signature` field of the parent object. Used to reconstruct parent. |
 | parent_header | [Header](#neo.fs.v2.object.Header) |  | `header` field of the parent object. Used to reconstruct parent. |
-| children | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | List of identifiers of the objects generated by splitting current one. |
-| split_id | [bytes](#bytes) |  | 16 byte UUIDv4 used to identify the split object hierarchy parts. Must be unique inside container. All objects participating in the split must have the same `split_id` value. |
+| children | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | DEPRECATED. Was used before creating the separate LINK object type. Keep child objects list in the LINK object's payload. List of identifiers of the objects generated by splitting current one. |
+| split_id | [bytes](#bytes) |  | DEPRECATED. Was used as an identifier of a split chain. Use the first part ID instead. 16 byte UUIDv4 used to identify the split object hierarchy parts. Must be unique inside container. All objects participating in the split must have the same `split_id` value. |
+| first | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) |  | Identifier of the first part of the origin object. Known to all the split parts except the first one. Identifies the split and allows to differ them. |
 
 
 <a name="neo.fs.v2.object.Object"></a>
@@ -1005,9 +1006,10 @@ right from the object parts.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| split_id | [bytes](#bytes) |  | 16 byte UUID used to identify the split object hierarchy parts. |
+| split_id | [bytes](#bytes) |  | DEPRECATED. Was used as an identifier of a split chain. Use the first part ID instead. 16 byte UUID used to identify the split object hierarchy parts. |
 | last_part | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) |  | The identifier of the last object in split hierarchy parts. It contains split header with the original object header. |
 | link | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) |  | The identifier of a linking object for split hierarchy parts. It contains split header with the original object header and a sorted list of object parts. |
+| first_part | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) |  | Identifier of the first part of the origin object. Known to all the split parts except the first one. Identifies the split and allows to differ them. |
 
  <!-- end messages -->
 
@@ -1043,13 +1045,15 @@ String presentation of object type is the same as definition:
 * TOMBSTONE
 * STORAGE_GROUP
 * LOCK
+* LINK
 
 | Name | Number | Description |
 | ---- | ------ | ----------- |
 | REGULAR | 0 | Just a normal object |
 | TOMBSTONE | 1 | Used internally to identify deleted objects |
 | STORAGE_GROUP | 2 | StorageGroup information |
 | LOCK | 3 | Object lock |
+| LINK | 4 | Object that stores child object IDs for the split objects. |
 
 
  <!-- end enums -->
