@helia/verified-fetch 2.4.0 → 2.5.0

package/src/plugins/plugin-handle-dag-pb.ts

@@ -0,0 +1,168 @@
+import { unixfs } from '@helia/unixfs'
+import { code as dagPbCode } from '@ipld/dag-pb'
+import { exporter } from 'ipfs-unixfs-exporter'
+import { CustomProgressEvent } from 'progress-events'
+import { ByteRangeContext } from '../utils/byte-range-context.js'
+import { getStreamFromAsyncIterable } from '../utils/get-stream-from-async-iterable.js'
+import { setIpfsRoots } from '../utils/response-headers.js'
+import { badGatewayResponse, badRangeResponse, movedPermanentlyResponse, notSupportedResponse, okRangeResponse } from '../utils/responses.js'
+import { setContentType } from '../utils/set-content-type.js'
+import { BasePlugin } from './plugin-base.js'
+import type { PluginContext } from './types.js'
+import type { CIDDetail } from '../index.js'
+
+/**
+ * Handles UnixFS and dag-pb content.
+ */
+export class DagPbPlugin extends BasePlugin {
+  readonly codes = [dagPbCode]
+  canHandle ({ cid, accept, pathDetails }: PluginContext): boolean {
+    this.log('checking if we can handle %c with accept %s', cid, accept)
+    if (pathDetails == null) {
+      return false
+    }
+
+    return cid.code === dagPbCode
+  }
+
+  /**
+   * @see https://specs.ipfs.tech/http-gateways/path-gateway/#use-in-directory-url-normalization
+   */
+  getRedirectUrl (context: PluginContext): string | null {
+    const { resource, path } = context
+    const redirectCheckNeeded = path === '' ? !resource.toString().endsWith('/') : !path.endsWith('/')
+    if (redirectCheckNeeded) {
+      try {
+        const url = new URL(resource.toString())
+        // make sure we append slash to end of the path
+        url.pathname = `${url.pathname}/`
+        return url.toString()
+      } catch (err: any) {
+        // resource is likely a CID
+        return `${resource.toString()}/`
+      }
+    }
+    return null
+  }
+
+  async handle (context: PluginContext): Promise<Response | null> {
+    const { cid, options, withServerTiming = false, pathDetails } = context
+    const { handleServerTiming, contentTypeParser, helia, getBlockstore } = this.pluginOptions
+    const log = this.log
+    let resource = context.resource
+    let path = context.path
+
+    let redirected = false
+    const byteRangeContext = new ByteRangeContext(this.pluginOptions.logger, options?.headers)
+
+    if (pathDetails == null) {
+      throw new TypeError('Path details are required')
+    }
+    const ipfsRoots = pathDetails.ipfsRoots
+    const terminalElement = pathDetails.terminalElement
+    let resolvedCID = terminalElement.cid
+
+    if (terminalElement?.type === 'directory') {
+      const dirCid = terminalElement.cid
+      const redirectUrl = this.getRedirectUrl(context)
+
+      if (redirectUrl != null) {
+        log.trace('directory url normalization spec requires redirect...')
+        if (options?.redirect === 'error') {
+          log('could not redirect to %s as redirect option was set to "error"', redirectUrl)
+          throw new TypeError('Failed to fetch')
+        } else if (options?.redirect === 'manual') {
+          log('returning 301 permanent redirect to %s', redirectUrl)
+          return movedPermanentlyResponse(resource, redirectUrl)
+        }
+        log('following redirect to %s', redirectUrl)
+
+        // fall-through simulates following the redirect?
+        resource = redirectUrl
+        redirected = true
+      }
+
+      const rootFilePath = 'index.html'
+      try {
+        log.trace('found directory at %c/%s, looking for index.html', cid, path)
+
+        const entry = await handleServerTiming('exporter-dir', '', async () => exporter(`/ipfs/${dirCid}/${rootFilePath}`, helia.blockstore, {
+          signal: options?.signal,
+          onProgress: options?.onProgress
+        }), withServerTiming)
+
+        log.trace('found root file at %c/%s with cid %c', dirCid, rootFilePath, entry.cid)
+        path = rootFilePath
+        resolvedCID = entry.cid
+      } catch (err: any) {
+        this.log.error('error loading path %c/%s', dirCid, rootFilePath, err)
+        options?.signal?.throwIfAborted()
+        context.isDirectory = true
+        context.directoryEntries = []
+        this.log.trace('attempting to get directory entries because index.html was not found')
+        const fs = unixfs({ ...helia, blockstore: getBlockstore(context.cid, context.resource, options?.session ?? true, options) })
+        try {
+          for await (const dirItem of fs.ls(dirCid, { signal: options?.signal, onProgress: options?.onProgress })) {
+            context.directoryEntries.push(dirItem)
+          }
+          // dir-index-html plugin or dir-index-json (future idea?) plugin should handle this
+          return null
+        } catch (e) {
+          log.error('error listing directory %c', dirCid, e)
+          return notSupportedResponse('Unable to get directory contents')
+        }
+      } finally {
+        options?.onProgress?.(new CustomProgressEvent<CIDDetail>('verified-fetch:request:end', { cid: dirCid, path: rootFilePath }))
+      }
+    }
+
+    // we have a validRangeRequest & terminalElement is a file, we know the size and should set it
+    if (byteRangeContext.isRangeRequest && byteRangeContext.isValidRangeRequest && terminalElement.type === 'file') {
+      byteRangeContext.setFileSize(terminalElement.unixfs.fileSize())
+
+      log.trace('fileSize for rangeRequest %d', byteRangeContext.getFileSize())
+    }
+    const offset = byteRangeContext.offset
+    const length = byteRangeContext.length
+    log.trace('calling exporter for %c/%s with offset=%o & length=%o', resolvedCID, path, offset, length)
+
+    try {
+      const entry = await handleServerTiming('exporter-file', '', async () => exporter(resolvedCID, helia.blockstore, {
+        signal: options?.signal,
+        onProgress: options?.onProgress
+      }), withServerTiming)
+
+      const asyncIter = entry.content({
+        signal: options?.signal,
+        onProgress: options?.onProgress,
+        offset,
+        length
+      })
+      log('got async iterator for %c/%s', cid, path)
+
+      const { stream, firstChunk } = await handleServerTiming('stream-and-chunk', '', async () => getStreamFromAsyncIterable(asyncIter, path ?? '', this.pluginOptions.logger, {
+        onProgress: options?.onProgress,
+        signal: options?.signal
+      }), withServerTiming)
+
+      byteRangeContext.setBody(stream)
+      // if not a valid range request, okRangeRequest will call okResponse
+      const response = okRangeResponse(resource, byteRangeContext.getBody(), { byteRangeContext, log }, {
+        redirected
+      })
+
+      await handleServerTiming('set-content-type', '', async () => setContentType({ bytes: firstChunk, path, response, contentTypeParser, log }), withServerTiming)
+
+      setIpfsRoots(response, ipfsRoots)
+
+      return response
+    } catch (err: any) {
+      options?.signal?.throwIfAborted()
+      log.error('error streaming %c/%s', cid, path, err)
+      if (byteRangeContext.isRangeRequest && err.code === 'ERR_INVALID_PARAMS') {
+        return badRangeResponse(resource)
+      }
+      return badGatewayResponse(resource.toString(), 'Unable to stream content')
+    }
+  }
+}

