feat: add dag-cbor HTML preview plugin (#256)

* feat: add dag-cbor HTML preview plugin

* fix: fix nested links and rendering objects

* chore: fix lint and some code cleanup

* fix: etag for cbor html preview is more accurate

* fix: cbor html preview etag hash allows cache busting

* chore: fix lint

* docs: update README with non-default plugins info

* docs: move plugins information to PLUGINS.md

* docs: remove one typescript code example

* docs(chore): remove extra hyphen for example

* chore: update gwc passing/failing tests

Author: SgtPooki

packages/gateway-conformance/src/expected-failing-tests.json

@@ -177,12 +177,8 @@
   "TestNativeDag/HEAD_plain_CBOR_codec_with_an_explicit_DAG-JSON_format_returns_HTTP_200",
   "TestNativeDag/HEAD_plain_CBOR_codec_with_only-if-cached_for_missing_block_returns_HTTP_412_Precondition_Failed/Status_code",
   "TestNativeDag/HEAD_plain_CBOR_codec_with_only-if-cached_for_missing_block_returns_HTTP_412_Precondition_Failed",
-  "TestNativeDag/GET_plain_CBOR_codec_on_%2Fipfs_with_Accept:_text%2Fhtml_returns_HTML_%28dag-index-html%29/Header_Etag",
-  "TestNativeDag/GET_plain_CBOR_codec_on_%2Fipfs_with_Accept:_text%2Fhtml_returns_HTML_%28dag-index-html%29/Header_Content-Type",
-  "TestNativeDag/GET_plain_CBOR_codec_on_%2Fipfs_with_Accept:_text%2Fhtml_returns_HTML_%28dag-index-html%29/Body",
+  "TestNativeDag/GET_plain_CBOR_codec_on_%2Fipfs_with_Accept:_text%2Fhtml_returns_HTML_%28dag-index-html%29/Header_Cache-Control",
   "TestNativeDag/GET_plain_CBOR_codec_on_%2Fipfs_with_Accept:_text%2Fhtml_returns_HTML_%28dag-index-html%29",
-  "TestNativeDag/Convert_application%2Fvnd.ipld.dag-cbor_to_text%2Fhtml/Body",
-  "TestNativeDag/Convert_application%2Fvnd.ipld.dag-cbor_to_text%2Fhtml",
   "TestNativeDag",
   "TestGatewayJSONCborAndIPNS/GET_plain_JSON_codec_from_%2Fipns_with_explicit_application%2Fvnd.ipld.dag-json_has_expected_headers/Header_Etag",
   "TestGatewayJSONCborAndIPNS/GET_plain_JSON_codec_from_%2Fipns_with_explicit_application%2Fvnd.ipld.dag-json_has_expected_headers/Header_X-Ipfs-Roots",
@@ -194,11 +190,6 @@
   "TestGatewayJSONCborAndIPNS/GET_plain_JSON_codec_on_%2Fipns_with_Accept:_text%2Fhtml_returns_HTML_%28dag-index-html%29",
   "TestGatewayJSONCborAndIPNS/GET_plain_CBOR_codec_from_%2Fipns_with_explicit_application%2Fvnd.ipld.dag-cbor_has_expected_headers/Header_Etag",
   "TestGatewayJSONCborAndIPNS/GET_plain_CBOR_codec_from_%2Fipns_with_explicit_application%2Fvnd.ipld.dag-cbor_has_expected_headers",
-  "TestGatewayJSONCborAndIPNS/GET_plain_CBOR_codec_on_%2Fipns_with_Accept:_text%2Fhtml_returns_HTML_%28dag-index-html%29/Check_0/Header_Etag",
-  "TestGatewayJSONCborAndIPNS/GET_plain_CBOR_codec_on_%2Fipns_with_Accept:_text%2Fhtml_returns_HTML_%28dag-index-html%29/Check_0/Header_Content-Type",
-  "TestGatewayJSONCborAndIPNS/GET_plain_CBOR_codec_on_%2Fipns_with_Accept:_text%2Fhtml_returns_HTML_%28dag-index-html%29/Check_0/Body",
-  "TestGatewayJSONCborAndIPNS/GET_plain_CBOR_codec_on_%2Fipns_with_Accept:_text%2Fhtml_returns_HTML_%28dag-index-html%29/Check_0",
-  "TestGatewayJSONCborAndIPNS/GET_plain_CBOR_codec_on_%2Fipns_with_Accept:_text%2Fhtml_returns_HTML_%28dag-index-html%29",
   "TestGatewayJSONCborAndIPNS",
   "TestRedirectCanonicalIPNS/GET_for_%2Fipns%2F%7Bb58-multihash-of-ed25519-key%7D_redirects_to_%2Fipns%2F%7Bcidv1-libp2p-key-base36%7D/Status_code",
   "TestRedirectCanonicalIPNS/GET_for_%2Fipns%2F%7Bb58-multihash-of-ed25519-key%7D_redirects_to_%2Fipns%2F%7Bcidv1-libp2p-key-base36%7D/Header_Location",

packages/gateway-conformance/src/expected-passing-tests.json

@@ -159,8 +159,10 @@
   "TestNativeDag/HEAD_plain_CBOR_codec_with_no_explicit_format_returns_HTTP_200/Status_code",
   "TestNativeDag/HEAD_plain_CBOR_codec_with_an_explicit_DAG-JSON_format_returns_HTTP_200/Status_code",
   "TestNativeDag/HEAD_plain_CBOR_codec_with_an_explicit_DAG-JSON_format_returns_HTTP_200/Header_Content-Type",
+  "TestNativeDag/GET_plain_CBOR_codec_on_%2Fipfs_with_Accept:_text%2Fhtml_returns_HTML_%28dag-index-html%29/Header_Etag",
+  "TestNativeDag/GET_plain_CBOR_codec_on_%2Fipfs_with_Accept:_text%2Fhtml_returns_HTML_%28dag-index-html%29/Header_Content-Type",
   "TestNativeDag/GET_plain_CBOR_codec_on_%2Fipfs_with_Accept:_text%2Fhtml_returns_HTML_%28dag-index-html%29/Header_Content-Disposition",
-  "TestNativeDag/GET_plain_CBOR_codec_on_%2Fipfs_with_Accept:_text%2Fhtml_returns_HTML_%28dag-index-html%29/Header_Cache-Control",
+  "TestNativeDag/GET_plain_CBOR_codec_on_%2Fipfs_with_Accept:_text%2Fhtml_returns_HTML_%28dag-index-html%29/Body",
   "TestNativeDag/Convert_application%2Fvnd.ipld.dag-cbor_to_application%2Fvnd.ipld.dag-json/Body",
   "TestNativeDag/Convert_application%2Fvnd.ipld.dag-cbor_to_application%2Fvnd.ipld.dag-json",
   "TestNativeDag/Convert_application%2Fvnd.ipld.dag-cbor_to_application%2Fvnd.ipld.dag-json_with_range_request_includes_correct_bytes_-_single_range/Check_0",
@@ -169,6 +171,8 @@
   "TestNativeDag/Convert_application%2Fvnd.ipld.dag-cbor_to_application%2Fvnd.ipld.dag-json_with_range_request_includes_correct_bytes_-_single_range/Check_1",
   "TestNativeDag/Convert_application%2Fvnd.ipld.dag-cbor_to_application%2Fvnd.ipld.dag-json_with_range_request_includes_correct_bytes_-_single_range",
   "TestNativeDag/Convert_application%2Fvnd.ipld.dag-cbor_to_application%2Fvnd.ipld.dag-json_with_range_request_includes_correct_bytes_-_multi_range",
+  "TestNativeDag/Convert_application%2Fvnd.ipld.dag-cbor_to_text%2Fhtml/Body",
+  "TestNativeDag/Convert_application%2Fvnd.ipld.dag-cbor_to_text%2Fhtml",
   "TestGatewayJSONCborAndIPNS/GET_plain_JSON_codec_from_%2Fipns_without_explicit_format_returns_the_same_payload_as_%2Fipfs",
   "TestGatewayJSONCborAndIPNS/GET_plain_JSON_codec_from_%2Fipns_with_explicit_format_returns_the_same_payload_as_%2Fipfs",
   "TestGatewayJSONCborAndIPNS/GET_plain_JSON_codec_from_%2Fipns_with_explicit_application%2Fvnd.ipld.dag-json_has_expected_headers/Header_Content-Type",
@@ -182,10 +186,15 @@
   "TestGatewayJSONCborAndIPNS/GET_plain_CBOR_codec_from_%2Fipns_with_explicit_application%2Fvnd.ipld.dag-cbor_has_expected_headers/Header_Content-Type",
   "TestGatewayJSONCborAndIPNS/GET_plain_CBOR_codec_from_%2Fipns_with_explicit_application%2Fvnd.ipld.dag-cbor_has_expected_headers/Header_X-Ipfs-Path",
   "TestGatewayJSONCborAndIPNS/GET_plain_CBOR_codec_from_%2Fipns_with_explicit_application%2Fvnd.ipld.dag-cbor_has_expected_headers/Header_X-Ipfs-Roots",
+  "TestGatewayJSONCborAndIPNS/GET_plain_CBOR_codec_on_%2Fipns_with_Accept:_text%2Fhtml_returns_HTML_%28dag-index-html%29/Check_0/Header_Etag",
+  "TestGatewayJSONCborAndIPNS/GET_plain_CBOR_codec_on_%2Fipns_with_Accept:_text%2Fhtml_returns_HTML_%28dag-index-html%29/Check_0/Header_Content-Type",
   "TestGatewayJSONCborAndIPNS/GET_plain_CBOR_codec_on_%2Fipns_with_Accept:_text%2Fhtml_returns_HTML_%28dag-index-html%29/Check_0/Header_Content-Disposition",
+  "TestGatewayJSONCborAndIPNS/GET_plain_CBOR_codec_on_%2Fipns_with_Accept:_text%2Fhtml_returns_HTML_%28dag-index-html%29/Check_0/Body",
+  "TestGatewayJSONCborAndIPNS/GET_plain_CBOR_codec_on_%2Fipns_with_Accept:_text%2Fhtml_returns_HTML_%28dag-index-html%29/Check_0",
   "TestGatewayJSONCborAndIPNS/GET_plain_CBOR_codec_on_%2Fipns_with_Accept:_text%2Fhtml_returns_HTML_%28dag-index-html%29/Check_1/Check_0",
   "TestGatewayJSONCborAndIPNS/GET_plain_CBOR_codec_on_%2Fipns_with_Accept:_text%2Fhtml_returns_HTML_%28dag-index-html%29/Check_1/Check_1",
   "TestGatewayJSONCborAndIPNS/GET_plain_CBOR_codec_on_%2Fipns_with_Accept:_text%2Fhtml_returns_HTML_%28dag-index-html%29/Check_1",
+  "TestGatewayJSONCborAndIPNS/GET_plain_CBOR_codec_on_%2Fipns_with_Accept:_text%2Fhtml_returns_HTML_%28dag-index-html%29",
   "TestGatewayIPNSPath/GET_for_%2Fipns%2Fname_with_V1-only_signature_MUST_fail_with_5XX",
   "TestGatewayIPNSPath/GET_for_%2Fipns%2Fname_with_valid_V1+V2_signatures_with_V1-vs-V2_value_mismatch_MUST_fail_with_5XX",
   "TestGatewayIPNSPath/GET_for_%2Fipns%2Fname_with_valid_V2_and_broken_V1_signature_succeeds/Status_code",

packages/gateway-conformance/src/fixtures/basic-server.ts

@@ -2,7 +2,7 @@ import { createServer } from 'node:http'
 import { trustlessGateway } from '@helia/block-brokers'
 import { createHeliaHTTP } from '@helia/http'
 import { httpGatewayRouting } from '@helia/routers'
-import { dirIndexHtmlPluginFactory } from '@helia/verified-fetch/plugins'
+import { dagCborHtmlPreviewPluginFactory, dirIndexHtmlPluginFactory } from '@helia/verified-fetch/plugins'
 import { logger } from '@libp2p/logger'
 import { dns } from '@multiformats/dns'
 import { MemoryBlockstore } from 'blockstore-core'
@@ -196,7 +196,7 @@ export async function startVerifiedFetchGateway ({ kuboGateway, serverPort, IPFS
   const helia = await createHelia({ gateways: [kuboGateway], dnsResolvers: [localDnsResolver], blockstore, datastore })
 
   const verifiedFetch = await createVerifiedFetch(helia, {
-    plugins: [dirIndexHtmlPluginFactory]
+    plugins: [dirIndexHtmlPluginFactory, dagCborHtmlPreviewPluginFactory]
   })
 
   const server = createServer((req, res) => {
@@ -220,7 +220,8 @@ export async function startVerifiedFetchGateway ({ kuboGateway, serverPort, IPFS
   })
 
   server.listen(serverPort, () => {
-    log(`Basic server listening on port ${serverPort}`)
+    // eslint-disable-next-line no-console
+    console.log(`Basic server listening on port ${serverPort}`)
   })
 
   return async () => {

packages/verified-fetch/README.md

@@ -664,6 +664,8 @@ Verified‑fetch can now be extended to alter how it handles requests by using p
 Plugins are classes that extend the `BasePlugin` class and implement the `VerifiedFetchPlugin`
 interface. They are instantiated with `PluginOptions` when the `VerifiedFetch` class is created.
 
+### Plugin Interface
+
 Each plugin must implement two methods:
 
 - **`canHandle(context: PluginContext): boolean`**
@@ -678,6 +680,8 @@ Each plugin must implement two methods:
   - **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.
 
+### Plugin Pipeline
+
 Plugins are executed in a chain (a **plugin pipeline**):
 
 1. **Initialization:**
@@ -724,6 +728,29 @@ Please see the original discussion on extensibility in [Issue #167](https://gith
 
 ***
 
+### Non-default plugins provided by this library
+
+#### `dir-index-html-plugin`
+
+This plugin is used to serve dag-pb/unixfs without an `index.html` child as HTML directory listing of the content requested.
+
+#### `dag-cbor-html-preview-plugin`
+
+This plugin is used to serve the requested dag-cbor object as HTML when the Accept header includes `text/html`.
+
+## Example - Using the plugins
+
+```typescript
+import { createVerifiedFetch } from '@helia/verified-fetch'
+import { dagCborHtmlPreviewPluginFactory, dirIndexHtmlPluginFactory } from '@helia/verified-fetch/plugins'
+import { createHelia } from 'helia'
+
+const helia = await createHelia()
+const fetch = await createVerifiedFetch(helia, {
+  plugins: [dagCborHtmlPreviewPluginFactory, dirIndexHtmlPluginFactory, ]
+})
+```
+
 ### Extending Verified‑Fetch with Custom Plugins
 
 To add your own plugin:

packages/verified-fetch/src/index.ts

@@ -633,6 +633,8 @@
  * Plugins are classes that extend the `BasePlugin` class and implement the `VerifiedFetchPlugin`
  * interface. They are instantiated with `PluginOptions` when the `VerifiedFetch` class is created.
  *
+ * ### Plugin Interface
+ *
  * Each plugin must implement two methods:
  *
  * - **`canHandle(context: PluginContext): boolean`**
@@ -647,6 +649,8 @@
  *    - **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.
  *
+ * ### Plugin Pipeline
+ *
  * Plugins are executed in a chain (a **plugin pipeline**):
  *
  * 1. **Initialization:**
@@ -692,6 +696,29 @@
  *
  * ---
  *
+ * ### Non-default plugins provided by this library
+ *
+ * #### `dir-index-html-plugin`
+ *
+ * This plugin is used to serve dag-pb/unixfs without an `index.html` child as HTML directory listing of the content requested.
+ *
+ * #### `dag-cbor-html-preview-plugin`
+ *
+ * This plugin is used to serve the requested dag-cbor object as HTML when the Accept header includes `text/html`.
+ *
+ * @example Using the plugins
+ *
+ * ```typescript
+ * import { createVerifiedFetch } from '@helia/verified-fetch'
+ * import { dagCborHtmlPreviewPluginFactory, dirIndexHtmlPluginFactory } from '@helia/verified-fetch/plugins'
+ * import { createHelia } from 'helia'
+ *
+ * const helia = await createHelia()
+ * const fetch = await createVerifiedFetch(helia, {
+ *   plugins: [dagCborHtmlPreviewPluginFactory, dirIndexHtmlPluginFactory, ]
+ * })
+ * ```
+ *
  * ### Extending Verified‑Fetch with Custom Plugins
  *
  * To add your own plugin: