frostfs-api/object/types.proto

syntax = "proto3";

package object;

option go_package = "github.com/nspcc-dev/neofs-api-go/object";
option csharp_namespace = "NeoFS.API.Object";

import "refs/types.proto";
import "service/verify.proto";

// Header groups the information about the NeoFS object.
message Header {
    // Main groups mandatory information about the object.
    // Message fields are presented in all NeoFS objects.
    message Main {
        // PayloadLength carries length of the object payload.
        // Each object has a fixed payload length since it's immutable.
        uint64 PayloadLength = 1;
        // Address carries object address in the NeoFS system.
        // It encapsulates the object and the container identifiers.
        refs.Address Address = 2;
        // OwnerID carries identifier the object owner in a binary format.
        bytes OwnerID = 3;
    }

    // Main carries the main part of the header.
    // Main MUST NOT be NULL.
    Main main = 1;

    // 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 groups meta information about a storage group.
        message StorageGroup {
        }

        // StorageGroup marks an object containing information about a storage group.
        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;
}

// Object groups the information about the NeoFS object.
// It consists of payload data with additional service information.
message Object {
    // Header carries the object header.
    Header Header = 1;

    // Payload carries the object payload bytes.
    bytes Payload = 2;
}