package/src/plugins/plugin-handle-dag-walk.ts

@@ -0,0 +1,53 @@
+import { code as dagCborCode } from '@ipld/dag-cbor'
+import { code as dagPbCode } from '@ipld/dag-pb'
+import { handlePathWalking } from '../utils/walk-path.js'
+import { BasePlugin } from './plugin-base.js'
+import type { PluginContext } from './types.js'
+
+/**
+ * This plugin should almost always run first because it's going to handle path walking if needed, and will only say it can handle
+ * the request if path walking is possible (path is not empty, terminalCid is unknown, and the path has not been walked yet).
+ *
+ * Once this plugin has run, the PluginContext will be updated and then this plugin will return false for canHandle, so it won't run again.
+ */
+export class DagWalkPlugin extends BasePlugin {
+  /**
+   * Return false if the path has already been walked, otherwise return true if the CID is encoded with a codec that supports pathing.
+   */
+  canHandle (context: PluginContext): boolean {
+    this.log('checking if we can handle %c with accept %s', context.cid, context.accept)
+    const { pathDetails, cid } = context
+    if (pathDetails != null) {
+      // path has already been walked
+      return false
+    }
+
+    return (cid.code === dagPbCode || cid.code === dagCborCode)
+  }
+
+  async handle (context: PluginContext): Promise<Response | null> {
+    const { cid, resource, options, withServerTiming = false } = context
+    const { getBlockstore, handleServerTiming } = this.pluginOptions
+    const blockstore = getBlockstore(cid, resource, options?.session ?? true, options)
+    // TODO: migrate handlePathWalking into this plugin
+    const pathDetails = await handleServerTiming('path-walking', '', async () => handlePathWalking({ ...context, blockstore, log: this.log }), withServerTiming)
+
+    context.modified++
+    if (pathDetails instanceof Response) {
+      this.log.trace('path walking failed')
+
+      if (pathDetails.status === 404) {
+        // invalid or incorrect path.. we walked the path but nothing is there
+        // send the 404 response
+        return pathDetails
+      }
+
+      // some error walking the path
+      return null
+    }
+
+    context.pathDetails = pathDetails
+
+    return null
+  }
+}

