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;

  // 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. Effectively the version of API library used to
  // create particular object
  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 Header
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;

  // Type of the object payload content
  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;

  // Bigger objects can be split into a chain of smaller objects. Information
  // about inter-dependencies between spawned objects and how to re-construct
  // the original one is in the `Split` headers. Parent and children objects
  // must be within the same container.
  message Split {
    // Identifier of the origin object. Known only to the minor child.
    neo.fs.v2.refs.ObjectID parent = 1;

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

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

// Object structure. Object is immutable and content-addressed. It means
// `ObjectID` will change if header or payload changes. It's calculated as a
// hash of header field, which contains hash of object's payload.
message Object {
  // Object's unique identifier.
  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;
}