Merge pull request #345 from nspcc-dev/feature/container-policy-ec

roman-khimov · web-flow · commit 63488606bcb3 · 2025-10-07T17:28:57.000+03:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,6 +3,8 @@
 ## [Unreleased]
 
 ### Added
+- EC rules to container storage policy (#345)
+- GET/RANGE query for EC part object (#345)
 
 ### Changed
 
diff --git a/netmap/types.proto b/netmap/types.proto
@@ -130,6 +130,53 @@ message PlacementPolicy {
     json_name = "subnetId",
     deprecated = true
   ];
+
+  // Erasure coding rule for container objects.
+  //
+  // For each original object, the payload is split into `data_part_num` data
+  // and `parity_part_num` parity parts. Each part is the same size. Data parts
+  // contain the original payload. If its length is not divisible by
+  // `data_part_num`, the last part is aligned with zero bytes. Both
+  // `data_part_num` and `parity_part_num` MUST NOT be zero or exceed 64,
+  // including in total.
+  //
+  // For each payload part, a part object is created. Original object's ID,
+  // signature and header is written in `header.split.parent`,
+  // `header.split.parent_signature` and `header.split.parent_header` fields
+  // correspondingly. Part index is written in the `__NEOFS__EC_PART_IDX`
+  // attribute as base-10 integer. Rule index in `PlacementPolicy.ec_rules`
+  // list is written in the `__NEOFS__EC_RULE_IDX` attribute as base-10
+  // integer.
+  //
+  // Each part object is stored in the container in one copy. Storage nodes are
+  // selected from the network map similar to `PlacementPolicy.replicas` rules.
+  // Optional `selector` acts the same way. The object for the `i`-th part is
+  // placed in the `i`-th node. If it is unavailable, the backup nodes with
+  // indexes `m * n + i` (`n = data_part_num + parity_part_num`,
+  // `m = 1, ..., CBF-1`). If all nodes for the `i`-th part
+  // are unavailable, nodes for the `i+1`-th (0 for the last) part are tried,
+  // and so on.
+  //
+  // Once part objects are stored in the container, the original object remains
+  // available if at least `data_part_num` of any part objects are available.
+  // In other words, unavailability (including complete loss) of any of
+  // `parity_part_num` part objects does not violate availability of the
+  // original one.
+  //
+  // Objects of TOMBSTONE and LOCK types are not encoded and stored as they are
+  // because they have no payload.
+  message ECRule {
+    // Number of data parts
+    uint32 data_part_num = 1;
+
+    // Number of parity parts
+    uint32 parity_part_num = 2;
+
+    // Name of the linked selector
+    string selector = 3 [json_name = "selector"];
+  }
+  // Erasure coding rules. Limited to 4 items.
+  repeated ECRule ec_rules = 6 [json_name = "ecRules"];
 }
 
 // NeoFS node description
diff --git a/object/service.proto b/object/service.proto
@@ -262,7 +262,17 @@ service ObjectService {
   rpc Replicate(ReplicateRequest) returns (ReplicateResponse);
 }
 
-// GET object request
+// GET object request.
+//
+// The query for a parent object's EC part locally stored on the server is
+// specified as follows:
+//  - `body.address` is an address of the parent;
+//  - `meta_header.x_headers` includes `__NEOFS__EC_RULE_IDX` and
+//    `__NEOFS__EC_PART_IDX` by object attribute format. Rule index MUST NOT
+//    exceed container's `PlacementPolicy.ec_rules` list. Part index MUST NOT
+//    exceed total part number in the indexed rule.
+// In this case, if `body.address` refers to TOMBSTONE or LOCK object (which
+// cannot have EC parts), the query applies to it.
 message GetRequest {
   // GET Object request body
   message Body {
@@ -653,7 +663,17 @@ message Range {
   uint64 length = 2;
 }
 
-// Request part of object's payload
+// Request part of object's payload.
+//
+// The query for a parent object's EC part locally stored on the server is
+// specified as follows:
+//  - `body.address` is an address of the parent;
+//  - `meta_header.x_headers` includes `__NEOFS__EC_RULE_IDX` and
+//    `__NEOFS__EC_PART_IDX` by object attribute format. Rule index MUST NOT
+//    exceed container's `PlacementPolicy.ec_rules` list. Part index MUST NOT
+//    exceed total part number in the indexed rule.
+// In this case, if `body.address` refers to TOMBSTONE or LOCK object (which
+// cannot have EC parts), the query applies to it.
 message GetRangeRequest {
   // Byte range of object's payload request body
   message Body {
diff --git a/object/types.proto b/object/types.proto
@@ -228,6 +228,12 @@ message Header {
   // * __NEOFS__TICK_TOPIC \
   //   UTF-8 string topic ID that is used for object notification.
   //   DEPRECATED: attribute ignored by servers.
+  // * __NEOFS__EC_RULE_IDX \
+  //   Index of EC rule in container's `PlacementPolicy.ec_rules` according to
+  //   which the part was created. Base-10 integer.
+  // * __NEOFS__EC_PART_IDX \
+  //   Index in the EC parts into which the parent object is divided according
+  //   to `__NEOFS__EC_RULE_IDX` EC rule. Base-10 integer.
   //
   // And some well-known attributes used by applications only:
   //
@@ -264,7 +270,8 @@ message Header {
   // the original one is in the `Split` headers. Parent and children objects
   // must be within the same container.
   message Split {
-    // Identifier of the origin object. Known only to the minor child.
+    // Identifier of the origin object. If the origin object is split to comply
+    // with the object size limit, `parent` is known only to the minor child.
     neo.fs.v2.refs.ObjectID parent = 1 [json_name = "parent"];
 
     // Identifier of the left split neighbor
diff --git a/proto-docs/netmap.md b/proto-docs/netmap.md
@@ -33,6 +33,7 @@
     - [NodeInfo](#neo.fs.v2.netmap.NodeInfo)
     - [NodeInfo.Attribute](#neo.fs.v2.netmap.NodeInfo.Attribute)
     - [PlacementPolicy](#neo.fs.v2.netmap.PlacementPolicy)
+    - [PlacementPolicy.ECRule](#neo.fs.v2.netmap.PlacementPolicy.ECRule)
     - [Replica](#neo.fs.v2.netmap.Replica)
     - [Selector](#neo.fs.v2.netmap.Selector)
     
@@ -486,6 +487,53 @@ storage policy definition languages.
 | selectors | [Selector](#neo.fs.v2.netmap.Selector) | repeated | Set of Selectors to form the container's nodes subset |
 | filters | [Filter](#neo.fs.v2.netmap.Filter) | repeated | List of named filters to reference in selectors |
 | subnet_id | [neo.fs.v2.refs.SubnetID](#neo.fs.v2.refs.SubnetID) |  | DEPRECATED. Was used for subnetwork ID to select nodes from, currently ignored. |
+| ec_rules | [PlacementPolicy.ECRule](#neo.fs.v2.netmap.PlacementPolicy.ECRule) | repeated | Erasure coding rules. Limited to 4 items. |
+
+
+<a name="neo.fs.v2.netmap.PlacementPolicy.ECRule"></a>
+
+### Message PlacementPolicy.ECRule
+Erasure coding rule for container objects.
+
+For each original object, the payload is split into `data_part_num` data
+and `parity_part_num` parity parts. Each part is the same size. Data parts
+contain the original payload. If its length is not divisible by
+`data_part_num`, the last part is aligned with zero bytes. Both
+`data_part_num` and `parity_part_num` MUST NOT be zero or exceed 64,
+including in total.
+
+For each payload part, a part object is created. Original object's ID,
+signature and header is written in `header.split.parent`,
+`header.split.parent_signature` and `header.split.parent_header` fields
+correspondingly. Part index is written in the `__NEOFS__EC_PART_IDX`
+attribute as base-10 integer. Rule index in `PlacementPolicy.ec_rules`
+list is written in the `__NEOFS__EC_RULE_IDX` attribute as base-10
+integer.
+
+Each part object is stored in the container in one copy. Storage nodes are
+selected from the network map similar to `PlacementPolicy.replicas` rules.
+Optional `selector` acts the same way. The object for the `i`-th part is
+placed in the `i`-th node. If it is unavailable, the backup nodes with
+indexes `m * n + i` (`n = data_part_num + parity_part_num`,
+`m = 1, ..., CBF-1`). If all nodes for the `i`-th part
+are unavailable, nodes for the `i+1`-th (0 for the last) part are tried,
+and so on.
+
+Once part objects are stored in the container, the original object remains
+available if at least `data_part_num` of any part objects are available.
+In other words, unavailability (including complete loss) of any of
+`parity_part_num` part objects does not violate availability of the
+original one.
+
+Objects of TOMBSTONE and LOCK types are not encoded and stored as they are
+because they have no payload.
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| data_part_num | [uint32](#uint32) |  | Number of data parts |
+| parity_part_num | [uint32](#uint32) |  | Number of parity parts |
+| selector | [string](#string) |  | Name of the linked selector |
 
 
 <a name="neo.fs.v2.netmap.Replica"></a>
diff --git a/proto-docs/object.md b/proto-docs/object.md
@@ -149,6 +149,9 @@ Please refer to detailed `XHeader` description.
 Statuses:
 - **OK** (0, SECTION_SUCCESS): \
   object has been successfully saved in the container;
+- **INCOMPLETE** (1, SECTION_SUCCESS): \
+  object was put to some nodes, but the number of replicas is not sufficient
+  to satisfy placement policy;
 - Common failures (SECTION_FAILURE_COMMON);
 - **ACCESS_DENIED** (2048, SECTION_OBJECT): \
   write access to the container is denied;
@@ -188,6 +191,9 @@ Please refer to detailed `XHeader` description.
 Statuses:
 - **OK** (0, SECTION_SUCCESS): \
   object has been successfully marked to be removed from the container;
+- **INCOMPLETE** (1, SECTION_SUCCESS): \
+  some nodes have accepted the deletion mark, but some may still store
+  the object;
 - Common failures (SECTION_FAILURE_COMMON);
 - **ACCESS_DENIED** (2048, SECTION_OBJECT): \
   delete access to the object is denied;
@@ -250,6 +256,9 @@ Please refer to detailed `XHeader` description.
 Statuses:
 - **OK** (0, SECTION_SUCCESS): \
   objects have been successfully selected;
+- **INCOMPLETE** (1, SECTION_SUCCESS): \
+  some nodes were unable to process the request, so the result may
+  not contain all data;
 - Common failures (SECTION_FAILURE_COMMON);
 - **ACCESS_DENIED** (2048, SECTION_OBJECT): \
   access to operation SEARCH of the object is denied;
@@ -474,7 +483,17 @@ Get hash of object's payload part response body.
 <a name="neo.fs.v2.object.GetRangeRequest"></a>
 
 ### Message GetRangeRequest
-Request part of object's payload
+Request part of object's payload.
+
+The query for a parent object's EC part locally stored on the server is
+specified as follows:
+ - `body.address` is an address of the parent;
+ - `meta_header.x_headers` includes `__NEOFS__EC_RULE_IDX` and
+   `__NEOFS__EC_PART_IDX` by object attribute format. Rule index MUST NOT
+   exceed container's `PlacementPolicy.ec_rules` list. Part index MUST NOT
+   exceed total part number in the indexed rule.
+In this case, if `body.address` refers to TOMBSTONE or LOCK object (which
+cannot have EC parts), the query applies to it.
 
 
 | Field | Type | Label | Description |
@@ -528,7 +547,17 @@ chunks.
 <a name="neo.fs.v2.object.GetRequest"></a>
 
 ### Message GetRequest
-GET object request
+GET object request.
+
+The query for a parent object's EC part locally stored on the server is
+specified as follows:
+ - `body.address` is an address of the parent;
+ - `meta_header.x_headers` includes `__NEOFS__EC_RULE_IDX` and
+   `__NEOFS__EC_PART_IDX` by object attribute format. Rule index MUST NOT
+   exceed container's `PlacementPolicy.ec_rules` list. Part index MUST NOT
+   exceed total part number in the indexed rule.
+In this case, if `body.address` refers to TOMBSTONE or LOCK object (which
+cannot have EC parts), the query applies to it.
 
 
 | Field | Type | Label | Description |
@@ -950,6 +979,12 @@ that affect system behaviour:
 * __NEOFS__TICK_TOPIC \
   UTF-8 string topic ID that is used for object notification.
   DEPRECATED: attribute ignored by servers.
+* __NEOFS__EC_RULE_IDX \
+  Index of EC rule in container's `PlacementPolicy.ec_rules` according to
+  which the part was created. Base-10 integer.
+* __NEOFS__EC_PART_IDX \
+  Index in the EC parts into which the parent object is divided according
+  to `__NEOFS__EC_RULE_IDX` EC rule. Base-10 integer.
 
 And some well-known attributes used by applications only:
 
@@ -990,7 +1025,7 @@ must be within the same container.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| parent | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) |  | Identifier of the origin object. Known only to the minor child. |
+| parent | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) |  | Identifier of the origin object. If the origin object is split to comply with the object size limit, `parent` is known only to the minor child. |
 | 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. |
