pool: Add documentation for auto-session mechanism

Signed-off-by: Evgenii Baidakov <[email protected]>

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%.

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)
+
+	// ...
+}

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()