frostfs

Documentation

Index

• Variables
• type ContainerCreateResult
• type CreateObjectResult
• type FrostFS
• type Object
• type PrmAddContainerPolicyChain
• type PrmAuth
• type PrmContainer
• type PrmContainerCreate
• type PrmObjectCreate
• type PrmObjectDelete
• type PrmObjectGet
• type PrmObjectHead
• type PrmObjectPatch
• type PrmObjectRange
• type PrmObjectSearch
• type PrmUserContainers

Variables

var (
	// ErrAccessDenied is returned from FrostFS in case of access violation.
	ErrAccessDenied = errors.New("access denied")

	// ErrGatewayTimeout is returned from FrostFS in case of timeout, deadline exceeded etc.
	ErrGatewayTimeout = errors.New("gateway timeout")

	// ErrGlobalDomainIsAlreadyTaken is returned from FrostFS in case of global domain is already taken.
	ErrGlobalDomainIsAlreadyTaken = errors.New("global domain is already taken")
)

Types

type ContainerCreateResult

type ContainerCreateResult struct {
	ContainerID             cid.ID
	HomomorphicHashDisabled bool
}

ContainerCreateResult is a result parameter of FrostFS.CreateContainer operation.

type CreateObjectResult

type CreateObjectResult struct {
	ObjectID      oid.ID
	CreationEpoch uint64
}

CreateObjectResult is a result parameter of FrostFS.CreateObject operation.

type FrostFS

type FrostFS interface {
	// CreateContainer creates and saves parameterized container in FrostFS.
	// It sets 'Timestamp' attribute to the current time.
	// It returns the ID of the saved container.
	//
	// It returns exactly one non-zero value. It returns any error encountered which
	// prevented the container from being created.
	CreateContainer(context.Context, PrmContainerCreate) (*ContainerCreateResult, error)

	// AddContainerPolicyChain create new policy chain for container.
	// Can be invoked only by container owner.
	AddContainerPolicyChain(context.Context, PrmAddContainerPolicyChain) error

	// Container reads a container from FrostFS by ID.
	//
	// It returns exactly one non-nil value. It returns any error encountered which
	// prevented the container from being read.
	Container(context.Context, PrmContainer) (*container.Container, error)

	// UserContainers reads a list of the containers owned by the specified user.
	//
	// It returns exactly one non-nil value. It returns any error encountered which
	// prevented the containers from being listed.
	UserContainers(context.Context, PrmUserContainers) ([]cid.ID, error)

	// DeleteContainer marks the container to be removed from FrostFS by ID.
	// Request is sent within session if the session token is specified.
	// Successful return does not guarantee actual removal.
	//
	// It returns any error encountered which prevented the removal request from being sent.
	DeleteContainer(context.Context, cid.ID, *session.Container) error

	// HeadObject reads an info of the object from the FrostFS container by identifier.
	//
	// It returns ErrAccessDenied on read access violation.
	//
	// It returns exactly one non-nil value. It returns any error encountered which
	// prevented the object header from being read.
	HeadObject(ctx context.Context, prm PrmObjectHead) (*object.Object, error)

	// GetObject reads an object from the FrostFS container by identifier.
	//
	// Payload reader should be closed if it is no longer needed.
	//
	// It returns ErrAccessDenied on read access violation.
	//
	// It returns exactly one non-nil value. It returns any error encountered which
	// prevented the object header from being read.
	GetObject(ctx context.Context, prm PrmObjectGet) (*Object, error)

	// RangeObject reads a part of object from the FrostFS container by identifier.
	//
	// Payload reader should be closed if it is no longer needed.
	//
	// It returns ErrAccessDenied on read access violation.
	//
	// It returns exactly one non-nil value. It returns any error encountered which
	// prevented the object header from being read.
	RangeObject(ctx context.Context, prm PrmObjectRange) (io.ReadCloser, error)

	// CreateObject creates and saves a parameterized object in the FrostFS container.
	// It sets 'Timestamp' attribute to the current time.
	// It returns the ID and creation epoch of the saved object.
	//
	// Creation time should be written into the object (UTC).
	//
	// It returns ErrAccessDenied on write access violation.
	//
	// It returns exactly one non-nil value. It returns any error encountered which
	// prevented the object from being created.
	CreateObject(context.Context, PrmObjectCreate) (*CreateObjectResult, error)

	// DeleteObject marks the object to be removed from the FrostFS container by identifier.
	// Successful return does not guarantee actual removal.
	//
	// It returns ErrAccessDenied on remove access violation.
	//
	// It returns any error encountered which prevented the removal request from being sent.
	DeleteObject(context.Context, PrmObjectDelete) error

	// SearchObjects performs object search from the NeoFS container according
	// to the specified parameters. It searches user's objects only.
	//
	// It returns ErrAccessDenied on selection access violation.
	//
	// It returns exactly one non-nil value. It returns any error encountered which
	// prevented the objects from being selected.
	SearchObjects(context.Context, PrmObjectSearch) ([]oid.ID, error)

	// PatchObject performs object patch in the FrostFS container.
	// It returns the ID of the patched object.
	//
	// It returns ErrAccessDenied on selection access violation.
	//
	// It returns exactly one non-nil value. It returns any error encountered which
	// prevented the objects from being patched.
	PatchObject(context.Context, PrmObjectPatch) (oid.ID, error)

	// TimeToEpoch computes current epoch and the epoch that corresponds to the provided now and future time.
	// Note:
	// * future time must be after the now
	// * future time will be ceil rounded to match epoch
	//
	// It returns any error encountered which prevented computing epochs.
	TimeToEpoch(ctx context.Context, now time.Time, future time.Time) (uint64, uint64, error)

	// NetworkInfo returns parameters of FrostFS network.
	NetworkInfo(context.Context) (netmap.NetworkInfo, error)
}

