@helia/verified-fetch 4.1.1 → 5.0.0

package/src/utils/get-range-header.ts

@@ -0,0 +1,107 @@
+import { InvalidRangeError } from '../errors.ts'
+import { badRequestResponse, notSatisfiableResponse } from './responses.ts'
+
+/**
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Range
+ */
+export interface Range {
+  /**
+   * Where the range starts, zero indexed
+   */
+  start?: number
+
+  /**
+   * Where the range ends, inclusive
+   */
+  end?: number
+}
+
+/**
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Range
+ */
+export interface RangeHeader {
+  multipartBoundary: string
+  ranges: Range[]
+}
+
+function parseValue (val?: string): number | undefined {
+  if (val == null || val === '') {
+    return
+  }
+
+  const num = Number(val)
+
+  if (isNaN(num)) {
+    throw new InvalidRangeError(`Invalid range specification: could not parse "${num}" as number`)
+  }
+
+  return num
+}
+
+function getByteRangeFromHeader (rangeHeader?: string): Range[] {
+  if (rangeHeader == null || rangeHeader === '') {
+    return []
+  }
+
+  /**
+   * Range: bytes=<start>-<end> | bytes=<start2>- | bytes=-<end2> | bytes=<start1>-<end1>,<start2>-<end2>,...
+   */
+  if (!rangeHeader.startsWith('bytes=')) {
+    throw new InvalidRangeError('Invalid range request')
+  }
+
+  const rangesStr = rangeHeader.substring(6) // Remove "bytes=" prefix
+  const rangeParts = rangesStr.split(',').map(part => part.trim())
+  const ranges: Range[] = []
+
+  for (const part of rangeParts) {
+    const match = part.match(/^(?<start>\d+)?-(?<end>\d+)?$/)
+
+    if (match?.groups == null) {
+      throw new InvalidRangeError(`Invalid range specification: ${part}`)
+    }
+
+    if (part.startsWith('-')) {
+      ranges.push({
+        end: parseValue(part)
+      })
+    } else {
+      const { start, end } = match.groups
+
+      ranges.push({
+        start: parseValue(start),
+        end: parseValue(end)
+      })
+    }
+  }
+
+  return ranges
+}
+
+export function getRangeHeader (resource: string, headers: Headers): RangeHeader | undefined | Response {
+  const header = headers.get('range')
+
+  // not a range request
+  if (header == null) {
+    return
+  }
+
+  try {
+    const ranges = getByteRangeFromHeader(header)
+
+    if (ranges.length === 0) {
+      return
+    }
+
+    return {
+      multipartBoundary: `multipart_byteranges_${Math.floor(Math.random() * 1_000_000_000)}`,
+      ranges
+    }
+  } catch (e: any) {
+    if (e.name === 'InvalidRangeError') {
+      return notSatisfiableResponse(resource)
+    }
+
+    return badRequestResponse(resource, e)
+  }
+}

package/src/utils/parse-url-string.ts

@@ -1,4 +1,6 @@
 import { InvalidParametersError } from '@libp2p/interface'
+import { peerIdFromCID, peerIdFromString } from '@libp2p/peer-id'
+import { CID } from 'multiformats/cid'
 import { decodeDNSLinkLabel, isInlinedDnsLink } from './dnslink-label.ts'
 import { ipfsPathToUrl, ipfsUrlToUrl } from './ipfs-path-to-url.ts'
 
@@ -7,7 +9,8 @@ interface SubdomainMatchGroups {
   cidOrPeerIdOrDnsLink: string
 }
 