package/src/plugins/plugin-handle-dir-index-html.ts

@@ -0,0 +1,44 @@
+import { code as dagPbCode } from '@ipld/dag-pb'
+import { dirIndexHtml } from '../utils/dir-index-html.js'
+import { okResponse } from '../utils/responses.js'
+import { BasePlugin } from './plugin-base.js'
+import type { PluginContext, VerifiedFetchPluginFactory } from './types.js'
+
+export class DirIndexHtmlPlugin extends BasePlugin {
+  readonly codes = [dagPbCode]
+  canHandle (context: PluginContext): boolean {
+    const { cid, pathDetails, directoryEntries } = context
+    if (pathDetails == null) {
+      return false
+    }
+    if (pathDetails.terminalElement?.type !== 'directory') {
+      return false
+    }
+
+    if (directoryEntries?.length === 0) {
+      return false
+    }
+
+    return cid.code === dagPbCode
+  }
+
+  async handle (context: PluginContext): Promise<Response> {
+    const { resource, pathDetails, directoryEntries } = context
+
+    if (pathDetails?.terminalElement == null) {
+      throw new Error('Path details are required')
+    }
+    if (directoryEntries == null || directoryEntries?.length === 0) {
+      throw new Error('Directory entries are required')
+    }
+    const terminalElement = pathDetails.terminalElement
+
+    const gatewayURL = resource
+    const htmlResponse = dirIndexHtml(terminalElement, directoryEntries, { gatewayURL, log: this.log })
+    const response = okResponse(resource, htmlResponse)
+    response.headers.set('content-type', 'text/html')
+    return response
+  }
+}
+
+export const dirIndexHtmlPluginFactory: VerifiedFetchPluginFactory = (opts) => new DirIndexHtmlPlugin(opts)

package/src/plugins/plugin-handle-ipns-record.ts