FrostFS represents virtual connection to FrostFS network.

type Object

type Object struct {
	// Object header (doesn't contain payload).
	Header object.Object

	// Object payload part encapsulated in io.Reader primitive.
	// Returns ErrAccessDenied on read access violation.
	Payload io.ReadCloser
}

Object represents full read FrostFS object.

type PrmAddContainerPolicyChain

type PrmAddContainerPolicyChain struct {
	// ContainerID is a container identifier.
	ContainerID cid.ID

	// Chain is Access Policy Engine chain that contains rules which provide access to specific actions in container.
	Chain chain.Chain
}

PrmAddContainerPolicyChain groups parameter of FrostFS.AddContainerPolicyChain operation.

type PrmAuth

type PrmAuth struct {
	// Bearer token to be used for the operation. Overlaps PrivateKey. Optional.
	BearerToken *bearer.Token

	// Private key used for the operation if BearerToken is missing (in this case non-nil).
	PrivateKey *ecdsa.PrivateKey
}

PrmAuth groups authentication parameters for the FrostFS operation.

type PrmContainer

type PrmContainer struct {
	// Container identifier.
	ContainerID cid.ID

	// Token of the container's creation session. Nil means session absence.
	SessionToken *session.Container
}

PrmContainer groups parameters of FrostFS.Container operation.

type PrmContainerCreate

type PrmContainerCreate struct {
	// FrostFS identifier of the container creator.
	Creator user.ID

	// Container placement policy.
	Policy netmap.PlacementPolicy

	// Name for the container.
	Name string

	// Zone for container registration.
	Zone string

	// CreationTime value for Timestamp attribute
	CreationTime time.Time

	// Token of the container's creation session. Nil means session absence.
	SessionToken *session.Container

	// Attributes for optional parameters.
	AdditionalAttributes [][2]string
}

PrmContainerCreate groups parameters of FrostFS.CreateContainer operation.

type PrmObjectCreate

type PrmObjectCreate struct {
	// Authentication parameters.
	PrmAuth

	// Container to store the object.
	Container cid.ID

	// Key-value object attributes.
	Attributes [][2]string

	// Value for Timestamp attribute (optional).
	CreationTime time.Time

	// List of ids to lock (optional).
	Locks []oid.ID

	// Full payload size (optional).
	PayloadSize uint64

	// Associated filepath (optional).
	Filepath string

	// Object payload encapsulated in io.Reader primitive.
	Payload io.Reader

	// Number of object copies that is enough to consider put successful.
	CopiesNumber []uint32

	// Enables client side object preparing.
	ClientCut bool

	// Disables using Tillich-Zémor hash for payload.
	WithoutHomomorphicHash bool

	// Sets max buffer size to read payload.
	BufferMaxSize uint64
}

PrmObjectCreate groups parameters of FrostFS.CreateObject operation.

type PrmObjectDelete

type PrmObjectDelete struct {
	// Authentication parameters.
	PrmAuth

	// Container to delete the object from.
	Container cid.ID

	// Identifier of the removed object.
	Object oid.ID
}

PrmObjectDelete groups parameters of FrostFS.DeleteObject operation.

type PrmObjectGet

type PrmObjectGet struct {
	// Authentication parameters.
	PrmAuth

	// Container to read the object header from.
	Container cid.ID

	// ID of the object for which to read the header.
	Object oid.ID
}

PrmObjectGet groups parameters of FrostFS.GetObject operation.

type PrmObjectHead

type PrmObjectHead struct {
	// Authentication parameters.
	PrmAuth

	// Container to read the object header from.
	Container cid.ID

	// ID of the object for which to read the header.
	Object oid.ID
}

PrmObjectHead groups parameters of FrostFS.HeadObject operation.

type PrmObjectPatch

type PrmObjectPatch struct {
	// Authentication parameters.
	PrmAuth

	// Container of the patched object.
	Container cid.ID

	// Identifier of the patched object.
	Object oid.ID

	// Object patch payload encapsulated in io.Reader primitive.
	Payload io.Reader

	// Object range to patch.
	Offset, Length uint64

	// Size of original object payload.
	ObjectSize uint64
}

PrmObjectPatch groups parameters of FrostFS.PatchObject operation.

type PrmObjectRange

type PrmObjectRange struct {
	// Authentication parameters.
	PrmAuth

	// Container to read the object header from.
	Container cid.ID

	// ID of the object for which to read the header.
	Object oid.ID

	// Offset-length range of the object payload to be read.
	PayloadRange [2]uint64
}

PrmObjectRange groups parameters of FrostFS.RangeObject operation.

type PrmObjectSearch

type PrmObjectSearch struct {
	// Authentication parameters.
	PrmAuth

	// Container to select the objects from.
	Container cid.ID

	// Key-value object attribute which should be
	// presented in selected objects. Optional, empty key means any.
	ExactAttribute [2]string

	// File prefix of the selected objects. Optional, empty value means any.
	FilePrefix string
}

PrmObjectSearch groups parameters of FrostFS.sear SearchObjects operation.

type PrmUserContainers

type PrmUserContainers struct {
	// User identifier.
	UserID user.ID

	// Token of the container's creation session. Nil means session absence.
	SessionToken *session.Container
}

PrmUserContainers groups parameters of FrostFS.UserContainers operation.