@helia/verified-fetch 2.3.1 → 2.5.0

package/src/verified-fetch.ts

@@ -1,41 +1,31 @@
-import { car } from '@helia/car'
 import { ipns as heliaIpns, type IPNS } from '@helia/ipns'
-import * as ipldDagCbor from '@ipld/dag-cbor'
-import * as ipldDagJson from '@ipld/dag-json'
-import { code as dagPbCode } from '@ipld/dag-pb'
-import { type AbortOptions, type Logger, type PeerId } from '@libp2p/interface'
-import { Record as DHTRecord } from '@libp2p/kad-dht'
-import { Key } from 'interface-datastore'
-import { exporter, type ObjectNode } from 'ipfs-unixfs-exporter'
-import toBrowserReadableStream from 'it-to-browser-readablestream'
+import { type AbortOptions, type Logger } from '@libp2p/interface'
+import { prefixLogger } from '@libp2p/logger'
 import { LRUCache } from 'lru-cache'
 import { type CID } from 'multiformats/cid'
-import { code as jsonCode } from 'multiformats/codecs/json'
-import { code as rawCode } from 'multiformats/codecs/raw'
-import { identity } from 'multiformats/hashes/identity'
 import { CustomProgressEvent } from 'progress-events'
-import { concat as uint8ArrayConcat } from 'uint8arrays/concat'
-import { fromString as uint8ArrayFromString } from 'uint8arrays/from-string'
-import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
-import { ByteRangeContext } from './utils/byte-range-context.js'
-import { dagCborToSafeJSON } from './utils/dag-cbor-to-safe-json.js'
+import { CarPlugin } from './plugins/plugin-handle-car.js'
+import { DagCborPlugin } from './plugins/plugin-handle-dag-cbor.js'
+import { DagPbPlugin } from './plugins/plugin-handle-dag-pb.js'
+import { DagWalkPlugin } from './plugins/plugin-handle-dag-walk.js'
+import { IpnsRecordPlugin } from './plugins/plugin-handle-ipns-record.js'
+import { JsonPlugin } from './plugins/plugin-handle-json.js'
+import { RawPlugin } from './plugins/plugin-handle-raw.js'
+import { TarPlugin } from './plugins/plugin-handle-tar.js'
 import { getContentDispositionFilename } from './utils/get-content-disposition-filename.js'
 import { getETag } from './utils/get-e-tag.js'
-import { getPeerIdFromString } from './utils/get-peer-id-from-string.js'
 import { getResolvedAcceptHeader } from './utils/get-resolved-accept-header.js'
-import { getStreamFromAsyncIterable } from './utils/get-stream-from-async-iterable.js'
-import { tarStream } from './utils/get-tar-stream.js'
 import { getRedirectResponse } from './utils/handle-redirects.js'
 import { parseResource } from './utils/parse-resource.js'
 import { type ParsedUrlStringResults } from './utils/parse-url-string.js'
 import { resourceToSessionCacheKey } from './utils/resource-to-cache-key.js'
-import { setCacheControlHeader, setIpfsRoots } from './utils/response-headers.js'
-import { badRequestResponse, movedPermanentlyResponse, notAcceptableResponse, notSupportedResponse, okResponse, badRangeResponse, okRangeResponse, badGatewayResponse, notFoundResponse } from './utils/responses.js'
+import { setCacheControlHeader } from './utils/response-headers.js'
+import { badRequestResponse, notAcceptableResponse, notSupportedResponse, badGatewayResponse } from './utils/responses.js'
 import { selectOutputType } from './utils/select-output-type.js'
-import { setContentType } from './utils/set-content-type.js'
-import { handlePathWalking, isObjectNode } from './utils/walk-path.js'
+import { serverTiming } from './utils/server-timing.js'
 import type { CIDDetail, ContentTypeParser, CreateVerifiedFetchOptions, Resource, ResourceDetail, VerifiedFetchInit as VerifiedFetchOptions } from './index.js'
-import type { FetchHandlerFunctionArg, RequestFormatShorthand } from './types.js'
+import type { VerifiedFetchPlugin, PluginContext, PluginOptions } from './plugins/types.js'
+import type { RequestFormatShorthand } from './types.js'
 import type { Helia, SessionBlockstore } from '@helia/interface'
 import type { Blockstore } from 'interface-blockstore'
 
