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. - - -### Message ExtendedHeader + +### 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. | + + + + +### 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. | - + -### 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. | - + -### 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. | - + -### 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. | - + -### Message ExtendedHeader.Tombstone +### Message Header.Extended.Tombstone Tombstone groups the options for deleting an object. - + -### 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 | @@ -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 | - - - -### 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 | -