@@ -0,0 +1,69 @@
+import { Record as DHTRecord } from '@libp2p/kad-dht'
+import { Key } from 'interface-datastore'
+import { concat as uint8ArrayConcat } from 'uint8arrays/concat'
+import { fromString as uint8ArrayFromString } from 'uint8arrays/from-string'
+import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
+import { getPeerIdFromString } from '../utils/get-peer-id-from-string.js'
+import { badRequestResponse, okResponse } from '../utils/responses.js'
+import { PluginFatalError } from './errors.js'
+import { BasePlugin } from './plugin-base.js'
+import type { PluginContext } from './types.js'
+import type { PeerId } from '@libp2p/interface'
+
+/**
+ * Accepts an `ipns://...`, `https?://<ipnsname>.ipns.<domain>`, or `https?://<domain>/ipns/...` URL as a string and
+ * returns a `Response` containing a raw IPNS record.
+ */
+export class IpnsRecordPlugin extends BasePlugin {
+  readonly codes = []
+  canHandle ({ cid, accept, query }: PluginContext): boolean {
+    this.log('checking if we can handle %c with accept %s', cid, accept)
+
+    return accept === 'application/vnd.ipfs.ipns-record' || query.format === 'ipns-record'
+  }
+
+  async handle (context: PluginContext): Promise<Response> {
+    const { resource, path, options } = context
+    const { helia } = this.pluginOptions
+    context.reqFormat = 'ipns-record'
+    if (path !== '' || !(resource.startsWith('ipns://') || resource.includes('.ipns.') || resource.includes('/ipns/'))) {
+      this.log.error('invalid request for IPNS name "%s" and path "%s"', resource, path)
+      throw new PluginFatalError('ERR_INVALID_IPNS_NAME', 'Invalid IPNS name', { response: badRequestResponse(resource, 'Invalid IPNS name') })
+    }
+    let peerId: PeerId
+
+    try {
+      let peerIdString: string
+      if (resource.startsWith('ipns://')) {
+        peerIdString = resource.replace('ipns://', '')
+      } else if (resource.includes('/ipns/')) {
+        peerIdString = resource.split('/ipns/')[1].split('/')[0].split('?')[0]
+      } else {
+        peerIdString = resource.split('.ipns.')[0].split('://')[1]
+      }
+
+      this.log.trace('trying to parse peer id from "%s"', peerIdString)
+      peerId = getPeerIdFromString(peerIdString)
+    } catch (err: any) {
+      this.log.error('could not parse peer id from IPNS url %s', resource, err)
+
+      throw new PluginFatalError('ERR_NO_PEER_ID_FOUND', 'could not parse peer id from url', { response: badRequestResponse(resource, err) })
+    }
+
+    // since this call happens after parseResource, we've already resolved the
+    // IPNS name so a local copy should be in the helia datastore, so we can
+    // just read it out..
+    const routingKey = uint8ArrayConcat([
+      uint8ArrayFromString('/ipns/'),
+      peerId.toMultihash().bytes
+    ])
+    const datastoreKey = new Key('/dht/record/' + uint8ArrayToString(routingKey, 'base32'), false)
+    const buf = await helia.datastore.get(datastoreKey, options)
+    const record = DHTRecord.deserialize(buf)
+
+    const response = okResponse(resource, record.value)
+    response.headers.set('content-type', 'application/vnd.ipfs.ipns-record')
+
+    return response
+  }
+}

package/src/plugins/plugin-handle-json.ts

@@ -0,0 +1,57 @@
+import * as ipldDagCbor from '@ipld/dag-cbor'
+import * as ipldDagJson from '@ipld/dag-json'
+import { code as jsonCode } from 'multiformats/codecs/json'
+import { notAcceptableResponse, okResponse } from '../utils/responses.js'
+import { BasePlugin } from './plugin-base.js'
+import type { PluginContext } from './types.js'
+
+/**
+ * Handles `dag-json` content, including requests with Accept: `application/vnd.ipld.dag-cbor` and `application/cbor`.
+ */
+export class JsonPlugin extends BasePlugin {
+  readonly codes = [ipldDagJson.code, jsonCode]
+  canHandle ({ cid, accept }: PluginContext): boolean {
+    this.log('checking if we can handle %c with accept %s', cid, accept)
+
+    if (accept === 'application/vnd.ipld.dag-json' && cid.code !== ipldDagCbor.code) {
+      // we can handle application/vnd.ipld.dag-json, but if the CID codec is ipldDagCbor, DagCborPlugin should handle it
+      // TODO: remove the need for deny-listing cases in plugins
+      return true
+    }
+
+    return ipldDagJson.code === cid.code || jsonCode === cid.code
+  }
+
+  async handle (context: PluginContext): Promise<Response> {
+    const { path, resource, cid, accept, options } = context
+    const { getBlockstore } = this.pluginOptions
+    const session = options?.session ?? true
+
+    this.log.trace('fetching %c/%s', cid, path)
+
+    const terminalCid = context.pathDetails?.terminalElement.cid ?? context.cid
+    const blockstore = getBlockstore(terminalCid, resource, session, options)
+    const block = await blockstore.get(terminalCid, options)
+    let body: string | Uint8Array
+
+    if (accept === 'application/vnd.ipld.dag-cbor' || accept === 'application/cbor') {
+      try {
+        // if vnd.ipld.dag-cbor has been specified, convert to the format - note
+        // that this supports more data types than regular JSON, the content-type
+        // response header is set so the user knows to process it differently
+        const obj = ipldDagJson.decode(block)
+        body = ipldDagCbor.encode(obj)
+      } catch (err) {
+        this.log.error('could not transform %c to application/vnd.ipld.dag-cbor', err)
+        return notAcceptableResponse(resource)
+      }
+    } else {
+      // skip decoding
+      body = block
+    }
+
+    const response = okResponse(resource, body)
+    response.headers.set('content-type', accept ?? 'application/json')
+    return response
+  }
+}

