[#92] client: Add docs about status returns

Signed-off-by: Leonard Lyubich <leonard@nspcc.ru>
This commit is contained in:
Leonard Lyubich 2022-01-24 13:33:43 +03:00 committed by Alex Vanin
parent 213d20e3fb
commit 883a26d210
6 changed files with 51 additions and 21 deletions

View file

@ -43,6 +43,7 @@ func (x GetBalanceRes) Amount() *accounting.Decimal {
// GetBalance requests current balance of the NeoFS account. // 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`, // Any client's internal or transport errors are returned as `error`,
// If WithNeoFSErrorParsing option has been provided, unsuccessful // If WithNeoFSErrorParsing option has been provided, unsuccessful
// NeoFS status codes are returned as `error`, otherwise, are included // 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). // Immediately panics if parameters are set incorrectly (see GetBalancePrm docs).
// Context is required and must not be nil. It is used for network communication. // 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. // Return statuses:
// Reflects all internal errors in second return value (transport problems, response processing, etc.). // - global (see Client docs).
func (c *Client) GetBalance(ctx context.Context, prm GetBalancePrm) (*GetBalanceRes, error) { func (c *Client) GetBalance(ctx context.Context, prm GetBalancePrm) (*GetBalanceRes, error) {
switch { switch {
case ctx == nil: case ctx == nil:

View file

@ -14,6 +14,16 @@ import (
// Using the Client that has been created with new(Client) // Using the Client that has been created with new(Client)
// expression (or just declaring a Client variable) is unsafe // expression (or just declaring a Client variable) is unsafe
// and can lead to panic. // 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 { type Client struct {
raw *client.Client raw *client.Client

View file

@ -55,6 +55,7 @@ func (x *ContainerPutRes) setID(id *cid.ID) {
// PutContainer sends request to save container in NeoFS. // 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`. // Any client's internal or transport errors are returned as `error`.
// If WithNeoFSErrorParsing option has been provided, unsuccessful // If WithNeoFSErrorParsing option has been provided, unsuccessful
// NeoFS status codes are returned as `error`, otherwise, are included // 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). // Immediately panics if parameters are set incorrectly (see ContainerPutPrm docs).
// Context is required and must not be nil. It is used for network communication. // 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. // Return statuses:
// Reflects all internal errors in second return value (transport problems, response processing, etc.). // - global (see Client docs).
func (c *Client) PutContainer(ctx context.Context, prm ContainerPutPrm) (*ContainerPutRes, error) { func (c *Client) PutContainer(ctx context.Context, prm ContainerPutPrm) (*ContainerPutRes, error) {
// check parameters // check parameters
switch { switch {
@ -166,8 +167,9 @@ func (x *ContainerGetRes) setContainer(cnr *container.Container) {
x.cnr = cnr 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`. // Any client's internal or transport errors are returned as `error`.
// If WithNeoFSErrorParsing option has been provided, unsuccessful // If WithNeoFSErrorParsing option has been provided, unsuccessful
// NeoFS status codes are returned as `error`, otherwise, are included // 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). // Immediately panics if parameters are set incorrectly (see ContainerGetPrm docs).
// Context is required and must not be nil. It is used for network communication. // 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. // Return statuses:
// Reflects all internal errors in second return value (transport problems, response processing, etc.). // - global (see Client docs).
func (c *Client) GetContainer(ctx context.Context, prm ContainerGetPrm) (*ContainerGetRes, error) { func (c *Client) GetContainer(ctx context.Context, prm ContainerGetPrm) (*ContainerGetRes, error) {
switch { switch {
case ctx == nil: case ctx == nil:
@ -267,6 +269,7 @@ func (x *ContainerListRes) setContainers(ids []*cid.ID) {
// ListContainers requests identifiers of the account-owned containers. // 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`. // Any client's internal or transport errors are returned as `error`.
// If WithNeoFSErrorParsing option has been provided, unsuccessful // If WithNeoFSErrorParsing option has been provided, unsuccessful
// NeoFS status codes are returned as `error`, otherwise, are included // 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). // Immediately panics if parameters are set incorrectly (see ContainerListPrm docs).
// Context is required and must not be nil. It is used for network communication. // 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. // Return statuses:
// Reflects all internal errors in second return value (transport problems, response processing, etc.). // - global (see Client docs).
func (c *Client) ListContainers(ctx context.Context, prm ContainerListPrm) (*ContainerListRes, error) { func (c *Client) ListContainers(ctx context.Context, prm ContainerListPrm) (*ContainerListRes, error) {
// check parameters // check parameters
switch { switch {
@ -365,6 +368,7 @@ func (c delContainerSignWrapper) SignedDataSize() int {
// DeleteContainer sends request to remove the NeoFS container. // 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`. // Any client's internal or transport errors are returned as `error`.
// If WithNeoFSErrorParsing option has been provided, unsuccessful // If WithNeoFSErrorParsing option has been provided, unsuccessful
// NeoFS status codes are returned as `error`, otherwise, are included // 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. // 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.). // 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) { func (c *Client) DeleteContainer(ctx context.Context, prm ContainerDeletePrm) (*ContainerDeleteRes, error) {
// check parameters // check parameters
switch { switch {
@ -475,6 +482,7 @@ func (x *EACLRes) setTable(table *eacl.Table) {
// EACL reads eACL table of the NeoFS container. // 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`. // Any client's internal or transport errors are returned as `error`.
// If WithNeoFSErrorParsing option has been provided, unsuccessful // If WithNeoFSErrorParsing option has been provided, unsuccessful
// NeoFS status codes are returned as `error`, otherwise, are included // 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). // Immediately panics if parameters are set incorrectly (see EACLPrm docs).
// Context is required and must not be nil. It is used for network communication. // 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. // Return statuses:
// Reflects all internal errors in second return value (transport problems, response processing, etc.). // - global (see Client docs).
func (c *Client) EACL(ctx context.Context, prm EACLPrm) (*EACLRes, error) { func (c *Client) EACL(ctx context.Context, prm EACLPrm) (*EACLRes, error) {
// check parameters // check parameters
switch { switch {
@ -564,6 +572,7 @@ type SetEACLRes struct {
// SetEACL sends request to update eACL table of the NeoFS container. // 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`. // Any client's internal or transport errors are returned as `error`.
// If WithNeoFSErrorParsing option has been provided, unsuccessful // If WithNeoFSErrorParsing option has been provided, unsuccessful
// NeoFS status codes are returned as `error`, otherwise, are included // 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). // Immediately panics if parameters are set incorrectly (see SetEACLPrm docs).
// Context is required and must not be nil. It is used for network communication. // 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. // Return statuses:
// Reflects all internal errors in second return value (transport problems, response processing, etc.). // - global (see Client docs).
func (c *Client) SetEACL(ctx context.Context, prm SetEACLPrm) (*SetEACLRes, error) { func (c *Client) SetEACL(ctx context.Context, prm SetEACLPrm) (*SetEACLRes, error) {
// check parameters // check parameters
switch { switch {
@ -658,6 +667,7 @@ type AnnounceSpaceRes struct {
// AnnounceContainerUsedSpace sends request to announce volume of the space used for the container objects. // 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`. // Any client's internal or transport errors are returned as `error`.
// If WithNeoFSErrorParsing option has been provided, unsuccessful // If WithNeoFSErrorParsing option has been provided, unsuccessful
// NeoFS status codes are returned as `error`, otherwise, are included // 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). // Immediately panics if parameters are set incorrectly (see AnnounceSpacePrm docs).
// Context is required and must not be nil. It is used for network communication. // 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. // Return statuses:
// Reflects all internal errors in second return value (transport problems, response processing, etc.). // - global (see Client docs).
func (c *Client) AnnounceContainerUsedSpace(ctx context.Context, prm AnnounceSpacePrm) (*AnnounceSpaceRes, error) { func (c *Client) AnnounceContainerUsedSpace(ctx context.Context, prm AnnounceSpacePrm) (*AnnounceSpaceRes, error) {
// check parameters // check parameters
switch { switch {

View file

@ -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. // 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.). // 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) { func (c *Client) EndpointInfo(ctx context.Context, _ EndpointInfoPrm) (*EndpointInfoRes, error) {
// check context // check context
if ctx == nil { 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. // 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.). // 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) { func (c *Client) NetworkInfo(ctx context.Context, _ NetworkInfoPrm) (*NetworkInfoRes, error) {
// check context // check context
if ctx == nil { if ctx == nil {

View file

@ -37,6 +37,7 @@ type AnnounceLocalTrustRes struct {
// AnnounceLocalTrust sends client's trust values to the NeoFS network participants. // 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`. // Any client's internal or transport errors are returned as `error`.
// If WithNeoFSErrorParsing option has been provided, unsuccessful // If WithNeoFSErrorParsing option has been provided, unsuccessful
// NeoFS status codes are returned as `error`, otherwise, are included // 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). // Immediately panics if parameters are set incorrectly (see AnnounceLocalTrustPrm docs).
// Context is required and must not be nil. It is used for network communication. // 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. // Return statuses:
// Reflects all internal errors in second return value (transport problems, response processing, etc.). // - global (see Client docs).
func (c *Client) AnnounceLocalTrust(ctx context.Context, prm AnnounceLocalTrustPrm) (*AnnounceLocalTrustRes, error) { func (c *Client) AnnounceLocalTrust(ctx context.Context, prm AnnounceLocalTrustPrm) (*AnnounceLocalTrustRes, error) {
// check parameters // check parameters
switch { switch {
@ -134,6 +135,7 @@ type AnnounceIntermediateTrustRes struct {
// AnnounceIntermediateTrust sends global trust values calculated for the specified NeoFS network participants // AnnounceIntermediateTrust sends global trust values calculated for the specified NeoFS network participants
// at some stage of client's calculation algorithm. // 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`. // Any client's internal or transport errors are returned as `error`.
// If WithNeoFSErrorParsing option has been provided, unsuccessful // If WithNeoFSErrorParsing option has been provided, unsuccessful
// NeoFS status codes are returned as `error`, otherwise, are included // 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). // Immediately panics if parameters are set incorrectly (see AnnounceIntermediateTrustPrm docs).
// Context is required and must not be nil. It is used for network communication. // 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. // Return statuses:
// Reflects all internal errors in second return value (transport problems, response processing, etc.). // - global (see Client docs).
func (c *Client) AnnounceIntermediateTrust(ctx context.Context, prm AnnounceIntermediateTrustPrm) (*AnnounceIntermediateTrustRes, error) { func (c *Client) AnnounceIntermediateTrust(ctx context.Context, prm AnnounceIntermediateTrustPrm) (*AnnounceIntermediateTrustRes, error) {
// check parameters // check parameters
switch { switch {

View file

@ -52,6 +52,7 @@ func (x CreateSessionRes) PublicKey() []byte {
// The session lifetime coincides with the server lifetime. Results can be written // The session lifetime coincides with the server lifetime. Results can be written
// to session token which can be later attached to the requests. // 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`. // Any client's internal or transport errors are returned as `error`.
// If WithNeoFSErrorParsing option has been provided, unsuccessful // If WithNeoFSErrorParsing option has been provided, unsuccessful
// NeoFS status codes are returned as `error`, otherwise, are included // 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). // Immediately panics if parameters are set incorrectly (see CreateSessionPrm docs).
// Context is required and must not be nil. It is used for network communication. // 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. // Return statuses:
// Reflects all internal errors in second return value (transport problems, response processing, etc.). // - global (see Client docs).
func (c *Client) CreateSession(ctx context.Context, prm CreateSessionPrm) (*CreateSessionRes, error) { func (c *Client) CreateSession(ctx context.Context, prm CreateSessionPrm) (*CreateSessionRes, error) {
// check context // check context
if ctx == nil { if ctx == nil {