frostfs-api/container/types.proto

syntax = "proto3";

package frost.fs.container;

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

// Container is a structure that defines object placement behaviour. Objects can
// be stored only within containers. They define placement rule, attributes and
// access control information. An ID of a container is a 32 byte long SHA256
// hash of stable-marshalled container message.
message Container {
  // Container format version. Effectively, the version of API library used to
  // create the container.
  frost.fs.refs.Version version = 1 [ json_name = "version" ];

  // Identifier of the container owner
  frost.fs.refs.OwnerID owner_id = 2 [ json_name = "ownerID" ];

  // Nonce is a 16 byte UUIDv4, used to avoid collisions of `ContainerID`s
  bytes nonce = 3 [ json_name = "nonce" ];

  // `BasicACL` contains access control rules for the owner, system and others
  // groups, as well as permission bits for `BearerToken` and `Extended ACL`
  uint32 basic_acl = 4 [ json_name = "basicACL" ];

  // `Attribute` is a user-defined Key-Value metadata pair attached to the
  // container. Container attributes are immutable. They are set at the moment
  // of container creation and can never be added or updated.
  //
  // Key name must be a container-unique valid UTF-8 string. Value can't be
  // empty. Containers with duplicated attribute names or attributes with empty
  // values will be considered invalid.
  //
  // There are some "well-known" attributes affecting system behaviour:
  //
  // * [ __SYSTEM__NAME ] \
  //   String of a human-friendly container name registered as a domain in
  //   NNS contract.
  // * [ __SYSTEM__ZONE ]  \
  //   String of a zone for `__SYSTEM__NAME`.
  //   Used as a TLD of a domain name in NNS contract. If no zone is specified,
  //   use default zone: `container`.
  // * [ __SYSTEM__DISABLE_HOMOMORPHIC_HASHING ] \
  //   Disables homomorphic hashing for the container if the value equals "true"
  //   string. Any other values are interpreted as missing attribute. Container
  //   could be accepted in a FrostFS network only if the global network hashing
  //   configuration value corresponds with that attribute's value. After
  //   container inclusion, network setting is ignored.
  //
  // And some well-known attributes used by applications only:
  //
  // * Name \
  //   Human-friendly name
  // * Timestamp \
  //   User-defined local time of container creation in Unix Timestamp format
  message Attribute {
    // Attribute name key
    string key = 1 [ json_name = "key" ];

    // Attribute value
    string value = 2 [ json_name = "value" ];
  }
  // Attributes represent immutable container's meta data
  repeated Attribute attributes = 5 [ json_name = "attributes" ];

  // Placement policy for the object inside the container
  frost.fs.netmap.PlacementPolicy placement_policy = 6
      [ json_name = "placementPolicy" ];
}