@@ -47,10 +37,6 @@ interface VerifiedFetchComponents {
   ipns?: IPNS
 }
 
-interface FetchHandlerFunction {
-  (options: FetchHandlerFunctionArg): Promise<Response>
-}
-
 function convertOptions (options?: VerifiedFetchOptions): (Omit<VerifiedFetchOptions, 'signal'> & AbortOptions) | undefined {
   if (options == null) {
     return undefined
@@ -69,40 +55,14 @@ function convertOptions (options?: VerifiedFetchOptions): (Omit<VerifiedFetchOpt
   }
 }
 
-/**
- * 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
-    }
-  }
+// TODO: merge/combine with PluginContext
+interface FinalResponseContext {
+  cid?: ParsedUrlStringResults['cid']
+  reqFormat?: RequestFormatShorthand
+  ttl?: ParsedUrlStringResults['ttl']
+  protocol?: ParsedUrlStringResults['protocol']
+  ipfsPath?: string
+  query?: ParsedUrlStringResults['query']
 }
 
 export class VerifiedFetch {
@@ -111,6 +71,9 @@ export class VerifiedFetch {
   private readonly log: Logger
   private readonly contentTypeParser: ContentTypeParser | undefined
   private readonly blockstoreSessions: LRUCache<string, SessionBlockstore>
+  private serverTimingHeaders: string[] = []
+  private readonly withServerTiming: boolean
+  private readonly plugins: VerifiedFetchPlugin[] = []
 
   constructor ({ helia, ipns }: VerifiedFetchComponents, init?: CreateVerifiedFetchOptions) {
     this.helia = helia
@@ -124,10 +87,47 @@ export class VerifiedFetch {
         store.close()
       }
     })
+    this.withServerTiming = init?.withServerTiming ?? false
+
+    const pluginOptions: PluginOptions = {
+      ...init,
+      logger: prefixLogger('helia:verified-fetch'),
+      getBlockstore: (cid, resource, useSession, options) => this.getBlockstore(cid, resource, useSession, options),
+      handleServerTiming: async (name, description, fn) => this.handleServerTiming(name, description, fn, this.withServerTiming),
+      helia,
+      contentTypeParser: this.contentTypeParser
+    }
+
+    const defaultPlugins = [
+      new DagWalkPlugin(pluginOptions),
+      new IpnsRecordPlugin(pluginOptions),
+      new CarPlugin(pluginOptions),
+      new RawPlugin(pluginOptions),
+      new TarPlugin(pluginOptions),
+      new JsonPlugin(pluginOptions),
+      new DagCborPlugin(pluginOptions),
+      new DagPbPlugin(pluginOptions)
+    ]
+
+    const customPlugins = init?.plugins?.map((pluginFactory) => pluginFactory(pluginOptions)) ?? []
+
+    if (customPlugins.length > 0) {
+      // allow custom plugins to replace default plugins
+      const defaultPluginMap = new Map(defaultPlugins.map(plugin => [plugin.constructor.name, plugin]))
+      const customPluginMap = new Map(customPlugins.map(plugin => [plugin.constructor.name, plugin]))
+
+      this.plugins = defaultPlugins.map(plugin => customPluginMap.get(plugin.constructor.name) ?? plugin)
+
+      // Add any remaining custom plugins that don't replace a default plugin
+      this.plugins.push(...customPlugins.filter(plugin => !defaultPluginMap.has(plugin.constructor.name)))
+    } else {
+      this.plugins = defaultPlugins
+    }
+
     this.log.trace('created VerifiedFetch instance')
   }
 
-  private getBlockstore (root: CID, resource: string | CID, useSession: boolean, options?: AbortOptions): Blockstore {
+  private getBlockstore (root: CID, resource: string | CID, useSession: boolean = true, options: AbortOptions = {}): Blockstore {
     const key = resourceToSessionCacheKey(resource)
     if (!useSession) {
       return this.helia.blockstore
@@ -143,313 +143,154 @@ export class VerifiedFetch {
     return session
   }
 
-  /**
-   * Accepts an `ipns://...` or `https?://<ipnsname>.ipns.<domain>` URL as a string and returns a `Response` containing
-   * a raw IPNS record.
-   */
-  private async handleIPNSRecord ({ resource, cid, path, options }: FetchHandlerFunctionArg): Promise<Response> {
-    if (path !== '' || !(resource.startsWith('ipns://') || resource.includes('.ipns.'))) {
-      this.log.error('invalid request for IPNS name "%s" and path "%s"', resource, path)
-      return badRequestResponse(resource, 'Invalid IPNS name')
+  private async handleServerTiming<T> (name: string, description: string, fn: () => Promise<T>, withServerTiming: boolean): Promise<T> {
+    if (!withServerTiming) {
+      return fn()
     }
-
-    let peerId: PeerId
-
-    try {
-      if (resource.startsWith('ipns://')) {
-        const peerIdString = resource.replace('ipns://', '')
-        this.log.trace('trying to parse peer id from "%s"', peerIdString)
-        peerId = getPeerIdFromString(peerIdString)
-      } else {
-        const 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)
-
-      return badRequestResponse(resource, err)
+    const { error, result, header } = await serverTiming(name, description, fn)
+    this.serverTimingHeaders.push(header)
+    if (error != null) {
+      throw error
     }
 
-    // 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 this.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
-  }
-
-  /**
-   * Accepts a `CID` and returns a `Response` with a body stream that is a CAR
-   * of the `DAG` referenced by the `CID`.
-   */
-  private async handleCar ({ resource, cid, session, options }: FetchHandlerFunctionArg): Promise<Response> {
-    const blockstore = this.getBlockstore(cid, resource, session, options)
-    const c = car({ blockstore, getCodec: this.helia.getCodec })
-    const stream = toBrowserReadableStream(c.stream(cid, options))
-
-    const response = okResponse(resource, stream)
-    response.headers.set('content-type', 'application/vnd.ipld.car; version=1')
-
-    return response
+    return result
   }
 
   /**
-   * Accepts a UnixFS `CID` and returns a `.tar` file containing the file or
-   * directory structure referenced by the `CID`.
+   * The last place a Response touches in verified-fetch before being returned to the user. This is where we add the
+   * Server-Timing header to the response if it has been collected. It should be used for any final processing of the
+   * response before it is returned to the user.
    */
-  private async handleTar ({ resource, cid, path, session, options }: FetchHandlerFunctionArg): Promise<Response> {
-    if (cid.code !== dagPbCode && cid.code !== rawCode) {
-      return notAcceptableResponse('only UnixFS data can be returned in a TAR file')
+  private handleFinalResponse (response: Response, { query, cid, reqFormat, ttl, protocol, ipfsPath }: FinalResponseContext = {}): Response {
+    if (this.serverTimingHeaders.length > 0) {
+      const headerString = this.serverTimingHeaders.join(', ')
+      response.headers.set('Server-Timing', headerString)
+      this.serverTimingHeaders = []
     }
 
-    const blockstore = this.getBlockstore(cid, resource, 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')
+    // set Content-Disposition header
+    let contentDisposition: string | undefined
 
-    return response
-  }
+    this.log.trace('checking for content disposition')
 
-  private async handleJson ({ resource, cid, path, accept, session, options }: FetchHandlerFunctionArg): Promise<Response> {
-    this.log.trace('fetching %c/%s', cid, path)
-    const blockstore = this.getBlockstore(cid, resource, session, options)
-    const block = await blockstore.get(cid, 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)
-      }
+    // force download if requested
+    if (query?.download === true) {
+      contentDisposition = 'attachment'
     } else {
-      // skip decoding
-      body = block
+      this.log.trace('download not requested')
     }
 
-    const response = okResponse(resource, body)
-    response.headers.set('content-type', accept ?? 'application/json')
-    return response
-  }
-
-  private async handleDagCbor ({ resource, cid, path, accept, session, options }: FetchHandlerFunctionArg): Promise<Response> {
-    this.log.trace('fetching %c/%s', cid, path)
-    let terminalElement: ObjectNode
-    const blockstore = this.getBlockstore(cid, resource, session, options)
+    // override filename if requested
+    if (query?.filename != null) {
+      if (contentDisposition == null) {
+        contentDisposition = 'inline'
+      }
 
-    // need to walk path, if it exists, to get the terminal element
-    const pathDetails = await handlePathWalking({ cid, path, resource, options, blockstore, log: this.log })
-    if (pathDetails instanceof Response) {
-      return pathDetails
-    }
-    const ipfsRoots = pathDetails.ipfsRoots
-    if (isObjectNode(pathDetails.terminalElement)) {
-      terminalElement = pathDetails.terminalElement
+      contentDisposition = `${contentDisposition}; ${getContentDispositionFilename(query.filename)}`
     } else {
-      // this should never happen, but if it does, we should log it and return notSupportedResponse
-      this.log.error('terminal element is not a dag-cbor node')
-      return notSupportedResponse(resource, 'Terminal element is not a dag-cbor node')
+      this.log.trace('no filename specified in query')
     }
 
-    const block = terminalElement.node
-
-    let body: string | Uint8Array
-
-    if (accept === 'application/octet-stream' || accept === 'application/vnd.ipld.dag-cbor' || accept === 'application/cbor') {
-      // skip decoding
-      body = block
-    } else if (accept === 'application/vnd.ipld.dag-json') {
-      try {
-        // if vnd.ipld.dag-json 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 = ipldDagCbor.decode(block)
-        body = ipldDagJson.encode(obj)
-      } catch (err) {
-        this.log.error('could not transform %c to application/vnd.ipld.dag-json', err)
-        return notAcceptableResponse(resource)
-      }
+    if (contentDisposition != null) {
+      response.headers.set('Content-Disposition', contentDisposition)
     } else {
-      try {
-        body = dagCborToSafeJSON(block)
-      } catch (err) {
-        if (accept === 'application/json') {
-          this.log('could not decode DAG-CBOR as JSON-safe, but the client sent "Accept: application/json"', err)
-
-          return notAcceptableResponse(resource)
-        }
-
-        this.log('could not decode DAG-CBOR as JSON-safe, falling back to `application/octet-stream`', err)
-        body = block
-      }
+      this.log.trace('no content disposition specified')
     }
 
-    const response = okResponse(resource, body)
-
-    if (accept == null) {
-      accept = body instanceof Uint8Array ? 'application/octet-stream' : 'application/json'
+    if (cid != null && response.headers.get('etag') == null) {
+      response.headers.set('etag', getETag({ cid, reqFormat, weak: false }))
     }
 
-    response.headers.set('content-type', accept)
-    setIpfsRoots(response, ipfsRoots)
+    if (protocol != null) {
+      setCacheControlHeader({ response, ttl, protocol })
+    }
+    if (ipfsPath != null) {
+      response.headers.set('X-Ipfs-Path', ipfsPath)
+    }
 
     return response
   }
 
-  private async handleDagPb ({ cid, path, resource, session, options }: FetchHandlerFunctionArg): Promise<Response> {
-    let redirected = false
-    const byteRangeContext = new ByteRangeContext(this.helia.logger, options?.headers)
-    const blockstore = this.getBlockstore(cid, resource, session, options)
-    const pathDetails = await handlePathWalking({ cid, path, resource, options, blockstore, log: this.log })
-    if (pathDetails instanceof Response) {
-      return pathDetails
-    }
-    const ipfsRoots = pathDetails.ipfsRoots
-    const terminalElement = pathDetails.terminalElement
-    let resolvedCID = terminalElement.cid
-
-    if (terminalElement?.type === 'directory') {
-      const dirCid = terminalElement.cid
-      const redirectCheckNeeded = path === '' ? !resource.toString().endsWith('/') : !path.endsWith('/')
-
-      // https://specs.ipfs.tech/http-gateways/path-gateway/#use-in-directory-url-normalization
-      if (redirectCheckNeeded) {
-        if (options?.redirect === 'error') {
-          this.log('could not redirect to %s/ as redirect option was set to "error"', resource)
-          throw new TypeError('Failed to fetch')
-        } else if (options?.redirect === 'manual') {
-          this.log('returning 301 permanent redirect to %s/', resource)
-          return movedPermanentlyResponse(resource, `${resource}/`)
+  /**
+   * Runs plugins in a loop. After each plugin that returns `null` (partial/no final),
+   * we re-check `canHandle()` for all plugins in the next iteration if the context changed.
+   */
+  private async runPluginPipeline (context: PluginContext, maxPasses: number = 3): Promise<Response | undefined> {
+    let finalResponse: Response | undefined
+    let passCount = 0
+    const pluginsUsed = new Set<string>()
+
+    let prevModificationId = context.modified
+
+    while (passCount < maxPasses) {
+      this.log(`Starting pipeline pass #${passCount + 1}`)
+      passCount++
+
+      // gather plugins that say they can handle the *current* context, but haven't been used yet
+      const readyPlugins = this.plugins.filter(p => !pluginsUsed.has(p.constructor.name)).filter(p => p.canHandle(context))
+      if (readyPlugins.length === 0) {
+        this.log.trace('No plugins can handle the current context.. checking by CID code')
+        const plugins = this.plugins.filter(p => p.codes.includes(context.cid.code))
+        if (plugins.length > 0) {
+          readyPlugins.push(...plugins)
+        } else {
+          this.log.trace('No plugins found that can handle request by CID code; exiting pipeline.')
+          break
         }
-
-        // fall-through simulates following the redirect?
-        resource = `${resource}/`
-        redirected = true
-      }
-
-      const rootFilePath = 'index.html'
-      try {
-        this.log.trace('found directory at %c/%s, looking for index.html', cid, path)
-
-        const entry = await exporter(`/ipfs/${dirCid}/${rootFilePath}`, this.helia.blockstore, {
-          signal: options?.signal,
-          onProgress: options?.onProgress
-        })
-
-        this.log.trace('found root file at %c/%s with cid %c', dirCid, rootFilePath, entry.cid)
-        path = rootFilePath
-        resolvedCID = entry.cid
-      } catch (err: any) {
-        options?.signal?.throwIfAborted()
-        this.log('error loading path %c/%s', dirCid, rootFilePath, err)
-        return notSupportedResponse('Unable to find index.html for directory at given path. Support for directories with implicit root is not implemented')
-      } 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())
+      this.log.trace('Plugins ready to handle request: ', readyPlugins.map(p => p.constructor.name).join(', '))
+
+      // track if any plugin changed the context or returned a response
+      let contextChanged = false
+      let pluginHandled = false
+
+      for (const plugin of readyPlugins) {
+        try {
+          this.log.trace('Invoking plugin:', plugin.constructor.name)
+          pluginsUsed.add(plugin.constructor.name)
+
+          const maybeResponse = await plugin.handle(context)
+          if (maybeResponse != null) {
+            // if a plugin returns a final Response, short-circuit
+            finalResponse = maybeResponse
+            pluginHandled = true
+            break
+          }
+        } catch (err: any) {
+          context.options?.signal?.throwIfAborted()
+          this.log.error('Error in plugin:', plugin.constructor.name, err)
+          // if fatal, short-circuit the pipeline
+          if (err.name === 'PluginFatalError') {
+            // if plugin provides a custom error response, return it
+            return err.response ?? badGatewayResponse(context.resource, 'Failed to fetch')
+          }
+        } finally {
+          // on each plugin call, check for changes in the context
+          const newModificationId = context.modified
+          contextChanged = newModificationId !== prevModificationId
+          if (contextChanged) {
+            prevModificationId = newModificationId
+          }
+        }
 
-      this.log.trace('fileSize for rangeRequest %d', byteRangeContext.getFileSize())
-    }
-    const offset = byteRangeContext.offset
-    const length = byteRangeContext.length
-    this.log.trace('calling exporter for %c/%s with offset=%o & length=%o', resolvedCID, path, offset, length)
+        if (finalResponse != null) {
+          this.log.trace('Plugin produced final response:', plugin.constructor.name)
+          break
+        }
+      }
 
-    try {
-      const entry = await exporter(resolvedCID, this.helia.blockstore, {
-        signal: options?.signal,
-        onProgress: options?.onProgress
-      })
-
-      const asyncIter = entry.content({
-        signal: options?.signal,
-        onProgress: options?.onProgress,
-        offset,
-        length
-      })
-      this.log('got async iterator for %c/%s', cid, path)
-
-      const { stream, firstChunk } = await getStreamFromAsyncIterable(asyncIter, path ?? '', this.helia.logger, {
-        onProgress: options?.onProgress,
-        signal: options?.signal
-      })
-      byteRangeContext.setBody(stream)
-      // if not a valid range request, okRangeRequest will call okResponse
-      const response = okRangeResponse(resource, byteRangeContext.getBody(), { byteRangeContext, log: this.log }, {
-        redirected
-      })
-
-      await setContentType({ bytes: firstChunk, path, response, contentTypeParser: this.contentTypeParser, log: this.log })
-      setIpfsRoots(response, ipfsRoots)
-
-      return response
-    } catch (err: any) {
-      options?.signal?.throwIfAborted()
-      this.log.error('error streaming %c/%s', cid, path, err)
-      if (byteRangeContext.isRangeRequest && err.code === 'ERR_INVALID_PARAMS') {
-        return badRangeResponse(resource)
+      if (pluginHandled && finalResponse != null) {
+        break
       }
-      return badGatewayResponse(resource.toString(), 'Unable to stream content')
-    }
-  }
 
-  private async handleRaw ({ resource, cid, path, session, options, accept }: FetchHandlerFunctionArg): Promise<Response> {
-    /**
-     * if we have a path, we can't walk it, so we need to return a 404.
-     *
-     * @see https://github.com/ipfs/gateway-conformance/blob/26994cfb056b717a23bf694ce4e94386728748dd/tests/subdomain_gateway_ipfs_test.go#L198-L204
-     */
-    if (path !== '') {
-      this.log.trace('404-ing raw codec request for %c/%s', cid, path)
-      return notFoundResponse(resource, 'Raw codec does not support paths')
+      if (!contextChanged) {
+        this.log.trace('No context changes and no final response; exiting pipeline.')
+        break
+      }
     }
 
-    const byteRangeContext = new ByteRangeContext(this.helia.logger, options?.headers)
-    const blockstore = this.getBlockstore(cid, resource, session, options)
-    const result = await blockstore.get(cid, options)
-    byteRangeContext.setBody(result)
-    const response = okRangeResponse(resource, byteRangeContext.getBody(), { byteRangeContext, log: this.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: this.contentTypeParser, log: this.log })
-
-    return response
-  }
-
-  /**
-   * If the user has not specified an Accept header or format query string arg,
-   * use the CID codec to choose an appropriate handler for the block data.
-   */
-  private readonly codecHandlers: Record<number, FetchHandlerFunction> = {
-    [dagPbCode]: this.handleDagPb,
-    [ipldDagJson.code]: this.handleJson,
-    [jsonCode]: this.handleJson,
-    [ipldDagCbor.code]: this.handleDagCbor,
-    [rawCode]: this.handleRaw,
-    [identity.code]: this.handleRaw
+    return finalResponse
   }
 
   /**
@@ -463,6 +304,7 @@ export class VerifiedFetch {
     this.log('fetch %s', resource)
 
     const options = convertOptions(opts)
+    const withServerTiming = options?.withServerTiming ?? this.withServerTiming
 
     options?.onProgress?.(new CustomProgressEvent<ResourceDetail>('verified-fetch:request:start', { resource }))
     // resolve the CID/path from the requested resource
@@ -473,105 +315,58 @@ export class VerifiedFetch {
     let protocol: ParsedUrlStringResults['protocol']
     let ipfsPath: string
     try {
-      const result = await parseResource(resource, { ipns: this.ipns, logger: this.helia.logger }, options)
+      const result = await this.handleServerTiming('parse-resource', '', async () => parseResource(resource, { ipns: this.ipns, logger: this.helia.logger }, { withServerTiming, ...options }), withServerTiming)
       cid = result.cid
       path = result.path
       query = result.query
       ttl = result.ttl
       protocol = result.protocol
       ipfsPath = result.ipfsPath
+      this.serverTimingHeaders.push(...result.serverTimings.map(({ header }) => header))
     } catch (err: any) {
       options?.signal?.throwIfAborted()
       this.log.error('error parsing resource %s', resource, err)
 
-      return badRequestResponse(resource.toString(), err)
+      return this.handleFinalResponse(badRequestResponse(resource.toString(), err))
     }
 
     options?.onProgress?.(new CustomProgressEvent<CIDDetail>('verified-fetch:request:resolve', { cid, path }))
 
     const acceptHeader = getResolvedAcceptHeader({ query, headers: options?.headers, logger: this.helia.logger })
 
-    const accept = selectOutputType(cid, acceptHeader)
+    const accept: string | undefined = selectOutputType(cid, acceptHeader)
     this.log('output type %s', accept)
 
     if (acceptHeader != null && accept == null) {
-      return notAcceptableResponse(resource.toString())
+      return this.handleFinalResponse(notAcceptableResponse(resource.toString()))
     }
 
-    let response: Response
-    let reqFormat: RequestFormatShorthand | undefined
+    const responseContentType: string = accept?.split(';')[0] ?? 'application/octet-stream'
 
     const redirectResponse = await getRedirectResponse({ resource, options, logger: this.helia.logger, cid })
     if (redirectResponse != null) {
-      return redirectResponse
-    }
-
-    const handlerArgs: FetchHandlerFunctionArg = { resource: resource.toString(), cid, path, accept, session: options?.session ?? true, options }
-
-    if (accept === 'application/vnd.ipfs.ipns-record') {
-      // the user requested a raw IPNS record
-      reqFormat = 'ipns-record'
-      response = await this.handleIPNSRecord(handlerArgs)
-    } else if (accept === 'application/vnd.ipld.car') {
-      // the user requested a CAR file
-      reqFormat = 'car'
-      query.download = true
-      query.filename = query.filename ?? `${cid.toString()}.car`
-      response = await this.handleCar(handlerArgs)
-    } else if (accept === 'application/vnd.ipld.raw') {
-      // the user requested a raw block
-      reqFormat = 'raw'
-      query.download = true
-      query.filename = query.filename ?? `${cid.toString()}.bin`
-      response = await this.handleRaw(handlerArgs)
-    } else if (accept === 'application/x-tar') {
-      // the user requested a TAR file
-      reqFormat = 'tar'
-      query.download = true
-      query.filename = query.filename ?? `${cid.toString()}.tar`
-      response = await this.handleTar(handlerArgs)
-    } else {
-      this.log.trace('finding handler for cid code "%s" and output type "%s"', cid.code, accept)
-      // derive the handler from the CID type
-      const codecHandler = this.codecHandlers[cid.code]
-
-      if (codecHandler == null) {
-        return notSupportedResponse(`Support for codec with code ${cid.code} is not yet implemented. Please open an issue at https://github.com/ipfs/helia-verified-fetch/issues/new`)
-      }
-      this.log.trace('calling handler "%s"', codecHandler.name)
-
-      response = await codecHandler.call(this, handlerArgs)
+      return this.handleFinalResponse(redirectResponse)
     }
 
-    response.headers.set('etag', getETag({ cid, reqFormat, weak: false }))
+    const context: PluginContext = { cid, path, resource: resource.toString(), accept, query, options, withServerTiming, onProgress: options?.onProgress, modified: 0 }
 
-    setCacheControlHeader({ response, ttl, protocol })
-    response.headers.set('X-Ipfs-Path', ipfsPath)
+    this.log.trace('finding handler for cid code "%s" and response content type "%s"', cid.code, responseContentType)
 
-    // set Content-Disposition header
-    let contentDisposition: string | undefined
-
-    // force download if requested
-    if (query.download === true) {
-      contentDisposition = 'attachment'
-    }
-
-    // override filename if requested
-    if (query.filename != null) {
-      if (contentDisposition == null) {
-        contentDisposition = 'inline'
-      }
-
-      contentDisposition = `${contentDisposition}; ${getContentDispositionFilename(query.filename)}`
-    }
-
-    if (contentDisposition != null) {
-      response.headers.set('Content-Disposition', contentDisposition)
-    }
+    const response = await this.runPluginPipeline(context)
 
     options?.onProgress?.(new CustomProgressEvent<CIDDetail>('verified-fetch:request:end', { cid, path }))
 
-    return response
+    return this.handleFinalResponse(response ?? notSupportedResponse(resource.toString()), {
+      query: {
+        ...query,
+        ...context.query
+      },
+      cid,
+      reqFormat: context.reqFormat,
+      ttl,
+      protocol,
+      ipfsPath
+    })
   }
 
   /**