frostfs-api/object/types.proto

syntax = "proto3";

package neo.fs.v2.object;

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

import "refs/types.proto";
import "session/types.proto";

// Type of the object payload content
enum ObjectType {
  // Just a normal object
  REGULAR = 0;

  // Used internally to identify deleted objects
  TOMBSTONE = 1;

  // Identifies that the object holds StorageGroup information
  STORAGE_GROUP = 2;
}

// Type of match expression
enum MatchType {
  // Unknown. Not used
  MATCH_TYPE_UNSPECIFIED = 0;
  // Full string match
  STRING_EQUAL = 1;
}

// Short header fields
message ShortHeader {
  // Object format version.
  neo.fs.v2.refs.Version version = 1;

  // Epoch when the object was created
  uint64 creation_epoch = 2;

  // Object's owner
  neo.fs.v2.refs.OwnerID owner_id = 3;

  // Type of the object payload content
  ObjectType object_type = 4;

  // Size of payload in bytes.
  // 0xFFFFFFFFFFFFFFFF means `payload_length` is unknown
  uint64 payload_length = 5;
}

// Object Headers
message Header {
  // Object format version.
  // Effectively the version of API library used to create particular object
  neo.fs.v2.refs.Version version = 1;

  // Object's container
  neo.fs.v2.refs.ContainerID container_id = 2;

  // Object's owner
  neo.fs.v2.refs.OwnerID owner_id = 3;

  // Object creation Epoch
  uint64 creation_epoch = 4;

  // Size of payload in bytes.
  // 0xFFFFFFFFFFFFFFFF means `payload_length` is unknown
  uint64 payload_length = 5;

  // Hash of payload bytes
  neo.fs.v2.refs.Checksum payload_hash = 6;

  // Special object type
  ObjectType object_type = 7;

  // Homomorphic hash of the object payload.
  neo.fs.v2.refs.Checksum homomorphic_hash = 8;

  // Session token, if it was used during Object creation.
  // Need it to verify integrity and authenticity out of Request scope.
  neo.fs.v2.session.SessionToken session_token = 9;

  // `Attribute` is a user-defined Key-Value metadata pair attached to the
  // object.
  //
  // There are some "well-known" attributes starting with `__NEOFS__` prefix
  // that affect system behaviour:
  //
  // * __NEOFS__UPLOAD_ID
  // * __NEOFS__EXPIRATION_EPOCH
  //
  // For detailed description of each well-known attribute please see the
  // corresponding section in NeoFS Technical specification.
  message Attribute {
    // string key to the object attribute
    string key = 1;
    // string value of the object attribute
    string value = 2;
  }
  // User-defined object attributes
  repeated Attribute attributes = 10;

  // Information about spawning the objects through a payload splitting.
  message Split {
    // Identifier of the origin object.
    // Parent and children objects must be within the same container.
    // Parent object_id is known only to the minor child.
    neo.fs.v2.refs.ObjectID parent = 1;

    // Previous carries identifier of the left split neighbor.
    neo.fs.v2.refs.ObjectID previous = 2;

    // `signature` field of the parent object. Used to reconstruct parent.
    neo.fs.v2.refs.Signature parent_signature = 3;

    // `header` field of the parent object. Used to reconstruct parent.
    Header parent_header = 4;

    // Children carries list of identifiers of the objects generated by splitting the current.
    repeated neo.fs.v2.refs.ObjectID children = 5;
  }
  // Position of the object in the split hierarchy.
  Split split = 11;
}

// Object structure.
message Object {
  // Object's unique identifier.
  // Object is content-addressed. It means id will change if header or payload
  // changes. It's calculated as a hash of header field, which contains hash of
  // object's payload
  neo.fs.v2.refs.ObjectID object_id = 1;

  // Signed object_id
  neo.fs.v2.refs.Signature signature = 2;

  // Object metadata headers
  Header header = 3;

  // Payload bytes.
  bytes payload = 4;
}