container

Documentation

Overview

Package container provides functionality related to the FrostFS containers.

The base type is Container. To create new container in the FrostFS network Container instance should be initialized

var cnr Container
cnr.Init()
// fill all the fields

// encode cnr and send

After the container is persisted in the FrostFS network, applications can process it using the instance of Container types

// recv binary container

var cnr Container

err := cnr.Unmarshal(bin)
// ...

// process the container data

Instances can be also used to process FrostFS API V2 protocol messages (see neo.fs.v2.container package in https://git.frostfs.info/TrueCloudLab/frostfs-api).

On client side:

import "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/container"

var msg container.Container
cnr.WriteToV2(&msg)

// send msg

On server side:

// recv msg

var cnr Container
cnr.ReadFromV2(msg)

// process cnr

Using package types in an application is recommended to potentially work with different protocol versions with which these types are compatible.

Index

• func ApplyNetworkConfig(cnr *Container, cfg netmap.NetworkInfo)
• func AssertID(id cid.ID, cnr Container) bool
• func AssertNetworkConfig(cnr Container, cfg netmap.NetworkInfo) bool
• func CalculateID(dst *cid.ID, cnr Container)
• func CalculateIDFromBinary(dst *cid.ID, cnr []byte)
• func CalculateSignature(dst *frostfscrypto.Signature, cnr Container, signer ecdsa.PrivateKey) error
• func CreatedAt(cnr Container) time.Time
• func DisableHomomorphicHashing(cnr *Container)
• func IsHomomorphicHashingDisabled(cnr Container) bool
• func Name(cnr Container) string
• func SetCreationTime(cnr *Container, t time.Time)
• func SetName(cnr *Container, name string)
• func VerifySignature(sig frostfscrypto.Signature, cnr Container) bool
• func WriteDomain(cnr *Container, domain Domain)
• type Container
  • func (x Container) Attribute(key string) string
  • func (x Container) BasicACL() (res acl.Basic)
  • func (x *Container) Init()
  • func (x Container) IterateAttributes(f func(key, val string))
  • func (x Container) IterateUserAttributes(f func(key, val string))
  • func (x Container) Marshal() []byte
  • func (x Container) MarshalJSON() ([]byte, error)
  • func (x Container) Owner() (res user.ID)
  • func (x Container) PlacementPolicy() (res netmap.PlacementPolicy)
  • func (x *Container) ReadFromV2(m container.Container) error
  • func (x *Container) SetAttribute(key, value string)
  • func (x *Container) SetBasicACL(basicACL acl.Basic)
  • func (x *Container) SetOwner(owner user.ID)
  • func (x *Container) SetPlacementPolicy(policy netmap.PlacementPolicy)
  • func (x *Container) Unmarshal(data []byte) error
  • func (x *Container) UnmarshalJSON(data []byte) error
  • func (x Container) WriteToV2(m *container.Container)
• type Domain
  • func ReadDomain(cnr Container) (res Domain)
  • func (x Domain) Name() string
  • func (x *Domain) SetName(name string)
  • func (x *Domain) SetZone(zone string)
  • func (x Domain) Zone() string
• type SizeEstimation
  • func (x SizeEstimation) Container() (res cid.ID)
  • func (x SizeEstimation) Epoch() uint64
  • func (x *SizeEstimation) ReadFromV2(m container.UsedSpaceAnnouncement) error
  • func (x *SizeEstimation) SetContainer(cnr cid.ID)
  • func (x *SizeEstimation) SetEpoch(epoch uint64)
  • func (x *SizeEstimation) SetValue(value uint64)
  • func (x SizeEstimation) Value() uint64
  • func (x SizeEstimation) WriteToV2(m *container.UsedSpaceAnnouncement)

Functions

func ApplyNetworkConfig

func ApplyNetworkConfig(cnr *Container, cfg netmap.NetworkInfo)

ApplyNetworkConfig applies network configuration to the container. Changes the container if it does not satisfy network configuration.

func AssertID

func AssertID(id cid.ID, cnr Container) bool

AssertID checks if the given Container matches its identifier in CAS of the FrostFS containers.

See also CalculateID.

func AssertNetworkConfig

func AssertNetworkConfig(cnr Container, cfg netmap.NetworkInfo) bool

AssertNetworkConfig checks if a container matches passed network configuration.

func CalculateID

func CalculateID(dst *cid.ID, cnr Container)

CalculateID encodes the given Container and passes the result into CalculateIDFromBinary.

See also Container.Marshal, AssertID.

func CalculateIDFromBinary

func CalculateIDFromBinary(dst *cid.ID, cnr []byte)

CalculateIDFromBinary calculates identifier of the binary-encoded container in CAS of the FrostFS containers and writes it into dst. ID instance MUST NOT be nil.

See also CalculateID, AssertID.

func CalculateSignature

func CalculateSignature(dst *frostfscrypto.Signature, cnr Container, signer ecdsa.PrivateKey) error

CalculateSignature calculates signature of the Container using provided signer and writes it into dst. Signature instance MUST NOT be nil. CalculateSignature is expected to be called after all the Container data is filled and before saving the Container in the FrostFS network. Note that мany subsequent change will most likely break the signature.

See also VerifySignature.

func CreatedAt

func CreatedAt(cnr Container) time.Time

CreatedAt returns container's creation time set using SetCreationTime.

Zero Container has zero timestamp (in seconds).

func DisableHomomorphicHashing

func DisableHomomorphicHashing(cnr *Container)

DisableHomomorphicHashing sets flag to disable homomorphic hashing of the Container data.

See also IsHomomorphicHashingDisabled.

func IsHomomorphicHashingDisabled

func IsHomomorphicHashingDisabled(cnr Container) bool

IsHomomorphicHashingDisabled checks if DisableHomomorphicHashing was called.

Zero Container has enabled hashing.

func Name

func Name(cnr Container) string

Name returns container name set using SetName.

Zero Container has no name.

func SetCreationTime

func SetCreationTime(cnr *Container, t time.Time)

SetCreationTime writes container's creation time in Unix Timestamp format.

See also CreatedAt.

func SetName

func SetName(cnr *Container, name string)

SetName sets human-readable name of the Container. Name MUST NOT be empty.

See also Name.

func VerifySignature

func VerifySignature(sig frostfscrypto.Signature, cnr Container) bool

VerifySignature verifies Container signature calculated using CalculateSignature. Result means signature correctness.

func WriteDomain

func WriteDomain(cnr *Container, domain Domain)

WriteDomain writes Domain into the Container. Name MUST NOT be empty.

Types

type Container

type Container struct {
	// contains filtered or unexported fields
}

Container represents descriptor of the FrostFS container. Container logically stores FrostFS objects. Container is one of the basic and at the same time necessary data storage units in the FrostFS. Container includes data about the owner, rules for placing objects and other information necessary for the system functioning.

Container type instances can represent different container states in the system, depending on the context. To create new container in FrostFS zero instance SHOULD be declared, initialized using Init method and filled using dedicated methods. Once container is saved in the FrostFS network, it can't be changed: containers stored in the system are immutable, and FrostFS is a CAS of containers that are identified by a fixed length value (see cid.ID type). Instances for existing containers can be initialized using decoding methods (e.g Unmarshal).

Container is mutually compatible with git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/container.Container message. See ReadFromV2 / WriteToV2 methods.

func (Container) Attribute

func (x Container) Attribute(key string) string

Attribute reads value of the Container attribute by key. Empty result means attribute absence.

See also SetAttribute, IterateAttributes, IterateUserAttributes.

func (Container) BasicACL

func (x Container) BasicACL() (res acl.Basic)

BasicACL returns basic ACL set using SetBasicACL.

Zero Container has zero basic ACL which structurally correct but doesn't make sense since it denies any access to any party.

func (*Container) Init

func (x *Container) Init()

Init initializes all internal data of the Container required by FrostFS API protocol. Init MUST be called when creating a new container. Init SHOULD NOT be called multiple times. Init SHOULD NOT be called if the Container instance is used for decoding only.

func (Container) IterateAttributes

func (x Container) IterateAttributes(f func(key, val string))

IterateAttributes iterates over all Container attributes and passes them into f. The handler MUST NOT be nil.

See also SetAttribute, Attribute.

func (Container) IterateUserAttributes

func (x Container) IterateUserAttributes(f func(key, val string))

IterateUserAttributes iterates over user Container attributes and passes them into f. The handler MUST NOT be nil.

See also SetAttribute, Attribute.

func (Container) Marshal

func (x Container) Marshal() []byte

Marshal encodes Container into a binary format of the FrostFS API protocol (Protocol Buffers with direct field order).

See also Unmarshal.

func (Container) MarshalJSON

func (x Container) MarshalJSON() ([]byte, error)

MarshalJSON encodes Container into a JSON format of the FrostFS API protocol (Protocol Buffers JSON).

See also UnmarshalJSON.

func (Container) Owner

func (x Container) Owner() (res user.ID)

Owner returns owner of the Container set using SetOwner.

Zero Container has no owner which is incorrect according to FrostFS API protocol.

func (Container) PlacementPolicy

func (x Container) PlacementPolicy() (res netmap.PlacementPolicy)

PlacementPolicy returns placement policy set using SetPlacementPolicy.

Zero Container has no placement policy which is incorrect according to FrostFS API protocol.

func (*Container) ReadFromV2

func (x *Container) ReadFromV2(m container.Container) error

ReadFromV2 reads Container from the container.Container message. Checks if the message conforms to FrostFS API V2 protocol.

See also WriteToV2.

func (*Container) SetAttribute

func (x *Container) SetAttribute(key, value string)

SetAttribute sets Container attribute value by key. Both key and value MUST NOT be empty. Attributes set by the creator (owner) are most commonly ignored by the FrostFS system and used for application layer. Some attributes are so-called system or well-known attributes: they are reserved for system needs. System attributes SHOULD NOT be modified using SetAttribute, use corresponding methods/functions. List of the reserved keys is documented in the particular protocol version.

SetAttribute overwrites existing attribute value.

See also Attribute, IterateAttributes, IterateUserAttributes.

func (*Container) SetBasicACL

func (x *Container) SetBasicACL(basicACL acl.Basic)

SetBasicACL specifies basic part of the Container ACL. Basic ACL is used to control access inside container storage.

See also BasicACL.

func (*Container) SetOwner

func (x *Container) SetOwner(owner user.ID)

SetOwner specifies the owner of the Container. Each Container has exactly one owner, so SetOwner MUST be called for instances to be saved in the FrostFS.

See also Owner.

func (*Container) SetPlacementPolicy

func (x *Container) SetPlacementPolicy(policy netmap.PlacementPolicy)

SetPlacementPolicy sets placement policy for the objects within the Container. FrostFS storage layer strives to follow the specified policy.

See also PlacementPolicy.

func (*Container) Unmarshal

func (x *Container) Unmarshal(data []byte) error

Unmarshal decodes FrostFS API protocol binary format into the Container (Protocol Buffers with direct field order). Returns an error describing a format violation.

See also Marshal.

func (*Container) UnmarshalJSON

func (x *Container) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes FrostFS API protocol JSON format into the Container (Protocol Buffers JSON). Returns an error describing a format violation.

See also MarshalJSON.

func (Container) WriteToV2

func (x Container) WriteToV2(m *container.Container)

WriteToV2 writes Container into the container.Container message. The message MUST NOT be nil.

See also ReadFromV2.

type Domain

type Domain struct {
	// contains filtered or unexported fields
}

Domain represents information about container domain registered in the NNS contract deployed in the FrostFS network.

func ReadDomain

func ReadDomain(cnr Container) (res Domain)

ReadDomain reads Domain from the Container. Returns value with empty name if domain is not specified.

func (Domain) Name

func (x Domain) Name() string

Name returns name set using SetName.

Zero Domain has zero name.

func (*Domain) SetName

func (x *Domain) SetName(name string)

SetName sets human-friendly container domain name.

func (*Domain) SetZone

func (x *Domain) SetZone(zone string)

SetZone sets zone which is used as a TLD of a domain name in NNS contract.

func (Domain) Zone

func (x Domain) Zone() string

Zone returns domain zone set using SetZone.

Zero Domain has "container" zone.

type SizeEstimation

type SizeEstimation struct {
	// contains filtered or unexported fields
}

SizeEstimation groups information about estimation of the size of the data stored in the FrostFS container.

SizeEstimation is mutually compatible with git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/container.UsedSpaceAnnouncement message. See ReadFromV2 / WriteToV2 methods.

func (SizeEstimation) Container

func (x SizeEstimation) Container() (res cid.ID)

Container returns container set using SetContainer.

Zero SizeEstimation is not bound to any container (returns zero) which is incorrect according to FrostFS API protocol.

func (SizeEstimation) Epoch

func (x SizeEstimation) Epoch() uint64

Epoch return epoch set using SetEpoch.

Zero SizeEstimation represents estimation in zero epoch.

func (*SizeEstimation) ReadFromV2

func (x *SizeEstimation) ReadFromV2(m container.UsedSpaceAnnouncement) error

ReadFromV2 reads SizeEstimation from the container.UsedSpaceAnnouncement message. Checks if the message conforms to FrostFS API V2 protocol.

See also WriteToV2.

func (*SizeEstimation) SetContainer

func (x *SizeEstimation) SetContainer(cnr cid.ID)

SetContainer specifies the container for which the amount of data is estimated. Required by the FrostFS API protocol.

See also Container.

func (*SizeEstimation) SetEpoch

func (x *SizeEstimation) SetEpoch(epoch uint64)

SetEpoch sets epoch when estimation of the container data size was calculated.

See also Epoch.

func (*SizeEstimation) SetValue

func (x *SizeEstimation) SetValue(value uint64)

SetValue sets estimated amount of data (in bytes) in the specified container.

See also Value.

func (SizeEstimation) Value

func (x SizeEstimation) Value() uint64

Value returns data size estimation set using SetValue.

Zero SizeEstimation has zero value.

func (SizeEstimation) WriteToV2

func (x SizeEstimation) WriteToV2(m *container.UsedSpaceAnnouncement)

WriteToV2 writes SizeEstimation into the container.UsedSpaceAnnouncement message. The message MUST NOT be nil.

See also ReadFromV2.