Describe pool session management (#454)

nspcc-dev · Jul 6, 2023 · 7edf97f · 7edf97f
2 parents 6acff6a + 42e02b3
commit 7edf97f
Show file tree

Hide file tree

Showing 10 changed files with 113 additions and 162 deletions.
diff --git a/client/object_delete.go b/client/object_delete.go
@@ -10,12 +10,10 @@ import (
 	v2refs "github.com/nspcc-dev/neofs-api-go/v2/refs"
 	rpcapi "github.com/nspcc-dev/neofs-api-go/v2/rpc"
 	"github.com/nspcc-dev/neofs-api-go/v2/rpc/client"
-	v2session "github.com/nspcc-dev/neofs-api-go/v2/session"
 	"github.com/nspcc-dev/neofs-sdk-go/bearer"
 	cid "github.com/nspcc-dev/neofs-sdk-go/container/id"
 	neofscrypto "github.com/nspcc-dev/neofs-sdk-go/crypto"
 	oid "github.com/nspcc-dev/neofs-sdk-go/object/id"
-	"github.com/nspcc-dev/neofs-sdk-go/session"
 	"github.com/nspcc-dev/neofs-sdk-go/stat"
 )
 
@@ -29,42 +27,12 @@ var (
 
 // PrmObjectDelete groups optional parameters of ObjectDelete operation.
 type PrmObjectDelete struct {
-	meta v2session.RequestMetaHeader
+	sessionContainer
 
 	keySet bool
 	signer neofscrypto.Signer
 }
 
-// WithinSession specifies session within which object should be read.
-//
-// Creator of the session acquires the authorship of the request.
-// This may affect the execution of an operation (e.g. access control).
-//
-// Must be signed.
-func (x *PrmObjectDelete) WithinSession(t session.Object) {
-	var tv2 v2session.Token
-	t.WriteToV2(&tv2)
-
-	x.meta.SetSessionToken(&tv2)
-}
-
-// GetSession returns session object.
-//
-// Returns ErrNoSession err if session wasn't set.
-func (x PrmObjectDelete) GetSession() (*session.Object, error) {
-	token := x.meta.GetSessionToken()
-	if token == nil {
-		return nil, ErrNoSession
-	}
-
-	var sess session.Object
-	if err := sess.ReadFromV2(*token); err != nil {
-		return nil, err
-	}
-
-	return &sess, nil
-}
-
 // WithBearerToken attaches bearer token to be used for the operation.
 //
 // If set, underlying eACL rules will be used in access control.

diff --git a/client/object_get.go b/client/object_get.go
@@ -11,13 +11,11 @@ import (
 	v2refs "github.com/nspcc-dev/neofs-api-go/v2/refs"
 	rpcapi "github.com/nspcc-dev/neofs-api-go/v2/rpc"
 	"github.com/nspcc-dev/neofs-api-go/v2/rpc/client"
-	v2session "github.com/nspcc-dev/neofs-api-go/v2/session"
 	"github.com/nspcc-dev/neofs-sdk-go/bearer"
 	cid "github.com/nspcc-dev/neofs-sdk-go/container/id"
 	neofscrypto "github.com/nspcc-dev/neofs-sdk-go/crypto"
 	"github.com/nspcc-dev/neofs-sdk-go/object"
 	oid "github.com/nspcc-dev/neofs-sdk-go/object/id"
-	"github.com/nspcc-dev/neofs-sdk-go/session"
 	"github.com/nspcc-dev/neofs-sdk-go/stat"
 )
 
@@ -30,7 +28,7 @@ var (
 
 // shared parameters of GET/HEAD/RANGE.
 type prmObjectRead struct {
-	meta v2session.RequestMetaHeader
+	sessionContainer
 
 	raw bool
 }
@@ -53,35 +51,6 @@ func (x *prmObjectRead) MarkLocal() {
 	x.meta.SetTTL(1)
 }
 
-// WithinSession specifies session within which object should be read.
-//
-// Creator of the session acquires the authorship of the request.
-// This may affect the execution of an operation (e.g. access control).
-//
-// Must be signed.
-func (x *prmObjectRead) WithinSession(t session.Object) {
-	var tokv2 v2session.Token
-	t.WriteToV2(&tokv2)
-	x.meta.SetSessionToken(&tokv2)
-}
-
-// GetSession returns session object.
-//
-// Returns ErrNoSession err if session wasn't set.
-func (x prmObjectRead) GetSession() (*session.Object, error) {
-	token := x.meta.GetSessionToken()
-	if token == nil {
-		return nil, ErrNoSession
-	}
-
-	var sess session.Object
-	if err := sess.ReadFromV2(*token); err != nil {
-		return nil, err
-	}
-
-	return &sess, nil
-}
-
 // WithBearerToken attaches bearer token to be used for the operation.
 //
 // If set, underlying eACL rules will be used in access control.

diff --git a/client/object_hash.go b/client/object_hash.go
@@ -9,12 +9,10 @@ import (
 	v2refs "github.com/nspcc-dev/neofs-api-go/v2/refs"
 	rpcapi "github.com/nspcc-dev/neofs-api-go/v2/rpc"
 	"github.com/nspcc-dev/neofs-api-go/v2/rpc/client"
-	v2session "github.com/nspcc-dev/neofs-api-go/v2/session"
 	"github.com/nspcc-dev/neofs-sdk-go/bearer"
 	cid "github.com/nspcc-dev/neofs-sdk-go/container/id"
 	neofscrypto "github.com/nspcc-dev/neofs-sdk-go/crypto"
 	oid "github.com/nspcc-dev/neofs-sdk-go/object/id"
-	"github.com/nspcc-dev/neofs-sdk-go/session"
 	"github.com/nspcc-dev/neofs-sdk-go/stat"
 )
 
@@ -25,7 +23,7 @@ var (
 
 // PrmObjectHash groups parameters of ObjectHash operation.
 type PrmObjectHash struct {
-	meta v2session.RequestMetaHeader
+	sessionContainer
 
 	body v2object.GetRangeHashRequestBody
 
@@ -50,36 +48,6 @@ func (x *PrmObjectHash) MarkLocal() {
 	x.meta.SetTTL(1)
 }
 
-// WithinSession specifies session within which object should be read.
-//
-// Creator of the session acquires the authorship of the request.
-// This may affect the execution of an operation (e.g. access control).
-//
-// Must be signed.
-func (x *PrmObjectHash) WithinSession(t session.Object) {
-	var tv2 v2session.Token
-	t.WriteToV2(&tv2)
-
-	x.meta.SetSessionToken(&tv2)
-}
-
-// GetSession returns session object.
-//
-// Returns ErrNoSession err if session wasn't set.
-func (x PrmObjectHash) GetSession() (*session.Object, error) {
-	token := x.meta.GetSessionToken()
-	if token == nil {
-		return nil, ErrNoSession
-	}
-
-	var sess session.Object
-	if err := sess.ReadFromV2(*token); err != nil {
-		return nil, err
-	}
-
-	return &sess, nil
-}
-
 // WithBearerToken attaches bearer token to be used for the operation.
 //
 // If set, underlying eACL rules will be used in access control.

diff --git a/client/object_put.go b/client/object_put.go
@@ -10,18 +10,21 @@ import (
 	v2object "github.com/nspcc-dev/neofs-api-go/v2/object"
 	rpcapi "github.com/nspcc-dev/neofs-api-go/v2/rpc"
 	"github.com/nspcc-dev/neofs-api-go/v2/rpc/client"
-	v2session "github.com/nspcc-dev/neofs-api-go/v2/session"
 	"github.com/nspcc-dev/neofs-sdk-go/bearer"
 	cid "github.com/nspcc-dev/neofs-sdk-go/container/id"
 	neofscrypto "github.com/nspcc-dev/neofs-sdk-go/crypto"
 	"github.com/nspcc-dev/neofs-sdk-go/object"
 	oid "github.com/nspcc-dev/neofs-sdk-go/object/id"
 	"github.com/nspcc-dev/neofs-sdk-go/object/slicer"
-	"github.com/nspcc-dev/neofs-sdk-go/session"
 	"github.com/nspcc-dev/neofs-sdk-go/stat"
 	"github.com/nspcc-dev/neofs-sdk-go/user"
 )
 
+var (
+	// ErrNoSessionExplicitly is a special error to show auto-session is disabled.
+	ErrNoSessionExplicitly = errors.New("session was removed explicitly")
+)
+
 var (
 	// special variable for test purposes only, to overwrite real RPC calls.
 	rpcAPIPutObject = rpcapi.PutObject
@@ -34,9 +37,10 @@ type shortStatisticCallback func(err error)
 
 // PrmObjectPutInit groups parameters of ObjectPutInit operation.
 type PrmObjectPutInit struct {
+	sessionContainer
+
 	copyNum uint32
 	signer  neofscrypto.Signer
-	meta    v2session.RequestMetaHeader
 }
 
 // SetCopiesNumber sets number of object copies that is enough to consider put successful.
@@ -100,32 +104,6 @@ func (x *PrmObjectPutInit) WithBearerToken(t bearer.Token) {
 	x.meta.SetBearerToken(&v2token)
 }
 
-// WithinSession specifies session within which object should be stored.
-// Should be called once before any writing steps.
-func (x *PrmObjectPutInit) WithinSession(t session.Object) {
-	var tv2 v2session.Token
-	t.WriteToV2(&tv2)
-
-	x.meta.SetSessionToken(&tv2)
-}
-
-// GetSession returns session object.
-//
-// Returns ErrNoSession err if session wasn't set.
-func (x PrmObjectPutInit) GetSession() (*session.Object, error) {
-	token := x.meta.GetSessionToken()
-	if token == nil {
-		return nil, ErrNoSession
-	}
-
-	var sess session.Object
-	if err := sess.ReadFromV2(*token); err != nil {
-		return nil, err
-	}
-
-	return &sess, nil
-}
-
 // MarkLocal tells the server to execute the operation locally.
 func (x *PrmObjectPutInit) MarkLocal() {
 	x.meta.SetTTL(1)

diff --git a/client/object_search.go b/client/object_search.go
@@ -11,13 +11,11 @@ import (
 	v2refs "github.com/nspcc-dev/neofs-api-go/v2/refs"
 	rpcapi "github.com/nspcc-dev/neofs-api-go/v2/rpc"
 	"github.com/nspcc-dev/neofs-api-go/v2/rpc/client"
-	v2session "github.com/nspcc-dev/neofs-api-go/v2/session"
 	"github.com/nspcc-dev/neofs-sdk-go/bearer"
 	cid "github.com/nspcc-dev/neofs-sdk-go/container/id"
 	neofscrypto "github.com/nspcc-dev/neofs-sdk-go/crypto"
 	"github.com/nspcc-dev/neofs-sdk-go/object"
 	oid "github.com/nspcc-dev/neofs-sdk-go/object/id"
-	"github.com/nspcc-dev/neofs-sdk-go/session"
 	"github.com/nspcc-dev/neofs-sdk-go/stat"
 )
 
@@ -28,7 +26,7 @@ var (
 
 // PrmObjectSearch groups optional parameters of ObjectSearch operation.
 type PrmObjectSearch struct {
-	meta v2session.RequestMetaHeader
+	sessionContainer
 
 	signer neofscrypto.Signer
 
@@ -40,35 +38,6 @@ func (x *PrmObjectSearch) MarkLocal() {
 	x.meta.SetTTL(1)
 }
 
-// WithinSession specifies session within which the search query must be executed.
-//
-// Creator of the session acquires the authorship of the request.
-// This may affect the execution of an operation (e.g. access control).
-//
-// Must be signed.
-func (x *PrmObjectSearch) WithinSession(t session.Object) {
-	var tokv2 v2session.Token
-	t.WriteToV2(&tokv2)
-	x.meta.SetSessionToken(&tokv2)
-}
-
-// GetSession returns session object.
-//
-// Returns ErrNoSession err if session wasn't set.
-func (x PrmObjectSearch) GetSession() (*session.Object, error) {
-	token := x.meta.GetSessionToken()
-	if token == nil {
-		return nil, ErrNoSession
-	}
-
-	var sess session.Object
-	if err := sess.ReadFromV2(*token); err != nil {
-		return nil, err
-	}
-
-	return &sess, nil
-}
-
 // WithBearerToken attaches bearer token to be used for the operation.
 //
 // If set, underlying eACL rules will be used in access control.

diff --git a/client/session_container.go b/client/session_container.go
@@ -0,0 +1,59 @@
+package client
+
+import (
+	v2session "github.com/nspcc-dev/neofs-api-go/v2/session"
+	"github.com/nspcc-dev/neofs-sdk-go/session"
+)
+
+// sessionContainer is a special type which unifies session logic management for client parameters.
+// All methods make public, because sessionContainer is included in Prm* structs.
+type sessionContainer struct {
+	isSessionIgnored bool
+	meta             v2session.RequestMetaHeader
+}
+
+// GetSession returns session object.
+//
+// Returns:
+//   - [ErrNoSession] err if session wasn't set.
+//   - [ErrNoSessionExplicitly] if IgnoreSession was used.
+func (x *sessionContainer) GetSession() (*session.Object, error) {
+	if x.isSessionIgnored {
+		return nil, ErrNoSessionExplicitly
+	}
+
+	token := x.meta.GetSessionToken()
+	if token == nil {
+		return nil, ErrNoSession
+	}
+
+	var sess session.Object
+	if err := sess.ReadFromV2(*token); err != nil {
+		return nil, err
+	}
+
+	return &sess, nil
+}
+
+// WithinSession specifies session within which the query must be executed.
+//
+// Creator of the session acquires the authorship of the request.
+// This may affect the execution of an operation (e.g. access control).
+//
+// See also IgnoreSession.
+//
+// Must be signed.
+func (x *sessionContainer) WithinSession(t session.Object) {
+	var tokv2 v2session.Token
+	t.WriteToV2(&tokv2)
+	x.meta.SetSessionToken(&tokv2)
+	x.isSessionIgnored = false
+}
+
+// IgnoreSession disables auto-session creation.
+//
+// See also WithinSession.
+func (x *sessionContainer) IgnoreSession() {
+	x.isSessionIgnored = true
+	x.meta.SetSessionToken(nil)
+}
diff --git 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%.