[#961] client: Clarify error returns in docs

Signed-off-by: Leonard Lyubich <leonard@nspcc.ru>
This commit is contained in:
Leonard Lyubich 2021-11-03 20:13:16 +03:00 committed by LeL
parent 378474b02c
commit 44d0d453ef
4 changed files with 63 additions and 1 deletions

View file

@ -34,6 +34,8 @@ func (x BalanceOfRes) Balance() *accounting.Decimal {
} }
// BalanceOf requests current balance of NeoFS user. // BalanceOf requests current balance of NeoFS user.
//
// Returns any error prevented the operation from completing correctly in error return.
func BalanceOf(prm BalanceOfPrm) (res BalanceOfRes, err error) { func BalanceOf(prm BalanceOfPrm) (res BalanceOfRes, err error) {
res.cliRes, err = prm.cli.GetBalance(context.Background(), prm.ownerID, res.cliRes, err = prm.cli.GetBalance(context.Background(), prm.ownerID,
client.WithKey(prm.privKey), client.WithKey(prm.privKey),
@ -59,6 +61,8 @@ func (x ListContainersRes) IDList() []*cid.ID {
} }
// ListContainers requests list of NeoFS user's containers. // ListContainers requests list of NeoFS user's containers.
//
// Returns any error prevented the operation from completing correctly in error return.
func ListContainers(prm ListContainersPrm) (res ListContainersRes, err error) { func ListContainers(prm ListContainersPrm) (res ListContainersRes, err error) {
res.cliRes, err = prm.cli.ListContainers(context.Background(), prm.ownerID, res.cliRes, err = prm.cli.ListContainers(context.Background(), prm.ownerID,
client.WithKey(prm.privKey), client.WithKey(prm.privKey),
@ -96,6 +100,8 @@ func (x PutContainerRes) ID() *cid.ID {
// The required time is also not predictable. // The required time is also not predictable.
// //
// Success can be verified by reading by identifier. // Success can be verified by reading by identifier.
//
// Returns any error prevented the operation from completing correctly in error return.
func PutContainer(prm PutContainerPrm) (res PutContainerRes, err error) { func PutContainer(prm PutContainerPrm) (res PutContainerRes, err error) {
res.cliRes, err = prm.cli.PutContainer(context.Background(), prm.cnr, res.cliRes, err = prm.cli.PutContainer(context.Background(), prm.cnr,
client.WithKey(prm.privKey), client.WithKey(prm.privKey),
@ -122,6 +128,8 @@ func (x GetContainerRes) Container() *container.Container {
} }
// GetContainer reads container from NeoFS by ID. // GetContainer reads container from NeoFS by ID.
//
// Returns any error prevented the operation from completing correctly in error return.
func GetContainer(prm GetContainerPrm) (res GetContainerRes, err error) { func GetContainer(prm GetContainerPrm) (res GetContainerRes, err error) {
res.cliRes, err = prm.cli.GetContainer(context.Background(), prm.cnrID, res.cliRes, err = prm.cli.GetContainer(context.Background(), prm.cnrID,
client.WithKey(prm.privKey), client.WithKey(prm.privKey),
@ -146,6 +154,8 @@ type DeleteContainerRes struct{}
// The required time is also not predictable. // The required time is also not predictable.
// //
// Success can be verified by reading by identifier. // Success can be verified by reading by identifier.
//
// Returns any error prevented the operation from completing correctly in error return.
func DeleteContainer(prm DeleteContainerPrm) (res DeleteContainerRes, err error) { func DeleteContainer(prm DeleteContainerPrm) (res DeleteContainerRes, err error) {
err = prm.cli.DeleteContainer(context.Background(), prm.cnrID, err = prm.cli.DeleteContainer(context.Background(), prm.cnrID,
client.WithKey(prm.privKey), client.WithKey(prm.privKey),
@ -172,6 +182,8 @@ func (x EACLRes) EACL() *eacl.Table {
} }
// EACL reads eACL table from NeoFS by container ID. // EACL reads eACL table from NeoFS by container ID.
//
// Returns any error prevented the operation from completing correctly in error return.
func EACL(prm EACLPrm) (res EACLRes, err error) { func EACL(prm EACLPrm) (res EACLRes, err error) {
res.cliRes, err = prm.cli.GetEACL(context.Background(), prm.cnrID, res.cliRes, err = prm.cli.GetEACL(context.Background(), prm.cnrID,
client.WithKey(prm.privKey), client.WithKey(prm.privKey),
@ -202,6 +214,8 @@ type SetEACLRes struct{}
// The required time is also not predictable. // The required time is also not predictable.
// //
// Success can be verified by reading by container identifier. // Success can be verified by reading by container identifier.
//
// Returns any error prevented the operation from completing correctly in error return.
func SetEACL(prm SetEACLPrm) (res SetEACLRes, err error) { func SetEACL(prm SetEACLPrm) (res SetEACLRes, err error) {
err = prm.cli.SetEACL(context.Background(), prm.eaclTable, err = prm.cli.SetEACL(context.Background(), prm.eaclTable,
client.WithKey(prm.privKey), client.WithKey(prm.privKey),
@ -227,6 +241,8 @@ func (x NetworkInfoRes) NetworkInfo() *netmap.NetworkInfo {
} }
// NetworkInfo reads information about the NeoFS network. // NetworkInfo reads information about the NeoFS network.
//
// Returns any error prevented the operation from completing correctly in error return.
func NetworkInfo(prm NetworkInfoPrm) (res NetworkInfoRes, err error) { func NetworkInfo(prm NetworkInfoPrm) (res NetworkInfoRes, err error) {
res.cliRes, err = prm.cli.NetworkInfo(context.Background(), res.cliRes, err = prm.cli.NetworkInfo(context.Background(),
client.WithKey(prm.privKey), client.WithKey(prm.privKey),
@ -256,6 +272,8 @@ func (x NodeInfoRes) LatestVersion() *version.Version {
} }
// NodeInfo requests information about the remote server from NeoFS netmap. // NodeInfo requests information about the remote server from NeoFS netmap.
//
// Returns any error prevented the operation from completing correctly in error return.
func NodeInfo(prm NodeInfoPrm) (res NodeInfoRes, err error) { func NodeInfo(prm NodeInfoPrm) (res NodeInfoRes, err error) {
res.cliRes, err = prm.cli.EndpointInfo(context.Background(), res.cliRes, err = prm.cli.EndpointInfo(context.Background(),
client.WithKey(prm.privKey), client.WithKey(prm.privKey),
@ -285,6 +303,8 @@ func (x CreateSessionRes) SessionKey() []byte {
} }
// CreateSession opens new unlimited session with the remote node. // CreateSession opens new unlimited session with the remote node.
//
// Returns any error prevented the operation from completing correctly in error return.
func CreateSession(prm CreateSessionPrm) (res CreateSessionRes, err error) { func CreateSession(prm CreateSessionPrm) (res CreateSessionRes, err error) {
res.cliRes, err = prm.cli.CreateSession(context.Background(), math.MaxUint64, res.cliRes, err = prm.cli.CreateSession(context.Background(), math.MaxUint64,
client.WithKey(prm.privKey), client.WithKey(prm.privKey),
@ -323,6 +343,8 @@ func (x PutObjectRes) ID() *object.ID {
} }
// PutObject saves the object in NeoFS network. // PutObject saves the object in NeoFS network.
//
// Returns any error prevented the operation from completing correctly in error return.
func PutObject(prm PutObjectPrm) (res PutObjectRes, err error) { func PutObject(prm PutObjectPrm) (res PutObjectRes, err error) {
var putPrm client.PutObjectParams var putPrm client.PutObjectParams
@ -355,6 +377,8 @@ func (x DeleteObjectRes) TombstoneAddress() *object.Address {
} }
// DeleteObject marks object to be removed from NeoFS through tombstone placement. // DeleteObject marks object to be removed from NeoFS through tombstone placement.
//
// Returns any error prevented the operation from completing correctly in error return.
func DeleteObject(prm DeleteObjectPrm) (res DeleteObjectRes, err error) { func DeleteObject(prm DeleteObjectPrm) (res DeleteObjectRes, err error) {
var delPrm client.DeleteObjectParams var delPrm client.DeleteObjectParams
@ -390,6 +414,9 @@ func (x GetObjectRes) Header() *object.Object {
// GetObject reads the object by address. // GetObject reads the object by address.
// //
// Interrupts on any writer error. If successful, payload is written to writer. // Interrupts on any writer error. If successful, payload is written to writer.
//
// Returns any error prevented the operation from completing correctly in error return.
// For raw reading, returns *object.SplitInfoError error if object is virtual.
func GetObject(prm GetObjectPrm) (res GetObjectRes, err error) { func GetObject(prm GetObjectPrm) (res GetObjectRes, err error) {
var getPrm client.GetObjectParams var getPrm client.GetObjectParams
@ -432,6 +459,7 @@ func (x HeadObjectRes) Header() *object.Object {
// HeadObject reads object header by address. // HeadObject reads object header by address.
// //
// Returns any error prevented the operation from completing correctly in error return.
// For raw reading, returns *object.SplitInfoError error if object is virtual. // For raw reading, returns *object.SplitInfoError error if object is virtual.
func HeadObject(prm HeadObjectPrm) (res HeadObjectRes, err error) { func HeadObject(prm HeadObjectPrm) (res HeadObjectRes, err error) {
var cliPrm client.ObjectHeaderParams var cliPrm client.ObjectHeaderParams
@ -478,6 +506,8 @@ func (x SearchObjectsRes) IDList() []*object.ID {
} }
// SearchObjects selects objects from container which match the filters. // SearchObjects selects objects from container which match the filters.
//
// Returns any error prevented the operation from completing correctly in error return.
func SearchObjects(prm SearchObjectsPrm) (res SearchObjectsRes, err error) { func SearchObjects(prm SearchObjectsPrm) (res SearchObjectsRes, err error) {
var cliPrm client.SearchObjectParams var cliPrm client.SearchObjectParams
@ -532,6 +562,7 @@ func (x HashPayloadRangesRes) HashList() [][]byte {
// HashPayloadRanges requests hashes (by default SHA256) of the object payload ranges. // HashPayloadRanges requests hashes (by default SHA256) of the object payload ranges.
// //
// Returns any error prevented the operation from completing correctly in error return.
// Returns an error if number of received hashes differs with the number of requested ranges. // Returns an error if number of received hashes differs with the number of requested ranges.
func HashPayloadRanges(prm HashPayloadRangesPrm) (res HashPayloadRangesRes, err error) { func HashPayloadRanges(prm HashPayloadRangesPrm) (res HashPayloadRangesRes, err error) {
var cliPrm client.RangeChecksumParams var cliPrm client.RangeChecksumParams
@ -596,6 +627,9 @@ type PayloadRangeRes struct{}
// PayloadRange reads object payload range from NeoFS and writes it to specified writer. // PayloadRange reads object payload range from NeoFS and writes it to specified writer.
// //
// Interrupts on any writer error. // Interrupts on any writer error.
//
// Returns any error prevented the operation from completing correctly in error return.
// For raw reading, returns *object.SplitInfoError error if object is virtual.
func PayloadRange(prm PayloadRangePrm) (res PayloadRangeRes, err error) { func PayloadRange(prm PayloadRangePrm) (res PayloadRangeRes, err error) {
var cliPrm client.RangeDataParams var cliPrm client.RangeDataParams

View file

@ -62,6 +62,8 @@ type AnnounceLocalRes struct{}
// AnnounceLocal sends estimations of local trust to the remote node. // AnnounceLocal sends estimations of local trust to the remote node.
// //
// Client, context and key must be set. // Client, context and key must be set.
//
// Returns any error prevented the operation from completing correctly in error return.
func AnnounceLocal(prm AnnounceLocalPrm) (res AnnounceLocalRes, err error) { func AnnounceLocal(prm AnnounceLocalPrm) (res AnnounceLocalRes, err error) {
_, err = prm.cli.AnnounceLocalTrust(prm.ctx, prm.cliPrm, prm.opts...) _, err = prm.cli.AnnounceLocalTrust(prm.ctx, prm.cliPrm, prm.opts...)
@ -97,6 +99,8 @@ type AnnounceIntermediateRes struct{}
// and epoch to to the remote node. // and epoch to to the remote node.
// //
// Client, context and key must be set. // Client, context and key must be set.
//
// Returns any error prevented the operation from completing correctly in error return.
func AnnounceIntermediate(prm AnnounceIntermediatePrm) (res AnnounceIntermediateRes, err error) { func AnnounceIntermediate(prm AnnounceIntermediatePrm) (res AnnounceIntermediateRes, err error) {
_, err = prm.cli.AnnounceIntermediateTrust(prm.ctx, prm.cliPrm, prm.opts...) _, err = prm.cli.AnnounceIntermediateTrust(prm.ctx, prm.cliPrm, prm.opts...)

View file

@ -53,6 +53,8 @@ func (x SearchSGRes) IDList() []*object.ID {
var sgFilter = storagegroup.SearchQuery() var sgFilter = storagegroup.SearchQuery()
// SearchSG lists objects of storage group type in the container. // SearchSG lists objects of storage group type in the container.
//
// Returns any error prevented the operation from completing correctly in error return.
func (x Client) SearchSG(prm SearchSGPrm) (res SearchSGRes, err error) { func (x Client) SearchSG(prm SearchSGPrm) (res SearchSGRes, err error) {
var cliPrm client.SearchObjectParams var cliPrm client.SearchObjectParams
@ -82,6 +84,8 @@ func (x GetObjectRes) Object() *object.Object {
} }
// GetObject reads the object by address. // GetObject reads the object by address.
//
// Returns any error prevented the operation from completing correctly in error return.
func (x Client) GetObject(prm GetObjectPrm) (res GetObjectRes, err error) { func (x Client) GetObject(prm GetObjectPrm) (res GetObjectRes, err error) {
var cliPrm client.GetObjectParams var cliPrm client.GetObjectParams
@ -125,7 +129,8 @@ func (x HeadObjectRes) Header() *object.Object {
// HeadObject reads short object header by address. // HeadObject reads short object header by address.
// //
// For raw requests, returns an error if requested object is virtual. // Returns any error prevented the operation from completing correctly in error return.
// For raw requests, returns *object.SplitInfoError error if requested object is virtual.
func (x Client) HeadObject(prm HeadObjectPrm) (res HeadObjectRes, err error) { func (x Client) HeadObject(prm HeadObjectPrm) (res HeadObjectRes, err error) {
var cliPrm client.ObjectHeaderParams var cliPrm client.ObjectHeaderParams
@ -142,6 +147,8 @@ func (x Client) HeadObject(prm HeadObjectPrm) (res HeadObjectRes, err error) {
} }
// GetObjectPayload reads object by address from NeoFS via Client and returns its payload. // GetObjectPayload reads object by address from NeoFS via Client and returns its payload.
//
// Returns any error prevented the operation from completing correctly in error return.
func GetObjectPayload(ctx context.Context, c Client, addr *object.Address) ([]byte, error) { func GetObjectPayload(ctx context.Context, c Client, addr *object.Address) ([]byte, error) {
var prm GetObjectPrm var prm GetObjectPrm
@ -210,6 +217,8 @@ func (x HashPayloadRangeRes) Hash() []byte {
// HashObjectRange requests to calculate Tillich-Zemor hash of the payload range of the object // HashObjectRange requests to calculate Tillich-Zemor hash of the payload range of the object
// from the remote server's local storage. // from the remote server's local storage.
//
// Returns any error prevented the operation from completing correctly in error return.
func (x Client) HashPayloadRange(prm HashPayloadRangePrm) (res HashPayloadRangeRes, err error) { func (x Client) HashPayloadRange(prm HashPayloadRangePrm) (res HashPayloadRangeRes, err error) {
var cliPrm client.RangeChecksumParams var cliPrm client.RangeChecksumParams
@ -233,6 +242,8 @@ func (x Client) HashPayloadRange(prm HashPayloadRangePrm) (res HashPayloadRangeR
// HashObjectRange reads Tillich-Zemor hash of the object payload range by address // HashObjectRange reads Tillich-Zemor hash of the object payload range by address
// from the remote server's local storage via Client. // from the remote server's local storage via Client.
//
// Returns any error prevented the operation from completing correctly in error return.
func HashObjectRange(ctx context.Context, c Client, addr *object.Address, rng *object.Range) ([]byte, error) { func HashObjectRange(ctx context.Context, c Client, addr *object.Address, rng *object.Range) ([]byte, error) {
var prm HashPayloadRangePrm var prm HashPayloadRangePrm

View file

@ -124,12 +124,15 @@ func (x GetObjectRes) Object() *object.Object {
// //
// Client, context and key must be set. // Client, context and key must be set.
// //
// Returns any error prevented the operation from completing correctly in error return.
// Returns: // Returns:
// error of type *object.SplitInfoError if object if raw flag is set and requested object is virtual; // error of type *object.SplitInfoError if object if raw flag is set and requested object is virtual;
// object.ErrAlreadyRemoved error if requested object is marked to be removed. // object.ErrAlreadyRemoved error if requested object is marked to be removed.
func GetObject(prm GetObjectPrm) (res GetObjectRes, err error) { func GetObject(prm GetObjectPrm) (res GetObjectRes, err error) {
res.cliRes, err = prm.cli.GetObject(prm.ctx, &prm.cliPrm, prm.opts...) res.cliRes, err = prm.cli.GetObject(prm.ctx, &prm.cliPrm, prm.opts...)
// FIXME: object.ErrAlreadyRemoved never returns
return return
} }
@ -168,12 +171,15 @@ func (x HeadObjectRes) Header() *object.Object {
// //
// Client, context and key must be set. // Client, context and key must be set.
// //
// Returns any error prevented the operation from completing correctly in error return.
// Returns: // Returns:
// error of type *object.SplitInfoError if object if raw flag is set and requested object is virtual; // error of type *object.SplitInfoError if object if raw flag is set and requested object is virtual;
// object.ErrAlreadyRemoved error if requested object is marked to be removed. // object.ErrAlreadyRemoved error if requested object is marked to be removed.
func HeadObject(prm HeadObjectPrm) (res HeadObjectRes, err error) { func HeadObject(prm HeadObjectPrm) (res HeadObjectRes, err error) {
res.cliRes, err = prm.cli.GetObjectHeader(prm.ctx, &prm.cliPrm, prm.opts...) res.cliRes, err = prm.cli.GetObjectHeader(prm.ctx, &prm.cliPrm, prm.opts...)
// FIXME: object.ErrAlreadyRemoved never returns
return return
} }
@ -219,12 +225,15 @@ func (x PayloadRangeRes) PayloadRange() []byte {
// //
// Client, context and key must be set. // Client, context and key must be set.
// //
// Returns any error prevented the operation from completing correctly in error return.
// Returns: // Returns:
// error of type *object.SplitInfoError if object if raw flag is set and requested object is virtual; // error of type *object.SplitInfoError if object if raw flag is set and requested object is virtual;
// object.ErrAlreadyRemoved error if requested object is marked to be removed. // object.ErrAlreadyRemoved error if requested object is marked to be removed.
func PayloadRange(prm PayloadRangePrm) (res PayloadRangeRes, err error) { func PayloadRange(prm PayloadRangePrm) (res PayloadRangeRes, err error) {
res.cliRes, err = prm.cli.ObjectPayloadRangeData(prm.ctx, &prm.cliPrm, prm.opts...) res.cliRes, err = prm.cli.ObjectPayloadRangeData(prm.ctx, &prm.cliPrm, prm.opts...)
// FIXME: object.ErrAlreadyRemoved never returns
return return
} }
@ -255,6 +264,8 @@ func (x PutObjectRes) ID() *object.ID {
// PutObject saves the object in local storage of the remote node. // PutObject saves the object in local storage of the remote node.
// //
// Client, context and key must be set. // Client, context and key must be set.
//
// Returns any error prevented the operation from completing correctly in error return.
func PutObject(prm PutObjectPrm) (res PutObjectRes, err error) { func PutObject(prm PutObjectPrm) (res PutObjectRes, err error) {
res.cliRes, err = prm.cli.PutObject(prm.ctx, &prm.cliPrm, res.cliRes, err = prm.cli.PutObject(prm.ctx, &prm.cliPrm,
append(prm.opts, client.WithTTL(1))..., append(prm.opts, client.WithTTL(1))...,
@ -293,6 +304,8 @@ func (x SearchObjectsRes) IDList() []*object.ID {
} }
// SearchObjects selects objects from container which match the filters. // SearchObjects selects objects from container which match the filters.
//
// Returns any error prevented the operation from completing correctly in error return.
func SearchObjects(prm SearchObjectsPrm) (res SearchObjectsRes, err error) { func SearchObjects(prm SearchObjectsPrm) (res SearchObjectsRes, err error) {
res.cliRes, err = prm.cli.SearchObject(prm.ctx, &prm.cliPrm, prm.opts...) res.cliRes, err = prm.cli.SearchObject(prm.ctx, &prm.cliPrm, prm.opts...)