package/src/plugins/plugin-handle-raw.ts

@@ -0,0 +1,92 @@
+import { code as rawCode } from 'multiformats/codecs/raw'
+import { identity } from 'multiformats/hashes/identity'
+import { ByteRangeContext } from '../utils/byte-range-context.js'
+import { notFoundResponse, okRangeResponse } from '../utils/responses.js'
+import { setContentType } from '../utils/set-content-type.js'
+import { PluginFatalError } from './errors.js'
+import { BasePlugin } from './plugin-base.js'
+import type { PluginContext } from './types.js'
+
+/**
+ * These are Accept header values that will cause content type sniffing to be
+ * skipped and set to these values.
+ */
+const RAW_HEADERS = [
+  'application/vnd.ipld.dag-json',
+  'application/vnd.ipld.raw',
+  'application/octet-stream'
+]
+
+/**
+ * if the user has specified an `Accept` header, and it's in our list of
+ * allowable "raw" format headers, use that instead of detecting the content
+ * type. This avoids the user from receiving something different when they
+ * signal that they want to `Accept` a specific mime type.
+ */
+function getOverridenRawContentType ({ headers, accept }: { headers?: HeadersInit, accept?: string }): string | undefined {
+  // accept has already been resolved by getResolvedAcceptHeader, if we have it, use it.
+  const acceptHeader = accept ?? new Headers(headers).get('accept') ?? ''
+
+  // e.g. "Accept: text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, */*;q=0.8"
+  const acceptHeaders = acceptHeader.split(',')
+    .map(s => s.split(';')[0])
+    .map(s => s.trim())
+
+  for (const mimeType of acceptHeaders) {
+    if (mimeType === '*/*') {
+      return
+    }
+
+    if (RAW_HEADERS.includes(mimeType ?? '')) {
+      return mimeType
+    }
+  }
+}
+
+export class RawPlugin extends BasePlugin {
+  codes: number[] = [rawCode, identity.code]
+
+  canHandle ({ cid, accept, query }: PluginContext): boolean {
+    this.log('checking if we can handle %c with accept %s', cid, accept)
+    return accept === 'application/vnd.ipld.raw' || query.format === 'raw'
+  }
+
+  async handle (context: PluginContext): Promise<Response> {
+    const { path, resource, cid, accept, query, options } = context
+    const { getBlockstore, contentTypeParser } = this.pluginOptions
+    const session = options?.session ?? true
+    const log = this.log
+
+    if (accept === 'application/vnd.ipld.raw' || query.format === 'raw') {
+      context.reqFormat = 'raw'
+      context.query.download = true
+      context.query.filename = context.query.filename ?? `${cid.toString()}.bin`
+      log.trace('Set content disposition...')
+    } else {
+      log.trace('Did NOT setting content disposition...')
+    }
+
+    if (path !== '' && cid.code === rawCode) {
+      log.trace('404-ing raw codec request for %c/%s', cid, path)
+      // throw new PluginError('ERR_RAW_PATHS_NOT_SUPPORTED', 'Raw codec does not support paths')
+      // return notFoundResponse(resource, 'Raw codec does not support paths')
+      throw new PluginFatalError('ERR_RAW_PATHS_NOT_SUPPORTED', 'Raw codec does not support paths', { response: notFoundResponse(resource, 'Raw codec does not support paths') })
+    }
+
+    const byteRangeContext = new ByteRangeContext(this.pluginOptions.logger, options?.headers)
+    const terminalCid = context.pathDetails?.terminalElement.cid ?? context.cid
+    const blockstore = getBlockstore(terminalCid, resource, session, options)
+    const result = await blockstore.get(terminalCid, options)
+    byteRangeContext.setBody(result)
+    const response = okRangeResponse(resource, byteRangeContext.getBody(), { byteRangeContext, log }, {
+      redirected: false
+    })
+
+    // if the user has specified an `Accept` header that corresponds to a raw
+    // type, honour that header, so for example they don't request
+    // `application/vnd.ipld.raw` but get `application/octet-stream`
+    await setContentType({ bytes: result, path, response, defaultContentType: getOverridenRawContentType({ headers: options?.headers, accept }), contentTypeParser, log })
+
+    return response
+  }
+}

