refine docs.

blockstore/blockstore.go

@@ -1,17 +1,3 @@
-// blockstore contains all the basic blockstore constructors used by lotus. Any
-// blockstores not ultimately constructed out of the building blocks in this
-// package may not work properly.
-//
-//  * This package correctly wraps blockstores with the IdBlockstore. This blockstore:
-//    * Filters out all puts for blocks with CIDs using the "identity" hash function.
-//    * Extracts inlined blocks from CIDs using the identity hash function and
-//      returns them on get/has, ignoring the contents of the blockstore.
-//  * In the future, this package may enforce additional restrictions on block
-//    sizes, CID validity, etc.
-//
-// To make auditing for misuse of blockstores tractable, this package re-exports
-// parts of the go-ipfs-blockstore package such that no other package needs to
-// import it directly.
 package blockstore
 
 import (
@@ -40,6 +26,10 @@ type BasicBlockstore = blockstore.Blockstore
 type Viewer = blockstore.Viewer
 
 // WrapIDStore wraps the underlying blockstore in an "identity" blockstore.
+// The ID store filters out all puts for blocks with CIDs using the "identity"
+// hash function. It also extracts inlined blocks from CIDs using the identity
+// hash function and returns them on get/has, ignoring the contents of the
+// blockstore.
 func WrapIDStore(bstore blockstore.Blockstore) Blockstore {
 	return blockstore.NewIdStore(bstore).(Blockstore)
 }

blockstore/doc.go

@@ -0,0 +1,9 @@
+// Package blockstore and subpackages contain most of the blockstore
+// implementations used by Lotus.
+//
+// Blockstores not ultimately constructed out of the building blocks in this
+// package may not work properly.
+//
+// This package re-exports parts of the go-ipfs-blockstore package such that
+// no other package needs to import it directly, for ergonomics and traceability.
+package blockstore

blockstore/fallback.go

@@ -14,17 +14,19 @@ import (
 type FallbackStore struct {
 	Blockstore
 
-	fallbackGetBlock func(context.Context, cid.Cid) (blocks.Block, error)
+	lk sync.RWMutex
-	lk               sync.RWMutex
+	// missFn is the function that will be invoked on a local miss to pull the
+	// block from elsewhere.
+	missFn func(context.Context, cid.Cid) (blocks.Block, error)
 }
 
 var _ Blockstore = (*FallbackStore)(nil)
 
-func (fbs *FallbackStore) SetFallback(fg func(context.Context, cid.Cid) (blocks.Block, error)) {
+func (fbs *FallbackStore) SetFallback(missFn func(context.Context, cid.Cid) (blocks.Block, error)) {
 	fbs.lk.Lock()
 	defer fbs.lk.Unlock()
 
-	fbs.fallbackGetBlock = fg
+	fbs.missFn = missFn
 }
 
 func (fbs *FallbackStore) getFallback(c cid.Cid) (blocks.Block, error) {
@@ -32,15 +34,15 @@ func (fbs *FallbackStore) getFallback(c cid.Cid) (blocks.Block, error) {
 	fbs.lk.RLock()
 	defer fbs.lk.RUnlock()
 
-	if fbs.fallbackGetBlock == nil {
+	if fbs.missFn == nil {
 		// FallbackStore wasn't configured yet (chainstore/bitswap aren't up yet)
 		// Wait for a bit and retry
 		fbs.lk.RUnlock()
 		time.Sleep(5 * time.Second)
 		fbs.lk.RLock()
 
-		if fbs.fallbackGetBlock == nil {
+		if fbs.missFn == nil {
-			log.Errorw("fallbackstore: fallbackGetBlock not configured yet")
+			log.Errorw("fallbackstore: missFn not configured yet")
 			return nil, ErrNotFound
 		}
 	}
@@ -48,7 +50,7 @@ func (fbs *FallbackStore) getFallback(c cid.Cid) (blocks.Block, error) {
 	ctx, cancel := context.WithTimeout(context.TODO(), 120*time.Second)
 	defer cancel()
 
-	b, err := fbs.fallbackGetBlock(ctx, c)
+	b, err := fbs.missFn(ctx, c)
 	if err != nil {
 		return nil, err
 	}