From 318639e5bf48a258d648cf1b5485153f35828d08 Mon Sep 17 00:00:00 2001 From: Leonard Lyubich Date: Thu, 17 Mar 2022 16:26:17 +0300 Subject: [PATCH] [#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 --- pkg/core/container/storage.go | 2 +- pkg/innerring/rpc.go | 2 +- pkg/innerring/settlement.go | 2 +- pkg/local_object_storage/blobovnicza/delete.go | 2 +- pkg/local_object_storage/blobovnicza/get.go | 2 +- pkg/local_object_storage/blobstor/delete_big.go | 2 +- pkg/local_object_storage/blobstor/delete_small.go | 2 +- pkg/local_object_storage/blobstor/get_big.go | 2 +- pkg/local_object_storage/blobstor/get_range_big.go | 2 +- pkg/local_object_storage/blobstor/get_range_small.go | 2 +- pkg/local_object_storage/blobstor/get_small.go | 2 +- pkg/local_object_storage/engine/get.go | 4 ++-- pkg/local_object_storage/engine/head.go | 4 ++-- pkg/local_object_storage/engine/put.go | 2 +- pkg/local_object_storage/engine/range.go | 4 ++-- pkg/local_object_storage/metabase/exists.go | 2 +- pkg/local_object_storage/metabase/get.go | 4 ++-- pkg/local_object_storage/metabase/put.go | 2 +- pkg/local_object_storage/shard/exists.go | 2 +- pkg/local_object_storage/shard/get.go | 4 ++-- pkg/local_object_storage/shard/head.go | 4 ++-- pkg/local_object_storage/shard/range.go | 4 ++-- pkg/local_object_storage/writecache/delete.go | 2 +- pkg/local_object_storage/writecache/get.go | 6 +++--- 24 files changed, 33 insertions(+), 33 deletions(-) diff --git a/pkg/core/container/storage.go b/pkg/core/container/storage.go index 5f6f23d2f..3d8b87c2f 100644 --- a/pkg/core/container/storage.go +++ b/pkg/core/container/storage.go @@ -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. diff --git a/pkg/innerring/rpc.go b/pkg/innerring/rpc.go index 8c2ddca3a..d02b5f2d8 100644 --- a/pkg/innerring/rpc.go +++ b/pkg/innerring/rpc.go @@ -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()) diff --git a/pkg/innerring/settlement.go b/pkg/innerring/settlement.go index c317ec57c..c49ac1eef 100644 --- a/pkg/innerring/settlement.go +++ b/pkg/innerring/settlement.go @@ -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 { diff --git a/pkg/local_object_storage/blobovnicza/delete.go b/pkg/local_object_storage/blobovnicza/delete.go index e3a5eb0d7..3dd4cde7c 100644 --- a/pkg/local_object_storage/blobovnicza/delete.go +++ b/pkg/local_object_storage/blobovnicza/delete.go @@ -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) { diff --git a/pkg/local_object_storage/blobovnicza/get.go b/pkg/local_object_storage/blobovnicza/get.go index 84dcb628c..10eb55b63 100644 --- a/pkg/local_object_storage/blobovnicza/get.go +++ b/pkg/local_object_storage/blobovnicza/get.go @@ -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 ( diff --git a/pkg/local_object_storage/blobstor/delete_big.go b/pkg/local_object_storage/blobstor/delete_big.go index 83fa8a8cd..b3b500d36 100644 --- a/pkg/local_object_storage/blobstor/delete_big.go +++ b/pkg/local_object_storage/blobstor/delete_big.go @@ -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) { diff --git a/pkg/local_object_storage/blobstor/delete_small.go b/pkg/local_object_storage/blobstor/delete_small.go index e43f41e81..7de368a7a 100644 --- a/pkg/local_object_storage/blobstor/delete_small.go +++ b/pkg/local_object_storage/blobstor/delete_small.go @@ -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) } diff --git a/pkg/local_object_storage/blobstor/get_big.go b/pkg/local_object_storage/blobstor/get_big.go index 8403924af..450879d6f 100644 --- a/pkg/local_object_storage/blobstor/get_big.go +++ b/pkg/local_object_storage/blobstor/get_big.go @@ -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 diff --git a/pkg/local_object_storage/blobstor/get_range_big.go b/pkg/local_object_storage/blobstor/get_range_big.go index d24509283..236b41cfb 100644 --- a/pkg/local_object_storage/blobstor/get_range_big.go +++ b/pkg/local_object_storage/blobstor/get_range_big.go @@ -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) diff --git a/pkg/local_object_storage/blobstor/get_range_small.go b/pkg/local_object_storage/blobstor/get_range_small.go index 1baa8c311..1b4eb1e3c 100644 --- a/pkg/local_object_storage/blobstor/get_range_small.go +++ b/pkg/local_object_storage/blobstor/get_range_small.go @@ -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) } diff --git a/pkg/local_object_storage/blobstor/get_small.go b/pkg/local_object_storage/blobstor/get_small.go index d2caec5f3..f906992af 100644 --- a/pkg/local_object_storage/blobstor/get_small.go +++ b/pkg/local_object_storage/blobstor/get_small.go @@ -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) } diff --git a/pkg/local_object_storage/engine/get.go b/pkg/local_object_storage/engine/get.go index 7edda40c9..3e0b13390 100644 --- a/pkg/local_object_storage/engine/get.go +++ b/pkg/local_object_storage/engine/get.go @@ -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) { diff --git a/pkg/local_object_storage/engine/head.go b/pkg/local_object_storage/engine/head.go index eb898a7cf..0a91a5ae8 100644 --- a/pkg/local_object_storage/engine/head.go +++ b/pkg/local_object_storage/engine/head.go @@ -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) { diff --git a/pkg/local_object_storage/engine/put.go b/pkg/local_object_storage/engine/put.go index a1597b5e3..ef6a01f2a 100644 --- a/pkg/local_object_storage/engine/put.go +++ b/pkg/local_object_storage/engine/put.go @@ -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) diff --git a/pkg/local_object_storage/engine/range.go b/pkg/local_object_storage/engine/range.go index a5d1deb79..992015b46 100644 --- a/pkg/local_object_storage/engine/range.go +++ b/pkg/local_object_storage/engine/range.go @@ -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). diff --git a/pkg/local_object_storage/metabase/exists.go b/pkg/local_object_storage/metabase/exists.go index 2642f1bc0..95162f52f 100644 --- a/pkg/local_object_storage/metabase/exists.go +++ b/pkg/local_object_storage/metabase/exists.go @@ -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) diff --git a/pkg/local_object_storage/metabase/get.go b/pkg/local_object_storage/metabase/get.go index f43748363..decc8d122 100644 --- a/pkg/local_object_storage/metabase/get.go +++ b/pkg/local_object_storage/metabase/get.go @@ -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) diff --git a/pkg/local_object_storage/metabase/put.go b/pkg/local_object_storage/metabase/put.go index 9ed483947..b898e872d 100644 --- a/pkg/local_object_storage/metabase/put.go +++ b/pkg/local_object_storage/metabase/put.go @@ -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) diff --git a/pkg/local_object_storage/shard/exists.go b/pkg/local_object_storage/shard/exists.go index b8473352a..488214231 100644 --- a/pkg/local_object_storage/shard/exists.go +++ b/pkg/local_object_storage/shard/exists.go @@ -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) diff --git a/pkg/local_object_storage/shard/get.go b/pkg/local_object_storage/shard/get.go index bed17a1c0..b5648db29 100644 --- a/pkg/local_object_storage/shard/get.go +++ b/pkg/local_object_storage/shard/get.go @@ -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 diff --git a/pkg/local_object_storage/shard/head.go b/pkg/local_object_storage/shard/head.go index 04348e6c4..d8761bfe3 100644 --- a/pkg/local_object_storage/shard/head.go +++ b/pkg/local_object_storage/shard/head.go @@ -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 diff --git a/pkg/local_object_storage/shard/range.go b/pkg/local_object_storage/shard/range.go index 7fa095652..454916625 100644 --- a/pkg/local_object_storage/shard/range.go +++ b/pkg/local_object_storage/shard/range.go @@ -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 diff --git a/pkg/local_object_storage/writecache/delete.go b/pkg/local_object_storage/writecache/delete.go index e843ebd9d..bfdeb46db 100644 --- a/pkg/local_object_storage/writecache/delete.go +++ b/pkg/local_object_storage/writecache/delete.go @@ -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() diff --git a/pkg/local_object_storage/writecache/get.go b/pkg/local_object_storage/writecache/get.go index a3351105f..2553fa9f1 100644 --- a/pkg/local_object_storage/writecache/get.go +++ b/pkg/local_object_storage/writecache/get.go @@ -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 {