-const SUBDOMAIN_GATEWAY_REGEX = /^(?<cidOrPeerIdOrDnsLink>[^/?]+)\.(?<protocol>ip[fn]s)\.([^/?]+)$/
+export const SUBDOMAIN_GATEWAY_REGEX = /^(?<cidOrPeerIdOrDnsLink>[^/?]+)\.(?<protocol>ip[fn]s)\.([^/?]+)$/
+const CODEC_LIBP2P_KEY = 0x72
 
 function matchSubdomainGroupsGuard (groups?: null | { [key in string]: string; } | SubdomainMatchGroups): groups is SubdomainMatchGroups {
   const protocol = groups?.protocol
@@ -34,40 +37,6 @@ export interface ParsedURL {
   fragment: string
 }
 
-function toQuery (query?: URLSearchParams): Record<string, any> {
-  if (query == null) {
-    return {}
-  }
-
-  const output: Record<string, any> = {}
-
-  for (const [key, value] of query.entries()) {
-    output[key] = value
-
-    if (value === 'true') {
-      output[key] = true
-    }
-
-    if (value === 'false') {
-      output[key] = false
-    }
-  }
-
-  return output
-}
-
-function stripLeadingHash (pathname: string): string {
-  return stripLeading(pathname, '#')
-}
-
-function stripLeading (str: string, char: string): string {
-  while (str.startsWith(char)) {
-    str = str.substring(1)
-  }
-
-  return str
-}
-
 /**
  * If the caller has passed a case-sensitive identifier (like a base58btc
  * encoded CID or PeerId) in a case-insensitive location (like a subdomain),
@@ -83,7 +52,11 @@ function findOriginalCidOrPeer (needle: string, haystack: string): string {
   return haystack.substring(start, start + needle.length)
 }
 
-function toUrl (urlString: string): URL {
+function stringToUrl (urlString: string | URL): URL {
+  if (urlString instanceof URL) {
+    return urlString
+  }
+
   // turn IPFS/IPNS path into gateway URL string
   if (urlString.startsWith('/ipfs/') || urlString.startsWith('/ipns/')) {
     urlString = ipfsPathToUrl(urlString)
@@ -101,21 +74,9 @@ function toUrl (urlString: string): URL {
   throw new InvalidParametersError(`Invalid URL: ${urlString}`)
 }
 
-/**
- * Accepts the following url strings:
- *
- * - /ipfs/Qmfoo/path
- * - /ipns/Qmfoo/path
- * - ipfs://cid/path
- * - ipns://name/path
- * - http://cid.ipfs.example.com/path
- * - http://name.ipns.example.com/path
- * - http://example.com/ipfs/cid/path
- * - http://example.com/ipns/name/path
- */
-export function parseURLString (urlString: string): ParsedURL {
+function toURL (urlString: string): URL {
   // validate url
-  const url = toUrl(urlString)
+  const url = stringToUrl(urlString)
 
   // test for subdomain gateway URL
   const subdomainMatch = url.hostname.match(SUBDOMAIN_GATEWAY_REGEX)
@@ -136,16 +97,7 @@ export function parseURLString (urlString: string): ParsedURL {
     // input while also maintaining a sane canonical URL for the resource. Phew.
     const wat = new URL(`not-${urlString}`)
 
-    return {
-      url: new URL(`${groups.protocol}://${cidOrPeerIdOrDnsLink}${wat.pathname}${url.search}${url.hash}`),
-      protocol: groups.protocol,
-      cidOrPeerIdOrDnsLink,
-      path: url.pathname.split('/')
-        .filter(str => str !== '')
-        .map(str => decodeURIComponent(str)),
-      query: toQuery(url.searchParams),
-      fragment: stripLeadingHash(url.hash)
-    }
+    return new URL(`${groups.protocol}://${cidOrPeerIdOrDnsLink}${wat.pathname}${url.search}${url.hash}`)
   }
 
   // test for IPFS path gateway URL
@@ -157,16 +109,7 @@ export function parseURLString (urlString: string): ParsedURL {
       throw new InvalidParametersError(`Path gateway URL ${urlString} had no CID`)
     }
 
-    return {
-      url: new URL(`ipfs://${cid}${url.pathname.replace(`/ipfs/${cid}`, '')}${url.search}${url.hash}`),
-      protocol: 'ipfs',
-      cidOrPeerIdOrDnsLink: cid,
-      path: parts
-        .filter(str => str !== '')
-        .map(str => decodeURIComponent(str)),
-      query: toQuery(url.searchParams),
-      fragment: stripLeadingHash(url.hash)
-    }
+    return new URL(`ipfs://${cid}${url.pathname.replace(`/ipfs/${cid}`, '')}${url.search}${url.hash}`)
   }
 
   // test for IPNS path gateway URL
@@ -178,17 +121,45 @@ export function parseURLString (urlString: string): ParsedURL {
       throw new InvalidParametersError(`Path gateway URL ${urlString} had no name`)
     }
 
-    return {
-      url: new URL(`ipns://${name}${url.pathname.replace(`/ipns/${name}`, '')}${url.search}${url.hash}`),
-      protocol: 'ipns',
-      cidOrPeerIdOrDnsLink: name,
-      path: parts
-        .filter(str => str !== '')
-        .map(str => decodeURIComponent(str)),
-      query: toQuery(url.searchParams),
-      fragment: stripLeadingHash(url.hash)
-    }
+    return new URL(`ipns://${name}${url.pathname.replace(`/ipns/${name}`, '')}${url.search}${url.hash}`)
   }
 
   throw new TypeError(`Invalid URL: ${urlString}, please use ipfs://, ipns://, or gateway URLs only`)
 }
