From 883a26d210f31cc3baaf753a249a42a1cb58844c Mon Sep 17 00:00:00 2001 From: Leonard Lyubich Date: Mon, 24 Jan 2022 13:33:43 +0300 Subject: [PATCH] [#92] client: Add docs about status returns Signed-off-by: Leonard Lyubich --- client/accounting.go | 5 +++-- client/client.go | 10 ++++++++++ client/container.go | 36 +++++++++++++++++++++++------------- client/netmap.go | 6 ++++++ client/reputation.go | 10 ++++++---- client/session.go | 5 +++-- 6 files changed, 51 insertions(+), 21 deletions(-) diff --git a/client/accounting.go b/client/accounting.go index e9ea673a..d388de46 100644 --- a/client/accounting.go +++ b/client/accounting.go @@ -43,6 +43,7 @@ func (x GetBalanceRes) Amount() *accounting.Decimal { // GetBalance requests current balance of the NeoFS account. // +// Exactly one return value is non-nil. By default, server status is returned in res structure. // Any client's internal or transport errors are returned as `error`, // If WithNeoFSErrorParsing option has been provided, unsuccessful // NeoFS status codes are returned as `error`, otherwise, are included @@ -51,8 +52,8 @@ func (x GetBalanceRes) Amount() *accounting.Decimal { // Immediately panics if parameters are set incorrectly (see GetBalancePrm docs). // Context is required and must not be nil. It is used for network communication. // -// Exactly one return value is non-nil. Server status return is returned in GetBalanceRes. -// Reflects all internal errors in second return value (transport problems, response processing, etc.). +// Return statuses: +// - global (see Client docs). func (c *Client) GetBalance(ctx context.Context, prm GetBalancePrm) (*GetBalanceRes, error) { switch { case ctx == nil: diff --git a/client/client.go b/client/client.go index e9372fb3..7ac01491 100644 --- a/client/client.go +++ b/client/client.go @@ -14,6 +14,16 @@ import ( // Using the Client that has been created with new(Client) // expression (or just declaring a Client variable) is unsafe // and can lead to panic. +// +// Each method which produces a NeoFS API call may return a server response. +// Status responses are returned in the result structure, and can be cast +// to built-in error instance (or in the returned error if the client is +// configured accordingly). Certain statuses can be checked using `apistatus` +// and standard `errors` packages. +// All possible responses are documented in methods, however, some may be +// returned from all of them (pay attention to the presence of the pointer sign): +// - *apistatus.ServerInternal on internal server error; +// - *apistatus.SuccessDefaultV2 on default success. type Client struct { raw *client.Client diff --git a/client/container.go b/client/container.go index d0909e8f..cba52a06 100644 --- a/client/container.go +++ b/client/container.go @@ -55,6 +55,7 @@ func (x *ContainerPutRes) setID(id *cid.ID) { // PutContainer sends request to save container in NeoFS. // +// Exactly one return value is non-nil. By default, server status is returned in res structure. // Any client's internal or transport errors are returned as `error`. // If WithNeoFSErrorParsing option has been provided, unsuccessful // NeoFS status codes are returned as `error`, otherwise, are included @@ -68,8 +69,8 @@ func (x *ContainerPutRes) setID(id *cid.ID) { // Immediately panics if parameters are set incorrectly (see ContainerPutPrm docs). // Context is required and must not be nil. It is used for network communication. // -// Exactly one return value is non-nil. Server status return is returned in ContainerPutRes. -// Reflects all internal errors in second return value (transport problems, response processing, etc.). +// Return statuses: +// - global (see Client docs). func (c *Client) PutContainer(ctx context.Context, prm ContainerPutPrm) (*ContainerPutRes, error) { // check parameters switch { @@ -166,8 +167,9 @@ func (x *ContainerGetRes) setContainer(cnr *container.Container) { x.cnr = cnr } -// GetContainer reads NeoFS container from by ID. +// GetContainer reads NeoFS container by ID. // +// Exactly one return value is non-nil. By default, server status is returned in res structure. // Any client's internal or transport errors are returned as `error`. // If WithNeoFSErrorParsing option has been provided, unsuccessful // NeoFS status codes are returned as `error`, otherwise, are included @@ -176,8 +178,8 @@ func (x *ContainerGetRes) setContainer(cnr *container.Container) { // Immediately panics if parameters are set incorrectly (see ContainerGetPrm docs). // Context is required and must not be nil. It is used for network communication. // -// Exactly one return value is non-nil. Server status return is returned in ContainerGetRes. -// Reflects all internal errors in second return value (transport problems, response processing, etc.). +// Return statuses: +// - global (see Client docs). func (c *Client) GetContainer(ctx context.Context, prm ContainerGetPrm) (*ContainerGetRes, error) { switch { case ctx == nil: @@ -267,6 +269,7 @@ func (x *ContainerListRes) setContainers(ids []*cid.ID) { // ListContainers requests identifiers of the account-owned containers. // +// Exactly one return value is non-nil. By default, server status is returned in res structure. // Any client's internal or transport errors are returned as `error`. // If WithNeoFSErrorParsing option has been provided, unsuccessful // NeoFS status codes are returned as `error`, otherwise, are included @@ -275,8 +278,8 @@ func (x *ContainerListRes) setContainers(ids []*cid.ID) { // Immediately panics if parameters are set incorrectly (see ContainerListPrm docs). // Context is required and must not be nil. It is used for network communication. // -// Exactly one return value is non-nil. Server status return is returned in ContainerListRes. -// Reflects all internal errors in second return value (transport problems, response processing, etc.). +// Return statuses: +// - global (see Client docs). func (c *Client) ListContainers(ctx context.Context, prm ContainerListPrm) (*ContainerListRes, error) { // check parameters switch { @@ -365,6 +368,7 @@ func (c delContainerSignWrapper) SignedDataSize() int { // DeleteContainer sends request to remove the NeoFS container. // +// Exactly one return value is non-nil. By default, server status is returned in res structure. // Any client's internal or transport errors are returned as `error`. // If WithNeoFSErrorParsing option has been provided, unsuccessful // NeoFS status codes are returned as `error`, otherwise, are included @@ -380,6 +384,9 @@ func (c delContainerSignWrapper) SignedDataSize() int { // // Exactly one return value is non-nil. Server status return is returned in ContainerDeleteRes. // Reflects all internal errors in second return value (transport problems, response processing, etc.). +// +// Return statuses: +// - global (see Client docs). func (c *Client) DeleteContainer(ctx context.Context, prm ContainerDeletePrm) (*ContainerDeleteRes, error) { // check parameters switch { @@ -475,6 +482,7 @@ func (x *EACLRes) setTable(table *eacl.Table) { // EACL reads eACL table of the NeoFS container. // +// Exactly one return value is non-nil. By default, server status is returned in res structure. // Any client's internal or transport errors are returned as `error`. // If WithNeoFSErrorParsing option has been provided, unsuccessful // NeoFS status codes are returned as `error`, otherwise, are included @@ -483,8 +491,8 @@ func (x *EACLRes) setTable(table *eacl.Table) { // Immediately panics if parameters are set incorrectly (see EACLPrm docs). // Context is required and must not be nil. It is used for network communication. // -// Exactly one return value is non-nil. Server status return is returned in EACLRes. -// Reflects all internal errors in second return value (transport problems, response processing, etc.). +// Return statuses: +// - global (see Client docs). func (c *Client) EACL(ctx context.Context, prm EACLPrm) (*EACLRes, error) { // check parameters switch { @@ -564,6 +572,7 @@ type SetEACLRes struct { // SetEACL sends request to update eACL table of the NeoFS container. // +// Exactly one return value is non-nil. By default, server status is returned in res structure. // Any client's internal or transport errors are returned as `error`. // If WithNeoFSErrorParsing option has been provided, unsuccessful // NeoFS status codes are returned as `error`, otherwise, are included @@ -577,8 +586,8 @@ type SetEACLRes struct { // Immediately panics if parameters are set incorrectly (see SetEACLPrm docs). // Context is required and must not be nil. It is used for network communication. // -// Exactly one return value is non-nil. Server status return is returned in ContainerDeleteRes. -// Reflects all internal errors in second return value (transport problems, response processing, etc.). +// Return statuses: +// - global (see Client docs). func (c *Client) SetEACL(ctx context.Context, prm SetEACLPrm) (*SetEACLRes, error) { // check parameters switch { @@ -658,6 +667,7 @@ type AnnounceSpaceRes struct { // AnnounceContainerUsedSpace sends request to announce volume of the space used for the container objects. // +// Exactly one return value is non-nil. By default, server status is returned in res structure. // Any client's internal or transport errors are returned as `error`. // If WithNeoFSErrorParsing option has been provided, unsuccessful // NeoFS status codes are returned as `error`, otherwise, are included @@ -671,8 +681,8 @@ type AnnounceSpaceRes struct { // Immediately panics if parameters are set incorrectly (see AnnounceSpacePrm docs). // Context is required and must not be nil. It is used for network communication. // -// Exactly one return value is non-nil. Server status return is returned in AnnounceSpaceRes. -// Reflects all internal errors in second return value (transport problems, response processing, etc.). +// Return statuses: +// - global (see Client docs). func (c *Client) AnnounceContainerUsedSpace(ctx context.Context, prm AnnounceSpacePrm) (*AnnounceSpaceRes, error) { // check parameters switch { diff --git a/client/netmap.go b/client/netmap.go index 0edfe88e..dddefa38 100644 --- a/client/netmap.go +++ b/client/netmap.go @@ -61,6 +61,9 @@ func (x *EndpointInfoRes) setNodeInfo(info *netmap.NodeInfo) { // // Exactly one return value is non-nil. Server status return is returned in EndpointInfoRes. // Reflects all internal errors in second return value (transport problems, response processing, etc.). +// +// Return statuses: +// - global (see Client docs). func (c *Client) EndpointInfo(ctx context.Context, _ EndpointInfoPrm) (*EndpointInfoRes, error) { // check context if ctx == nil { @@ -136,6 +139,9 @@ func (x *NetworkInfoRes) setInfo(info *netmap.NetworkInfo) { // // Exactly one return value is non-nil. Server status return is returned in NetworkInfoRes. // Reflects all internal errors in second return value (transport problems, response processing, etc.). +// +// Return statuses: +// - global (see Client docs). func (c *Client) NetworkInfo(ctx context.Context, _ NetworkInfoPrm) (*NetworkInfoRes, error) { // check context if ctx == nil { diff --git a/client/reputation.go b/client/reputation.go index 1c53a0a1..1a16eee7 100644 --- a/client/reputation.go +++ b/client/reputation.go @@ -37,6 +37,7 @@ type AnnounceLocalTrustRes struct { // AnnounceLocalTrust sends client's trust values to the NeoFS network participants. // +// Exactly one return value is non-nil. By default, server status is returned in res structure. // Any client's internal or transport errors are returned as `error`. // If WithNeoFSErrorParsing option has been provided, unsuccessful // NeoFS status codes are returned as `error`, otherwise, are included @@ -45,8 +46,8 @@ type AnnounceLocalTrustRes struct { // Immediately panics if parameters are set incorrectly (see AnnounceLocalTrustPrm docs). // Context is required and must not be nil. It is used for network communication. // -// Exactly one return value is non-nil. Server status return is returned in AnnounceLocalTrustRes. -// Reflects all internal errors in second return value (transport problems, response processing, etc.). +// Return statuses: +// - global (see Client docs). func (c *Client) AnnounceLocalTrust(ctx context.Context, prm AnnounceLocalTrustPrm) (*AnnounceLocalTrustRes, error) { // check parameters switch { @@ -134,6 +135,7 @@ type AnnounceIntermediateTrustRes struct { // AnnounceIntermediateTrust sends global trust values calculated for the specified NeoFS network participants // at some stage of client's calculation algorithm. // +// Exactly one return value is non-nil. By default, server status is returned in res structure. // Any client's internal or transport errors are returned as `error`. // If WithNeoFSErrorParsing option has been provided, unsuccessful // NeoFS status codes are returned as `error`, otherwise, are included @@ -142,8 +144,8 @@ type AnnounceIntermediateTrustRes struct { // Immediately panics if parameters are set incorrectly (see AnnounceIntermediateTrustPrm docs). // Context is required and must not be nil. It is used for network communication. // -// Exactly one return value is non-nil. Server status return is returned in AnnounceIntermediateTrustRes. -// Reflects all internal errors in second return value (transport problems, response processing, etc.). +// Return statuses: +// - global (see Client docs). func (c *Client) AnnounceIntermediateTrust(ctx context.Context, prm AnnounceIntermediateTrustPrm) (*AnnounceIntermediateTrustRes, error) { // check parameters switch { diff --git a/client/session.go b/client/session.go index 65d0051c..31858e7b 100644 --- a/client/session.go +++ b/client/session.go @@ -52,6 +52,7 @@ func (x CreateSessionRes) PublicKey() []byte { // The session lifetime coincides with the server lifetime. Results can be written // to session token which can be later attached to the requests. // +// Exactly one return value is non-nil. By default, server status is returned in res structure. // Any client's internal or transport errors are returned as `error`. // If WithNeoFSErrorParsing option has been provided, unsuccessful // NeoFS status codes are returned as `error`, otherwise, are included @@ -60,8 +61,8 @@ func (x CreateSessionRes) PublicKey() []byte { // Immediately panics if parameters are set incorrectly (see CreateSessionPrm docs). // Context is required and must not be nil. It is used for network communication. // -// Exactly one return value is non-nil. Server status return is returned in CreateSessionRes. -// Reflects all internal errors in second return value (transport problems, response processing, etc.). +// Return statuses: +// - global (see Client docs). func (c *Client) CreateSession(ctx context.Context, prm CreateSessionPrm) (*CreateSessionRes, error) { // check context if ctx == nil {