package/src/plugins/plugin-handle-tar.ts

@@ -0,0 +1,44 @@
+import { code as dagPbCode } from '@ipld/dag-pb'
+import toBrowserReadableStream from 'it-to-browser-readablestream'
+import { code as rawCode } from 'multiformats/codecs/raw'
+import { getETag } from '../utils/get-e-tag.js'
+import { tarStream } from '../utils/get-tar-stream.js'
+import { notAcceptableResponse, okResponse } from '../utils/responses.js'
+import { BasePlugin } from './plugin-base.js'
+import type { PluginContext } from './types.js'
+
+/**
+ * Accepts a UnixFS `CID` and returns a `.tar` file containing the file or
+ * directory structure referenced by the `CID`.
+ */
+export class TarPlugin extends BasePlugin {
+  readonly codes = []
+  canHandle ({ cid, accept, query }: PluginContext): boolean {
+    this.log('checking if we can handle %c with accept %s', cid, accept)
+    return accept === 'application/x-tar' || query.format === 'tar'
+  }
+
+  async handle (context: PluginContext): Promise<Response> {
+    const { cid, path, resource, options, pathDetails } = context
+    const { getBlockstore } = this.pluginOptions
+
+    const terminusElement = pathDetails?.terminalElement.cid ?? cid
+    if (terminusElement.code !== dagPbCode && terminusElement.code !== rawCode) {
+      return notAcceptableResponse('only UnixFS data can be returned in a TAR file')
+    }
+
+    context.reqFormat = 'tar'
+    context.query.download = true
+    context.query.filename = context.query.filename ?? `${terminusElement.toString()}.tar`
+
+    const blockstore = getBlockstore(terminusElement, resource, options?.session, options)
+    const stream = toBrowserReadableStream<Uint8Array>(tarStream(`/ipfs/${cid}/${path}`, blockstore, options))
+
+    const response = okResponse(resource, stream)
+    response.headers.set('content-type', 'application/x-tar')
+
+    response.headers.set('etag', getETag({ cid: terminusElement, reqFormat: context.reqFormat, weak: true }))
+
+    return response
+  }
+}

package/src/plugins/plugins.ts

@@ -0,0 +1,4 @@
+/**
+ * Export extension (non-default) plugins here
+ */
+export { DirIndexHtmlPlugin, dirIndexHtmlPluginFactory } from './plugin-handle-dir-index-html.js'

package/src/plugins/types.ts