+
+/**
+ * Accepts the following url strings:
+ *
+ * - /ipfs/Qmfoo/path
+ * - /ipns/Qmfoo/path
+ * - ipfs://cid/path
+ * - ipns://name/path
+ * - http://cid.ipfs.example.com/path
+ * - http://name.ipns.example.com/path
+ * - http://example.com/ipfs/cid/path
+ * - http://example.com/ipns/name/path
+ */
+export function parseURLString (urlString: string): URL {
+  // validate url
+  const url = toURL(urlString)
+
+  // treat IPNS keys that do not parse as PeerIds as DNSLink
+  if (url.protocol === 'ipns:') {
+    try {
+      peerIdFromString(url.hostname)
+    } catch {
+      url.protocol = 'dnslink:'
+    }
+  }
+
+  if (url.protocol === 'ipfs:') {
+    const cid = CID.parse(url.hostname)
+
+    // special case - peer id encoded as a CID
+    if (cid.code === CODEC_LIBP2P_KEY) {
+      return new URL(`ipns://${peerIdFromCID(cid)}${url.pathname}${url.search}${url.hash}`)
+    }
+  }
+
+  return url
+}

package/src/utils/resource-to-cache-key.ts

@@ -8,9 +8,9 @@ import { parseURLString } from './parse-url-string.js'
  * E.g.
  *
  * - Qmfoo -> /ipfs/Qmfoo
- * - https://Qmfoo.ipfs.gateway.org -> /ipfs/Qmfoo
- * - https://gateway.org/ipfs/Qmfoo -> /ipfs/Qmfoo
- * - https://gateway.org/ipfs/Qmfoo/bar.txt -> /ipfs/Qmfoo
+ * - https://Qmfoo.ipfs.gateway.org -> ipfs://Qmfoo
+ * - https://gateway.org/ipfs/Qmfoo -> ipfs://Qmfoo
+ * - https://gateway.org/ipfs/Qmfoo/bar.txt -> ipfs://Qmfoo
  * - etc
  */
 export function resourceToSessionCacheKey (url: string | CID): string {
@@ -24,7 +24,7 @@ export function resourceToSessionCacheKey (url: string | CID): string {
     return `ipfs://${CID.parse(url.toString())}`
   } catch {}
 
-  const { protocol, cidOrPeerIdOrDnsLink } = parseURLString(url.toString())
+  const { protocol, host } = parseURLString(url.toString())
 
-  return `${protocol}://${cidOrPeerIdOrDnsLink}`
+  return `${protocol}//${host}`
 }

package/src/utils/response-headers.ts

@@ -1,5 +1,4 @@
 import { InvalidRangeError } from '../errors.js'
