@helia/verified-fetch 4.1.0 → 5.0.0

package/src/plugins/plugin-base.ts

@@ -1,19 +1,17 @@
-import type { VerifiedFetchPlugin, PluginContext, PluginOptions } from './types.js'
+import type { VerifiedFetchPlugin, PluginContext, PluginOptions } from '../index.js'
 import type { Logger } from '@libp2p/interface'
 
 /**
- * Base class for verified-fetch plugins. This class provides a basic implementation of the `FetchHandlerPlugin`
- * interface.
+ * Base class for verified-fetch plugins. This class provides a basic
+ * implementation of the `VerifiedFetchPlugin` interface.
  *
- * Subclasses must implement the `id` property and the `canHandle` and `handle` methods.
- * Subclasses may override the `codes` and `log` properties.
+ * Subclasses must implement the `id` property, the `canHandle`, and `handle`
+ * methods.
  *
- * If your plugin adds/edits the context supplied in `handle`, you should increment the `context.modified` property.
+ * Subclasses may override the `codes` and `log` properties.
  */
 export abstract class BasePlugin implements VerifiedFetchPlugin {
-  readonly codes: number[] = []
   readonly pluginOptions: PluginOptions
-  abstract readonly id: string
   protected _log?: Logger
 
   get log (): Logger {
@@ -29,7 +27,7 @@ export abstract class BasePlugin implements VerifiedFetchPlugin {
     this.pluginOptions = options
   }
 
+  abstract readonly id: string
   abstract canHandle (context: PluginContext): boolean
-
-  abstract handle (context: PluginContext): Promise<Response | null>
+  abstract handle (context: PluginContext): Promise<Response>
 }

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

@@ -2,17 +2,15 @@ import { BlockExporter, car, CIDPath, depthFirstWalker, naturalOrderWalker, Subg
 import { code as dagPbCode } from '@ipld/dag-pb'
 import { createScalableCuckooFilter } from '@libp2p/utils'
 import toBrowserReadableStream from 'it-to-browser-readablestream'
-import { getOffsetAndLength } from '../utils/get-offset-and-length.ts'
-import { notAcceptableResponse, okRangeResponse } from '../utils/responses.js'
+import { CONTENT_TYPE_CAR, MEDIA_TYPE_CAR } from '../utils/content-types.ts'
+import { getContentDispositionFilename } from '../utils/get-content-disposition-filename.ts'
+import { entityBytesToOffsetAndLength } from '../utils/get-offset-and-length.ts'
+import { badRequestResponse, notAcceptableResponse, okResponse } from '../utils/responses.js'
 import { BasePlugin } from './plugin-base.js'
-import type { PluginContext } from './types.js'
+import type { PluginContext } from '../index.js'
 import type { ExportCarOptions, UnixFSExporterOptions } from '@helia/car'
 
-function getFilename ({ cid, ipfsPath, query }: Pick<PluginContext, 'query' | 'cid' | 'ipfsPath'>): string {
-  if (query.filename != null) {
-    return query.filename
-  }
-
+function getFilename (ipfsPath: string): string {
   // convert context.ipfsPath to a filename. replace all / with _, replace prefix protocol with empty string
   const filename = ipfsPath
     .replace(/\/ipfs\//, '')
@@ -23,17 +21,20 @@ function getFilename ({ cid, ipfsPath, query }: Pick<PluginContext, 'query' | 'c
   return `${filename}.car`
 }
 
-// https://specs.ipfs.tech/http-gateways/trustless-gateway/#dag-scope-request-query-parameter
+/**
+ * @see https://specs.ipfs.tech/http-gateways/trustless-gateway/#dag-scope-request-query-parameter
+ */
 type DagScope = 'all' | 'entity' | 'block'
-function getDagScope ({ query }: Pick<PluginContext, 'query'>): DagScope | null {
-  const dagScope = query['dag-scope']
+
+function getDagScope ({ url }: PluginContext): DagScope | null {
+  const dagScope = url.searchParams.get('dag-scope')
 
   if (dagScope === 'all' || dagScope === 'entity' || dagScope === 'block') {
     return dagScope
   }
 
   // entity-bytes implies entity scope
-  if (query['entity-bytes']) {
+  if (url.searchParams.has('entity-bytes')) {
     return 'entity'
   }
 
@@ -47,38 +48,36 @@ function getDagScope ({ query }: Pick<PluginContext, 'query'>): DagScope | null
 export class CarPlugin extends BasePlugin {
   readonly id = 'car-plugin'
 
-  canHandle (context: PluginContext): boolean {
-    if (context.byteRangeContext == null) {
-      return false
-    }
-
-    if (context.pathDetails == null) {
-      return false
-    }
-
-    return context.accept?.mimeType.startsWith('application/vnd.ipld.car') === true || context.query.format === 'car' // application/vnd.ipld.car
+  canHandle ({ accept }: PluginContext): boolean {
+    return accept.some(header => header.contentType.mediaType === MEDIA_TYPE_CAR)
   }
 
-  async handle (context: PluginContext & Required<Pick<PluginContext, 'byteRangeContext'>>): Promise<Response> {
-    const { options, pathDetails, cid, query, accept, resource } = context
+  async handle (context: PluginContext): Promise<Response> {
+    const { options, url, accept, resource, blockstore, range, ipfsRoots, terminalElement } = context
+
+    if (range != null) {
+      return badRequestResponse(resource, new Error('Range requests are not supported for CAR files'))
+    }
 
-    const order = accept?.options.order === 'dfs' || context.query['car-order'] === 'dfs' ? 'dfs' : 'unk'
-    const duplicates = accept?.options.dups !== 'n' && context.query['car-dups'] !== 'n'
+    const acceptCar = accept.filter(header => header.contentType.mediaType === MEDIA_TYPE_CAR).pop()
 
-    if (pathDetails == null) {
-      throw new Error('attempted to handle request for car with no path details')
+    // we have already asserted that the CAR media type is present so this
+    // branch should never be hit
+    if (acceptCar == null) {
+      return badRequestResponse(resource, new Error('Could not find CAR media type in accept header'))
     }
 
+    const order = acceptCar.options.order === 'dfs' || url.searchParams.get('car-order') === 'dfs' ? 'dfs' : 'unk'
+    const duplicates = acceptCar.options.dups !== 'n' && url.searchParams.get('car-dups') !== 'n'
+
     // TODO: `@ipld/car` only supports CARv1
-    if (accept?.options.version === '2' || context.query['car-version'] === '2') {
-      return notAcceptableResponse(resource, 'Only CARv1 is supported')
+    if (acceptCar.options.version === '2' || url.searchParams.get('car-version') === '2') {
+      return notAcceptableResponse(resource, [
+        CONTENT_TYPE_CAR
+      ])
     }
 
-    const { getBlockstore, helia } = this.pluginOptions
-    context.reqFormat = 'car'
-    context.query.download = true
-    context.query.filename = getFilename(context)
-    const blockstore = getBlockstore(cid, context.resource, options?.session ?? true, options)
+    const helia = this.pluginOptions.helia
 
     const c = car({
       blockstore,
@@ -95,12 +94,12 @@ export class CarPlugin extends BasePlugin {
       carExportOptions.blockFilter = createScalableCuckooFilter(1024)
     }
 
-    if (pathDetails.ipfsRoots.length > 1) {
-      carExportOptions.traversal = new CIDPath(pathDetails.ipfsRoots)
+    if (ipfsRoots.length > 1) {
+      carExportOptions.traversal = new CIDPath(ipfsRoots)
     }
 
     const dagScope = getDagScope(context)
-    const target = pathDetails.terminalElement.cid ?? cid
+    const target = terminalElement.cid
 
     if (dagScope === 'block') {
       carExportOptions.exporter = new BlockExporter()
@@ -112,7 +111,7 @@ export class CarPlugin extends BasePlugin {
           listingOnly: true
         }
 
-        const slice = getOffsetAndLength(pathDetails.terminalElement, query['entity-bytes']?.toString())
+        const slice = entityBytesToOffsetAndLength(terminalElement.size, url.searchParams.get('entity-bytes'))
         options.offset = slice.offset
         options.length = slice.length
 
@@ -126,14 +125,17 @@ export class CarPlugin extends BasePlugin {
       })
     }
 
-    context.byteRangeContext.setBody(toBrowserReadableStream(c.export(target, carExportOptions)))
+    const stream = toBrowserReadableStream(c.export(target, carExportOptions))
 
-    const response = okRangeResponse(context.resource, context.byteRangeContext.getBody('application/vnd.ipld.car; version=1'), {
-      byteRangeContext: context.byteRangeContext,
-      log: this.log
+    return okResponse(resource, stream, {
+      headers: {
+        'content-type': `${MEDIA_TYPE_CAR}; version=1; order=${order}; dups=${duplicates ? 'y' : 'n'}`,
+        'content-disposition': `attachment; ${
+          getContentDispositionFilename(url.searchParams.get('filename') ?? getFilename(`/ipfs/${url.hostname}${url.pathname}`))
+        }`,
+        'x-content-type-options': 'nosniff',
+        'accept-ranges': 'none'
+      }
     })
-    response.headers.set('content-type', context.byteRangeContext.getContentType() ?? `application/vnd.ipld.car; version=1; order=${order}; dups=${duplicates ? 'y' : 'n'}`)
-
-    return response
   }
 }

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

@@ -0,0 +1,93 @@
+import * as ipldDagCbor from '@ipld/dag-cbor'
+import * as ipldDagJson from '@ipld/dag-json'
+import * as dagPb from '@ipld/dag-pb'
+import toBuffer from 'it-to-buffer'
+import * as json from 'multiformats/codecs/json'
+import * as raw from 'multiformats/codecs/raw'
+import { identity } from 'multiformats/hashes/identity'
+import { CODEC_CBOR } from '../constants.ts'
+import { getContentTypesForCid, MEDIA_TYPE_CBOR, MEDIA_TYPE_DAG_CBOR, MEDIA_TYPE_DAG_JSON, MEDIA_TYPE_JSON, MEDIA_TYPE_OCTET_STREAM, MEDIA_TYPE_RAW } from '../utils/content-types.ts'
+import { convertOutput } from '../utils/convert-output.ts'
+import { getContentDispositionFilename } from '../utils/get-content-disposition-filename.ts'
+import { notAcceptableResponse, okResponse, partialContentResponse } from '../utils/responses.js'
+import { BasePlugin } from './plugin-base.js'
+import type { ContentType, PluginContext } from '../index.ts'
+
+/**
+ * Handles loading JSON and CBOR content
+ */
+export class IpldPlugin extends BasePlugin {
+  readonly id = 'ipld-plugin'
+  readonly codes = [
+    CODEC_CBOR,
+    ipldDagCbor.code,
+    ipldDagJson.code,
+    json.code,
+    raw.code,
+    dagPb.code,
+    identity.code
+  ]
+
+  canHandle ({ terminalElement, accept }: PluginContext): boolean {
+    const supportsCid = this.codes.includes(terminalElement.cid.code)
+    const supportsAccept = accept.length === 0 ||
+      accept.some(header => header.contentType.mediaType === MEDIA_TYPE_CBOR ||
+        header.contentType.mediaType === MEDIA_TYPE_DAG_CBOR ||
+        header.contentType.mediaType === MEDIA_TYPE_JSON ||
+        header.contentType.mediaType === MEDIA_TYPE_DAG_JSON ||
+        header.contentType.mediaType === MEDIA_TYPE_RAW ||
+        header.contentType.mediaType === MEDIA_TYPE_OCTET_STREAM
+      )
+
+    return supportsCid && supportsAccept
+  }
+
+  async handle (context: PluginContext): Promise<Response> {
+    const { url, resource, accept, ipfsRoots, terminalElement, blockstore, options } = context
+
+    this.log.trace('fetching %c/%s', terminalElement.cid, url.pathname)
+    let block: Uint8Array
+    if (terminalElement.node == null) {
+      block = await toBuffer(blockstore.get(terminalElement.cid, options))
+    } else if (terminalElement.type === 'object' || terminalElement.type === 'raw' || terminalElement.type === 'identity') {
+      block = terminalElement.node
+    } else {
+      block = dagPb.encode(terminalElement.node)
+    }
+
+    let contentType: ContentType
+
+    try {
+      // maybe convert output to different binary format
+      const result = convertOutput(terminalElement.cid, block, accept)
+      block = result.output
+      contentType = result.contentType
+    } catch (err) {
+      this.log.error('could not decode object from block - %e', err)
+      return notAcceptableResponse(resource, getContentTypesForCid(terminalElement.cid))
+    }
+
+    const headers = {
+      'content-length': `${block.byteLength}`,
+      'content-type': contentType.mediaType,
+      'content-disposition': `${url.searchParams.get('download') === 'true' ? 'attachment' : contentType.disposition}; ${
+        getContentDispositionFilename(url.searchParams.get('filename') ?? `${terminalElement.cid}${contentType.extension}`)
+      }`,
+      'x-ipfs-roots': ipfsRoots.map(cid => cid.toV1()).join(','),
+      'x-content-type-options': 'nosniff',
+      'accept-ranges': 'bytes'
+    }
+
+    if (context.range != null) {
+      return partialContentResponse(resource, async function * (offset, length) {
+        yield block.subarray(offset, offset + length)
+      }, context.range, block.byteLength, {
+        headers
+      })
+    }
+
+    return okResponse(resource, block, {
+      headers
+    })
+  }
+}

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

@@ -1,8 +1,10 @@
+import { peerIdFromString } from '@libp2p/peer-id'
 import { marshalIPNSRecord } from 'ipns'
-import { getPeerIdFromString } from '../utils/get-peer-id-from-string.js'
-import { badRequestResponse, okRangeResponse } from '../utils/responses.js'
+import { CONTENT_TYPE_IPNS, MEDIA_TYPE_IPNS_RECORD } from '../utils/content-types.ts'
+import { getContentDispositionFilename } from '../utils/get-content-disposition-filename.ts'
+import { badRequestResponse, okResponse } from '../utils/responses.js'
 import { BasePlugin } from './plugin-base.js'
-import type { PluginContext } from './types.js'
+import type { PluginContext } from '../index.js'
 import type { PeerId } from '@libp2p/interface'
 
 /**
@@ -13,60 +15,48 @@ export class IpnsRecordPlugin extends BasePlugin {
   readonly id = 'ipns-record-plugin'
   readonly codes = []
 
-  canHandle ({ accept, query, byteRangeContext }: PluginContext): boolean {
-    if (byteRangeContext == null) {
-      return false
-    }
-
-    return accept?.mimeType === 'application/vnd.ipfs.ipns-record' || query.format === 'ipns-record'
+  canHandle ({ accept }: PluginContext): boolean {
+    return accept.some(header => header.contentType.mediaType === MEDIA_TYPE_IPNS_RECORD)
   }
 
-  async handle (context: PluginContext & Required<Pick<PluginContext, 'byteRangeContext'>>): Promise<Response> {
-    const { resource, path, query, options } = context
+  async handle (context: Pick<PluginContext, 'resource' | 'url' | 'options' | 'range'>): Promise<Response> {
+    const { resource, url, options, range } = context
     const { ipnsResolver } = this.pluginOptions
-    context.reqFormat = 'ipns-record'
 
-    if (path.length > 0 || !(resource.startsWith('ipns://') || resource.includes('.ipns.') || resource.includes('/ipns/'))) {
-      this.log.error('invalid request for IPNS name "%s" and path "%s"', resource, path)
+    if (url.pathname !== '' || url.protocol !== 'ipns:') {
+      this.log.error('invalid request for IPNS name "%s" and path "%s"', resource, url.pathname)
       return badRequestResponse(resource, new Error('Invalid IPNS name'))
     }
 
+    if (range != null) {
+      return badRequestResponse(resource, new Error('Range requests are not supported for IPNS records'))
+    }
+
     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)
+      this.log.trace('trying to parse peer id from "%s"', url.hostname)
+      peerId = peerIdFromString(url.hostname)
     } catch (err: any) {
       this.log.error('could not parse peer id from IPNS url %s', resource, err)
 
       return badRequestResponse(resource, err)
     }
 
-    // force download in handleFinalResponse
-    query.filename = query.filename ?? `${peerId}.bin`
-    query.download = true
-
-    // @ts-expect-error progress handler types are incompatible
     const result = await ipnsResolver.resolve(peerId, options)
-    const buf = marshalIPNSRecord(result.record)
-
-    context.byteRangeContext.setBody(buf)
-
-    const response = okRangeResponse(resource, context.byteRangeContext.getBody('application/vnd.ipfs.ipns-record'), { byteRangeContext: context.byteRangeContext, log: this.log })
-    response.headers.set('content-type', context.byteRangeContext.getContentType() ?? 'application/vnd.ipfs.ipns-record')
-    response.headers.set('content-length', buf.byteLength.toString())
-    response.headers.set('x-ipfs-roots', result.cid.toV1().toString())
-
-    return response
+    const block = marshalIPNSRecord(result.record)
+
+    return okResponse(resource, block, {
+      headers: {
+        'content-length': `${block.byteLength}`,
+        'content-type': CONTENT_TYPE_IPNS.mediaType,
+        'content-disposition': `attachment; ${
+          getContentDispositionFilename(url.searchParams.get('filename') ?? `${peerId}${CONTENT_TYPE_IPNS.extension}`)
+        }`,
+        'x-ipfs-roots': result.cid.toV1().toString(),
+        'cache-control': `public, max-age=${Number((result.record.ttl ?? 0n) / BigInt(1e9))}`,
+        'accept-ranges': 'none'
+      }
+    })
   }
 }

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

@@ -1,11 +1,13 @@
+import { NotUnixFSError } from '@helia/unixfs/errors'
 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 { MEDIA_TYPE_TAR } from '../utils/content-types.ts'
+import { getContentDispositionFilename } from '../utils/get-content-disposition-filename.ts'
 import { tarStream } from '../utils/get-tar-stream.js'
-import { notAcceptableResponse, okRangeResponse } from '../utils/responses.js'
+import { badRequestResponse, okResponse } from '../utils/responses.js'
 import { BasePlugin } from './plugin-base.js'
-import type { PluginContext } from './types.js'
+import type { PluginContext } from '../index.js'
 
 /**
  * Accepts a UnixFS `CID` and returns a `.tar` file containing the file or
@@ -15,37 +17,31 @@ export class TarPlugin extends BasePlugin {
   readonly id = 'tar-plugin'
   readonly codes = []
 
-  canHandle ({ cid, accept, query, byteRangeContext }: PluginContext): boolean {
-    if (byteRangeContext == null) {
-      return false
-    }
-
-    return accept?.mimeType === 'application/x-tar' || query.format === 'tar'
+  canHandle ({ accept }: PluginContext): boolean {
+    return accept.some(header => header.contentType.mediaType === MEDIA_TYPE_TAR)
   }
 
-  async handle (context: PluginContext & Required<Pick<PluginContext, 'byteRangeContext'>>): Promise<Response> {
-    const { cid, path, resource, options, pathDetails } = context
-    const { getBlockstore } = this.pluginOptions
+  async handle (context: PluginContext): Promise<Response> {
+    const { terminalElement, url, resource, options, blockstore, range } = context
 
-    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')
+    if (terminalElement.cid.code !== dagPbCode && terminalElement.cid.code !== rawCode) {
+      return badRequestResponse(resource, new NotUnixFSError('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))
-
-    context.byteRangeContext.setBody(stream)
-
-    const response = okRangeResponse(resource, context.byteRangeContext.getBody('application/x-tar'), { byteRangeContext: context.byteRangeContext, log: this.log })
-    response.headers.set('content-type', context.byteRangeContext.getContentType() ?? 'application/x-tar')
-
-    response.headers.set('etag', getETag({ cid: terminusElement, reqFormat: context.reqFormat, weak: true }))
+    if (range != null) {
+      return badRequestResponse(resource, new Error('Range requests are not supported for TAR files'))
+    }
 
-    return response
+    const stream = toBrowserReadableStream<Uint8Array>(tarStream(`/ipfs/${terminalElement.cid}${url.pathname}`, blockstore, options))
+
+    return okResponse(resource, stream, {
+      headers: {
+        'content-type': MEDIA_TYPE_TAR,
+        'content-disposition': `attachment; ${
+          getContentDispositionFilename(url.searchParams.get('filename') ?? `${terminalElement.cid.toString()}.tar`)
+        }`,
+        'accept-ranges': 'none'
+      }
+    })
   }
 }