@helia/verified-fetch 2.4.0 → 2.5.0

package/dist/src/index.d.ts

@@ -626,12 +626,204 @@
  * 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. Note that this is a `AbortError` from `@libp2p/interface` and not the standard `AbortError` from the Fetch API.
+ *
+ * ## Pluggability and Extensibility
+ *
+ * Verified‑fetch can now be extended to alter how it handles requests by using plugins.
+ * Plugins are classes that extend the `BasePlugin` class and implement the `VerifiedFetchPlugin`
+ * interface. They are instantiated with `PluginOptions` when the `VerifiedFetch` class is created.
+ *
+ * Each plugin must implement two methods:
+ *
+ * - **`canHandle(context: PluginContext): boolean`**
+ *   Inspects the current `PluginContext` (which includes the CID, path, query, accept header, etc.)
+ *   and returns `true` if the plugin can operate on the current state of the request.
+ *
+ * - **`handle(context: PluginContext): Promise<Response | null>`**
+ *   Performs the plugin’s work. It may:
+ *     - **Return a final `Response`**: This stops the pipeline immediately.
+ *     - **Return `null`**: This indicates that the plugin has only partially processed the request
+ *       (for example, by performing path walking or decoding) and the pipeline should continue.
+ *    - **Throw a `PluginError`**: This logs a non-fatal error and continues the pipeline.
+ *    - **Throw a `PluginFatalError`**: This logs a fatal error and stops the pipeline immediately.
+ *
+ * Plugins are executed in a chain (a **plugin pipeline**):
+ *
+ * 1. **Initialization:**
+ *    - The `VerifiedFetch` class is instantiated with a list of plugins.
+ *    - When a request is made via the `fetch` method, the resource and options are parsed to
+ *      create a mutable `PluginContext` object.
+ *
+ * 2. **Pipeline Execution:**
+ *    - The pipeline repeatedly checks, up to a maximum number of passes (default = 3), which plugins
+ *      are currently able to handle the request by calling each plugin’s `canHandle()` method.
+ *    - Plugins that have not yet been called in the current run and return `true` for `canHandle()`
+ *      are invoked in sequence.
+ *      - If a plugin returns a final `Response` or throws a `PluginFatalError`, the pipeline immediately
+ *        stops and that response is returned.
+ *      - If a plugin returns `null`, it may have updated the context (for example, by
+ *        performing path walking), other plugins that said they `canHandle` will run.
+ *    - If no plugin modifies the context (i.e. no change to `context.modified`) and no final response is
+ *      produced after iterating through all plugins, the pipeline exits and a default “Not Supported”
+ *      response is returned.
+ *
+ *    **Diagram of the Plugin Pipeline:**
+ *
+ * ```mermaid
+ * flowchart TD
+ *     A[Resource & Options] --> B[Parse into PluginContext]
+ *     B --> C[Plugin Pipeline]
+ *     subgraph IP[Iterative Passes max 3 passes]
+ *       C1[Check canHandle for each plugin]
+ *       C2[Call handle on ready plugins]
+ *       C3[Update PluginContext if partial work is done]
+ *       C1 --> C2
+ *       C2 --> C3
+ *     end
+ *     C --> IP
+ *     IP --> D[Final Response]
+ * ```
+ *
+ * 3. **Finalization:**
+ *    - After the pipeline completes, the resulting response & context is processed (e.g. headers such as ETag,
+ *      Cache‑Control, and Content‑Disposition are set) and returned.
+ *
+ * Please see the original discussion on extensibility in [Issue #167](https://github.com/ipfs/helia-verified-fetch/issues/167).
+ *
+ * ---
+ *
+ * ### Extending Verified‑Fetch with Custom Plugins
+ *
+ * To add your own plugin:
+ *
+ * 1. **Extend the BasePlugin:**
+ *
+ *    Create a new class that extends `BasePlugin` and implements:
+ *
+ *    - `canHandle(context: PluginContext): boolean`
+ *    - `handle(context: PluginContext): Promise<Response | null>`
+ *
+ * @example custom plugin
+ *
+ *    ```typescript
+ *    import { BasePlugin, type PluginContext, type VerifiedFetchPluginFactory, type PluginOptions } from '@helia/verified-fetch'
+ *    import { okResponse } from './dist/src/utils/responses.js'
+ *
+ *    export class MyCustomPlugin extends BasePlugin {
+ *      // Optionally, list any codec codes your plugin supports:
+ *      codes = [] //
+ *
+ *      canHandle(context: PluginContext): boolean {
+ *        // Only handle requests if the Accept header matches your custom type
+ *        // Or check context for pathDetails, custom values, etc...
+ *        return context.accept === 'application/vnd.my-custom-type'
+ *      }
+ *
+ *      async handle(context: PluginContext): Promise<Response | null> {
+ *        // Perform any partial processing here, e.g., modify the context:
+ *        context.customProcessed = true;
+ *
+ *        // If you are ready to finalize the response:
+ *        return new Response('Hello, world!', {
+ *          status: 200,
+ *          headers: {
+ *            'Content-Type': 'text/plain'
+ *          }
+          });
+ *
+ *        // Or, if further processing is needed by another plugin, simply return null.
+ *      }
+ *    }
+ *    export const myCustomPluginFactory: VerifiedFetchPluginFactory = (opts: PluginOptions) => new MyCustomPlugin(opts)
+ *    ```
+ *
+ * 2. **Integrate Your Plugin:**
+ *
+ *    Add your custom plugin to Verified‑Fetch’s plugin list when instantiating Verified‑Fetch:
+ *
+ * @example Integrate custom plugin
+ *
+ *    ```typescript
+ *    import { createVerifiedFetch, type VerifiedFetchPluginFactory } from '@helia/verified-fetch'
+ *    import { createHelia } from 'helia'
+ *
+ *    const helia = await createHelia()
+ *    const plugins: VerifiedFetchPluginFactory[] = [
+ *      // myCustomPluginFactory
+ *    ]
+ *
+ *    const fetch = await createVerifiedFetch(helia, { plugins })
+ *    ```
+ *
+ * ---
+ *
+ * ### Error Handling in the Plugin Pipeline
+ *
+ * Verified‑Fetch distinguishes between two types of errors thrown by plugins:
+ *
+ * - **PluginError (Non‑Fatal):**
+ *   - Use this when your plugin encounters an issue that should be logged but does not prevent the pipeline
+ *     from continuing.
+ *   - When a plugin throws a `PluginError`, the error is logged and the pipeline continues with the next plugin.
+ *
+ * - **PluginFatalError (Fatal):**
+ *   - Use this when a critical error occurs that should immediately abort the request.
+ *   - When a plugin throws a `PluginFatalError`, the pipeline immediately terminates and the provided error
+ *     response is returned.
+ *
+ * @example Plugin error Handling
+ *
+ * ```typescript
+ * import { PluginError, PluginFatalError } from '@helia/verified-fetch'
+ *
+ * // async handle(context: PluginContext): Promise<Response | null> {
+ * const recoverable = Math.random() > 0.5 // Use more sophisticated logic here ;)
+ * if (recoverable === true) {
+ *   throw new PluginError('MY_CUSTOM_WARNING', 'A non‑fatal issue occurred', {
+ *     details: {
+ *       someKey: 'Additional details here'
+ *     }
+ *   });
+ * }
+ *
+ * if (recoverable === false) {
+ *   throw new PluginFatalError('MY_CUSTOM_FATAL', 'A critical error occurred', {
+ *     response: new Response('Something happened', { status: 500 })  // Required: supply your own error response
+ *   });
+ * }
+ *
+ *   // Otherwise, continue processing...
+ * // }
+ * ```
+ *
+ * ### How the Plugin Pipeline Works
+ *
+ * - **Shared Context:**
+ *   A mutable `PluginContext` is created for each request. It includes the parsed CID, path, query parameters,
+ *   accept header, and any other metadata. Plugins can update this context as they perform partial work (for example,
+ *   by doing path walking or decoding).
+ *
+ * - **Iterative Processing:**
+ *   The pipeline repeatedly checks which plugins can currently handle the request by calling `canHandle(context)`.
+ *   - Plugins that perform partial processing update the context and return `null`, allowing subsequent passes by other plugins.
+ *   - Once a plugin is ready to finalize the response, it returns a final `Response` and the pipeline terminates.
+ *
+ * - **No Strict Ordering:**
+ *   Plugins are invoked based solely on whether they can handle the current state of the context.
+ *   This means you do not have to specify a rigid order, each plugin simply checks the context and acts if appropriate.
+ *
+ * - **Error Handling:**
+ *   - A thrown `PluginError` is considered non‑fatal and is logged, allowing the pipeline to continue.
+ *   - A thrown `PluginFatalError` immediately stops the pipeline and returns the error response.
+ *
+ * For a detailed explanation of the pipeline, please refer to the discussion in [Issue #167](https://github.com/ipfs/helia-verified-fetch/issues/167).
  */
 import { type ResolveDNSLinkProgressEvents } from '@helia/ipns';
 import { type ServiceMap } from '@libp2p/interface';
 import { type HeliaInit } from 'helia';
 import { type Libp2pOptions } from 'libp2p';
 import { type ContentTypeParser } from './types.js';
+import type { VerifiedFetchPluginFactory } from './plugins/types.js';
 import type { GetBlockProgressEvents, Helia } from '@helia/interface';
 import type { DNSResolvers } from '@multiformats/dns';
 import type { DNSResolver } from '@multiformats/dns/resolvers';
@@ -745,6 +937,11 @@ export interface CreateVerifiedFetchOptions {
      * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Server-Timing
      */
     withServerTiming?: boolean;
+    /**
+     * Plugins to use with the verified-fetch instance. Note that we have a set of default plugins that are always used.
+     * If you want to replace one of the default plugins, you can do so by passing a plugin with the same name.
+     */
+    plugins?: VerifiedFetchPluginFactory[];
 }
 export type { ContentTypeParser } from './types.js';
 export type BubbledProgressEvents = ExporterProgressEvents | GetBlockProgressEvents | ResolveDNSLinkProgressEvents;
@@ -808,4 +1005,5 @@ export interface VerifiedFetchInit extends RequestInit, ProgressOptions<BubbledP
  */
 export declare function createVerifiedFetch(init?: Helia | CreateVerifiedFetchInit, options?: CreateVerifiedFetchOptions): Promise<VerifiedFetch>;
 export { verifiedFetch } from './singleton.js';
+export * from './plugins/index.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/dist/src/index.js

@@ -626,6 +626,197 @@
  * 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. Note that this is a `AbortError` from `@libp2p/interface` and not the standard `AbortError` from the Fetch API.
+ *
+ * ## Pluggability and Extensibility
+ *
+ * Verified‑fetch can now be extended to alter how it handles requests by using plugins.
+ * Plugins are classes that extend the `BasePlugin` class and implement the `VerifiedFetchPlugin`
+ * interface. They are instantiated with `PluginOptions` when the `VerifiedFetch` class is created.
+ *
+ * Each plugin must implement two methods:
+ *
+ * - **`canHandle(context: PluginContext): boolean`**
+ *   Inspects the current `PluginContext` (which includes the CID, path, query, accept header, etc.)
+ *   and returns `true` if the plugin can operate on the current state of the request.
+ *
+ * - **`handle(context: PluginContext): Promise<Response | null>`**
+ *   Performs the plugin’s work. It may:
+ *     - **Return a final `Response`**: This stops the pipeline immediately.
+ *     - **Return `null`**: This indicates that the plugin has only partially processed the request
+ *       (for example, by performing path walking or decoding) and the pipeline should continue.
+ *    - **Throw a `PluginError`**: This logs a non-fatal error and continues the pipeline.
+ *    - **Throw a `PluginFatalError`**: This logs a fatal error and stops the pipeline immediately.
+ *
+ * Plugins are executed in a chain (a **plugin pipeline**):
+ *
+ * 1. **Initialization:**
+ *    - The `VerifiedFetch` class is instantiated with a list of plugins.
+ *    - When a request is made via the `fetch` method, the resource and options are parsed to
+ *      create a mutable `PluginContext` object.
+ *
+ * 2. **Pipeline Execution:**
+ *    - The pipeline repeatedly checks, up to a maximum number of passes (default = 3), which plugins
+ *      are currently able to handle the request by calling each plugin’s `canHandle()` method.
+ *    - Plugins that have not yet been called in the current run and return `true` for `canHandle()`
+ *      are invoked in sequence.
+ *      - If a plugin returns a final `Response` or throws a `PluginFatalError`, the pipeline immediately
+ *        stops and that response is returned.
+ *      - If a plugin returns `null`, it may have updated the context (for example, by
+ *        performing path walking), other plugins that said they `canHandle` will run.
+ *    - If no plugin modifies the context (i.e. no change to `context.modified`) and no final response is
+ *      produced after iterating through all plugins, the pipeline exits and a default “Not Supported”
+ *      response is returned.
+ *
+ *    **Diagram of the Plugin Pipeline:**
+ *
+ * ```mermaid
+ * flowchart TD
+ *     A[Resource & Options] --> B[Parse into PluginContext]
+ *     B --> C[Plugin Pipeline]
+ *     subgraph IP[Iterative Passes max 3 passes]
+ *       C1[Check canHandle for each plugin]
+ *       C2[Call handle on ready plugins]
+ *       C3[Update PluginContext if partial work is done]
+ *       C1 --> C2
+ *       C2 --> C3
+ *     end
+ *     C --> IP
+ *     IP --> D[Final Response]
+ * ```
+ *
+ * 3. **Finalization:**
+ *    - After the pipeline completes, the resulting response & context is processed (e.g. headers such as ETag,
+ *      Cache‑Control, and Content‑Disposition are set) and returned.
+ *
+ * Please see the original discussion on extensibility in [Issue #167](https://github.com/ipfs/helia-verified-fetch/issues/167).
+ *
+ * ---
+ *
+ * ### Extending Verified‑Fetch with Custom Plugins
+ *
+ * To add your own plugin:
+ *
+ * 1. **Extend the BasePlugin:**
+ *
+ *    Create a new class that extends `BasePlugin` and implements:
+ *
+ *    - `canHandle(context: PluginContext): boolean`
+ *    - `handle(context: PluginContext): Promise<Response | null>`
+ *
+ * @example custom plugin
+ *
+ *    ```typescript
+ *    import { BasePlugin, type PluginContext, type VerifiedFetchPluginFactory, type PluginOptions } from '@helia/verified-fetch'
+ *    import { okResponse } from './dist/src/utils/responses.js'
+ *
+ *    export class MyCustomPlugin extends BasePlugin {
+ *      // Optionally, list any codec codes your plugin supports:
+ *      codes = [] //
+ *
+ *      canHandle(context: PluginContext): boolean {
+ *        // Only handle requests if the Accept header matches your custom type
+ *        // Or check context for pathDetails, custom values, etc...
+ *        return context.accept === 'application/vnd.my-custom-type'
+ *      }
+ *
+ *      async handle(context: PluginContext): Promise<Response | null> {
+ *        // Perform any partial processing here, e.g., modify the context:
+ *        context.customProcessed = true;
+ *
+ *        // If you are ready to finalize the response:
+ *        return new Response('Hello, world!', {
+ *          status: 200,
+ *          headers: {
+ *            'Content-Type': 'text/plain'
+ *          }
+          });
+ *
+ *        // Or, if further processing is needed by another plugin, simply return null.
+ *      }
+ *    }
+ *    export const myCustomPluginFactory: VerifiedFetchPluginFactory = (opts: PluginOptions) => new MyCustomPlugin(opts)
+ *    ```
+ *
+ * 2. **Integrate Your Plugin:**
+ *
+ *    Add your custom plugin to Verified‑Fetch’s plugin list when instantiating Verified‑Fetch:
+ *
+ * @example Integrate custom plugin
+ *
+ *    ```typescript
+ *    import { createVerifiedFetch, type VerifiedFetchPluginFactory } from '@helia/verified-fetch'
+ *    import { createHelia } from 'helia'
+ *
+ *    const helia = await createHelia()
+ *    const plugins: VerifiedFetchPluginFactory[] = [
+ *      // myCustomPluginFactory
+ *    ]
+ *
+ *    const fetch = await createVerifiedFetch(helia, { plugins })
+ *    ```
+ *
+ * ---
+ *
+ * ### Error Handling in the Plugin Pipeline
+ *
+ * Verified‑Fetch distinguishes between two types of errors thrown by plugins:
+ *
+ * - **PluginError (Non‑Fatal):**
+ *   - Use this when your plugin encounters an issue that should be logged but does not prevent the pipeline
+ *     from continuing.
+ *   - When a plugin throws a `PluginError`, the error is logged and the pipeline continues with the next plugin.
+ *
+ * - **PluginFatalError (Fatal):**
+ *   - Use this when a critical error occurs that should immediately abort the request.
+ *   - When a plugin throws a `PluginFatalError`, the pipeline immediately terminates and the provided error
+ *     response is returned.
+ *
+ * @example Plugin error Handling
+ *
+ * ```typescript
+ * import { PluginError, PluginFatalError } from '@helia/verified-fetch'
+ *
+ * // async handle(context: PluginContext): Promise<Response | null> {
+ * const recoverable = Math.random() > 0.5 // Use more sophisticated logic here ;)
+ * if (recoverable === true) {
+ *   throw new PluginError('MY_CUSTOM_WARNING', 'A non‑fatal issue occurred', {
+ *     details: {
+ *       someKey: 'Additional details here'
+ *     }
+ *   });
+ * }
+ *
+ * if (recoverable === false) {
+ *   throw new PluginFatalError('MY_CUSTOM_FATAL', 'A critical error occurred', {
+ *     response: new Response('Something happened', { status: 500 })  // Required: supply your own error response
+ *   });
+ * }
+ *
+ *   // Otherwise, continue processing...
+ * // }
+ * ```
+ *
+ * ### How the Plugin Pipeline Works
+ *
+ * - **Shared Context:**
+ *   A mutable `PluginContext` is created for each request. It includes the parsed CID, path, query parameters,
+ *   accept header, and any other metadata. Plugins can update this context as they perform partial work (for example,
+ *   by doing path walking or decoding).
+ *
+ * - **Iterative Processing:**
+ *   The pipeline repeatedly checks which plugins can currently handle the request by calling `canHandle(context)`.
+ *   - Plugins that perform partial processing update the context and return `null`, allowing subsequent passes by other plugins.
+ *   - Once a plugin is ready to finalize the response, it returns a final `Response` and the pipeline terminates.
+ *
+ * - **No Strict Ordering:**
+ *   Plugins are invoked based solely on whether they can handle the current state of the context.
+ *   This means you do not have to specify a rigid order, each plugin simply checks the context and acts if appropriate.
+ *
+ * - **Error Handling:**
+ *   - A thrown `PluginError` is considered non‑fatal and is logged, allowing the pipeline to continue.
+ *   - A thrown `PluginFatalError` immediately stops the pipeline and returns the error response.
+ *
+ * For a detailed explanation of the pipeline, please refer to the discussion in [Issue #167](https://github.com/ipfs/helia-verified-fetch/issues/167).
  */
 import { bitswap, trustlessGateway } from '@helia/block-brokers';
 import { createDelegatedRoutingV1HttpApiClient } from '@helia/delegated-routing-v1-http-api-client';
@@ -686,6 +877,7 @@ export async function createVerifiedFetch(init, options) {
     return verifiedFetch;
 }
 export { verifiedFetch } from './singleton.js';
+export * from './plugins/index.js';
 function isHelia(obj) {
     // test for the presence of known Helia properties, return a boolean value
     return obj?.blockstore != null &&

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/dist/src/plugins/errors.d.ts

@@ -0,0 +1,25 @@
+import type { FatalPluginErrorOptions, PluginErrorOptions } from './types.js';
+/**
+ * If a plugin encounters an error, it should throw an instance of this class.
+ */
+export declare class PluginError extends Error {
+    name: string;
+    code: string;
+    fatal: boolean;
+    details?: Record<string, any>;
+    response?: any;
+    constructor(code: string, message: string, options?: PluginErrorOptions);
+}
+/**
+ * If a plugin encounters a fatal error and verified-fetch should not continue processing the request, it should throw
+ * an instance of this class.
+ *
+ * Note that you should be very careful when throwing a `PluginFatalError`, as it will stop the request from being
+ * processed further. If you do not have a response to return to the client, you should consider throwing a
+ * `PluginError` instead.
+ */
+export declare class PluginFatalError extends PluginError {
+    name: string;
+    constructor(code: string, message: string, options: FatalPluginErrorOptions);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/plugins/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/plugins/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAE7E;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;IAC7B,IAAI,SAAgB;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,OAAO,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC7B,QAAQ,CAAC,EAAE,GAAG,CAAA;gBAER,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB;CAOzE;AAED;;;;;;;GAOG;AACH,qBAAa,gBAAiB,SAAQ,WAAW;IACxC,IAAI,SAAqB;gBAEnB,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,uBAAuB;CAI7E"}

package/dist/src/plugins/errors.js

@@ -0,0 +1,33 @@
+/**
+ * If a plugin encounters an error, it should throw an instance of this class.
+ */
+export class PluginError extends Error {
+    name = 'PluginError';
+    code;
+    fatal;
+    details;
+    response;
+    constructor(code, message, options) {
+        super(message);
+        this.code = code;
+        this.fatal = options?.fatal ?? false;
+        this.details = options?.details;
+        this.response = options?.response;
+    }
+}
+/**
+ * If a plugin encounters a fatal error and verified-fetch should not continue processing the request, it should throw
+ * an instance of this class.
+ *
+ * Note that you should be very careful when throwing a `PluginFatalError`, as it will stop the request from being
+ * processed further. If you do not have a response to return to the client, you should consider throwing a
+ * `PluginError` instead.
+ */
+export class PluginFatalError extends PluginError {
+    name = 'PluginFatalError';
+    constructor(code, message, options) {
+        super(code, message, { ...options, fatal: true });
+        this.name = 'PluginFatalError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/plugins/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/plugins/errors.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC7B,IAAI,GAAG,aAAa,CAAA;IACpB,IAAI,CAAQ;IACZ,KAAK,CAAS;IACd,OAAO,CAAsB;IAC7B,QAAQ,CAAM;IAErB,YAAa,IAAY,EAAE,OAAe,EAAE,OAA4B;QACtE,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,KAAK,CAAA;QACpC,IAAI,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,CAAA;QAC/B,IAAI,CAAC,QAAQ,GAAG,OAAO,EAAE,QAAQ,CAAA;IACnC,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,gBAAiB,SAAQ,WAAW;IACxC,IAAI,GAAG,kBAAkB,CAAA;IAEhC,YAAa,IAAY,EAAE,OAAe,EAAE,OAAgC;QAC1E,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,GAAG,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;QACjD,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAA;IAChC,CAAC;CACF"}

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

@@ -0,0 +1,8 @@
+/**
+ * This file is the entry into all things we export from the `src/plugins` directory.
+ */
+export { PluginError, PluginFatalError } from './errors.js';
+export { BasePlugin } from './plugin-base.js';
+export type { PluginOptions, PluginContext, VerifiedFetchPluginFactory } from './types.js';
+export * from './plugins.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAA;AAC1F,cAAc,cAAc,CAAA"}

package/dist/src/plugins/index.js

@@ -0,0 +1,7 @@
+/**
+ * This file is the entry into all things we export from the `src/plugins` directory.
+ */
+export { PluginError, PluginFatalError } from './errors.js';
+export { BasePlugin } from './plugin-base.js';
+export * from './plugins.js';
+//# sourceMappingURL=index.js.map

package/dist/src/plugins/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/plugins/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,cAAc,cAAc,CAAA"}

package/dist/src/plugins/plugin-base.d.ts

@@ -0,0 +1,19 @@
+import type { VerifiedFetchPlugin, PluginContext, PluginOptions } from './types.js';
+import type { Logger } from '@libp2p/interface';
+/**
+ * Base class for verified-fetch plugins. This class provides a basic implementation of the `FetchHandlerPlugin`
+ * interface.
+ *
+ * Subclasses should implement the `canHandle` and `handle` methods, and may override the `codes` and `log` properties.
+ *
+ * If your plugin adds/edits the context supplied in `handle`, you should increment the `context.modified` property.
+ */
+export declare class BasePlugin implements VerifiedFetchPlugin {
+    readonly codes: number[];
+    readonly log: Logger;
+    readonly pluginOptions: PluginOptions;
+    constructor(options: PluginOptions);
+    canHandle(context: PluginContext): boolean;
+    handle(context: PluginContext): Promise<Response | null>;
+}
+//# sourceMappingURL=plugin-base.d.ts.map

package/dist/src/plugins/plugin-base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-base.d.ts","sourceRoot":"","sources":["../../../src/plugins/plugin-base.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AACnF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAE/C;;;;;;;GAOG;AACH,qBAAa,UAAW,YAAW,mBAAmB;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,CAAK;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAA;gBACxB,OAAO,EAAE,aAAa;IAOnC,SAAS,CAAE,OAAO,EAAE,aAAa,GAAG,OAAO;IAIrC,MAAM,CAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;CAGhE"}

package/dist/src/plugins/plugin-base.js

@@ -0,0 +1,26 @@
+/**
+ * Base class for verified-fetch plugins. This class provides a basic implementation of the `FetchHandlerPlugin`
+ * interface.
+ *
+ * Subclasses should implement the `canHandle` and `handle` methods, and may override the `codes` and `log` properties.
+ *
+ * If your plugin adds/edits the context supplied in `handle`, you should increment the `context.modified` property.
+ */
+export class BasePlugin {
+    codes = [];
+    log;
+    pluginOptions;
+    constructor(options) {
+        // convert a CamelCase string to a kebab-case string for the logger name of subclasses
+        const loggerName = this.constructor.name.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+        this.log = options.logger.forComponent(loggerName);
+        this.pluginOptions = options;
+    }
+    canHandle(context) {
+        throw new Error('Not implemented');
+    }
+    async handle(context) {
+        throw new Error('Not implemented');
+    }
+}
+//# sourceMappingURL=plugin-base.js.map

package/dist/src/plugins/plugin-base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-base.js","sourceRoot":"","sources":["../../../src/plugins/plugin-base.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,MAAM,OAAO,UAAU;IACZ,KAAK,GAAa,EAAE,CAAA;IACpB,GAAG,CAAQ;IACX,aAAa,CAAe;IACrC,YAAa,OAAsB;QACjC,sFAAsF;QACtF,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC,CAAC,WAAW,EAAE,CAAA;QAC7F,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,UAAU,CAAC,CAAA;QAClD,IAAI,CAAC,aAAa,GAAG,OAAO,CAAA;IAC9B,CAAC;IAED,SAAS,CAAE,OAAsB;QAC/B,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAA;IACpC,CAAC;IAED,KAAK,CAAC,MAAM,CAAE,OAAsB;QAClC,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAA;IACpC,CAAC;CACF"}

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

@@ -0,0 +1,11 @@
+import { BasePlugin } from './plugin-base.js';
+import type { PluginContext } from './types.js';
+/**
+ * Accepts a `CID` and returns a `Response` with a body stream that is a CAR
+ * of the `DAG` referenced by the `CID`.
+ */
+export declare class CarPlugin extends BasePlugin {
+    canHandle(context: PluginContext): boolean;
+    handle(context: PluginContext): Promise<Response>;
+}
+//# sourceMappingURL=plugin-handle-car.d.ts.map

package/dist/src/plugins/plugin-handle-car.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-handle-car.d.ts","sourceRoot":"","sources":["../../../src/plugins/plugin-handle-car.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C;;;GAGG;AACH,qBAAa,SAAU,SAAQ,UAAU;IACvC,SAAS,CAAE,OAAO,EAAE,aAAa,GAAG,OAAO;IAKrC,MAAM,CAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,CAAC;CAezD"}