diff --git a/pool/doc.go b/pool/doc.go index ace8a04c..a9abeb8d 100644 --- a/pool/doc.go +++ b/pool/doc.go @@ -5,6 +5,12 @@ 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. +Pool has an auto-session mechanism for object operations. It is enabled by default. +The mechanism allows to manipulate objects like upload, download, delete, etc, without explicit session passing. +This behavior may be disabled per request by calling IgnoreSession() on the appropriate Prm* argument. +Note that if auto-session is disabled, the user MUST provide the appropriate session manually for PUT and DELETE object operations. +The user may provide session, for another object operations. + 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%. diff --git a/pool/example_pool_test.go b/pool/example_pool_test.go index 7e881b4d..54e12bb4 100644 --- a/pool/example_pool_test.go +++ b/pool/example_pool_test.go @@ -5,7 +5,9 @@ import ( "crypto/elliptic" "crypto/rand" + "github.com/nspcc-dev/neofs-sdk-go/client" neofsecdsa "github.com/nspcc-dev/neofs-sdk-go/crypto/ecdsa" + "github.com/nspcc-dev/neofs-sdk-go/session" ) func ExampleNew_easiestWay() { @@ -32,3 +34,21 @@ func ExampleNew_adjustingParameters() { // ... } + +func ExamplePool_ObjectPutInit_explicitAutoSessionDisabling() { + var prm client.PrmObjectPutInit + + // If you don't provide the session manually with prm.WithinSession, the request will be executed without session. + prm.IgnoreSession() + // ... +} + +func ExamplePool_ObjectPutInit_autoSessionDisabling() { + var sess session.Object + var prm client.PrmObjectPutInit + + // Auto-session disabled, because you provided session already. + prm.WithinSession(sess) + + // ... +} diff --git a/pool/object.go b/pool/object.go index bed31bec..afb0e1f6 100644 --- a/pool/object.go +++ b/pool/object.go @@ -27,6 +27,8 @@ func (p *Pool) actualSigner(signer neofscrypto.Signer) neofscrypto.Signer { // ObjectPutInit initiates writing an object through a remote server using NeoFS API protocol. // +// Operation is executed within a session automatically created by [Pool] unless parameters explicitly override session settings. +// // See details in [client.Client.ObjectPutInit]. func (p *Pool) ObjectPutInit(ctx context.Context, hdr object.Object, prm client.PrmObjectPutInit) (*client.ObjectWriter, error) { c, err := p.sdkClient() @@ -55,6 +57,8 @@ func (p *Pool) ObjectPutInit(ctx context.Context, hdr object.Object, prm client. // ObjectGetInit initiates reading an object through a remote server using NeoFS API protocol. // +// Operation is executed within a session automatically created by [Pool] unless parameters explicitly override session settings. +// // See details in [client.Client.ObjectGetInit]. func (p *Pool) ObjectGetInit(ctx context.Context, containerID cid.ID, objectID oid.ID, prm client.PrmObjectGet) (object.Object, *client.ObjectReader, error) { var hdr object.Object @@ -78,6 +82,8 @@ func (p *Pool) ObjectGetInit(ctx context.Context, containerID cid.ID, objectID o // ObjectHead reads object header through a remote server using NeoFS API protocol. // +// Operation is executed within a session automatically created by [Pool] unless parameters explicitly override session settings. +// // See details in [client.Client.ObjectHead]. func (p *Pool) ObjectHead(ctx context.Context, containerID cid.ID, objectID oid.ID, prm client.PrmObjectHead) (*client.ResObjectHead, error) { c, err := p.sdkClient() @@ -100,6 +106,8 @@ func (p *Pool) ObjectHead(ctx context.Context, containerID cid.ID, objectID oid. // ObjectRangeInit initiates reading an object's payload range through a remote // +// Operation is executed within a session automatically created by [Pool] unless parameters explicitly override session settings. +// // See details in [client.Client.ObjectRangeInit]. func (p *Pool) ObjectRangeInit(ctx context.Context, containerID cid.ID, objectID oid.ID, offset, length uint64, prm client.PrmObjectRange) (*client.ObjectRangeReader, error) { c, err := p.sdkClient() @@ -122,6 +130,8 @@ func (p *Pool) ObjectRangeInit(ctx context.Context, containerID cid.ID, objectID // ObjectDelete marks an object for deletion from the container using NeoFS API protocol. // +// Operation is executed within a session automatically created by [Pool] unless parameters explicitly override session settings. +// // See details in [client.Client.ObjectDelete]. func (p *Pool) ObjectDelete(ctx context.Context, containerID cid.ID, objectID oid.ID, prm client.PrmObjectDelete) (oid.ID, error) { c, err := p.sdkClient() @@ -144,6 +154,8 @@ func (p *Pool) ObjectDelete(ctx context.Context, containerID cid.ID, objectID oi // ObjectHash requests checksum of the range list of the object payload using // +// Operation is executed within a session automatically created by [Pool] unless parameters explicitly override session settings. +// // See details in [client.Client.ObjectHash]. func (p *Pool) ObjectHash(ctx context.Context, containerID cid.ID, objectID oid.ID, prm client.PrmObjectHash) ([][]byte, error) { c, err := p.sdkClient() @@ -166,6 +178,8 @@ func (p *Pool) ObjectHash(ctx context.Context, containerID cid.ID, objectID oid. // ObjectSearchInit initiates object selection through a remote server using NeoFS API protocol. // +// Operation is executed within a session automatically created by [Pool] unless parameters explicitly override session settings. +// // See details in [client.Client.ObjectSearchInit]. func (p *Pool) ObjectSearchInit(ctx context.Context, containerID cid.ID, prm client.PrmObjectSearch) (*client.ObjectListReader, error) { c, err := p.sdkClient()