Blockstores

This wiki page is temporary - it's a prototype for https://github.com/status-im/nim-codex/tree/main/codex/stores/readme.md

This directory contains implementations for blockstores. Blockstore is a storage of datablocks (seq[byte]) addressed by cids (strings), i.e. it's a hashtable-like interface.

Modules:

• blockstore.nim - abstract base class and API definition
• cachestore.nim - in-memory store employing LRU cache
• fsstore.nim - disk-based store with each block stored in separate file, backed up by cachestore.nim for least recently used blocks
• networkstore.nim - retrieves data from the network (peers), backed up by local fsstore.nim

API:

method getBlock*(self: BlockStore, cid: Cid): Future[?! (?Block)]
  ## Get a block from the store. If no block corresponds to the given cid, 
  ## returns Block.none.success. On error, returns Block.failure(exception), 
  ## and implementations tend to `trace` the error message

method putBlock*(self: BlockStore, blk: Block): Future[?!void]
  ## Put a block to the blockstore (blk contains both cid and block contents)

method delBlock*(self: BlockStore, cid: Cid): Future[?!void]
  ## Delete a block from the blockstore

method hasBlock*(self: BlockStore, cid: Cid): Future[?!bool]
  ## Check if the block exists in the blockstore

method listBlocks*(self: BlockStore, onBlock: OnBlock): Future[?!void]
  ## Get the list of blocks in the BlockStore. This is an intensive operation

proc contains*(self: BlockStore, blk: Cid): Future[bool]
  ## Check if the block exists in the blockstore.
  ## Return false if error encountered

Notes:

• all real errors should be signaled via Return
• getBlock may fail to find a block with given id - return Block.none in this case in order to distinguish that from "hard failures", such as ruined DB. F.e. in BlockExc we can delete block in one task before another task get a chance to read it - it's not a failure at all
• putBlock can create new block or overwrite existing one - we don't care, thus void
• delBlock: if it can't delete a block - it's an error; if block already doesn't exist - we don't care (it may be deleted by other task)