@helia/verified-fetch 0.0.0-f243de2

package/dist/src/index.d.ts

@@ -0,0 +1,259 @@
+/**
+ * @packageDocumentation
+ *
+ * `@helia/verified-fetch` is a library that provides a fetch-like API for fetching trustless content from IPFS and verifying it.
+ *
+ * This library should act as a replacement for the `fetch()` API for fetching content from IPFS, and will return a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) object that can be used in a similar manner to the `fetch()` API. This means browser and HTTP caching inside browser main threads, web-workers, and service workers, as well as other features of the `fetch()` API should work in a way familiar to developers.
+ *
+ * Exports a `createVerifiedFetch` function that returns a `fetch()` like API method {@link Helia} for fetching IPFS content.
+ *
+ * You may use any supported resource argument to fetch content:
+ *
+ * - CID instance
+ * - IPFS URL
+ * - IPNS URL
+ *
+ * @example
+ *
+ * ```typescript
+ * import { createVerifiedFetch } from '@helia/verified-fetch'
+ *
+ * const fetch = await createVerifiedFetch({
+ *  gateways: ['https://mygateway.example.net', 'https://trustless-gateway.link']
+ *})
+ *
+ * const resp = await fetch('ipfs://bafy...')
+ *
+ * const json = await resp.json()
+ *```
+ *
+ *
+ * @example Using a CID instance to fetch JSON
+ *
+ * ```typescript
+ * import { createVerifiedFetch } from '@helia/verified-fetch'
+ * import { CID } from 'multiformats/cid'
+ *
+ * const fetch = await createVerifiedFetch({
+ *  gateways: ['https://mygateway.example.net', 'https://trustless-gateway.link']
+ * })
+ *
+ * const cid = CID.parse('bafyFoo') // some image file
+ * const response = await fetch(cid)
+ * const json = await response.json()
+ * ```
+ *
+ * @example Using IPFS protocol to fetch an image
+ *
+ * ```typescript
+ * import { createVerifiedFetch } from '@helia/verified-fetch'
+ *
+ * const fetch = await createVerifiedFetch({
+ *  gateways: ['https://mygateway.example.net', 'https://trustless-gateway.link']
+ * })
+ * const response = await fetch('ipfs://bafyFoo') // CID for some image file
+ * const blob = await response.blob()
+ * const image = document.createElement('img')
+ * image.src = URL.createObjectURL(blob)
+ * document.body.appendChild(image)
+ * ```
+ *
+ * @example Using IPNS protocol to stream a big file
+ *
+ * ```typescript
+ * import { createVerifiedFetch } from '@helia/verified-fetch'
+ *
+ * const fetch = await createVerifiedFetch({
+ *  gateways: ['https://mygateway.example.net', 'https://trustless-gateway.link']
+ * })
+ * const response = await fetch('ipns://mydomain.com/path/to/very-long-file.log')
+ * const bigFileStreamReader = await response.body.getReader()
+ * ```
+ *
+ * ### Configuration
+ *
+ * #### Usage with customized Helia
+ *
+ * You can see variations of Helia and js-libp2p configuration options at https://helia.io/interfaces/helia.index.HeliaInit.html.
+ *
+ * The `@helia/http` module is currently in-progress, but the init options should be a subset of the `helia` module's init options. See https://github.com/ipfs/helia/issues/289 for more information.
+ *
+ * ```typescript
+ * import { trustlessGateway } from '@helia/block-brokers'
+ * import { createHeliaHTTP } from '@helia/http'
+ * import { delegatedHTTPRouting } from '@helia/routers'
+ * import { createVerifiedFetch } from '@helia/verified-fetch'
+ *
+ * const fetch = await createVerifiedFetch(
+ *   await createHeliaHTTP({
+ *       blockBrokers: [
+ *         trustlessGateway({
+ *           gateways: ['https://mygateway.example.net', 'https://trustless-gateway.link']
+ *         })
+ *       ],
+ *       routers: ['http://delegated-ipfs.dev'].map((routerUrl) => delegatedHTTPRouting(routerUrl))
+ *     })
+ * )
+ *
+ * const resp = await fetch('ipfs://bafy...')
+ *
+ * const json = await resp.json()
+ * ```
+ *
+ * ### Comparison to fetch
+ *
+ * First, this library will require instantiation in order to configure the gateways and delegated routers, or potentially a custom Helia instance. Secondly, once your verified-fetch method is created, it will act as similar to the `fetch()` API as possible.
+ *
+ * [The `fetch()` API](https://developer.mozilla.org/en-US/docs/Web/API/fetch) takes two parameters:
+ *
+ * 1. A [resource](https://developer.mozilla.org/en-US/docs/Web/API/fetch#resource)
+ * 2. An [options object](https://developer.mozilla.org/en-US/docs/Web/API/fetch#options)
+ *
+ * #### Resource argument
+ *
+ * This library intends to support the following methods of fetching web3 content from IPFS:
+ *
+ * 1. IPFS protocol: `ipfs://<cidv0>` & `ipfs://<cidv0>`
+ * 2. IPNS protocol: `ipns://<peerId>` & `ipns://<publicKey>` & `ipns://<hostUri_Supporting_DnsLink_TxtRecords>`
+ * 3. CID instances: An actual CID instance `CID.parse('bafy...')`
+ *
+ * As well as support for pathing & params for item 1&2 above according to [IPFS - Path Gateway Specification](https://specs.ipfs.tech/http-gateways/path-gateway) & [IPFS - Trustless Gateway Specification](https://specs.ipfs.tech/http-gateways/trustless-gateway/). Further refinement of those specifications specifically for web-based scenarios can be found in the [Web Pathing Specification IPIP](https://github.com/ipfs/specs/pull/453).
+ *
+ * If you pass a CID instance, we assume you want the content for that specific CID only, and do not support pathing or params for that CID.
+ *
+ * #### Options argument
+ *
+ * This library does not plan to support the exact Fetch API options object, as some of the arguments don't make sense. Instead, it will only support options necessary to meet [IPFS specs](https://specs.ipfs.tech/) related to specifying the resultant shape of desired content.
+ *
+ * Some of those header specifications are:
+ *
+ * 1. https://specs.ipfs.tech/http-gateways/path-gateway/#request-headers
+ * 2. https://specs.ipfs.tech/http-gateways/trustless-gateway/#request-headers
+ * 3. https://specs.ipfs.tech/http-gateways/subdomain-gateway/#request-headers
+ *
+ * Where possible, options and Helia internals will be automatically configured to the appropriate codec & content type based on the `verified-fetch` configuration and `options` argument passed.
+ *
+ * Known Fetch API options that will be supported:
+ *
+ * 1. `signal` - An AbortSignal that a user can use to abort the request.
+ * 2. `redirect` - A string that specifies the redirect type. One of `follow`, `error`, or `manual`. Defaults to `follow`. Best effort to adhere to the [Fetch API redirect](https://developer.mozilla.org/en-US/docs/Web/API/fetch#redirect) parameter.
+ * 3. `headers` - An object of headers to be sent with the request. Best effort to adhere to the [Fetch API headers](https://developer.mozilla.org/en-US/docs/Web/API/fetch#headers) parameter.
+ *     - `accept` - A string that specifies the accept header. Relevant values:
+ *         - [`vnd.ipld.raw`](https://www.iana.org/assignments/media-types/application/vnd.ipld.raw). (default)
+ *         - [`vnd.ipld.car`](https://www.iana.org/assignments/media-types/application/vnd.ipld.car)
+ *         - [`vnd.ipfs.ipns-record`](https://www.iana.org/assignments/media-types/application/vnd.ipfs.ipns-record)
+ * 4. `method` - A string that specifies the HTTP method to use for the request. Defaults to `GET`. Best effort to adhere to the [Fetch API method](https://developer.mozilla.org/en-US/docs/Web/API/fetch#method) parameter.
+ * 5. `body` - An object that specifies the body of the request. Best effort to adhere to the [Fetch API body](https://developer.mozilla.org/en-US/docs/Web/API/fetch#body) parameter.
+ * 6. `cache` - Will basically act as `force-cache` for the request. Best effort to adhere to the [Fetch API cache](https://developer.mozilla.org/en-US/docs/Web/API/fetch#cache) parameter.
+ *
+ *
+ * Non-Fetch API options that will be supported:
+ *
+ * 1. `onProgress` - Similar to Helia `onProgress` options, this will be a function that will be called with a progress event. Supported progress events are:
+ *     - `helia:verified-fetch:error` - An error occurred during the request.
+ *     - `helia:verified-fetch:request:start` - The request has been sent
+ *     - `helia:verified-fetch:request:complete` - The request has been sent
+ *     - `helia:verified-fetch:request:error` - An error occurred during the request.
+ *     - `helia:verified-fetch:request:abort` - The request was aborted prior to completion.
+ *     - `helia:verified-fetch:response:start` - The initial HTTP Response headers have been set, and response stream is started.
+ *     - `helia:verified-fetch:response:complete` - The response stream has completed.
+ *     - `helia:verified-fetch:response:error` - An error occurred while building the response.
+ *
+ * Some in-flight specs (IPIPs) that will affect the options object this library supports in the future can be seen at https://specs.ipfs.tech/ipips, a subset are:
+ *
+ * 1. [IPIP-0412: Signaling Block Order in CARs on HTTP Gateways](https://specs.ipfs.tech/ipips/ipip-0412/)
+ * 2. [IPIP-0402: Partial CAR Support on Trustless Gateways](https://specs.ipfs.tech/ipips/ipip-0402/)
+ * 3. [IPIP-0386: Subdomain Gateway Interop with _redirects](https://specs.ipfs.tech/ipips/ipip-0386/)
+ * 4. [IPIP-0328: JSON and CBOR Response Formats on HTTP Gateways](https://specs.ipfs.tech/ipips/ipip-0328/)
+ * 5. [IPIP-0288: TAR Response Format on HTTP Gateways](https://specs.ipfs.tech/ipips/ipip-0288/)
+ *
+ * #### Response types
+ *
+ * This library's purpose is to return reasonably representable content from IPFS. In other words, fetching content is intended for leaf-node content -- such as images/videos/audio & other assets, or other IPLD content (with link) -- that can be represented by https://developer.mozilla.org/en-US/docs/Web/API/Response#instance_methods. The content type you receive back will depend upon the CID you request as well as the `Accept` header value you provide.
+ *
+ * All content we retrieve from the IPFS network is obtained via an AsyncIterable, and will be set as the [body of the HTTP Response](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response#body) via a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API/Using_readable_streams#consuming_a_fetch_as_a_stream) or other efficient method that avoids loading the entire response into memory or getting the entire response from the network before returning a response to the user.
+ *
+ * If your content doesn't have a mime-type or an [IPFS spec](https://specs.ipfs.tech), this library will not support it, but you can use the [`helia`](https://github.com/ipfs/helia) library directly for those use cases. See [Unsupported response types](#unsupported-response-types) for more information.
+ *
+ * ##### Handling response types
+ *
+ * For handling responses we want to follow conventions/abstractions from Fetch API where possible:
+ *
+ * - For JSON, assuming you abstract any differences between dag-json/dag-cbor/json/and json-file-on-unixfs, you would call `.json()` to get a JSON object.
+ * - For images (or other web-relevant asset) you want to add to the DOM, use `.blob()` or `.arrayBuffer()` to get the raw bytes.
+ * - For plain text in utf-8, you would call `.text()`
+ * - For streaming response data, use something like `response.body.getReader()` to get a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API/Using_readable_streams#consuming_a_fetch_as_a_stream).
+ *
+ * ##### Unsupported response types
+ *
+ * * Returning IPLD nodes or DAGs as JS objects is not supported, as there is no currently well-defined structure for representing this data in an [HTTP Response](https://developer.mozilla.org/en-US/docs/Web/API/Response). Instead, users should request `aplication/vnd.ipld.car` or use the [`helia`](https://github.com/ipfs/helia) library directly for this use case.
+ * * Others? Open an issue or PR!
+ *
+ * #### Response headers
+ *
+ * This library will set the [HTTP Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) headers to the appropriate values for the content type according to the appropriate [IPFS Specifications](https://specs.ipfs.tech/).
+ *
+ * Some known header specifications:
+ *
+ * * https://specs.ipfs.tech/http-gateways/path-gateway/#response-headers
+ * * https://specs.ipfs.tech/http-gateways/trustless-gateway/#response-headers
+ * * https://specs.ipfs.tech/http-gateways/subdomain-gateway/#response-headers
+ *
+ * #### Possible Scenarios that could cause confusion
+ *
+ * ##### Attempting to fetch the CID for content that does not make sense
+ *
+ * If you request `bafybeiaysi4s6lnjev27ln5icwm6tueaw2vdykrtjkwiphwekaywqhcjze`, which points to the root of the en.wikipedia.org mirror, a response object does not make sense.
+ *
+ * #### Errors
+ *
+ * Known Errors that can be thrown:
+ *
+ * 1. `TypeError` - If the resource argument is not a string, CID, or CID string.
+ * 2. `TypeError` - If the options argument is passed and not an object.
+ * 3. `TypeError` - If the options argument is passed and is malformed.
+ * 4. `AbortError` - If the content request is aborted due to user aborting provided AbortSignal.
+ */
+import type { Helia } from '@helia/interface';
+import type { IPNSRoutingEvents, ResolveDnsLinkProgressEvents, ResolveProgressEvents } from '@helia/ipns';
+import type { GetEvents } from '@helia/unixfs';
+import type { CID } from 'multiformats/cid';
+import type { ProgressEvent, ProgressOptions } from 'progress-events';
+/**
+ * The types for the first argument of the `verifiedFetch` function.
+ */
+export type Resource = string | CID;
+export interface CIDDetail {
+    cid: string;
+    path: string;
+}
+export interface CIDDetailError extends CIDDetail {
+    error: Error;
+}
+export interface VerifiedFetch {
+    (resource: Resource, options?: VerifiedFetchInit): Promise<Response>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+/**
+ * Instead of passing a Helia instance, you can pass a list of gateways and routers, and a HeliaHTTP instance will be created for you.
+ */
+export interface CreateVerifiedFetchWithOptions {
+    gateways: string[];
+    routers?: string[];
+}
+export type BubbledProgressEvents = GetEvents | ResolveProgressEvents | ResolveDnsLinkProgressEvents | IPNSRoutingEvents;
+export type VerifiedFetchProgressEvents = ProgressEvent<'verified-fetch:request:start', CIDDetail> | ProgressEvent<'verified-fetch:request:info', string> | ProgressEvent<'verified-fetch:request:progress:chunk', CIDDetail> | ProgressEvent<'verified-fetch:request:end', CIDDetail> | ProgressEvent<'verified-fetch:request:error', CIDDetailError>;
+/**
+ * Options for the `fetch` function returned by `createVerifiedFetch`.
+ *
+ * This method accepts all the same options as the `fetch` function in the browser, plus an `onProgress` option to
+ * listen for progress events.
+ */
+export interface VerifiedFetchInit extends RequestInit, ProgressOptions<BubbledProgressEvents | VerifiedFetchProgressEvents> {
+}
+/**
+ * Create and return a Helia node
+ */
+export declare function createVerifiedFetch(init: Helia | CreateVerifiedFetchWithOptions): Promise<VerifiedFetch>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuNG;AAMH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,4BAA4B,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AACzG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAErE;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,GAAG,CAAA;AAEnC,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,cAAe,SAAQ,SAAS;IAC/C,KAAK,EAAE,KAAK,CAAA;CACb;AAED,MAAM,WAAW,aAAa;IAC5B,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IACpE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,MAAM,MAAM,qBAAqB,GAE/B,SAAS,GAET,qBAAqB,GAAG,4BAA4B,GAAG,iBAAiB,CAAA;AAE1E,MAAM,MAAM,2BAA2B,GACrC,aAAa,CAAC,8BAA8B,EAAE,SAAS,CAAC,GACxD,aAAa,CAAC,6BAA6B,EAAE,MAAM,CAAC,GACpD,aAAa,CAAC,uCAAuC,EAAE,SAAS,CAAC,GACjE,aAAa,CAAC,4BAA4B,EAAE,SAAS,CAAC,GACtD,aAAa,CAAC,8BAA8B,EAAE,cAAc,CAAC,CAAA;AAE/D;;;;;GAKG;AACH,MAAM,WAAW,iBAAkB,SAAQ,WAAW,EAAE,eAAe,CAAC,qBAAqB,GAAG,2BAA2B,CAAC;CAC3H;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CAAE,IAAI,EAAE,KAAK,GAAG,8BAA8B,GAAG,OAAO,CAAC,aAAa,CAAC,CAoB/G"}

package/dist/src/index.js

@@ -0,0 +1,251 @@
+/**
+ * @packageDocumentation
+ *
+ * `@helia/verified-fetch` is a library that provides a fetch-like API for fetching trustless content from IPFS and verifying it.
+ *
+ * This library should act as a replacement for the `fetch()` API for fetching content from IPFS, and will return a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) object that can be used in a similar manner to the `fetch()` API. This means browser and HTTP caching inside browser main threads, web-workers, and service workers, as well as other features of the `fetch()` API should work in a way familiar to developers.
+ *
+ * Exports a `createVerifiedFetch` function that returns a `fetch()` like API method {@link Helia} for fetching IPFS content.
+ *
+ * You may use any supported resource argument to fetch content:
+ *
+ * - CID instance
+ * - IPFS URL
+ * - IPNS URL
+ *
+ * @example
+ *
+ * ```typescript
+ * import { createVerifiedFetch } from '@helia/verified-fetch'
+ *
+ * const fetch = await createVerifiedFetch({
+ *  gateways: ['https://mygateway.example.net', 'https://trustless-gateway.link']
+ *})
+ *
+ * const resp = await fetch('ipfs://bafy...')
+ *
+ * const json = await resp.json()
+ *```
+ *
+ *
+ * @example Using a CID instance to fetch JSON
+ *
+ * ```typescript
+ * import { createVerifiedFetch } from '@helia/verified-fetch'
+ * import { CID } from 'multiformats/cid'
+ *
+ * const fetch = await createVerifiedFetch({
+ *  gateways: ['https://mygateway.example.net', 'https://trustless-gateway.link']
+ * })
+ *
+ * const cid = CID.parse('bafyFoo') // some image file
+ * const response = await fetch(cid)
+ * const json = await response.json()
+ * ```
+ *
+ * @example Using IPFS protocol to fetch an image
+ *
+ * ```typescript
+ * import { createVerifiedFetch } from '@helia/verified-fetch'
+ *
+ * const fetch = await createVerifiedFetch({
+ *  gateways: ['https://mygateway.example.net', 'https://trustless-gateway.link']
+ * })
+ * const response = await fetch('ipfs://bafyFoo') // CID for some image file
+ * const blob = await response.blob()
+ * const image = document.createElement('img')
+ * image.src = URL.createObjectURL(blob)
+ * document.body.appendChild(image)
+ * ```
+ *
+ * @example Using IPNS protocol to stream a big file
+ *
+ * ```typescript
+ * import { createVerifiedFetch } from '@helia/verified-fetch'
+ *
+ * const fetch = await createVerifiedFetch({
+ *  gateways: ['https://mygateway.example.net', 'https://trustless-gateway.link']
+ * })
+ * const response = await fetch('ipns://mydomain.com/path/to/very-long-file.log')
+ * const bigFileStreamReader = await response.body.getReader()
+ * ```
+ *
+ * ### Configuration
+ *
+ * #### Usage with customized Helia
+ *
+ * You can see variations of Helia and js-libp2p configuration options at https://helia.io/interfaces/helia.index.HeliaInit.html.
+ *
+ * The `@helia/http` module is currently in-progress, but the init options should be a subset of the `helia` module's init options. See https://github.com/ipfs/helia/issues/289 for more information.
+ *
+ * ```typescript
+ * import { trustlessGateway } from '@helia/block-brokers'
+ * import { createHeliaHTTP } from '@helia/http'
+ * import { delegatedHTTPRouting } from '@helia/routers'
+ * import { createVerifiedFetch } from '@helia/verified-fetch'
+ *
+ * const fetch = await createVerifiedFetch(
+ *   await createHeliaHTTP({
+ *       blockBrokers: [
+ *         trustlessGateway({
+ *           gateways: ['https://mygateway.example.net', 'https://trustless-gateway.link']
+ *         })
+ *       ],
+ *       routers: ['http://delegated-ipfs.dev'].map((routerUrl) => delegatedHTTPRouting(routerUrl))
+ *     })
+ * )
+ *
+ * const resp = await fetch('ipfs://bafy...')
+ *
+ * const json = await resp.json()
+ * ```
+ *
+ * ### Comparison to fetch
+ *
+ * First, this library will require instantiation in order to configure the gateways and delegated routers, or potentially a custom Helia instance. Secondly, once your verified-fetch method is created, it will act as similar to the `fetch()` API as possible.
+ *
+ * [The `fetch()` API](https://developer.mozilla.org/en-US/docs/Web/API/fetch) takes two parameters:
+ *
+ * 1. A [resource](https://developer.mozilla.org/en-US/docs/Web/API/fetch#resource)
+ * 2. An [options object](https://developer.mozilla.org/en-US/docs/Web/API/fetch#options)
+ *
+ * #### Resource argument
+ *
+ * This library intends to support the following methods of fetching web3 content from IPFS:
+ *
+ * 1. IPFS protocol: `ipfs://<cidv0>` & `ipfs://<cidv0>`
+ * 2. IPNS protocol: `ipns://<peerId>` & `ipns://<publicKey>` & `ipns://<hostUri_Supporting_DnsLink_TxtRecords>`
+ * 3. CID instances: An actual CID instance `CID.parse('bafy...')`
+ *
+ * As well as support for pathing & params for item 1&2 above according to [IPFS - Path Gateway Specification](https://specs.ipfs.tech/http-gateways/path-gateway) & [IPFS - Trustless Gateway Specification](https://specs.ipfs.tech/http-gateways/trustless-gateway/). Further refinement of those specifications specifically for web-based scenarios can be found in the [Web Pathing Specification IPIP](https://github.com/ipfs/specs/pull/453).
+ *
+ * If you pass a CID instance, we assume you want the content for that specific CID only, and do not support pathing or params for that CID.
+ *
+ * #### Options argument
+ *
+ * This library does not plan to support the exact Fetch API options object, as some of the arguments don't make sense. Instead, it will only support options necessary to meet [IPFS specs](https://specs.ipfs.tech/) related to specifying the resultant shape of desired content.
+ *
+ * Some of those header specifications are:
+ *
+ * 1. https://specs.ipfs.tech/http-gateways/path-gateway/#request-headers
+ * 2. https://specs.ipfs.tech/http-gateways/trustless-gateway/#request-headers
+ * 3. https://specs.ipfs.tech/http-gateways/subdomain-gateway/#request-headers
+ *
+ * Where possible, options and Helia internals will be automatically configured to the appropriate codec & content type based on the `verified-fetch` configuration and `options` argument passed.
+ *
+ * Known Fetch API options that will be supported:
+ *
+ * 1. `signal` - An AbortSignal that a user can use to abort the request.
+ * 2. `redirect` - A string that specifies the redirect type. One of `follow`, `error`, or `manual`. Defaults to `follow`. Best effort to adhere to the [Fetch API redirect](https://developer.mozilla.org/en-US/docs/Web/API/fetch#redirect) parameter.
+ * 3. `headers` - An object of headers to be sent with the request. Best effort to adhere to the [Fetch API headers](https://developer.mozilla.org/en-US/docs/Web/API/fetch#headers) parameter.
+ *     - `accept` - A string that specifies the accept header. Relevant values:
+ *         - [`vnd.ipld.raw`](https://www.iana.org/assignments/media-types/application/vnd.ipld.raw). (default)
+ *         - [`vnd.ipld.car`](https://www.iana.org/assignments/media-types/application/vnd.ipld.car)
+ *         - [`vnd.ipfs.ipns-record`](https://www.iana.org/assignments/media-types/application/vnd.ipfs.ipns-record)
+ * 4. `method` - A string that specifies the HTTP method to use for the request. Defaults to `GET`. Best effort to adhere to the [Fetch API method](https://developer.mozilla.org/en-US/docs/Web/API/fetch#method) parameter.
+ * 5. `body` - An object that specifies the body of the request. Best effort to adhere to the [Fetch API body](https://developer.mozilla.org/en-US/docs/Web/API/fetch#body) parameter.
+ * 6. `cache` - Will basically act as `force-cache` for the request. Best effort to adhere to the [Fetch API cache](https://developer.mozilla.org/en-US/docs/Web/API/fetch#cache) parameter.
+ *
+ *
+ * Non-Fetch API options that will be supported:
+ *
+ * 1. `onProgress` - Similar to Helia `onProgress` options, this will be a function that will be called with a progress event. Supported progress events are:
+ *     - `helia:verified-fetch:error` - An error occurred during the request.
+ *     - `helia:verified-fetch:request:start` - The request has been sent
+ *     - `helia:verified-fetch:request:complete` - The request has been sent
+ *     - `helia:verified-fetch:request:error` - An error occurred during the request.
+ *     - `helia:verified-fetch:request:abort` - The request was aborted prior to completion.
+ *     - `helia:verified-fetch:response:start` - The initial HTTP Response headers have been set, and response stream is started.
+ *     - `helia:verified-fetch:response:complete` - The response stream has completed.
+ *     - `helia:verified-fetch:response:error` - An error occurred while building the response.
+ *
+ * Some in-flight specs (IPIPs) that will affect the options object this library supports in the future can be seen at https://specs.ipfs.tech/ipips, a subset are:
+ *
+ * 1. [IPIP-0412: Signaling Block Order in CARs on HTTP Gateways](https://specs.ipfs.tech/ipips/ipip-0412/)
+ * 2. [IPIP-0402: Partial CAR Support on Trustless Gateways](https://specs.ipfs.tech/ipips/ipip-0402/)
+ * 3. [IPIP-0386: Subdomain Gateway Interop with _redirects](https://specs.ipfs.tech/ipips/ipip-0386/)
+ * 4. [IPIP-0328: JSON and CBOR Response Formats on HTTP Gateways](https://specs.ipfs.tech/ipips/ipip-0328/)
+ * 5. [IPIP-0288: TAR Response Format on HTTP Gateways](https://specs.ipfs.tech/ipips/ipip-0288/)
+ *
+ * #### Response types
+ *
+ * This library's purpose is to return reasonably representable content from IPFS. In other words, fetching content is intended for leaf-node content -- such as images/videos/audio & other assets, or other IPLD content (with link) -- that can be represented by https://developer.mozilla.org/en-US/docs/Web/API/Response#instance_methods. The content type you receive back will depend upon the CID you request as well as the `Accept` header value you provide.
+ *
+ * All content we retrieve from the IPFS network is obtained via an AsyncIterable, and will be set as the [body of the HTTP Response](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response#body) via a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API/Using_readable_streams#consuming_a_fetch_as_a_stream) or other efficient method that avoids loading the entire response into memory or getting the entire response from the network before returning a response to the user.
+ *
+ * If your content doesn't have a mime-type or an [IPFS spec](https://specs.ipfs.tech), this library will not support it, but you can use the [`helia`](https://github.com/ipfs/helia) library directly for those use cases. See [Unsupported response types](#unsupported-response-types) for more information.
+ *
+ * ##### Handling response types
+ *
+ * For handling responses we want to follow conventions/abstractions from Fetch API where possible:
+ *
+ * - For JSON, assuming you abstract any differences between dag-json/dag-cbor/json/and json-file-on-unixfs, you would call `.json()` to get a JSON object.
+ * - For images (or other web-relevant asset) you want to add to the DOM, use `.blob()` or `.arrayBuffer()` to get the raw bytes.
+ * - For plain text in utf-8, you would call `.text()`
+ * - For streaming response data, use something like `response.body.getReader()` to get a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API/Using_readable_streams#consuming_a_fetch_as_a_stream).
+ *
+ * ##### Unsupported response types
+ *
+ * * Returning IPLD nodes or DAGs as JS objects is not supported, as there is no currently well-defined structure for representing this data in an [HTTP Response](https://developer.mozilla.org/en-US/docs/Web/API/Response). Instead, users should request `aplication/vnd.ipld.car` or use the [`helia`](https://github.com/ipfs/helia) library directly for this use case.
+ * * Others? Open an issue or PR!
+ *
+ * #### Response headers
+ *
+ * This library will set the [HTTP Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) headers to the appropriate values for the content type according to the appropriate [IPFS Specifications](https://specs.ipfs.tech/).
+ *
+ * Some known header specifications:
+ *
+ * * https://specs.ipfs.tech/http-gateways/path-gateway/#response-headers
+ * * https://specs.ipfs.tech/http-gateways/trustless-gateway/#response-headers
+ * * https://specs.ipfs.tech/http-gateways/subdomain-gateway/#response-headers
+ *
+ * #### Possible Scenarios that could cause confusion
+ *
+ * ##### Attempting to fetch the CID for content that does not make sense
+ *
+ * If you request `bafybeiaysi4s6lnjev27ln5icwm6tueaw2vdykrtjkwiphwekaywqhcjze`, which points to the root of the en.wikipedia.org mirror, a response object does not make sense.
+ *
+ * #### Errors
+ *
+ * Known Errors that can be thrown:
+ *
+ * 1. `TypeError` - If the resource argument is not a string, CID, or CID string.
+ * 2. `TypeError` - If the options argument is passed and not an object.
+ * 3. `TypeError` - If the options argument is passed and is malformed.
+ * 4. `AbortError` - If the content request is aborted due to user aborting provided AbortSignal.
+ */
+import { trustlessGateway } from '@helia/block-brokers';
+import { createHeliaHTTP } from '@helia/http';
+import { delegatedHTTPRouting } from '@helia/routers';
+import { VerifiedFetch as VerifiedFetchClass } from './verified-fetch.js';
+/**
+ * Create and return a Helia node
+ */
+export async function createVerifiedFetch(init) {
+    if (!isHelia(init)) {
+        init = await createHeliaHTTP({
+            blockBrokers: [
+                trustlessGateway({
+                    gateways: init.gateways
+                })
+            ],
+            routers: init.routers?.map((routerUrl) => delegatedHTTPRouting(routerUrl))
+        });
+    }
+    const verifiedFetchInstance = new VerifiedFetchClass({ helia: init });
+    async function verifiedFetch(resource, options) {
+        return verifiedFetchInstance.fetch(resource, options);
+    }
+    verifiedFetch.stop = verifiedFetchInstance.stop.bind(verifiedFetchInstance);
+    verifiedFetch.start = verifiedFetchInstance.start.bind(verifiedFetchInstance);
+    return verifiedFetch;
+}
+function isHelia(obj) {
+    // test for the presence of known Helia properties, return a boolean value
+    return obj?.blockstore != null &&
+        obj?.datastore != null &&
+        obj?.gc != null &&
+        obj?.stop != null &&
+        obj?.start != null;
+}
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuNG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,EAAE,aAAa,IAAI,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAyDzE;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAE,IAA4C;IACrF,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACnB,IAAI,GAAG,MAAM,eAAe,CAAC;YAC3B,YAAY,EAAE;gBACZ,gBAAgB,CAAC;oBACf,QAAQ,EAAE,IAAI,CAAC,QAAQ;iBACxB,CAAC;aACH;YACD,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,oBAAoB,CAAC,SAAS,CAAC,CAAC;SAC3E,CAAC,CAAA;IACJ,CAAC;IAED,MAAM,qBAAqB,GAAG,IAAI,kBAAkB,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;IACrE,KAAK,UAAU,aAAa,CAAE,QAAkB,EAAE,OAA2B;QAC3E,OAAO,qBAAqB,CAAC,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;IACvD,CAAC;IACD,aAAa,CAAC,IAAI,GAAG,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAA;IAC3E,aAAa,CAAC,KAAK,GAAG,qBAAqB,CAAC,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAA;IAE7E,OAAO,aAAa,CAAA;AACtB,CAAC;AAED,SAAS,OAAO,CAAE,GAAQ;IACxB,0EAA0E;IAC1E,OAAO,GAAG,EAAE,UAAU,IAAI,IAAI;QAC5B,GAAG,EAAE,SAAS,IAAI,IAAI;QACtB,GAAG,EAAE,EAAE,IAAI,IAAI;QACf,GAAG,EAAE,IAAI,IAAI,IAAI;QACjB,GAAG,EAAE,KAAK,IAAI,IAAI,CAAA;AACtB,CAAC"}

package/dist/src/utils/get-content-type.d.ts

@@ -0,0 +1,11 @@
+interface TestInput {
+    bytes: Uint8Array;
+    path: string;
+}
+export declare const DEFAULT_MIME_TYPE = "application/octet-stream";
+/**
+ * Get the content type from the input based on the tests.
+ */
+export declare function getContentType(input: TestInput): Promise<string>;
+export {};
+//# sourceMappingURL=get-content-type.d.ts.map

package/dist/src/utils/get-content-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-content-type.d.ts","sourceRoot":"","sources":["../../../src/utils/get-content-type.ts"],"names":[],"mappings":"AAEA,UAAU,SAAS;IACjB,KAAK,EAAE,UAAU,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;CACb;AAID,eAAO,MAAM,iBAAiB,6BAA6B,CAAA;AAkC3D;;GAEG;AACH,wBAAsB,cAAc,CAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAQvE"}

package/dist/src/utils/get-content-type.js

@@ -0,0 +1,43 @@
+import mime from 'mime-types';
+export const DEFAULT_MIME_TYPE = 'application/octet-stream';
+const xmlRegex = /^(<\?xml[^>]+>)?[^<^\w]+<svg/ig;
+/**
+ * Tests to determine the content type of the input.
+ * The order is important on this one.
+ */
+const tests = [
+    // svg
+    async ({ bytes }) => xmlRegex.test(new TextDecoder().decode(bytes.slice(0, 64)))
+        ? 'image/svg+xml'
+        : undefined,
+    // testing file-type from path
+    async ({ path }) => {
+        const mimeType = mime.lookup(path);
+        if (mimeType !== false) {
+            return mimeType;
+        }
+        return undefined;
+    }
+];
+const overrides = {
+    'video/quicktime': 'video/mp4'
+};
+/**
+ * Override the content type based on overrides.
+ */
+function overrideContentType(type) {
+    return overrides[type] ?? type;
+}
+/**
+ * Get the content type from the input based on the tests.
+ */
+export async function getContentType(input) {
+    for (const test of tests) {
+        const type = await test(input);
+        if (type !== undefined) {
+            return overrideContentType(type);
+        }
+    }
+    return DEFAULT_MIME_TYPE;
+}
+//# sourceMappingURL=get-content-type.js.map

package/dist/src/utils/get-content-type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-content-type.js","sourceRoot":"","sources":["../../../src/utils/get-content-type.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,YAAY,CAAA;AAS7B,MAAM,CAAC,MAAM,iBAAiB,GAAG,0BAA0B,CAAA;AAE3D,MAAM,QAAQ,GAAG,gCAAgC,CAAA;AAEjD;;;GAGG;AACH,MAAM,KAAK,GAA4C;IACrD,MAAM;IACN,KAAK,EAAE,EAAE,KAAK,EAAE,EAAc,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QAC1F,CAAC,CAAC,eAAe;QACjB,CAAC,CAAC,SAAS;IACb,8BAA8B;IAC9B,KAAK,EAAE,EAAE,IAAI,EAAE,EAAc,EAAE;QAC7B,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QAClC,IAAI,QAAQ,KAAK,KAAK,EAAE,CAAC;YACvB,OAAO,QAAQ,CAAA;QACjB,CAAC;QACD,OAAO,SAAS,CAAA;IAClB,CAAC;CACF,CAAA;AAED,MAAM,SAAS,GAA2B;IACxC,iBAAiB,EAAE,WAAW;CAC/B,CAAA;AAED;;GAEG;AACH,SAAS,mBAAmB,CAAE,IAAY;IACxC,OAAO,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,CAAA;AAChC,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAE,KAAgB;IACpD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,CAAA;QAC9B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,OAAO,mBAAmB,CAAC,IAAI,CAAC,CAAA;QAClC,CAAC;IACH,CAAC;IACD,OAAO,iBAAiB,CAAA;AAC1B,CAAC"}

package/dist/src/utils/get-stream-and-content-type.d.ts

@@ -0,0 +1,10 @@
+import type { VerifiedFetchInit } from '../index.js';
+import type { ComponentLogger } from '@libp2p/interface';
+/**
+ * Converts an async iterator of Uint8Array bytes to a stream and attempts to determine the content type of those bytes.
+ */
+export declare function getStreamAndContentType(iterator: AsyncIterable<Uint8Array>, path: string, logger: ComponentLogger, options?: Pick<VerifiedFetchInit, 'onProgress'>): Promise<{
+    contentType: string;
+    stream: ReadableStream<Uint8Array>;
+}>;
+//# sourceMappingURL=get-stream-and-content-type.d.ts.map

package/dist/src/utils/get-stream-and-content-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-stream-and-content-type.d.ts","sourceRoot":"","sources":["../../../src/utils/get-stream-and-content-type.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAExD;;GAEG;AACH,wBAAsB,uBAAuB,CAAE,QAAQ,EAAE,aAAa,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,iBAAiB,EAAE,YAAY,CAAC,GAAG,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,CAAA;CAAE,CAAC,CAmChP"}

package/dist/src/utils/get-stream-and-content-type.js

@@ -0,0 +1,37 @@
+import { CustomProgressEvent } from 'progress-events';
+import { getContentType } from './get-content-type.js';
+/**
+ * Converts an async iterator of Uint8Array bytes to a stream and attempts to determine the content type of those bytes.
+ */
+export async function getStreamAndContentType(iterator, path, logger, options) {
+    const log = logger.forComponent('helia:verified-fetch:get-stream-and-content-type');
+    const reader = iterator[Symbol.asyncIterator]();
+    const { value, done } = await reader.next();
+    if (done === true) {
+        log.error('No content found for path', path);
+        throw new Error('No content found');
+    }
+    const contentType = await getContentType({ bytes: value, path });
+    const stream = new ReadableStream({
+        async start(controller) {
+            // the initial value is already available
+            options?.onProgress?.(new CustomProgressEvent('verified-fetch:request:progress:chunk'));
+            controller.enqueue(value);
+        },
+        async pull(controller) {
+            const { value, done } = await reader.next();
+            if (done === true) {
+                if (value != null) {
+                    options?.onProgress?.(new CustomProgressEvent('verified-fetch:request:progress:chunk'));
+                    controller.enqueue(value);
+                }
+                controller.close();
+                return;
+            }
+            options?.onProgress?.(new CustomProgressEvent('verified-fetch:request:progress:chunk'));
+            controller.enqueue(value);
+        }
+    });
+    return { contentType, stream };
+}
+//# sourceMappingURL=get-stream-and-content-type.js.map

package/dist/src/utils/get-stream-and-content-type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-stream-and-content-type.js","sourceRoot":"","sources":["../../../src/utils/get-stream-and-content-type.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAItD;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAE,QAAmC,EAAE,IAAY,EAAE,MAAuB,EAAE,OAA+C;IACxK,MAAM,GAAG,GAAG,MAAM,CAAC,YAAY,CAAC,kDAAkD,CAAC,CAAA;IACnF,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAA;IAC/C,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAA;IAE3C,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,GAAG,CAAC,KAAK,CAAC,2BAA2B,EAAE,IAAI,CAAC,CAAA;QAC5C,MAAM,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAA;IACrC,CAAC;IAED,MAAM,WAAW,GAAG,MAAM,cAAc,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;IAChE,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC;QAChC,KAAK,CAAC,KAAK,CAAE,UAAU;YACrB,yCAAyC;YACzC,OAAO,EAAE,UAAU,EAAE,CAAC,IAAI,mBAAmB,CAAO,uCAAuC,CAAC,CAAC,CAAA;YAC7F,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;QAC3B,CAAC;QACD,KAAK,CAAC,IAAI,CAAE,UAAU;YACpB,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAA;YAE3C,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;gBAClB,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;oBAClB,OAAO,EAAE,UAAU,EAAE,CAAC,IAAI,mBAAmB,CAAO,uCAAuC,CAAC,CAAC,CAAA;oBAC7F,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;gBAC3B,CAAC;gBACD,UAAU,CAAC,KAAK,EAAE,CAAA;gBAClB,OAAM;YACR,CAAC;YAED,OAAO,EAAE,UAAU,EAAE,CAAC,IAAI,mBAAmB,CAAO,uCAAuC,CAAC,CAAC,CAAA;YAC7F,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;QAC3B,CAAC;KACF,CAAC,CAAA;IAEF,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,CAAA;AAChC,CAAC"}