From 0525786d0903f5b4bae04223b9ca3488370c92f4 Mon Sep 17 00:00:00 2001
From: Leonard Lyubich <leonard@nspcc.ru>
Date: Tue, 4 Aug 2020 23:43:33 +0300
Subject: [PATCH] [#26] object: Use nested types in Header

This commit replaces all message definitions related to object header to
Header message.

Signed-off-by: Leonard Lyubich <leonard@nspcc.ru>
---
 object/types.proto   | 175 ++++++++++++++++++++++---------------------
 proto-docs/object.md |  81 ++++++++++----------
 2 files changed, 132 insertions(+), 124 deletions(-)

diff --git a/object/types.proto b/object/types.proto
index d22a938..bdbf17e 100644
--- a/object/types.proto
+++ b/object/types.proto
@@ -7,94 +7,99 @@ import "refs/types.proto";
 import "service/verify.proto";
 import "storagegroup/types.proto";
 
-message ExtendedHeader {
-    // Integrity groups evidence of the integrity of an object's structure.
-    message Integrity {
-        // PayloadChecksum carries the checksum of object payload bytes.
-        // Changing any byte of the payload changes the checksum.
-        // It is calculated as a SHA-256 hash over payload bytes.
-        bytes PayloadChecksum = 1;
-        // HeaderChecksum carries checksum of the object header structure.
-        // It covers all object attributes. Changing any field of the object except
-        // CreatorKey and ChecksumSignature changes the checksum.
-        // PayloadChecksum and HeaderChecksum cannot be merged due to the need
-        // to verify the header in the absence of a payload (e.g. in object.Head rpc).
-        // It is calculated as a SHA-256 hash over marshaled object header
-        // with cut CreatorKey and ChecksumSignature.
-        bytes HeaderChecksum = 2;
-        // SessionToken carries token of the session within which the object was created.
-        // If session token is presented in object, it acts as the user's proof of the
-        // correctness of the CreatorKey.
-        service.Token SessionToken = 3;
-        // CreatorKey carries public key of the object creator in a binary format.
-        bytes CreatorKey = 4;
-        // ChecksumSignature carries signature of the structure checksum by the object creator.
-        bytes ChecksumSignature = 5;
-    }
-    // Integrity carries object integrity evidence.
-    Integrity integrity = 1;
-
-    // Attribute groups the parameters of the object attributes.
-    message Attribute {
-        // Key carries the string key to the object attribute.
-        string Key = 1;
-
-        // Value carries the string value of the object attribute.
-        string Value = 2;
-    }
-    // Attributes carries list of the object attributes in a string key-value format.
-    repeated Attribute Attributes = 2;
-    // CreationEpoch carries number of NeoFS epoch on which the object was created.
-    uint64 CreationEpoch = 3;
-
-    // Tombstone groups the options for deleting an object.
-    message Tombstone {
-    }
-    // Tombstone marks the object to be deleted.
-    Tombstone tombstone = 4;
-    // HomomorphicHash carries homomorphic hash of the object payload.
-    bytes HomomorphicHash = 5;
-    // StorageGroup carries information about the NeoFS storage group.
-    storagegroup.StorageGroup StorageGroup = 6;
-
-    // Split groups information about spawning the object through a payload splitting.
-    message Split {
-        // Parent carries identifier of the origin object.
-        refs.ObjectID Parent = 1;
-
-        // Previous carries identifier of the left split neighbor.
-        refs.ObjectID Previous = 2;
-
-        // Previous carries identifier of the right split neighbor.
-        refs.ObjectID Next = 3;
-
-        // Children carries list of identifiers of the objects generated by splitting the current.
-        repeated refs.ObjectID Children = 4;
-
-        // Origin carries the header of the origin object.
-        Header Origin = 5;
-    }
-    // Split carries the position of the object in the split hierarchy.
-    Split split = 7;
-}
-
-message SystemHeader {
-    // PayloadLength is an object payload length
-    uint64 PayloadLength = 1;
-    // Address carries object address in the NeoFS system.
-    // It encapsulates the object and the container identifiers.
-    refs.Address Address = 2;
-    // OwnerID is a wallet address
-    bytes OwnerID = 3;
-}
-
 // Header groups the information about the NeoFS object.
 message Header {
-    // SystemHeader describes system header
-    SystemHeader SystemHeader = 1;
+    // System groups mandatory information about the object.
+    // Message fields are presented in all NeoFS objects.
+    message System {
+        // PayloadLength is an object payload length
+        uint64 PayloadLength = 1;
+        // Address carries object address in the NeoFS system.
+        // It encapsulates the object and the container identifiers.
+        refs.Address Address = 2;
+        // OwnerID is a wallet address
+        bytes OwnerID = 3;
+    }
+    // System carries the main part of the header.
+    // System MUST NOT be NULL.
+    System system = 1;
 
-    // ExtendedHeader carries the additional part of the header.
-    ExtendedHeader ExtendedHeader = 2;
+    // Extended groups additional information about the object.
+    // It encapsulates both user and system attributes needed to regulate
+    // the NeoFS sub-systems.
+    message Extended {
+        // Integrity groups evidence of the integrity of an object's structure.
+        message Integrity {
+            // PayloadChecksum carries the checksum of object payload bytes.
+            // Changing any byte of the payload changes the checksum.
+            // It is calculated as a SHA-256 hash over payload bytes.
+            bytes PayloadChecksum = 1;
+            // HeaderChecksum carries checksum of the object header structure.
+            // It covers all object attributes. Changing any field of the object except
+            // CreatorKey and ChecksumSignature changes the checksum.
+            // PayloadChecksum and HeaderChecksum cannot be merged due to the need
+            // to verify the header in the absence of a payload (e.g. in object.Head rpc).
+            // It is calculated as a SHA-256 hash over marshaled object header
+            // with cut CreatorKey and ChecksumSignature.
+            bytes HeaderChecksum = 2;
+            // SessionToken carries token of the session within which the object was created.
+            // If session token is presented in object, it acts as the user's proof of the
+            // correctness of the CreatorKey.
+            service.Token SessionToken = 3;
+            // CreatorKey carries public key of the object creator in a binary format.
+            bytes CreatorKey = 4;
+            // ChecksumSignature carries signature of the structure checksum by the object creator.
+            bytes ChecksumSignature = 5;
+        }
+        // Integrity carries object integrity evidence.
+        Integrity integrity = 1;
+
+        // Attribute groups the parameters of the object attributes.
+        message Attribute {
+            // Key carries the string key to the object attribute.
+            string Key = 1;
+
+            // Value carries the string value of the object attribute.
+            string Value = 2;
+        }
+        // Attributes carries list of the object attributes in a string key-value format.
+        repeated Attribute Attributes = 2;
+        // CreationEpoch carries number of NeoFS epoch on which the object was created.
+        uint64 CreationEpoch = 3;
+
+        // Tombstone groups the options for deleting an object.
+        message Tombstone {
+        }
+        // Tombstone marks the object to be deleted.
+        Tombstone tombstone = 4;
+        // HomomorphicHash carries homomorphic hash of the object payload.
+        bytes HomomorphicHash = 5;
+        // StorageGroup carries information about the NeoFS storage group.
+        storagegroup.StorageGroup StorageGroup = 6;
+
+        // Split groups information about spawning the object through a payload splitting.
+        message Split {
+            // Parent carries identifier of the origin object.
+            refs.ObjectID Parent = 1;
+
+            // Previous carries identifier of the left split neighbor.
+            refs.ObjectID Previous = 2;
+
+            // Previous carries identifier of the right split neighbor.
+            refs.ObjectID Next = 3;
+
+            // Children carries list of identifiers of the objects generated by splitting the current.
+            repeated refs.ObjectID Children = 4;
+
+            // Origin carries the header of the origin object.
+            Header Origin = 5;
+        }
+        // Split carries the position of the object in the split hierarchy.
+        Split split = 7;
+    }
+
+    // Extended carries the additional part of the header.
+    Extended extended = 2;
 }
 
 message Object {
diff --git a/proto-docs/object.md b/proto-docs/object.md
index 256c20a..59d8548 100644
--- a/proto-docs/object.md
+++ b/proto-docs/object.md
@@ -29,14 +29,14 @@
 - [object/types.proto](#object/types.proto)
 
   - Messages
-    - [ExtendedHeader](#object.ExtendedHeader)
-    - [ExtendedHeader.Attribute](#object.ExtendedHeader.Attribute)
-    - [ExtendedHeader.Integrity](#object.ExtendedHeader.Integrity)
-    - [ExtendedHeader.Split](#object.ExtendedHeader.Split)
-    - [ExtendedHeader.Tombstone](#object.ExtendedHeader.Tombstone)
     - [Header](#object.Header)
+    - [Header.Extended](#object.Header.Extended)
+    - [Header.Extended.Attribute](#object.Header.Extended.Attribute)
+    - [Header.Extended.Integrity](#object.Header.Extended.Integrity)
+    - [Header.Extended.Split](#object.Header.Extended.Split)
+    - [Header.Extended.Tombstone](#object.Header.Extended.Tombstone)
+    - [Header.System](#object.Header.System)
     - [Object](#object.Object)
-    - [SystemHeader](#object.SystemHeader)
     
 
 - [Scalar Value Types](#scalar-value-types)
@@ -359,26 +359,40 @@ in distributed system.
  <!-- end services -->
 
 
-<a name="object.ExtendedHeader"></a>
-
-### Message ExtendedHeader
+<a name="object.Header"></a>
 
+### Message Header
+Header groups the information about the NeoFS object.
 
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| integrity | [ExtendedHeader.Integrity](#object.ExtendedHeader.Integrity) |  | Integrity carries object integrity evidence. |
-| Attributes | [ExtendedHeader.Attribute](#object.ExtendedHeader.Attribute) | repeated | Attributes carries list of the object attributes in a string key-value format. |
+| system | [Header.System](#object.Header.System) |  | System carries the main part of the header. System MUST NOT be NULL. |
+| extended | [Header.Extended](#object.Header.Extended) |  | Extended carries the additional part of the header. |
+
+
+<a name="object.Header.Extended"></a>
+
+### Message Header.Extended
+Extended groups additional information about the object.
+It encapsulates both user and system attributes needed to regulate
+the NeoFS sub-systems.
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| integrity | [Header.Extended.Integrity](#object.Header.Extended.Integrity) |  | Integrity carries object integrity evidence. |
+| Attributes | [Header.Extended.Attribute](#object.Header.Extended.Attribute) | repeated | Attributes carries list of the object attributes in a string key-value format. |
 | CreationEpoch | [uint64](#uint64) |  | CreationEpoch carries number of NeoFS epoch on which the object was created. |
-| tombstone | [ExtendedHeader.Tombstone](#object.ExtendedHeader.Tombstone) |  | Tombstone marks the object to be deleted. |
+| tombstone | [Header.Extended.Tombstone](#object.Header.Extended.Tombstone) |  | Tombstone marks the object to be deleted. |
 | HomomorphicHash | [bytes](#bytes) |  | HomomorphicHash carries homomorphic hash of the object payload. |
 | StorageGroup | [storagegroup.StorageGroup](#storagegroup.StorageGroup) |  | StorageGroup carries information about the NeoFS storage group. |
-| split | [ExtendedHeader.Split](#object.ExtendedHeader.Split) |  | Split carries the position of the object in the split hierarchy. |
+| split | [Header.Extended.Split](#object.Header.Extended.Split) |  | Split carries the position of the object in the split hierarchy. |
 
 
-<a name="object.ExtendedHeader.Attribute"></a>
+<a name="object.Header.Extended.Attribute"></a>
 
-### Message ExtendedHeader.Attribute
+### Message Header.Extended.Attribute
 Attribute groups the parameters of the object attributes.
 
 
@@ -388,9 +402,9 @@ Attribute groups the parameters of the object attributes.
 | Value | [string](#string) |  | Value carries the string value of the object attribute. |
 
 
-<a name="object.ExtendedHeader.Integrity"></a>
+<a name="object.Header.Extended.Integrity"></a>
 
-### Message ExtendedHeader.Integrity
+### Message Header.Extended.Integrity
 Integrity groups evidence of the integrity of an object's structure.
 
 
@@ -403,9 +417,9 @@ Integrity groups evidence of the integrity of an object's structure.
 | ChecksumSignature | [bytes](#bytes) |  | ChecksumSignature carries signature of the structure checksum by the object creator. |
 
 
-<a name="object.ExtendedHeader.Split"></a>
+<a name="object.Header.Extended.Split"></a>
 
-### Message ExtendedHeader.Split
+### Message Header.Extended.Split
 Split groups information about spawning the object through a payload splitting.
 
 
@@ -418,23 +432,25 @@ Split groups information about spawning the object through a payload splitting.
 | Origin | [Header](#object.Header) |  | Origin carries the header of the origin object. |
 
 
-<a name="object.ExtendedHeader.Tombstone"></a>
+<a name="object.Header.Extended.Tombstone"></a>
 
-### Message ExtendedHeader.Tombstone
+### Message Header.Extended.Tombstone
 Tombstone groups the options for deleting an object.
 
 
 
-<a name="object.Header"></a>
+<a name="object.Header.System"></a>
 
-### Message Header
-Header groups the information about the NeoFS object.
+### Message Header.System
+System groups mandatory information about the object.
+Message fields are presented in all NeoFS objects.
 
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| SystemHeader | [SystemHeader](#object.SystemHeader) |  | SystemHeader describes system header |
-| ExtendedHeader | [ExtendedHeader](#object.ExtendedHeader) |  | ExtendedHeader carries the additional part of the header. |
+| PayloadLength | [uint64](#uint64) |  | PayloadLength is an object payload length |
+| Address | [refs.Address](#refs.Address) |  | Address carries object address in the NeoFS system. It encapsulates the object and the container identifiers. |
+| OwnerID | [bytes](#bytes) |  | OwnerID is a wallet address |
 
 
 <a name="object.Object"></a>
@@ -448,19 +464,6 @@ Header groups the information about the NeoFS object.
 | Header | [Header](#object.Header) |  | Header carries the object header. |
 | Payload | [bytes](#bytes) |  | Payload is an object's payload |
 
-
-<a name="object.SystemHeader"></a>
-
-### Message SystemHeader
-
-
-
-| Field | Type | Label | Description |
-| ----- | ---- | ----- | ----------- |
-| PayloadLength | [uint64](#uint64) |  | PayloadLength is an object payload length |
-| Address | [refs.Address](#refs.Address) |  | Address carries object address in the NeoFS system. It encapsulates the object and the container identifiers. |
-| OwnerID | [bytes](#bytes) |  | OwnerID is a wallet address |
-
  <!-- end messages -->
 
  <!-- end enums -->