Documentation ¶
Overview ¶
Package pool provides a wrapper for several NeoFS API clients.
The main component is Pool type. It is a virtual connection to the network and provides methods for executing operations on the server. It also supports a weighted random selection of the underlying client to make requests.
Create pool instance with 3 nodes connection. This InitParameters will make pool use 192.168.130.71 node while it is healthy. Otherwise, it will make the pool use 192.168.130.72 for 90% of requests and 192.168.130.73 for remaining 10%. :
var prm pool.InitParameters prm.SetKey(key) prm.AddNode(NewNodeParam(1, "192.168.130.71", 1)) prm.AddNode(NewNodeParam(2, "192.168.130.72", 9)) prm.AddNode(NewNodeParam(2, "192.168.130.73", 1)) // ... p, err := pool.NewPool(prm) // ...
Connect to the NeoFS server:
err := p.Dial(ctx) // ...
Execute NeoFS operation on the server:
var prm pool.PrmContainerPut prm.SetContainer(cnr) // ... res, err := p.PutContainer(context.Background(), prm) // ...
Execute NeoFS operation on the server and check error:
var prm pool.PrmObjectHead prm.SetAddress(addr) // ... res, err := p.HeadObject(context.Background(), prm) if client.IsErrObjectNotFound(err) { // ... } // ...
Close the connection:
p.Close()
Index ¶
- type InitParameters
- func (x *InitParameters) AddNode(nodeParam NodeParam)
- func (x *InitParameters) SetClientRebalanceInterval(interval time.Duration)
- func (x *InitParameters) SetHealthcheckTimeout(timeout time.Duration)
- func (x *InitParameters) SetKey(key *ecdsa.PrivateKey)
- func (x *InitParameters) SetLogger(logger *zap.Logger)
- func (x *InitParameters) SetNodeDialTimeout(timeout time.Duration)
- func (x *InitParameters) SetSessionExpirationDuration(expirationDuration uint64)
- type NodeParam
- type Pool
- func (p *Pool) Balance(ctx context.Context, prm PrmBalanceGet) (*accounting.Decimal, error)
- func (p *Pool) Close()
- func (p *Pool) DeleteContainer(ctx context.Context, prm PrmContainerDelete) error
- func (p *Pool) DeleteObject(ctx context.Context, prm PrmObjectDelete) error
- func (p *Pool) Dial(ctx context.Context) error
- func (p *Pool) GetContainer(ctx context.Context, prm PrmContainerGet) (*container.Container, error)
- func (p *Pool) GetEACL(ctx context.Context, prm PrmContainerEACL) (*eacl.Table, error)
- func (p *Pool) GetObject(ctx context.Context, prm PrmObjectGet) (*ResGetObject, error)
- func (p *Pool) HeadObject(ctx context.Context, prm PrmObjectHead) (*object.Object, error)
- func (p *Pool) ListContainers(ctx context.Context, prm PrmContainerList) ([]cid.ID, error)
- func (p *Pool) NetworkInfo(ctx context.Context) (*netmap.NetworkInfo, error)
- func (p *Pool) ObjectRange(ctx context.Context, prm PrmObjectRange) (*ResObjectRange, error)
- func (p *Pool) PutContainer(ctx context.Context, prm PrmContainerPut) (*cid.ID, error)
- func (p *Pool) PutObject(ctx context.Context, prm PrmObjectPut) (*oid.ID, error)
- func (p *Pool) SearchObjects(ctx context.Context, prm PrmObjectSearch) (*ResObjectSearch, error)
- func (p *Pool) SetEACL(ctx context.Context, prm PrmContainerSetEACL) error
- type PrmBalanceGet
- type PrmContainerDelete
- type PrmContainerEACL
- type PrmContainerGet
- type PrmContainerList
- type PrmContainerPut
- type PrmContainerSetEACL
- type PrmObjectDelete
- type PrmObjectGet
- type PrmObjectHead
- type PrmObjectPut
- type PrmObjectRange
- func (x *PrmObjectRange) SetAddress(addr oid.Address)
- func (x *PrmObjectRange) SetLength(length uint64)
- func (x *PrmObjectRange) SetOffset(offset uint64)
- func (x *PrmObjectRange) UseBearer(token bearer.Token)
- func (x *PrmObjectRange) UseKey(key *ecdsa.PrivateKey)
- func (x *PrmObjectRange) UseSession(token session.Object)
- type PrmObjectSearch
- type ResGetObject
- type ResObjectRange
- type ResObjectSearch
- type WaitParams
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type InitParameters ¶
type InitParameters struct {
// contains filtered or unexported fields
}
InitParameters contains values used to initialize connection Pool.
func (*InitParameters) AddNode ¶
func (x *InitParameters) AddNode(nodeParam NodeParam)
AddNode append information about the node to which you want to connect.
func (*InitParameters) SetClientRebalanceInterval ¶
func (x *InitParameters) SetClientRebalanceInterval(interval time.Duration)
SetClientRebalanceInterval specifies the interval for updating nodes health status.
See also Pool.Dial.
func (*InitParameters) SetHealthcheckTimeout ¶
func (x *InitParameters) SetHealthcheckTimeout(timeout time.Duration)
SetHealthcheckTimeout specifies the timeout for request to node to decide if it is alive.
See also Pool.Dial.
func (*InitParameters) SetKey ¶
func (x *InitParameters) SetKey(key *ecdsa.PrivateKey)
SetKey specifies default key to be used for the protocol communication by default.
func (*InitParameters) SetLogger ¶
func (x *InitParameters) SetLogger(logger *zap.Logger)
SetLogger specifies logger.
func (*InitParameters) SetNodeDialTimeout ¶
func (x *InitParameters) SetNodeDialTimeout(timeout time.Duration)
SetNodeDialTimeout specifies the timeout for connection to be established.
func (*InitParameters) SetSessionExpirationDuration ¶
func (x *InitParameters) SetSessionExpirationDuration(expirationDuration uint64)
SetSessionExpirationDuration specifies the session token lifetime in epochs.
type NodeParam ¶
type NodeParam struct {
// contains filtered or unexported fields
}
NodeParam groups parameters of remote node.
func NewNodeParam ¶
NewNodeParam creates NodeParam using parameters.
func (*NodeParam) SetAddress ¶
SetAddress specifies address of the node.
func (*NodeParam) SetPriority ¶
SetPriority specifies priority of the node. Negative value is allowed. In the result node groups with the same priority will be sorted by descent.
type Pool ¶
type Pool struct {
// contains filtered or unexported fields
}
Pool represents virtual connection to the NeoFS network to communicate with multiple NeoFS servers without thinking about switching between servers due to load balancing proportions or their unavailability. It is designed to provide a convenient abstraction from the multiple sdkClient.client types.
Pool can be created and initialized using NewPool function. Before executing the NeoFS operations using the Pool, connection to the servers MUST BE correctly established (see Dial method). Using the Pool before connecting have been established can lead to a panic. After the work, the Pool SHOULD BE closed (see Close method): it frees internal and system resources which were allocated for the period of work of the Pool. Calling Dial/Close methods during the communication process step strongly discouraged as it leads to undefined behavior.
Each method which produces a NeoFS API call may return an error. Status of underlying server response is casted to built-in error instance. Certain statuses can be checked using `sdkClient` and standard `errors` packages. Note that package provides some helper functions to work with status returns (e.g. sdkClient.IsErrContainerNotFound, sdkClient.IsErrObjectNotFound).
See pool package overview to get some examples.
func NewPool ¶
func NewPool(options InitParameters) (*Pool, error)
NewPool creates connection pool using parameters.
func (*Pool) Balance ¶
func (p *Pool) Balance(ctx context.Context, prm PrmBalanceGet) (*accounting.Decimal, error)
Balance requests current balance of the NeoFS account.
func (*Pool) Close ¶
func (p *Pool) Close()
Close closes the Pool and releases all the associated resources.
func (*Pool) DeleteContainer ¶
func (p *Pool) DeleteContainer(ctx context.Context, prm PrmContainerDelete) error
DeleteContainer sends request to remove the NeoFS container and waits for the operation to complete.
Waiting parameters can be specified using SetWaitParams. If not called, defaults are used:
polling interval: 5s waiting timeout: 120s
Success can be verified by reading by identifier (see GetContainer).
func (*Pool) DeleteObject ¶
func (p *Pool) DeleteObject(ctx context.Context, prm PrmObjectDelete) error
DeleteObject marks an object for deletion from the container using NeoFS API protocol. As a marker, a special unit called a tombstone is placed in the container. It confirms the user's intent to delete the object, and is itself a container object. Explicit deletion is done asynchronously, and is generally not guaranteed.
func (*Pool) Dial ¶
Dial establishes a connection to the servers from the NeoFS network. It also starts a routine that checks the health of the nodes and updates the weights of the nodes for balancing. Returns an error describing failure reason.
If failed, the Pool SHOULD NOT be used.
See also InitParameters.SetClientRebalanceInterval.
func (*Pool) GetContainer ¶
GetContainer reads NeoFS container by ID.
func (*Pool) GetObject ¶
func (p *Pool) GetObject(ctx context.Context, prm PrmObjectGet) (*ResGetObject, error)
GetObject reads object header and initiates reading an object payload through a remote server using NeoFS API protocol.
func (*Pool) HeadObject ¶
HeadObject reads object header through a remote server using NeoFS API protocol.
func (*Pool) ListContainers ¶
ListContainers requests identifiers of the account-owned containers.
func (*Pool) NetworkInfo ¶
NetworkInfo requests information about the NeoFS network of which the remote server is a part.
func (*Pool) ObjectRange ¶
func (p *Pool) ObjectRange(ctx context.Context, prm PrmObjectRange) (*ResObjectRange, error)
ObjectRange initiates reading an object's payload range through a remote server using NeoFS API protocol.
func (*Pool) PutContainer ¶
PutContainer sends request to save container in NeoFS and waits for the operation to complete.
Waiting parameters can be specified using SetWaitParams. If not called, defaults are used:
polling interval: 5s waiting timeout: 120s
Success can be verified by reading by identifier (see GetContainer).
func (*Pool) PutObject ¶
PutObject writes an object through a remote server using NeoFS API protocol.
func (*Pool) SearchObjects ¶
func (p *Pool) SearchObjects(ctx context.Context, prm PrmObjectSearch) (*ResObjectSearch, error)
SearchObjects initiates object selection through a remote server using NeoFS API protocol.
The call only opens the transmission channel, explicit fetching of matched objects is done using the ResObjectSearch. Exactly one return value is non-nil. Resulting reader must be finally closed.
func (*Pool) SetEACL ¶
func (p *Pool) SetEACL(ctx context.Context, prm PrmContainerSetEACL) error
SetEACL sends request to update eACL table of the NeoFS container and waits for the operation to complete.
Waiting parameters can be specified using SetWaitParams. If not called, defaults are used:
polling interval: 5s waiting timeout: 120s
Success can be verified by reading by identifier (see GetEACL).
type PrmBalanceGet ¶
type PrmBalanceGet struct {
// contains filtered or unexported fields
}
PrmBalanceGet groups parameters of Balance operation.
func (*PrmBalanceGet) SetAccount ¶
func (x *PrmBalanceGet) SetAccount(id user.ID)
SetAccount specifies identifier of the NeoFS account for which the balance is requested.
type PrmContainerDelete ¶
type PrmContainerDelete struct {
// contains filtered or unexported fields
}
PrmContainerDelete groups parameters of DeleteContainer operation.
func (*PrmContainerDelete) SetContainerID ¶
func (x *PrmContainerDelete) SetContainerID(cnrID cid.ID)
SetContainerID specifies identifier of the NeoFS container to be removed.
func (*PrmContainerDelete) SetSessionToken ¶
func (x *PrmContainerDelete) SetSessionToken(token session.Container)
SetSessionToken specifies session within which operation should be performed.
func (*PrmContainerDelete) SetWaitParams ¶
func (x *PrmContainerDelete) SetWaitParams(waitParams WaitParams)
SetWaitParams specifies timeout params to complete operation. If not provided the default one will be used. Panics if any of the wait params isn't positive.
type PrmContainerEACL ¶
type PrmContainerEACL struct {
// contains filtered or unexported fields
}
PrmContainerEACL groups parameters of GetEACL operation.
func (*PrmContainerEACL) SetContainerID ¶
func (x *PrmContainerEACL) SetContainerID(cnrID cid.ID)
SetContainerID specifies identifier of the NeoFS container to read the eACL table.
type PrmContainerGet ¶
type PrmContainerGet struct {
// contains filtered or unexported fields
}
PrmContainerGet groups parameters of GetContainer operation.
func (*PrmContainerGet) SetContainerID ¶
func (x *PrmContainerGet) SetContainerID(cnrID cid.ID)
SetContainerID specifies identifier of the container to be read.
type PrmContainerList ¶
type PrmContainerList struct {
// contains filtered or unexported fields
}
PrmContainerList groups parameters of ListContainers operation.
func (*PrmContainerList) SetOwnerID ¶
func (x *PrmContainerList) SetOwnerID(ownerID user.ID)
SetOwnerID specifies identifier of the NeoFS account to list the containers.
type PrmContainerPut ¶
type PrmContainerPut struct {
// contains filtered or unexported fields
}
PrmContainerPut groups parameters of PutContainer operation.
func (*PrmContainerPut) SetContainer ¶
func (x *PrmContainerPut) SetContainer(cnr container.Container)
SetContainer specifies structured information about new NeoFS container.
func (*PrmContainerPut) SetWaitParams ¶
func (x *PrmContainerPut) SetWaitParams(waitParams WaitParams)
SetWaitParams specifies timeout params to complete operation. If not provided the default one will be used. Panics if any of the wait params isn't positive.
type PrmContainerSetEACL ¶
type PrmContainerSetEACL struct {
// contains filtered or unexported fields
}
PrmContainerSetEACL groups parameters of SetEACL operation.
func (*PrmContainerSetEACL) SetTable ¶
func (x *PrmContainerSetEACL) SetTable(table eacl.Table)
SetTable specifies eACL table structure to be set for the container.
func (*PrmContainerSetEACL) SetWaitParams ¶
func (x *PrmContainerSetEACL) SetWaitParams(waitParams WaitParams)
SetWaitParams specifies timeout params to complete operation. If not provided the default one will be used. Panics if any of the wait params isn't positive.
type PrmObjectDelete ¶
type PrmObjectDelete struct {
// contains filtered or unexported fields
}
PrmObjectDelete groups parameters of DeleteObject operation.
func (*PrmObjectDelete) SetAddress ¶
func (x *PrmObjectDelete) SetAddress(addr oid.Address)
SetAddress specifies NeoFS address of the object.
func (*PrmObjectDelete) UseKey ¶
func (x *PrmObjectDelete) UseKey(key *ecdsa.PrivateKey)
UseKey specifies private key to sign the requests. If key is not provided, then Pool default key is used.
func (*PrmObjectDelete) UseSession ¶
UseSession specifies session within which operation should be performed.
type PrmObjectGet ¶
type PrmObjectGet struct {
// contains filtered or unexported fields
}
PrmObjectGet groups parameters of GetObject operation.
func (*PrmObjectGet) SetAddress ¶
func (x *PrmObjectGet) SetAddress(addr oid.Address)
SetAddress specifies NeoFS address of the object.
func (*PrmObjectGet) UseKey ¶
func (x *PrmObjectGet) UseKey(key *ecdsa.PrivateKey)
UseKey specifies private key to sign the requests. If key is not provided, then Pool default key is used.
func (*PrmObjectGet) UseSession ¶
UseSession specifies session within which operation should be performed.
type PrmObjectHead ¶
type PrmObjectHead struct {
// contains filtered or unexported fields
}
PrmObjectHead groups parameters of HeadObject operation.
func (*PrmObjectHead) SetAddress ¶
func (x *PrmObjectHead) SetAddress(addr oid.Address)
SetAddress specifies NeoFS address of the object.
func (*PrmObjectHead) UseKey ¶
func (x *PrmObjectHead) UseKey(key *ecdsa.PrivateKey)
UseKey specifies private key to sign the requests. If key is not provided, then Pool default key is used.
func (*PrmObjectHead) UseSession ¶
UseSession specifies session within which operation should be performed.
type PrmObjectPut ¶
type PrmObjectPut struct {
// contains filtered or unexported fields
}
PrmObjectPut groups parameters of PutObject operation.
func (*PrmObjectPut) SetHeader ¶
func (x *PrmObjectPut) SetHeader(hdr object.Object)
SetHeader specifies header of the object.
func (*PrmObjectPut) SetPayload ¶
func (x *PrmObjectPut) SetPayload(payload io.Reader)
SetPayload specifies payload of the object.
func (*PrmObjectPut) UseKey ¶
func (x *PrmObjectPut) UseKey(key *ecdsa.PrivateKey)
UseKey specifies private key to sign the requests. If key is not provided, then Pool default key is used.
func (*PrmObjectPut) UseSession ¶
UseSession specifies session within which operation should be performed.
type PrmObjectRange ¶
type PrmObjectRange struct {
// contains filtered or unexported fields
}
PrmObjectRange groups parameters of RangeObject operation.
func (*PrmObjectRange) SetAddress ¶
func (x *PrmObjectRange) SetAddress(addr oid.Address)
SetAddress specifies NeoFS address of the object.
func (*PrmObjectRange) SetLength ¶
func (x *PrmObjectRange) SetLength(length uint64)
SetLength sets length of the payload range to be read.
func (*PrmObjectRange) SetOffset ¶
func (x *PrmObjectRange) SetOffset(offset uint64)
SetOffset sets offset of the payload range to be read.
func (*PrmObjectRange) UseKey ¶
func (x *PrmObjectRange) UseKey(key *ecdsa.PrivateKey)
UseKey specifies private key to sign the requests. If key is not provided, then Pool default key is used.
func (*PrmObjectRange) UseSession ¶
UseSession specifies session within which operation should be performed.
type PrmObjectSearch ¶
type PrmObjectSearch struct {
// contains filtered or unexported fields
}
PrmObjectSearch groups parameters of SearchObjects operation.
func (*PrmObjectSearch) SetContainerID ¶
func (x *PrmObjectSearch) SetContainerID(cnrID cid.ID)
SetContainerID specifies the container in which to look for objects.
func (*PrmObjectSearch) SetFilters ¶
func (x *PrmObjectSearch) SetFilters(filters object.SearchFilters)
SetFilters specifies filters by which to select objects.
func (*PrmObjectSearch) UseKey ¶
func (x *PrmObjectSearch) UseKey(key *ecdsa.PrivateKey)
UseKey specifies private key to sign the requests. If key is not provided, then Pool default key is used.
func (*PrmObjectSearch) UseSession ¶
UseSession specifies session within which operation should be performed.
type ResGetObject ¶
type ResGetObject struct { Header object.Object Payload io.ReadCloser }
ResGetObject is designed to provide object header nad read one object payload from NeoFS system.
type ResObjectRange ¶
type ResObjectRange struct {
// contains filtered or unexported fields
}
ResObjectRange is designed to read payload range of one object from NeoFS system.
Must be initialized using Pool.ObjectRange, any other usage is unsafe.
func (*ResObjectRange) Close ¶
func (x *ResObjectRange) Close() error
Close ends reading the payload range and returns the result of the operation along with the final results. Must be called after using the ResObjectRange.
type ResObjectSearch ¶
type ResObjectSearch struct {
// contains filtered or unexported fields
}
ResObjectSearch is designed to read list of object identifiers from NeoFS system.
Must be initialized using Pool.SearchObjects, any other usage is unsafe.
func (*ResObjectSearch) Close ¶
func (x *ResObjectSearch) Close()
Close ends reading list of the matched objects and returns the result of the operation along with the final results. Must be called after using the ResObjectSearch.
type WaitParams ¶
type WaitParams struct {
// contains filtered or unexported fields
}
WaitParams contains parameters used in polling is a something applied on NeoFS network.
func (*WaitParams) SetPollInterval ¶
func (x *WaitParams) SetPollInterval(tick time.Duration)
SetPollInterval specifies the interval, once it will check the completion of the operation.
func (*WaitParams) SetTimeout ¶
func (x *WaitParams) SetTimeout(timeout time.Duration)
SetTimeout specifies the time to wait for the operation to complete.