@helia/car 5.0.1 → 5.1.0-faac4ad3

package/src/traversal-strategies/graph-search.ts

@@ -1,25 +1,83 @@
+import { breadthFirstWalker, depthFirstWalker } from '@helia/utils'
+import { InvalidParametersError } from '@libp2p/interface'
+import toBuffer from 'it-to-buffer'
+import { createUnsafe } from 'multiformats/block'
+import { InvalidTraversalError } from '../errors.ts'
 import type { TraversalStrategy } from '../index.js'
-import type { BlockView } from 'multiformats/block/interface'
+import type { CodecLoader } from '@helia/interface'
+import type { GraphWalker } from '@helia/utils'
+import type { AbortOptions } from '@libp2p/interface'
+import type { Blockstore } from 'interface-blockstore'
+import type { BlockView } from 'multiformats'
 import type { CID } from 'multiformats/cid'
 
+export interface GraphSearchOptions {
+  strategy?: 'depth-first' | 'breadth-first'
+}
+
+function isCID (obj?: any): obj is CID {
+  return obj != null && obj?.asCID === obj
+}
+
 /**
- * A traversal strategy that performs a breadth-first search (so as to not load blocks unnecessarily) looking for a
- * target CID. Traversal stops when we reach the target CID or run out of nodes.
+ * A traversal strategy that performs a depth-first search looking for a target
+ * CID.
  */
 export class GraphSearch implements TraversalStrategy {
-  private readonly target: CID
+  private haystack?: CID
+  private readonly needle: CID
+  private readonly options?: GraphSearchOptions
 
-  constructor (target: CID) {
-    this.target = target
+  constructor (needle: CID, options?: GraphSearchOptions)
+  constructor (haystack: CID, needle: CID, options?: GraphSearchOptions)
+  constructor (...args: any[]) {
+    if (isCID(args[0])) {
+      if (isCID(args[1])) {
+        this.haystack = args[0]
+        this.needle = args[1]
+        this.options = args[2]
+      } else {
+        this.needle = args[0]
+        this.options = args[1]
+      }
+    } else {
+      throw new InvalidParametersError('needle must be specified')
+    }
   }
 
-  isTarget (cid: CID): boolean {
-    return this.target.equals(cid)
-  }
+  async * traverse (root: CID, blockstore: Blockstore, getCodec: CodecLoader, options?: AbortOptions): AsyncGenerator<BlockView<unknown, number, number, 0 | 1>, void, undefined> {
+    const start = this.haystack ?? root
+    let walker: GraphWalker
 
-  async * traverse <T extends BlockView<any, any, any, 0 | 1>>(cid: CID, block: T): AsyncGenerator<CID, void, undefined> {
-    for (const [, linkedCid] of block.links()) {
-      yield linkedCid
+    if (this.options?.strategy === 'breadth-first') {
+      walker = breadthFirstWalker({
+        blockstore,
+        getCodec
+      })
+    } else {
+      walker = depthFirstWalker({
+        blockstore,
+        getCodec
+      })
     }
+
+    for await (const node of walker.walk(start, options)) {
+      if (node.block.cid.equals(this.needle)) {
+        for (const cid of node.path) {
+          const bytes = await toBuffer(blockstore.get(cid, options))
+          const block = createUnsafe({
+            cid,
+            bytes,
+            codec: await getCodec(cid.code)
+          })
+
+          yield block
+        }
+
+        return
+      }
+    }
+
+    throw new InvalidTraversalError(`${this.needle} was not a child of ${start}`)
   }
 }

package/src/traversal-strategies/unixfs-path.ts

@@ -1,58 +1,94 @@
-import { decode } from '@ipld/dag-pb'
-import { UnixFS } from 'ipfs-unixfs'
-import { DAG_PB_CODEC_CODE } from '../constants.js'
-import { NotUnixFSError } from '../errors.js'
+import * as dagPb from '@ipld/dag-pb'
+import { walkPath } from 'ipfs-unixfs-exporter'
+import { createUnsafe } from 'multiformats/block'
 import type { TraversalStrategy } from '../index.js'
-import type { BlockView } from 'multiformats/block/interface'
+import type { CodecLoader } from '@helia/interface'
+import type { AbortOptions } from '@libp2p/interface'
+import type { Blockstore } from 'interface-blockstore'
+import type { BlockView } from 'multiformats'
 import type { CID } from 'multiformats/cid'
 
 /**
  * Traverses a DAG containing UnixFS directories
+ *
+ * A root CID may be specified to begin traversal from, otherwise the root
+ * currently being exported will be used.
+ *
+ * @example Begin traversal from the root being exported
+ *
+ * In this example, the UnixFS path `/foo/bar/baz.txt` path should be resolvable
+ * beneath the `root` CID.
+ *
+ * ```typescript
+ * import { createHelia } from 'helia'
+ * import { car, UnixFSPath } from '@helia/car'
+ * import { CID } from 'multiformats/cid'
+ *
+ * const helia = await createHelia()
+ * const c = car(helia)
+ * const root = CID.parse('QmRoot')
+ *
+ * for await (const buf of c.export(root, {
+ *   traversal: new UnixFSPath('/foo/bar/baz.txt')
+ * })) {
+ *   // do something with `buf`
+ * }
+ * ```
+ *
+ * @example Begin traversal from a parent node
+ *
+ * In this example, the `root` CID should be resolvable at the UnixFS path
+ * beneath `parentCID`.
+ *
+ * ```typescript
+ * import { createHelia } from 'helia'
+ * import { car, UnixFSPath } from '@helia/car'
+ * import { CID } from 'multiformats/cid'
+ *
+ * const helia = await createHelia()
+ * const c = car(helia)
+ * const root = CID.parse('QmRoot')
+ * const parentCID = CID.parse('QmParent')
+ *
+ * for await (const buf of c.export(root, {
+ *   traversal: new UnixFSPath(parentCID, '/foo/bar/baz.txt')
+ * })) {
+ *   // do something with `buf`
+ * }
+ * ```
  */
 export class UnixFSPath implements TraversalStrategy {
-  private readonly path: string[]
+  private readonly root?: CID
+  private readonly path: string
 
-  constructor (path: string) {
-    // "/foo/bar/baz.txt" -> ['foo', 'bar', 'baz.txt']
-    this.path = path.replace(/^\//, '').split('/')
-  }
-
-  isTarget (): boolean {
-    return this.path.length === 0
-  }
-
-  async * traverse <T extends BlockView<any, any, any, 0 | 1>>(cid: CID, block: T): AsyncGenerator<CID, void, undefined> {
-    if (cid.code !== DAG_PB_CODEC_CODE) {
-      throw new NotUnixFSError('Target CID is not UnixFS')
-    }
-
-    const segment = this.path.shift()
+  constructor (path: string)
+  constructor (root: CID, path: string)
+  constructor (...args: any[]) {
+    let root: CID | string | undefined = args[0]
+    let path: string = args[1]
 
-    if (segment == null) {
-      return
+    if (typeof root === 'string') {
+      path = root
+      root = undefined
+    } else if (args.length < 2) {
+      throw new Error('path or CID and path must be specified')
     }
 
-    const pb = decode(block.bytes)
-
-    if (pb.Data == null) {
-      throw new NotUnixFSError('Target CID has no UnixFS data in decoded bytes')
+    if (!path.startsWith('/')) {
+      path = `/${path}`
     }
 
-    const unixfs = UnixFS.unmarshal(pb.Data)
-
-    if (unixfs.type === 'directory') {
-      const link = pb.Links.filter(link => link.Name === segment).pop()
-
-      if (link == null) {
-        throw new NotUnixFSError(`Target CID directory has no link with name ${segment}`)
-      }
+    this.root = root
+    this.path = path
+  }
 
-      yield link.Hash
-      return
+  async * traverse (root: CID, blockstore: Blockstore, getCodec: CodecLoader, options?: AbortOptions): AsyncGenerator<BlockView<unknown, number, number, 0 | 1>, void, undefined> {
+    for await (const entry of walkPath(`${this.root ?? root}${this.path}`, blockstore, options)) {
+      yield createUnsafe({
+        cid: entry.cid,
+        bytes: entry.node instanceof Uint8Array ? entry.node : dagPb.encode(entry.node),
+        codec: await getCodec(entry.cid.code)
+      })
     }
-
-    // TODO: HAMT support
-
-    throw new NotUnixFSError('Target CID is not a UnixFS directory')
   }
 }

package/dist/typedoc-urls.json

@@ -1,20 +0,0 @@
-{
-  "BlockExporter": "https://ipfs.github.io/helia/classes/_helia_car.BlockExporter.html",
-  "CIDPath": "https://ipfs.github.io/helia/classes/_helia_car.CIDPath.html",
-  "GraphSearch": "https://ipfs.github.io/helia/classes/_helia_car.GraphSearch.html",
-  "SubgraphExporter": "https://ipfs.github.io/helia/classes/_helia_car.SubgraphExporter.html",
-  "UnixFSExporter": "https://ipfs.github.io/helia/classes/_helia_car.UnixFSExporter.html",
-  "UnixFSPath": "https://ipfs.github.io/helia/classes/_helia_car.UnixFSPath.html",
-  "Car": "https://ipfs.github.io/helia/interfaces/_helia_car.Car.html",
-  ".:Car": "https://ipfs.github.io/helia/interfaces/_helia_car.Car.html",
-  "CarComponents": "https://ipfs.github.io/helia/interfaces/_helia_car.CarComponents.html",
-  ".:CarComponents": "https://ipfs.github.io/helia/interfaces/_helia_car.CarComponents.html",
-  "ExportCarOptions": "https://ipfs.github.io/helia/interfaces/_helia_car.ExportCarOptions.html",
-  ".:ExportCarOptions": "https://ipfs.github.io/helia/interfaces/_helia_car.ExportCarOptions.html",
-  "ExportStrategy": "https://ipfs.github.io/helia/interfaces/_helia_car.ExportStrategy.html",
-  ".:ExportStrategy": "https://ipfs.github.io/helia/interfaces/_helia_car.ExportStrategy.html",
-  "TraversalStrategy": "https://ipfs.github.io/helia/interfaces/_helia_car.TraversalStrategy.html",
-  ".:TraversalStrategy": "https://ipfs.github.io/helia/interfaces/_helia_car.TraversalStrategy.html",
-  "car": "https://ipfs.github.io/helia/functions/_helia_car.car.html",
-  ".:car": "https://ipfs.github.io/helia/functions/_helia_car.car.html"
-}