[#1247] *: Clarify docs about returned errors from apistatus package

`apistatus` package provides types which implement build-in `error`
interface. Add `error of type` pattern when documenting these errors in
order to clarify how these errors should be handled (e.g. `errors.Is` is
not good).

Signed-off-by: Leonard Lyubich <leonard@nspcc.ru>
This commit is contained in:
Leonard Lyubich 2022-03-17 16:26:17 +03:00 committed by Alex Vanin
parent 459bdcf04b
commit 318639e5bf
24 changed files with 33 additions and 33 deletions

View file

@ -15,7 +15,7 @@ type Source interface {
// It returns the pointer to requested container and any error encountered.
//
// Get must return exactly one non-nil value.
// Get must return apistatus.ContainerNotFound if the container is not in storage.
// Get must return an error of type apistatus.ContainerNotFound if the container is not in storage.
//
// Implementations must not retain the container pointer and modify
// the container through it.

View file

@ -61,7 +61,7 @@ func (c *ClientCache) Get(info clientcore.NodeInfo) (clientcore.Client, error) {
// GetSG polls the container from audit task to get the object by id.
// Returns storage groups structure from received object.
//
// Returns apistatus.ObjectNotFound if storage group is missing.
// Returns an error of type apistatus.ObjectNotFound if storage group is missing.
func (c *ClientCache) GetSG(task *audit.Task, id *oidSDK.ID) (*storagegroup.StorageGroup, error) {
sgAddress := new(addressSDK.Address)
sgAddress.SetContainerID(task.ContainerID())

View file

@ -169,7 +169,7 @@ func (s settlementDeps) ContainerNodes(e uint64, cid *cid.ID) ([]common.NodeInfo
// SGInfo returns audit.SGInfo by object address.
//
// Returns apistatus.ObjectNotFound if storage group is missing.
// Returns an error of type apistatus.ObjectNotFound if storage group is missing.
func (s settlementDeps) SGInfo(addr *addressSDK.Address) (audit.SGInfo, error) {
cn, nm, err := s.buildContainer(0, addr.ContainerID())
if err != nil {

View file

@ -26,7 +26,7 @@ func (p *DeletePrm) SetAddress(addr *addressSDK.Address) {
// Returns any error encountered that
// did not allow to completely delete the object.
//
// Returns apistatus.ObjectNotFound if the object to be deleted is not in blobovnicza.
// Returns an error of type apistatus.ObjectNotFound if the object to be deleted is not in blobovnicza.
//
// Should not be called in read-only configuration.
func (b *Blobovnicza) Delete(prm *DeletePrm) (*DeleteRes, error) {

View file

@ -32,7 +32,7 @@ func (p *GetRes) Object() []byte {
// Returns any error encountered that
// did not allow to completely read the object.
//
// Returns apistatus.ObjectNotFound if requested object is not
// Returns an error of type apistatus.ObjectNotFound if requested object is not
// presented in Blobovnicza.
func (b *Blobovnicza) Get(prm *GetPrm) (*GetRes, error) {
var (

View file

@ -21,7 +21,7 @@ type DeleteBigRes struct{}
// Returns any error encountered that did not allow
// to completely remove the object.
//
// Returns apistatus.ObjectNotFound if there is no object to delete.
// Returns an error of type apistatus.ObjectNotFound if there is no object to delete.
func (b *BlobStor) DeleteBig(prm *DeleteBigPrm) (*DeleteBigRes, error) {
err := b.fsTree.Delete(prm.addr)
if errors.Is(err, fstree.ErrFileNotFound) {

View file

@ -17,7 +17,7 @@ type DeleteSmallRes struct{}
// Returns any error encountered that did not allow
// to completely remove the object.
//
// Returns apistatus.ObjectNotFound if there is no object to delete.
// Returns an error of type apistatus.ObjectNotFound if there is no object to delete.
func (b *BlobStor) DeleteSmall(prm *DeleteSmallPrm) (*DeleteSmallRes, error) {
return b.blobovniczas.delete(prm)
}

View file

@ -24,7 +24,7 @@ type GetBigRes struct {
// Returns any error encountered that
// did not allow to completely read the object.
//
// Returns apistatus.ObjectNotFound if requested object is not
// Returns an error of type apistatus.ObjectNotFound if requested object is not
// presented in shallow dir.
func (b *BlobStor) GetBig(prm *GetBigPrm) (*GetBigRes, error) {
// get compressed object data

View file

@ -27,7 +27,7 @@ type GetRangeBigRes struct {
// did not allow to completely read the object payload range.
//
// Returns ErrRangeOutOfBounds if requested object range is out of bounds.
// Returns apistatus.ObjectNotFound if object is missing.
// Returns an error of type apistatus.ObjectNotFound if object is missing.
func (b *BlobStor) GetRangeBig(prm *GetRangeBigPrm) (*GetRangeBigRes, error) {
// get compressed object data
data, err := b.fsTree.Get(prm.addr)

View file

@ -21,7 +21,7 @@ type GetRangeSmallRes struct {
// did not allow to completely read the object payload range.
//
// Returns ErrRangeOutOfBounds if requested object range is out of bounds.
// Returns apistatus.ObjectNotFound if requested object is missing in blobovnicza(s).
// Returns an error of type apistatus.ObjectNotFound if requested object is missing in blobovnicza(s).
func (b *BlobStor) GetRangeSmall(prm *GetRangeSmallPrm) (*GetRangeSmallRes, error) {
return b.blobovniczas.getRange(prm)
}

View file

@ -19,7 +19,7 @@ type GetSmallRes struct {
// Returns any error encountered that
// did not allow to completely read the object.
//
// Returns apistatus.ObjectNotFound if requested object is missing in blobovnicza(s).
// Returns an error of type apistatus.ObjectNotFound if requested object is missing in blobovnicza(s).
func (b *BlobStor) GetSmall(prm *GetSmallPrm) (*GetSmallRes, error) {
return b.blobovniczas.get(prm)
}

View file

@ -42,8 +42,8 @@ func (r *GetRes) Object() *objectSDK.Object {
// Returns any error encountered that
// did not allow to completely read the object part.
//
// Returns apistatus.ObjectNotFound if requested object is missing in local storage.
// Returns apistatus.ObjectAlreadyRemoved if object has been marked as removed.
// Returns an error of type apistatus.ObjectNotFound if requested object is missing in local storage.
// Returns an error of type apistatus.ObjectAlreadyRemoved if object has been marked as removed.
//
// Returns an error if executions are blocked (see BlockExecution).
func (e *StorageEngine) Get(prm *GetPrm) (res *GetRes, err error) {

View file

@ -55,8 +55,8 @@ func (r *HeadRes) Header() *objectSDK.Object {
// Returns any error encountered that
// did not allow to completely read the object header.
//
// Returns apistatus.ObjectNotFound if requested object is missing in local storage.
// Returns apistatus.ObjectAlreadyRemoved if requested object was inhumed.
// Returns an error of type apistatus.ObjectNotFound if requested object is missing in local storage.
// Returns an error of type apistatus.ObjectAlreadyRemoved if requested object was inhumed.
//
// Returns an error if executions are blocked (see BlockExecution).
func (e *StorageEngine) Head(prm *HeadPrm) (res *HeadRes, err error) {

View file

@ -37,7 +37,7 @@ func (p *PutPrm) WithObject(obj *objectSDK.Object) *PutPrm {
//
// Returns an error if executions are blocked (see BlockExecution).
//
// Returns apistatus.ObjectAlreadyRemoved if object has been marked as removed.
// Returns an error of type apistatus.ObjectAlreadyRemoved if object has been marked as removed.
func (e *StorageEngine) Put(prm *PutPrm) (res *PutRes, err error) {
err = e.execIfNotBlocked(func() error {
res, err = e.put(prm)

View file

@ -59,8 +59,8 @@ func (r *RngRes) Object() *objectSDK.Object {
// Returns any error encountered that
// did not allow to completely read the object part.
//
// Returns apistatus.ObjectNotFound if requested object is missing in local storage.
// Returns apistatus.ObjectAlreadyRemoved if requested object is inhumed.
// Returns an error of type apistatus.ObjectNotFound if requested object is missing in local storage.
// Returns an error of type apistatus.ObjectAlreadyRemoved if requested object is inhumed.
// Returns ErrRangeOutOfBounds if requested object range is out of bounds.
//
// Returns an error if executions are blocked (see BlockExecution).

View file

@ -53,7 +53,7 @@ func Exists(db *DB, addr *addressSDK.Address) (bool, error) {
// Exists returns ErrAlreadyRemoved if addr was marked as removed. Otherwise it
// returns true if addr is in primary index or false if it is not.
//
// Returns apistatus.ObjectAlreadyRemoved if object has been placed in graveyard.
// Returns an error of type apistatus.ObjectAlreadyRemoved if object has been placed in graveyard.
func (db *DB) Exists(prm *ExistsPrm) (res *ExistsRes, err error) {
res = new(ExistsRes)

View file

@ -70,8 +70,8 @@ func GetRaw(db *DB, addr *addressSDK.Address, raw bool) (*objectSDK.Object, erro
// Get returns object header for specified address.
//
// Returns apistatus.ObjectNotFound if object is missing in DB.
// Returns apistatus.ObjectAlreadyRemoved if object has been placed in graveyard.
// Returns an error of type apistatus.ObjectNotFound if object is missing in DB.
// Returns an error of type apistatus.ObjectAlreadyRemoved if object has been placed in graveyard.
func (db *DB) Get(prm *GetPrm) (res *GetRes, err error) {
res = new(GetRes)

View file

@ -70,7 +70,7 @@ func Put(db *DB, obj *objectSDK.Object, id *blobovnicza.ID) error {
// Put saves object header in metabase. Object payload expected to be cut.
// Big objects have nil blobovniczaID.
//
// Returns apistatus.ObjectAlreadyRemoved if object has been placed in graveyard.
// Returns an error of type apistatus.ObjectAlreadyRemoved if object has been placed in graveyard.
func (db *DB) Put(prm *PutPrm) (res *PutRes, err error) {
err = db.boltDB.Batch(func(tx *bbolt.Tx) error {
return db.put(tx, prm.obj, prm.id, nil)

View file

@ -34,7 +34,7 @@ func (p *ExistsRes) Exists() bool {
// Returns any error encountered that does not allow to
// unambiguously determine the presence of an object.
//
// Returns apistatus.ObjectAlreadyRemoved if object has been marked as removed.
// Returns an error of type apistatus.ObjectAlreadyRemoved if object has been marked as removed.
func (s *Shard) Exists(prm *ExistsPrm) (*ExistsRes, error) {
exists, err := s.objectExists(prm.addr)

View file

@ -64,8 +64,8 @@ func (r *GetRes) HasMeta() bool {
// Returns any error encountered that
// did not allow to completely read the object part.
//
// Returns apistatus.ObjectNotFound if requested object is missing in shard.
// Returns apistatus.ObjectAlreadyRemoved if requested object has been marked as removed in shard.
// Returns an error of type apistatus.ObjectNotFound if requested object is missing in shard.
// Returns an error of type apistatus.ObjectAlreadyRemoved if requested object has been marked as removed in shard.
func (s *Shard) Get(prm *GetPrm) (*GetRes, error) {
var big, small storFetcher

View file

@ -51,8 +51,8 @@ func (r *HeadRes) Object() *objectSDK.Object {
//
// Returns any error encountered.
//
// Returns apistatus.ObjectNotFound if object is missing in Shard.
// Returns apistatus.ObjectAlreadyRemoved if requested object has been marked as removed in shard.
// Returns an error of type apistatus.ObjectNotFound if object is missing in Shard.
// Returns an error of type apistatus.ObjectAlreadyRemoved if requested object has been marked as removed in shard.
func (s *Shard) Head(prm *HeadPrm) (*HeadRes, error) {
// object can be saved in write-cache (if enabled) or in metabase

View file

@ -69,8 +69,8 @@ func (r *RngRes) HasMeta() bool {
// did not allow to completely read the object part.
//
// Returns ErrRangeOutOfBounds if requested object range is out of bounds.
// Returns apistatus.ObjectNotFound if requested object is missing.
// Returns apistatus.ObjectAlreadyRemoved if requested object has been marked as removed in shard.
// Returns an error of type apistatus.ObjectNotFound if requested object is missing.
// Returns an error of type apistatus.ObjectAlreadyRemoved if requested object has been marked as removed in shard.
func (s *Shard) GetRange(prm *RngPrm) (*RngRes, error) {
var big, small storFetcher

View file

@ -12,7 +12,7 @@ import (
// Delete removes object from write-cache.
//
// Returns apistatus.ObjectNotFound is object is missing in write-cache.
// Returns an error of type apistatus.ObjectNotFound if object is missing in write-cache.
func (c *cache) Delete(addr *addressSDK.Address) error {
c.modeMtx.RLock()
defer c.modeMtx.RUnlock()

View file

@ -9,7 +9,7 @@ import (
// Get returns object from write-cache.
//
// Returns apistatus.ObjectNotFound if requested object is missing in write-cache.
// Returns an error of type apistatus.ObjectNotFound if requested object is missing in write-cache.
func (c *cache) Get(addr *addressSDK.Address) (*objectSDK.Object, error) {
saddr := addr.String()
@ -48,7 +48,7 @@ func (c *cache) Get(addr *addressSDK.Address) (*objectSDK.Object, error) {
// Head returns object header from write-cache.
//
// Returns apistatus.ObjectNotFound if requested object is missing in write-cache.
// Returns an error of type apistatus.ObjectNotFound if requested object is missing in write-cache.
func (c *cache) Head(addr *addressSDK.Address) (*objectSDK.Object, error) {
// TODO: #1149 easiest to implement solution is presented here, consider more efficient way, e.g.:
// - provide header as common object.Object to Put, but marked to prevent correlation with full object
@ -68,7 +68,7 @@ func (c *cache) Head(addr *addressSDK.Address) (*objectSDK.Object, error) {
// Get fetches object from the underlying database.
// Key should be a stringified address.
//
// Returns apistatus.ObjectNotFound if requested object is missing in db.
// Returns an error of type apistatus.ObjectNotFound if requested object is missing in db.
func Get(db *bbolt.DB, key []byte) ([]byte, error) {
var value []byte
err := db.View(func(tx *bbolt.Tx) error {