forked from TrueCloudLab/frostfs-sdk-go
[#92] client: Add docs about status returns
Signed-off-by: Leonard Lyubich <leonard@nspcc.ru>
This commit is contained in:
parent
213d20e3fb
commit
883a26d210
6 changed files with 51 additions and 21 deletions
|
@ -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:
|
||||
|
|
|
@ -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
|
||||
|
||||
|
|
|
@ -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 {
|
||||
|
|
|
@ -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 {
|
||||
|
|
|
@ -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 {
|
||||
|
|
|
@ -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 {
|
||||
|
|
Loading…
Reference in a new issue