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 {
    // 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.SessionToken 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;
}