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 {
        // payload_length carries length of the object payload.
        // Each object has a fixed payload length since it's immutable.
        uint64 payload_length = 1;
        // address carries object address in the NeoFS system.
        // It encapsulates the object and the container identifiers.
        refs.Address address = 2;
        // owner_id carries identifier of the object owner.
        refs.OwnerID owner_id = 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 {
            // payload_checksum 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 payload_checksum = 1;

            // header_checksum 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.
            // payload_checksum and header_checksum 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 creator_key and checksum_signature.
            bytes header_checksum = 2;

            // session_token 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 creator_key.
            service.Token session_token = 3;

            // creator_key carries public key of the object creator in a binary format.
            bytes creator_key = 4;

            // checksum_signature carries signature of the structure checksum by the object creator.
            bytes checksum_signature = 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;

        // creation_epoch carries number of NeoFS epoch on which the object was created.
        uint64 creation_epoch = 3;

        // Tombstone groups the options for deleting an object.
        message Tombstone {
        }

        // Tombstone marks the object to be deleted.
        Tombstone tombstone = 4;

        // homomorphic_hash carries homomorphic hash of the object payload.
        bytes homomorphic_hash = 5;

        // StorageGroup groups meta information about a storage group.
        message StorageGroup {
        }

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

            // Next 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;
}