@@ -0,0 +1,73 @@
+import type { PluginError } from './errors.js'
+import type { VerifiedFetchInit } from '../index.js'
+import type { ContentTypeParser, RequestFormatShorthand } from '../types.js'
+import type { ParsedUrlStringResults } from '../utils/parse-url-string.js'
+import type { PathWalkerResponse } from '../utils/walk-path.js'
+import type { AbortOptions, ComponentLogger, Logger } from '@libp2p/interface'
+import type { Helia } from 'helia'
+import type { Blockstore } from 'interface-blockstore'
+import type { UnixFSEntry } from 'ipfs-unixfs-exporter'
+import type { CID } from 'multiformats/cid'
+import type { CustomProgressEvent } from 'progress-events'
+
+/**
+ * Contains common components and functions required by plugins to handle a request.
+ * - Read-Only: Plugins can read but shouldn’t rewrite them.
+ * - Persistent: Relevant even after the request completes (e.g., logging or metrics).
+ */
+export interface PluginOptions {
+  logger: ComponentLogger
+  getBlockstore(cid: CID, resource: string | CID, useSession?: boolean, options?: AbortOptions): Blockstore
+  handleServerTiming<T>(name: string, description: string, fn: () => Promise<T>, withServerTiming: boolean): Promise<T>
+  contentTypeParser?: ContentTypeParser
+  helia: Helia
+}
+
+/**
+ * Represents the ephemeral, modifiable state used by the pipeline.
+ * - Mutable: Evolves as you walk the plugin chain.
+ * - Shared Data: Allows plugins to communicate partial results, discovered data, or interim errors.
+ * - Ephemeral: Typically discarded once fetch(...) completes.
+ */
+export interface PluginContext {
+  readonly cid: CID
+  readonly path: string
+  readonly resource: string
+  readonly accept?: string
+  /**
+   * The last time the context is modified, so we know whether a plugin has modified it.
+   * A plugin should increment this value if it modifies the context.
+   */
+  modified: number
+  withServerTiming?: boolean
+  onProgress?(evt: CustomProgressEvent<any>): void
+  options?: Omit<VerifiedFetchInit, 'signal'> & AbortOptions
+  isDirectory?: boolean
+  directoryEntries?: UnixFSEntry[]
+  errors?: PluginError[]
+  reqFormat?: RequestFormatShorthand
+  pathDetails?: PathWalkerResponse
+  query: ParsedUrlStringResults['query']
+  [key: string]: unknown
+}
+
+export interface VerifiedFetchPlugin {
+  readonly codes: number[]
+  readonly log: Logger
+  canHandle (context: PluginContext): boolean
+  handle (context: PluginContext): Promise<Response | null>
+}
+
+export interface VerifiedFetchPluginFactory {
+  (options: PluginOptions): VerifiedFetchPlugin
+}
+
+export interface PluginErrorOptions {
+  fatal?: boolean
+  details?: Record<string, any>
+  response?: Response
+}
+
+export interface FatalPluginErrorOptions extends PluginErrorOptions {
+  response: Response
+}

package/src/types.ts

@@ -1,41 +1,7 @@
-import { type AbortOptions } from '@libp2p/interface'
-import { type CID } from 'multiformats/cid'
-import type { VerifiedFetchInit } from './index.js'
-
 export type RequestFormatShorthand = 'raw' | 'car' | 'tar' | 'ipns-record' | 'dag-json' | 'dag-cbor' | 'json' | 'cbor'
 
 export type SupportedBodyTypes = string | ArrayBuffer | Blob | ReadableStream<Uint8Array> | null
 
-export interface FetchHandlerFunctionArg {
-  cid: CID
-  path: string
-
-  /**
-   * Whether to use a session during fetch operations
-   *
-   * @default true
-   */
-  session: boolean
-
-  options?: Omit<VerifiedFetchInit, 'signal'> & AbortOptions
-
-  /**
-   * If present, the user has sent an accept header with this value - if the
-   * content cannot be represented in this format a 406 should be returned
-   */
-  accept?: string
-
-  /**
-   * The originally requested resource
-   */
-  resource: string
-
-  /**
-   * Whether to include server-timing headers in the response.
-   */
-  withServerTiming: boolean
-}
-
 /**
  * A ContentTypeParser attempts to return the mime type of a given file. It
  * receives the first chunk of the file data and the file name, if it is