feat: add offline option to blockstore get (#145)

Adds an `offline` option to blockstore get methods to only go to
the local blockstore and not the network.

Author: achingbrain

packages/helia/src/storage.ts

@@ -1,5 +1,5 @@
 import createMortice from 'mortice'
-import type { Blocks, Pair, DeleteManyBlocksProgressEvents, DeleteBlockProgressEvents, GetBlockProgressEvents, GetManyBlocksProgressEvents, PutManyBlocksProgressEvents, PutBlockProgressEvents, GetAllBlocksProgressEvents } from '@helia/interface/blocks'
+import type { Blocks, Pair, DeleteManyBlocksProgressEvents, DeleteBlockProgressEvents, GetBlockProgressEvents, GetManyBlocksProgressEvents, PutManyBlocksProgressEvents, PutBlockProgressEvents, GetAllBlocksProgressEvents, GetOfflineOptions } from '@helia/interface/blocks'
 import type { Pins } from '@helia/interface/pins'
 import type { AbortOptions } from '@libp2p/interfaces'
 import type { Blockstore } from 'interface-blockstore'
@@ -70,7 +70,7 @@ export class BlockStorage implements Blocks {
   /**
    * Get a block by cid
    */
-  async get (cid: CID, options: AbortOptions & ProgressOptions<GetBlockProgressEvents> = {}): Promise<Uint8Array> {
+  async get (cid: CID, options: GetOfflineOptions & AbortOptions & ProgressOptions<GetBlockProgressEvents> = {}): Promise<Uint8Array> {
     const releaseLock = await this.lock.readLock()
 
     try {
@@ -83,7 +83,7 @@ export class BlockStorage implements Blocks {
   /**
    * Get multiple blocks back from an (async) iterable of cids
    */
-  async * getMany (cids: AwaitIterable<CID>, options: AbortOptions & ProgressOptions<GetManyBlocksProgressEvents> = {}): AsyncIterable<Pair> {
+  async * getMany (cids: AwaitIterable<CID>, options: GetOfflineOptions & AbortOptions & ProgressOptions<GetManyBlocksProgressEvents> = {}): AsyncIterable<Pair> {
     const releaseLock = await this.lock.readLock()
 
     try {

packages/helia/src/utils/networked-storage.ts

@@ -1,7 +1,7 @@
 import filter from 'it-filter'
 import forEach from 'it-foreach'
 import { CustomProgressEvent, type ProgressOptions } from 'progress-events'
-import type { Blocks, Pair, DeleteManyBlocksProgressEvents, DeleteBlockProgressEvents, GetBlockProgressEvents, GetManyBlocksProgressEvents, PutManyBlocksProgressEvents, PutBlockProgressEvents, GetAllBlocksProgressEvents } from '@helia/interface/blocks'
+import type { Blocks, Pair, DeleteManyBlocksProgressEvents, DeleteBlockProgressEvents, GetBlockProgressEvents, GetManyBlocksProgressEvents, PutManyBlocksProgressEvents, PutBlockProgressEvents, GetAllBlocksProgressEvents, GetOfflineOptions } from '@helia/interface/blocks'
 import type { AbortOptions } from '@libp2p/interfaces'
 import type { Blockstore } from 'interface-blockstore'
 import type { AwaitIterable } from 'interface-store'
@@ -82,8 +82,8 @@ export class NetworkedStorage implements Blocks {
   /**
    * Get a block by cid
    */
-  async get (cid: CID, options: AbortOptions & ProgressOptions<GetBlockProgressEvents> = {}): Promise<Uint8Array> {
-    if (this.bitswap?.isStarted() != null && !(await this.child.has(cid))) {
+  async get (cid: CID, options: GetOfflineOptions & AbortOptions & ProgressOptions<GetBlockProgressEvents> = {}): Promise<Uint8Array> {
+    if (options.offline !== true && this.bitswap?.isStarted() != null && !(await this.child.has(cid))) {
       options.onProgress?.(new CustomProgressEvent<CID>('blocks:get:bitswap:get', cid))
       const block = await this.bitswap.want(cid, options)
 
@@ -101,11 +101,11 @@ export class NetworkedStorage implements Blocks {
   /**
    * Get multiple blocks back from an (async) iterable of cids
    */
-  async * getMany (cids: AwaitIterable<CID>, options: AbortOptions & ProgressOptions<GetManyBlocksProgressEvents> = {}): AsyncIterable<Pair> {
+  async * getMany (cids: AwaitIterable<CID>, options: GetOfflineOptions & AbortOptions & ProgressOptions<GetManyBlocksProgressEvents> = {}): AsyncIterable<Pair> {
     options.onProgress?.(new CustomProgressEvent('blocks:get-many:blockstore:get-many'))
 
     yield * this.child.getMany(forEach(cids, async (cid): Promise<void> => {
-      if (this.bitswap?.isStarted() === true && !(await this.child.has(cid))) {
+      if (options.offline !== true && this.bitswap?.isStarted() === true && !(await this.child.has(cid))) {
         options.onProgress?.(new CustomProgressEvent<CID>('blocks:get-many:bitswap:get', cid))
         const block = await this.bitswap.want(cid, options)
         options.onProgress?.(new CustomProgressEvent<CID>('blocks:get-many:blockstore:put', cid))

packages/helia/test/utils/networked-storage.spec.ts

@@ -42,6 +42,14 @@ describe('storage', () => {
     expect(retrieved).to.equalBytes(block)
   })
 
+  it('gets a block from the blockstore offline', async () => {
+    const { cid } = blocks[0]
+
+    await expect(storage.get(cid, {
+      offline: true
+    })).to.eventually.be.rejected.with.property('code', 'ERR_NOT_FOUND')
+  })
+
   it('gets a block from the blockstore with progress', async () => {
     const { cid, block } = blocks[0]
     await blockstore.put(cid, block)
@@ -72,6 +80,14 @@ describe('storage', () => {
     expect(retrieved).to.deep.equal(new Array(count).fill(0).map((_, i) => blocks[i]))
   })
 
+  it('gets many blocks from the blockstore offline', async () => {
+    const { cid } = blocks[0]
+
+    await expect(drain(storage.getMany([cid], {
+      offline: true
+    }))).to.eventually.be.rejected.with.property('code', 'ERR_NOT_FOUND')
+  })
+
   it('puts a block into the blockstore', async () => {
     const { cid, block } = blocks[0]
     await storage.put(cid, block)

packages/interface/src/blocks.ts

@@ -47,9 +47,16 @@ export type DeleteBlockProgressEvents =
 export type DeleteManyBlocksProgressEvents =
   ProgressEvent<'blocks:delete-many:blockstore:delete-many'>
 
+export interface GetOfflineOptions {
+  /**
+   * If true, do not attempt to fetch any missing blocks from the network (default: false)
+   */
+  offline?: boolean
+}
+
 export interface Blocks extends Blockstore<ProgressOptions<HasBlockProgressEvents>,
 ProgressOptions<PutBlockProgressEvents>, ProgressOptions<PutManyBlocksProgressEvents>,
-ProgressOptions<GetBlockProgressEvents>, ProgressOptions<GetManyBlocksProgressEvents>, ProgressOptions<GetAllBlocksProgressEvents>,
+GetOfflineOptions & ProgressOptions<GetBlockProgressEvents>, GetOfflineOptions & ProgressOptions<GetManyBlocksProgressEvents>, ProgressOptions<GetAllBlocksProgressEvents>,
 ProgressOptions<DeleteBlockProgressEvents>, ProgressOptions<DeleteManyBlocksProgressEvents>
 > {