-import type { CID } from 'multiformats/cid'
 
 interface CacheControlHeaderOptions {
   /**
@@ -24,8 +23,10 @@ export function setCacheControlHeader ({ ttl, protocol, response }: CacheControl
     // don't set the header if it's already set by a plugin
     return
   }
+
   let headerValue: string
-  if (protocol === 'ipfs') {
+
+  if (protocol === 'ipfs:') {
     headerValue = 'public, max-age=29030400, immutable'
   } else if (ttl == null) {
     /**
@@ -42,59 +43,57 @@ export function setCacheControlHeader ({ ttl, protocol, response }: CacheControl
 }
 
 /**
- * This function returns the value of the `Content-Range` header for a given range.
+ * This function returns the value of the `Content-Range` header for a given
+ * range.
+ *
  * If you know the total size of the body, pass it as `byteSize`
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Range
  */
-export function getContentRangeHeader ({ byteStart, byteEnd, byteSize }: { byteStart: number | undefined, byteEnd: number | undefined, byteSize: number | undefined }): string {
-  const total = byteSize ?? '*' // if we don't know the total size, we should use *
-
-  if ((byteEnd ?? 0) >= (byteSize ?? Infinity)) {
-    throw new InvalidRangeError('Invalid range: Range-end index is greater than or equal to the size of the file.')
-  }
-  if ((byteStart ?? 0) >= (byteSize ?? Infinity)) {
-    throw new InvalidRangeError('Invalid range: Range-start index is greater than or equal to the size of the file.')
+export function getContentRangeHeader (byteSize: number | bigint | string, byteStart?: number | bigint | string, byteEnd?: number | bigint | string): string {
+  if (byteStart != null) {
+    byteStart = BigInt(byteStart)
   }
 
-  if (byteStart != null && byteEnd == null) {
-    // only byteStart in range
-    if (byteSize == null) {
-      return `bytes */${total}`
-    }
-    return `bytes ${byteStart}-${byteSize - 1}/${byteSize}`
+  if (byteEnd != null) {
+    byteEnd = BigInt(byteEnd)
   }
 
-  if (byteStart == null && byteEnd != null) {
-    // only byteEnd in range
-    if (byteSize == null) {
-      return `bytes */${total}`
-    }
-    const end = byteSize - 1
-    const start = end - byteEnd + 1
+  // if we don't know the total size, we should use *
+  const total = BigInt(byteSize)
 
-    return `bytes ${start}-${end}/${byteSize}`
+  // validate start/end are not outside total size
+  if ((byteEnd ?? 0n) >= total) {
+    throw new InvalidRangeError('Invalid range: Range-end index is greater than or equal to the size of the file.')
   }
 
-  if (byteStart == null && byteEnd == null) {
-    // neither are provided, we can't return a valid range.
-    return `bytes */${total}`
+  if ((byteStart ?? 0n) >= total) {
+    throw new InvalidRangeError('Invalid range: Range-start index is greater than or equal to the size of the file.')
   }
 
-  return `bytes ${byteStart}-${byteEnd}/${total}`
-}
+  let range = '*'
 
-/**
- * Sets the `X-Ipfs-Roots` header on the response if it exists.
- *
- * @see https://specs.ipfs.tech/http-gateways/path-gateway/#x-ipfs-roots-response-header
- */
-export function setIpfsRoots (response: Response, ipfsRoots?: CID[]): void {
-  if (ipfsRoots != null) {
-    response.headers.set('X-Ipfs-Roots', getIpfsRoots(ipfsRoots))
+  if (byteStart == null) {
+    if (byteEnd != null) {
+      if (byteEnd < 0n) {
+        range = `${total + byteEnd}-${total - 1n}`
+      } else {
+        range = `0-${byteEnd}`
+      }
+    }
+  } else {
+    if (byteEnd == null) {
+      let end = '*'
+
+      if (byteSize != null) {
+        end = `${total - 1n}`
+      }
+
+      range = `${byteStart}-${end}`
+    } else {
+      range = `${byteStart}-${byteEnd}`
+    }
   }
-}
 
-export function getIpfsRoots (ipfsRoots: CID[]): string {
-  return ipfsRoots.map(cid => cid.toV1().toString()).join(',')
+  return `bytes ${range}/${total}`
 }