From 7c9769dcdc5eb3a38ef24023b289037d52d7bde8 Mon Sep 17 00:00:00 2001 From: "aegir[bot]" Date: Wed, 12 Feb 2025 17:21:08 +0000 Subject: [PATCH] docs: update documentation [skip ci] --- assets/highlight.css | 60 +- assets/navigation.js | 2 +- assets/search.js | 2 +- classes/_helia_verified_fetch.BasePlugin.html | 11 + ...lia_verified_fetch.DirIndexHtmlPlugin.html | 11 + .../_helia_verified_fetch.PluginError.html | 17 + ...helia_verified_fetch.PluginFatalError.html | 21 + classes/index.BasePlugin.html | 11 - classes/index.DirIndexHtmlPlugin.html | 11 - classes/index.PluginError.html | 17 - classes/index.PluginFatalError.html | 21 - ...ia_verified_fetch.createVerifiedFetch.html | 2 + ...ified_fetch.dirIndexHtmlPluginFactory.html | 1 + ...helia_verified_fetch.verifiedFetch-1.html} | 6 +- functions/index.createVerifiedFetch.html | 2 - .../index.dirIndexHtmlPluginFactory.html | 1 - hierarchy.html | 2 +- index.html | 372 +-------- .../_helia_verified_fetch.CIDDetail.html | 3 + .../_helia_verified_fetch.CIDDetailError.html | 4 + ...lia_verified_fetch.ContentTypeParser.html} | 4 +- ...rified_fetch.CreateVerifiedFetchInit.html} | 30 +- ...ied_fetch.CreateVerifiedFetchOptions.html} | 24 +- .../_helia_verified_fetch.PluginContext.html | 23 + .../_helia_verified_fetch.PluginOptions.html | 11 + .../_helia_verified_fetch.ResourceDetail.html | 2 + ... _helia_verified_fetch.VerifiedFetch.html} | 6 +- ...lia_verified_fetch.VerifiedFetchInit.html} | 52 +- ...fied_fetch.VerifiedFetchPluginFactory.html | 1 + interfaces/index.CIDDetail.html | 3 - interfaces/index.CIDDetailError.html | 4 - interfaces/index.PluginContext.html | 23 - interfaces/index.PluginOptions.html | 11 - interfaces/index.ResourceDetail.html | 2 - .../index.VerifiedFetchPluginFactory.html | 1 - modules/_helia_verified_fetch.html | 744 ++++++++++++++++++ ...ia_verified_fetch_gateway_conformance.html | 32 + modules/index.html | 360 --------- modules/plugins_plugins.html | 3 - ..._verified_fetch.BubbledProgressEvents.html | 1 + ...ml => _helia_verified_fetch.Resource.html} | 4 +- ...ied_fetch.VerifiedFetchProgressEvents.html | 1 + types/index.BubbledProgressEvents.html | 1 - types/index.VerifiedFetchProgressEvents.html | 1 - 44 files changed, 990 insertions(+), 931 deletions(-) create mode 100644 classes/_helia_verified_fetch.BasePlugin.html create mode 100644 classes/_helia_verified_fetch.DirIndexHtmlPlugin.html create mode 100644 classes/_helia_verified_fetch.PluginError.html create mode 100644 classes/_helia_verified_fetch.PluginFatalError.html delete mode 100644 classes/index.BasePlugin.html delete mode 100644 classes/index.DirIndexHtmlPlugin.html delete mode 100644 classes/index.PluginError.html delete mode 100644 classes/index.PluginFatalError.html create mode 100644 functions/_helia_verified_fetch.createVerifiedFetch.html create mode 100644 functions/_helia_verified_fetch.dirIndexHtmlPluginFactory.html rename functions/{index.verifiedFetch-1.html => _helia_verified_fetch.verifiedFetch-1.html} (52%) delete mode 100644 functions/index.createVerifiedFetch.html delete mode 100644 functions/index.dirIndexHtmlPluginFactory.html create mode 100644 interfaces/_helia_verified_fetch.CIDDetail.html create mode 100644 interfaces/_helia_verified_fetch.CIDDetailError.html rename interfaces/{index.ContentTypeParser.html => _helia_verified_fetch.ContentTypeParser.html} (72%) rename interfaces/{index.CreateVerifiedFetchInit.html => _helia_verified_fetch.CreateVerifiedFetchInit.html} (54%) rename interfaces/{index.CreateVerifiedFetchOptions.html => _helia_verified_fetch.CreateVerifiedFetchOptions.html} (56%) create mode 100644 interfaces/_helia_verified_fetch.PluginContext.html create mode 100644 interfaces/_helia_verified_fetch.PluginOptions.html create mode 100644 interfaces/_helia_verified_fetch.ResourceDetail.html rename interfaces/{index.VerifiedFetch.html => _helia_verified_fetch.VerifiedFetch.html} (50%) rename interfaces/{index.VerifiedFetchInit.html => _helia_verified_fetch.VerifiedFetchInit.html} (62%) create mode 100644 interfaces/_helia_verified_fetch.VerifiedFetchPluginFactory.html delete mode 100644 interfaces/index.CIDDetail.html delete mode 100644 interfaces/index.CIDDetailError.html delete mode 100644 interfaces/index.PluginContext.html delete mode 100644 interfaces/index.PluginOptions.html delete mode 100644 interfaces/index.ResourceDetail.html delete mode 100644 interfaces/index.VerifiedFetchPluginFactory.html create mode 100644 modules/_helia_verified_fetch.html create mode 100644 modules/_helia_verified_fetch_gateway_conformance.html delete mode 100644 modules/index.html delete mode 100644 modules/plugins_plugins.html create mode 100644 types/_helia_verified_fetch.BubbledProgressEvents.html rename types/{index.Resource.html => _helia_verified_fetch.Resource.html} (52%) create mode 100644 types/_helia_verified_fetch.VerifiedFetchProgressEvents.html delete mode 100644 types/index.BubbledProgressEvents.html delete mode 100644 types/index.VerifiedFetchProgressEvents.html diff --git a/assets/highlight.css b/assets/highlight.css index 59bc22b8..a3cd9949 100644 --- a/assets/highlight.css +++ b/assets/highlight.css @@ -1,34 +1,34 @@ :root { - --light-hl-0: #AF00DB; - --dark-hl-0: #C586C0; - --light-hl-1: #000000; - --dark-hl-1: #D4D4D4; - --light-hl-2: #001080; - --dark-hl-2: #9CDCFE; - --light-hl-3: #A31515; - --dark-hl-3: #CE9178; - --light-hl-4: #0000FF; - --dark-hl-4: #569CD6; - --light-hl-5: #0070C1; - --dark-hl-5: #4FC1FF; - --light-hl-6: #795E26; - --dark-hl-6: #DCDCAA; - --light-hl-7: #008000; - --dark-hl-7: #6A9955; - --light-hl-8: #267F99; - --dark-hl-8: #4EC9B0; - --light-hl-9: #098658; - --dark-hl-9: #B5CEA8; - --light-hl-10: #800000; - --dark-hl-10: #808080; - --light-hl-11: #800000; - --dark-hl-11: #569CD6; - --light-hl-12: #000000FF; - --dark-hl-12: #D4D4D4; - --light-hl-13: #E50000; - --dark-hl-13: #9CDCFE; - --light-hl-14: #0000FF; - --dark-hl-14: #CE9178; + --light-hl-0: #000000; + --dark-hl-0: #D4D4D4; + --light-hl-1: #800000; + --dark-hl-1: #808080; + --light-hl-2: #800000; + --dark-hl-2: #569CD6; + --light-hl-3: #000000FF; + --dark-hl-3: #D4D4D4; + --light-hl-4: #E50000; + --dark-hl-4: #9CDCFE; + --light-hl-5: #0000FF; + --dark-hl-5: #CE9178; + --light-hl-6: #AF00DB; + --dark-hl-6: #C586C0; + --light-hl-7: #001080; + --dark-hl-7: #9CDCFE; + --light-hl-8: #A31515; + --dark-hl-8: #CE9178; + --light-hl-9: #0000FF; + --dark-hl-9: #569CD6; + --light-hl-10: #0070C1; + --dark-hl-10: #4FC1FF; + --light-hl-11: #795E26; + --dark-hl-11: #DCDCAA; + --light-hl-12: #008000; + --dark-hl-12: #6A9955; + --light-hl-13: #267F99; + --dark-hl-13: #4EC9B0; + --light-hl-14: #098658; + --dark-hl-14: #B5CEA8; --light-code-background: #FFFFFF; --dark-code-background: #1E1E1E; } diff --git a/assets/navigation.js b/assets/navigation.js index 87dccf10..be1a0b9a 100644 --- a/assets/navigation.js +++ b/assets/navigation.js @@ -1 +1 @@ -window.navigationData = "data:application/octet-stream;base64,H4sIAAAAAAAAA5WVwW7CMAyG3yW7srEyYKNHBmichqZpF4SmkBqIFtIqcRFo4t2nQWmbtrjlFKn5/f1O7NTzX4awR+YzqQPYsxaLOG6Yz7ZhECuw7dPnhw1uFWuxH6kD5ndaTGykCgxo5s9TwJBbmKl4LXVGEYpbm1IyhQv0Oi/HVsoZSTP9l7/hVtG8spLinhVjY0JzDZiT1JMmHLlqgMt0FPN1OhoBcqkymNQIZsVFyks1hXr0+lWgQmrXaRW5FZChRtD4eYhgxo0FklrUkmADHOELjFxJCCaAYjPVEil8dcSNJu8RylDb23ySIMrqXPDTFeypUzi6emB9uo6OAn6ADWMjoLbXXCGFdC6JIDq6xsCafripExzx5XEKDM2hqYMTRFkN4+VSQTAz4dqAteMdaMwVEA9R9leskhbYj4Nnr9epqGM18rJbR3HP1iBXIqDOS5RfVOaxirU49W7iUyF2+f1uDh2U5kCprEWDqyGEza5Z7o7s3isBFzlkdLK27WQtj99k4ztZGw1iaoBS3LvKwLNV1xt0nx5vvHTSjIp3PRfHxR98cCfMpwgAAA==" \ No newline at end of file +window.navigationData = "data:application/octet-stream;base64,H4sIAAAAAAAAA6WVXU/CMBRA/0ufQYUIKk8GgciTxBhfiFlKd8caS0vaO4QY/7vhy6376FYMj/Scszvu2PybIGyRDMhjDIJT0iIs5iLUIMlg/vflBjSPOITtCJDF7SVF+KK7NlMyUnpFJQPSImuKMRmQlQoTAeY6OAiDMxoc0OCEBhn0KsaVIC3yyWVIBt2fVkW2YSKnKx9oSA3MRLLkMrUyQY2ptKaEHeh07zNXPOJ6KkPYPuNK+PmLpKtzPDHWWummgQxSb55QpOICfcq5Gk/T0QiQcpHKuUTQEWWV/j8m9/v2+mXi3KU3t5dcey6hJILEt90aZlQb8KrkWWdIA0V4Pxkme8FUcvTJlRs8oy9r5Eqa/3VPElf6uECHW7T1mdLi6gP+41icK/AKRiWagfdu26ArYd1Uj4LFNQ547pvXplmHz38eDJXeXVq0JK70MFksBIQzrZYajBlvQGJmIXC3rn4LlKG51s3DXafXLdmLZonz6TqrPfsFszgEdW1WfMLTZpRIdnhWKrolsN3r32ZSYeG9WFiTumClwpHdXDabhbU7hcDH/vMLx2MMCHUJAAA=" \ No newline at end of file diff --git a/assets/search.js b/assets/search.js index 9f87ceac..4b27b743 100644 --- a/assets/search.js +++ b/assets/search.js @@ -1 +1 @@ -window.searchData = "data:application/octet-stream;base64,H4sIAAAAAAAAA7VcW4+byBL+L/iVzLpvXOYxmUQbaaUTnY32xRqtiN0zRmuDA0yyOaP896OGxlRBFwbjPI0yU5ev66uqvtCdV6/Iv5fe/ebV+yfNdt49970sOWrv3kuznf7X872X4uDde8d893LQ5W/1b+/21fHg+d72kJSlLr17z/vptxYCeTaxLXRS6b90kT6levdBV9v92eDTS7at0jxrTTpkHW5875QUOqvO+Dq/fB2HTHX4/6vL/KXY6rPH6sfpPID2jzNdqGBg/kFXSXo4O0mzShdPyXbgqZGb54+teRfMoj+eKa5WQGvEZ0+VGPK7jw+XRnsWWTDQbbqb6mDVyI6NrANNuDsl1X6yPys816Eziu+LIi8meK7lFsRTz/azalUmjbMZxyIyges+o1W5e5OWb9Jsr4u00rtrgUykGSAZcL0ACkwAdz8cQFrUCmV0dldWSVHNcbNqNcbYx4MgXeenmZ5rhascwxIbziUfs3QkCITCgqJ7Tir9PflRXudzBdRHa5AYKDWF5C+VLq7F1GnfENIuK83cc/h2Pa6eiRuC2yfl/npcnfYNISWHQ/79j3ybjE3CY6iQgVsD+5iVevtSjKxRLmMDNm4I75B+OfHTuzx7Sp+vRNczsQzchXb1n1O9Np6F1OosWXnlWaWz6vOPk/6UFKUeWzWM+1+5TM2MWBsDAmypyzLNs3fJdq//TP83L+cQVoelXwL18+c/jtdTuupZuS3E72m1/1MX33TxOT2m2bwaQTAdlm4L9XR4eU4X1MaqM7AYWH/T+fbly5eD3n0q8udCl+X7bzqrSucO1Cm5bMeLsE6AMCJ//b54xqrrlustWxxzna06vcmLzqXT89KJ+dZT8g0m48mQprcZAtXM7jI6Bfc7ym/9ztIeetnf/21/jh5/oYl9xnzaF51XC+DQ7duk4zYk9YbdbH85xc+kDSYexpQN5kTXF3eYlGfGO8ef6kzAJzjWpvUOJOYFVzEOF2RlVbxsq8luVlhlbJxwDES51j8mOrayCz1u891kj1Z2ocenpALd+oLLVnihz119SFRO9dqJL/Rb6PKUZ+XkCAP5KzwP6uWDid7lounEfn3l9HzNLh8wpGtrqA9hciFd9n2xmobD75XU5TPPqVgu11kfzLDYbodmSgX28bjK8HaIJtVmH5KzQJdhAlX7Nil1I0qA6gR+ZaX2vMyoUTCAkQqhsmDot5Fd5vGQP0/010gu89YsWfvHSeN++zqzEaA12jbJfk+y3YFK7EGUgfwyz/s5bvfX+wQr/k/OcA9W+0hswa73kD8/j+0qhn5WZ5XL84vruAOE91lXbw/59p+yyse2lw4Mfc3FUBrypm0sHXic6teAuvY01YFp7gHqJEh7fUiTeaGxGldRNCiMepf778iREBL7VXcIhk4m3CPAA7jqI7PD74T7BJMcX74c4nA+8W7IJADJdqtPs4hdnVUWOz/mu3rHPss9UFoMYPqxlgPIzCMtChBqiHnWnufOgoLUFkclnzYNYgSTVh2T3KflQ1pos0r8MQsC1lsMY9cae59VRarnhcOhvBhQfblnHoyzyg0a1dcPeXFM5rUKqHWTJv3Q2/5N7dUPM05iLsD4+qJnJmarcVV3oD7RtFvBC3VC68ycpcH28iEtPpo//14dD6PbzKHgr9xuEt7Ibefl7bZjoFdsR2lcl7elowhmbddIFBO3bdORjG7fKBiTtnHT+aA36xSA/qb9ltkxZTNP4aI39QsRBmiq68n1+0r/Gw2pMa/AJYulWMspnWXsm97KqeeG0P9mSIO5HJVRTGPqE6E9+jZi96/m82D9wfve43fiLvZ87ynVh515A9AeVW/z49FYerR/+6teghiJRuS3tedv1r5kdzKSj4/+ptWo/1D/ohZjnr9hLjGGxLjnb7gvxN2aMSTGkZjw/I1wWRNITFLWJBJTnr+RLmsKiQWev1EuawESCz1/E7jEQiQWef4mdDmNkFjs+ZvIJRbj8K4pcKzHA6PgMcwEMxGPfRHciTDAgpgLZmLO1k5JTAczYWfMKYkZYSbyjDvzBZPCTPCZMxcY5oWZ+DMnzwxTwwwFTDklMTvMsMACpyQmiBsaWOgaO8cM8bpUIqdkr1gMESx2eeeYI26I4M4y5ZgjXtcMc5Yg5ogbIriTI4454oYI7uSIY464IYJLp3fMETdEcCdHHHPEDRHcyRHHHAlDBHcWpcAcCUMEd9alwByJuqM5ORK9nibIDBGYIyHJDBGYI6HIeArMkTBECGeGCMyRCMkMEZgjEVEtRGCKREy2EIEpkmuyhUhMkTQ8COeUIzFF0vAguC/WdzKOsCSmSNbzjnB67808hgchnZKYIml4EMopiSmSNUWBUxJTJA0PwplKElMkDRHCmcgScyRjOkqYI7Umo6QwR4qRUVKYI8XJKCnMkRJklBTmSEkySqq3QKg5chaxwhypgIySwhwpQ4R05rzCHClDhHTmvMIcKUOEdK54FOYoMERIJ0cB5igwREgnRwHmKOCk9wBzFBgipLN5B5ijwBAhnc07wBwF9SrO2byD3jouIBtYgDkKao6c1RFgjoKaI2eGBJijICaXkZiicE0uJDFDIaOWuSEmKDQsKGePDzFBoWFBOZtniAkKJTnDhJig0LCgnOuFEBMU1itt53oh7K21DQvKuaYLMUGhYUE5Uy7EBIU1Qc6UCzFDUb3odi/iMUWRIUI5EynCHEU1R85EijBHkSEicLIZYY4iQ0TgbCAR5ihSZPuKMEdRQLavCHMUhWSriXpboohsNRHmKIrJlhhhjuI12ZRizFFc74y4y2aMOYo5Gc8YcxQL2mbDUb0d/6aLSu8+Ntvyzeb8Ae3V+9vu1dW6PUJ49ULu3b/+/Nntzc2/jOn6lnZ6vqXdabOo0+bMyPuekGNWDs3dc2AiBCbW1oQgTHxJSn2yRyadCRF3JpSiVJunECf76UnbFwudFR4AIDFhZZtk7eFfpylFpxnYIUQhZcF8BAbxB6qNJrMWAhJDutvZF/IAAwjBJT378LpTBhRElHJ9Zw/EHDiUskGs2IgyirUEWadCG7GA1AZH4gABBwh4Y0PGFomNZUTGorn4YB6qnOzFB5AJDGSCHZuwKAMSZf2Sp73W/dTciwdp3pkkozS0kNZPW4AVMGZGjm1o5/zBEwwSUMCpejtfRgRhB2UibZgVqd9+WdTtl0WQ+SD1QyrtdmlRi5tDymHhByCqkSUqpprY0NRTe8QJLIIAx7ahxeTosrLo3gQDlsDIGDWyQRGCVkpVfvuFFAQRsBFSavaKK+AQAJTKckjFrXslDkYIOh6jKuJZV1/ABSxQ/QB0QM0WjjYLWk5guYmo8DbqZX3jobI3HoAp0PECqo7OT6vBuAFyRoXb3mYC3gC1ATUvNLJAC9TnmtIpd90lApAUIFAh5a95aLy1D43BEMFkyqmcqL8/gQGCOlSRZYYKT3s3EKjDSZAqtu4mDRgo8BtSirUATH6Qu1LY5KcinGen810V4Bd0iZBKH0fPVcB1SJVNc1sLtCSgY1cINvlDCrUx4WjdCuRhRM1CTWvctnfoAEsgMQKq7BrtQW8TgCg57rluVkMDALocd+6IuwR8KbtECOySISaD2L7TA3MmSFQ+jgK88wOjADUtKP7tBQxAGwh8RFVkob8+2csrQBMu7Khxdhf0wEDBOO3KyqYcRV5rZbgyBTlPlWj3wACoAezSJr6iJovz/xoC+hhogoxqgueHuWDoINqCirbV25rH/GX9mB8YgMGjmoM1UFWHI84wEC1OZYh92QjGCvKK2ZYmqP7bPE4EynBpammWVLKQ61sQNWZTRlAVMrrE5aDSBZVtyAK9mANhiajcw6bo3SFIR0FFx1yypJYcHOQjt/ks7NordOb1o++d0pM+pJn27jePP3/+H9J747RITwAA"; \ No newline at end of file +window.searchData = "data:application/octet-stream;base64,H4sIAAAAAAAAA82cUW+cuBbHvwt5JenY2MDkadWm1VZa6Vbdal9GUUQHJ0E7A1Mg6fZG/e5XBjOcw/hMBvDc7lO6G5/D3+d3fGyMnRevLL5X3vXqxfs7y1PvmvtenmyVd+399qg2WfLmWZXZfabSy3tVrx8vH5JafU9+XK6L/L4ot0m+Vp7vPZUb79rbFunTRlVv7hrLu87yrrG8M5Z3wPLqsd5uPN9bb5KqUpV37Xk//ROVnPbUo09gPN4/421SqU+bp4cs3zs2NoTj3sDyDN/bJaXKa1J8L0KyvqPrIq/q8mldF+U0FRfYwwhFwBOM0IILoC5V1WRdra1bRZviYaKe1tKtml3z2//s6qzIp8Zp6GO2Qr4QfZKvk/z3JE83aipFYO9W2eMcWY/ONMGKcJOVH/NU/fN7vd2MqgyHhr+yQhBqyEpRV+llVl1m+aMqs1qlr0fSEigHFYTWPb6SnK7w9IpC6RtWlnPGc0rFoXTTlcdxD2ZVJDIrJlam05WOqlCUzEmV6ng+gIrV/vJ9WZ5cHIDFr6xRQxkzljEwBkeq0HRh6Vh8JyhKVZ1km1NH8IGo3tyxrvukTjZTVXXGjjU1PyZKMraOFZWq2hV5NVkVsHeg7KAefNAcxheF3uzXV4aBltnlAYTEVY04lDgoFONn0VO1TqkeQ7m2EnI+xePrylDvYXE5n9rRFWcodnLZeV3bpNoz1GctQE7jyWW4l/zu481Nk217zVleq/I+WZOy9ybzShEe4Vk6VcBFazuGZ99paimf1I+T9RjjuYKslPDMcboyB1OHA16wIg+gjU/wQUwIoWp2wC46F5OAHhU3Mc2AtoNccxhHlIBFXqu8/vJjpz4lZaXGhHRoOi8NkapSJbX6yzT9oFt+zLN6hDa7A4cDJdlsiu8f80qtn0rlRtjF0OeoxCRCdkz+H8U6GTM/vKq9c3hG4WlefVZVsXlWZeVI+sDlGcWbjzOuhAN3ZxT9mFSP7oLdezuj5E32dcd374r8PntwpHvg8oziy+Kpdhfv3ptbya+U6+Fu6ZROGB8uVzczZrvj+i5srmdGvIvh0W1pdyG+6B2eV3ilqior8nfJ+lH9mf133uyJemDx/H/pypcvf2wdghh4PW8Xvmf145+qfFbll2yb5fPqJeqGxbPzrsAy1L4ZN8vSf0asFZGZyxXieq12s3Rc7F2M39TowuDiPc+ibPy7+Umy0qxUer/xx/u8LjM1YkxZNFqcORfcvEPOk7l34VxcVt10IZilEPtxLnNbpI3NLI3AiXOBxdjFjEVfMemwyUnyxu02WLRN2Ng6WdjNYNt8qr6bGV/fXpH57UnNHCCdB+fSSvXtgz7FN28agV7OILEqnsr1iFWcVeHeiXOB0xc4FqEz1zSUYHQGosg/lcVDqaqZFQe6cSLyYK01+i0Pmf07XuwOJc1+l8PBobZVtOUsmZ0H59I2xcPDzBDuXbgQh0bHg6rfbor131VdjNl4tWgcenIutT2HNKf2YN42d05Eg4H92VTisR8PsZ3DoT1+frFImTrBDKJhDxl6RT1dJjKb+e0EZl1VJ+WI9cKhjIvOw5hI4SCQ0ordTGWNAyfCKILjvjT9C78xneHr0lm/K7n+onSyWLPPNltp7+csMqcvYAm9Mxexp34WQO26YysjdyNoH3Mr5jJisj8z9/bp69eNSrsV8/tnldf9urb+saOvSdgs3Yr7PJwCj+npGruVgDmMj9IR+3lCQ/AScLhhvNd2/5Svm2UPoc9i60xXenCyfDgMXlNHenCm8XlS1JDVJTvbImaKjkmrGByGU1YxE6WNXsYMlN36XqYzwrt+0eya6efa41fB1dLzvftMbVJ937Q7Vbkutlvt/db87q9mN1e3aJu8WXj+auGz8CoSS591/+A+W14xJv3A/OP21l91zhqb5n80HljjgYdXgc+aH6gtQ22556+EL9jVMo5QM46aBZ6/kn6wuIoZahWgVsLzV6EfhFfRErUSqJX0/FVkaSVRq9DzV7EfBFdBiIWFqFnk+aulxVmEWsWev2ILS7MYNVvqZswWjSUO8IIIBxuAYERAGIbAOBEShimwgAoKwyCYIMLCMAomqcAwTIPpqDNuCw3DQFhExQYjYQ2TwPZoDIU1VIStIabCdfD1CDloyDEWrqPPbFz4YHDo8DMbGI7BcB1+FlvHESbDBREejslwSYWHYzI8pMLDMRgekeHBZHhMhgeT4UsyPJhM0JBZ2sITYDSBBsAXthQPMJtAE+DM2nJQuzQBbs3dAMMJBP10jCfQEHhg9Yn5BCGtEwMKNAYurC0xoUBz4NL6dIwo0CC4jWWAEQnNgdtYCkxINISsqS4wIdEQslIXmJDQGIKFteVghtEYAmuJFpiQ0BgCK3WBCQmNIbCyFJiQoAkJTEhoDIF1YhWYkNAcAitLgRFJDSIIbS0lZiQ1iCCy6ZSYkdQgAitNiRnJhpGVpsSMJD2K5GAloEEIK3eJGUkNQli5S8xIahDCyl1iRlKDEFbuEjOSGoSw0pSYUbggR3uIGYUahLByDzGjsFmjWbmHmFGoQYjI2hIzCjUIYV9fYUahJHMpHKzYGkbWDAkxozAiF3cYURiTAy7EiELNQVpTKcSIombxZk2lCCOKNAdpTaUII4o0B2lNpQgjipqVtDWVIowoohFFGFGkOUjbzB5hQpHGIG2zQTRYVTeLONtsEGFAkaYgrfUjwoAiciaKMJ+YnIlijCdu8FjzLcZ4Yk7mcIzxxJpBaE2jGOOJm5cdaxrFGE8sSZAx5hNrCqE14WIMKNYYQmvCxYNXH40htCZcjAnFSyqNYkxouaDSaIkJLRmVRssWUPPu/KzKWqUf23fo1Wp/Wu/FuzMv1sGye+N/8WTgXb/8/Nm/SOv/0q6bTepsv6neW/Owtw6Wur3vRctjXjbtVjdwEfUuxKJ1ES8IF1+TSu3M30/pXYjeA6cM2/3LndmTU2ZPr/cRst5JLAgv6yTv/upCbwkCGLXyGWmvzxOCri9A9FhrG4j2pzziIzVfLXtPDIgIqODtLc2VMCCEA3MqCdpbyOCZQW/E4lY1l0eMcbwBdRM1RtqCPw8GMrf3QPYY3u3uLSXorXm2STxmCHIy+u2hCb0JvDOHJkAYQSIGxpMwP8OY8tjsyXYbX+12IYwT6GYcne4ja77vAW2w0yO07E/0gcADSSIkXO0vgYOEAeFhplhw0r47i6m6Y61gvINxI6mMS7Oyaa63Ig9LBgPDnapXhx7uux1twAd0KqbimuZV2d+9AlBiEEkq/Q9HK4h/QHW/O28Loga6LKmwm7vwIFAgb7gZJZzKw4PsZYMx6ntUL80tL9TP1wd4fzcMmIFaKKj54EHVX8GpGFAbwFMjSuzhJMBASppayCg0rXXVfJqszadJIADQjSj5+/tlYFQCBYKq4eYwFXgasAqpgYC36qH54mS+WZX2p6tBUoJwSyqt2ltpa3MrDXQZpJegKnbzN7R6G7DakEYxFeTudBeIFnhgROVkf0YbdBNAlVSVaBrAnAJzJDfLA04ZF/lufw4SPBeMhZAa85YSL0BVk1RatAeqwcAD0Qm4Wc6EZvqjoqWdWOYKAcpOSOVUW5TX3VUYkBigrkoKb2t9UF0ZyEhGhaybDurkcDHFwMM5NRBbB5bIA2MTOmbWKCE1PPY32kAAAD9BpYw5zw2CDhIupMJWqm/35pg1sATDKqT63J9OA4awv2YhGJmfMVVAO0eH62AJ+h0d0WH+RAmABjrATe5yKvH3t01BwEHWCEr3/gQNEAwGaEzlubFb6wt/VXPhDzwYDBRBCTYO6nqzxaoBcEmNUPOFGWgGVpFJ0iVtrT8CA2MQ6MisjZdUx8lVsQS9jkwdj6neH10XS5CAETVSkAd6KQjXAFTyYVf06yjIp5iqQvqEE7WMCOBEZyaPsIuUdWzf+t4u26lNlivvenX78+f/ALnnbb7QWQAA"; \ No newline at end of file diff --git a/classes/_helia_verified_fetch.BasePlugin.html b/classes/_helia_verified_fetch.BasePlugin.html new file mode 100644 index 00000000..38897b98 --- /dev/null +++ b/classes/_helia_verified_fetch.BasePlugin.html @@ -0,0 +1,11 @@ +BasePlugin | Helia Verified Fetch

Class BasePlugin

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.

+

Hierarchy (view full)

Implements

Constructors

constructor +

Properties

codes +log +pluginOptions +

Methods

canHandle +handle +

Constructors

constructor

Properties

Readonly codes

codes: number[] = []

Readonly log

log: Logger

Readonly pluginOptions

pluginOptions: PluginOptions

Methods

canHandle

handle

Settings

Member Visibility

Theme

On This Page

constructorcodeslogpluginOptionscanHandlehandle
\ No newline at end of file diff --git a/classes/_helia_verified_fetch.DirIndexHtmlPlugin.html b/classes/_helia_verified_fetch.DirIndexHtmlPlugin.html new file mode 100644 index 00000000..851ec7ce --- /dev/null +++ b/classes/_helia_verified_fetch.DirIndexHtmlPlugin.html @@ -0,0 +1,11 @@ +DirIndexHtmlPlugin | Helia Verified Fetch

Class DirIndexHtmlPlugin

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.

+

Hierarchy (view full)

Constructors

constructor +

Properties

codes +log +pluginOptions +

Methods

canHandle +handle +

Constructors

constructor

Properties

Readonly codes

codes: 112[] = ...

Readonly log

log: Logger

Readonly pluginOptions

pluginOptions: PluginOptions

Methods

canHandle

handle

Settings

Member Visibility

Theme

On This Page

constructorcodeslogpluginOptionscanHandlehandle
\ No newline at end of file diff --git a/classes/_helia_verified_fetch.PluginError.html b/classes/_helia_verified_fetch.PluginError.html new file mode 100644 index 00000000..1f8c94fb --- /dev/null +++ b/classes/_helia_verified_fetch.PluginError.html @@ -0,0 +1,17 @@ +PluginError | Helia Verified Fetch

Class PluginError

If a plugin encounters an error, it should throw an instance of this class.

+

Hierarchy (view full)

Constructors

constructor +

Properties

cause? +code +details? +fatal +message +name +response? +stack? +prepareStackTrace? +stackTraceLimit +

Methods

captureStackTrace +

Constructors

constructor

Properties

Optional cause

cause?: unknown

code

code: string

Optional details

details?: Record<string, any>

fatal

fatal: boolean

message

message: string

name

name: string = 'PluginError'

Optional response

response?: any

Optional stack

stack?: string

Static Optional prepareStackTrace

prepareStackTrace?: ((err, stackTraces) => any)

Optional override for formatting stack traces

+

Type declaration

    • (err, stackTraces): any

    • Parameters

      Returns any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

+

Static stackTraceLimit

stackTraceLimit: number

Methods

Static captureStackTrace

  • captureStackTrace(targetObject, constructorOpt?): void

  • Create .stack property on a target object

    +

    Parameters

    • targetObject: object
    • Optional constructorOpt: Function

    Returns void

Settings

Member Visibility

Theme

On This Page

constructorcausecodedetailsfatalmessagenameresponsestackprepareStackTracestackTraceLimitcaptureStackTrace
\ No newline at end of file diff --git a/classes/_helia_verified_fetch.PluginFatalError.html b/classes/_helia_verified_fetch.PluginFatalError.html new file mode 100644 index 00000000..beca180b --- /dev/null +++ b/classes/_helia_verified_fetch.PluginFatalError.html @@ -0,0 +1,21 @@ +PluginFatalError | Helia Verified Fetch

Class PluginFatalError

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.

+

Hierarchy (view full)

Constructors

constructor +

Properties

cause? +code +details? +fatal +message +name +response? +stack? +prepareStackTrace? +stackTraceLimit +

Methods

captureStackTrace +

Constructors

constructor

Properties

Optional cause

cause?: unknown

code

code: string

Optional details

details?: Record<string, any>

fatal

fatal: boolean

message

message: string

name

name: string = 'PluginFatalError'

Optional response

response?: any

Optional stack

stack?: string

Static Optional prepareStackTrace

prepareStackTrace?: ((err, stackTraces) => any)

Optional override for formatting stack traces

+

Type declaration

    • (err, stackTraces): any

    • Parameters

      Returns any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

+

Static stackTraceLimit

stackTraceLimit: number

Methods

Static captureStackTrace

  • captureStackTrace(targetObject, constructorOpt?): void

  • Create .stack property on a target object

    +

    Parameters

    • targetObject: object
    • Optional constructorOpt: Function

    Returns void

Settings

Member Visibility

Theme

On This Page

constructorcausecodedetailsfatalmessagenameresponsestackprepareStackTracestackTraceLimitcaptureStackTrace
\ No newline at end of file diff --git a/classes/index.BasePlugin.html b/classes/index.BasePlugin.html deleted file mode 100644 index 7f53c6e3..00000000 --- a/classes/index.BasePlugin.html +++ /dev/null @@ -1,11 +0,0 @@ -BasePlugin | @helia/verified-fetch

Class BasePlugin

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.

-

Hierarchy (view full)

Implements

Constructors

constructor -

Properties

codes -log -pluginOptions -

Methods

canHandle -handle -

Constructors

constructor

Properties

Readonly codes

codes: number[] = []

Readonly log

log: Logger

Readonly pluginOptions

pluginOptions: PluginOptions

Methods

canHandle

handle

Settings

Member Visibility

Theme

On This Page

constructorcodeslogpluginOptionscanHandlehandle
\ No newline at end of file diff --git a/classes/index.DirIndexHtmlPlugin.html b/classes/index.DirIndexHtmlPlugin.html deleted file mode 100644 index e3f424af..00000000 --- a/classes/index.DirIndexHtmlPlugin.html +++ /dev/null @@ -1,11 +0,0 @@ -DirIndexHtmlPlugin | @helia/verified-fetch

Class DirIndexHtmlPlugin

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.

-

Hierarchy (view full)

Constructors

constructor -

Properties

codes -log -pluginOptions -

Methods

canHandle -handle -

Constructors

constructor

Properties

Readonly codes

codes: 112[] = ...

Readonly log

log: Logger

Readonly pluginOptions

pluginOptions: PluginOptions

Methods

canHandle

handle

Settings

Member Visibility

Theme

On This Page

constructorcodeslogpluginOptionscanHandlehandle
\ No newline at end of file diff --git a/classes/index.PluginError.html b/classes/index.PluginError.html deleted file mode 100644 index b9657645..00000000 --- a/classes/index.PluginError.html +++ /dev/null @@ -1,17 +0,0 @@ -PluginError | @helia/verified-fetch

Class PluginError

If a plugin encounters an error, it should throw an instance of this class.

-

Hierarchy (view full)

Constructors

constructor -

Properties

cause? -code -details? -fatal -message -name -response? -stack? -prepareStackTrace? -stackTraceLimit -

Methods

captureStackTrace -

Constructors

constructor

Properties

Optional cause

cause?: unknown

code

code: string

Optional details

details?: Record<string, any>

fatal

fatal: boolean

message

message: string

name

name: string = 'PluginError'

Optional response

response?: any

Optional stack

stack?: string

Static Optional prepareStackTrace

prepareStackTrace?: ((err, stackTraces) => any)

Optional override for formatting stack traces

-

Type declaration

    • (err, stackTraces): any

    • Parameters

      Returns any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

-

Static stackTraceLimit

stackTraceLimit: number

Methods

Static captureStackTrace

  • captureStackTrace(targetObject, constructorOpt?): void

  • Create .stack property on a target object

    -

    Parameters

    • targetObject: object
    • Optional constructorOpt: Function

    Returns void

Settings

Member Visibility

Theme

On This Page

constructorcausecodedetailsfatalmessagenameresponsestackprepareStackTracestackTraceLimitcaptureStackTrace
\ No newline at end of file diff --git a/classes/index.PluginFatalError.html b/classes/index.PluginFatalError.html deleted file mode 100644 index 2e83f1c0..00000000 --- a/classes/index.PluginFatalError.html +++ /dev/null @@ -1,21 +0,0 @@ -PluginFatalError | @helia/verified-fetch

Class PluginFatalError

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.

-

Hierarchy (view full)

Constructors

constructor -

Properties

cause? -code -details? -fatal -message -name -response? -stack? -prepareStackTrace? -stackTraceLimit -

Methods

captureStackTrace -

Constructors

constructor

Properties

Optional cause

cause?: unknown

code

code: string

Optional details

details?: Record<string, any>

fatal

fatal: boolean

message

message: string

name

name: string = 'PluginFatalError'

Optional response

response?: any

Optional stack

stack?: string

Static Optional prepareStackTrace

prepareStackTrace?: ((err, stackTraces) => any)

Optional override for formatting stack traces

-

Type declaration

    • (err, stackTraces): any

    • Parameters

      Returns any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

-

Static stackTraceLimit

stackTraceLimit: number

Methods

Static captureStackTrace

  • captureStackTrace(targetObject, constructorOpt?): void

  • Create .stack property on a target object

    -

    Parameters

    • targetObject: object
    • Optional constructorOpt: Function

    Returns void

Settings

Member Visibility

Theme

On This Page

constructorcausecodedetailsfatalmessagenameresponsestackprepareStackTracestackTraceLimitcaptureStackTrace
\ No newline at end of file diff --git a/functions/_helia_verified_fetch.createVerifiedFetch.html b/functions/_helia_verified_fetch.createVerifiedFetch.html new file mode 100644 index 00000000..00ecb980 --- /dev/null +++ b/functions/_helia_verified_fetch.createVerifiedFetch.html @@ -0,0 +1,2 @@ +createVerifiedFetch | Helia Verified Fetch

Function createVerifiedFetch

Settings

Member Visibility

Theme

\ No newline at end of file diff --git a/functions/_helia_verified_fetch.dirIndexHtmlPluginFactory.html b/functions/_helia_verified_fetch.dirIndexHtmlPluginFactory.html new file mode 100644 index 00000000..04ac2640 --- /dev/null +++ b/functions/_helia_verified_fetch.dirIndexHtmlPluginFactory.html @@ -0,0 +1 @@ +dirIndexHtmlPluginFactory | Helia Verified Fetch

Function dirIndexHtmlPluginFactory

Settings

Member Visibility

Theme

\ No newline at end of file diff --git a/functions/index.verifiedFetch-1.html b/functions/_helia_verified_fetch.verifiedFetch-1.html similarity index 52% rename from functions/index.verifiedFetch-1.html rename to functions/_helia_verified_fetch.verifiedFetch-1.html index b3bfa14e..3583dc31 100644 --- a/functions/index.verifiedFetch-1.html +++ b/functions/_helia_verified_fetch.verifiedFetch-1.html @@ -1,3 +1,3 @@ -verifiedFetch | @helia/verified-fetch

Function verifiedFetch

Methods

start -stop -

Methods

start

stop

Settings

Member Visibility

Theme

On This Page

startstop
\ No newline at end of file +verifiedFetch | Helia Verified Fetch

Function verifiedFetch

Methods

start +stop +

Methods

start

stop

Settings

Member Visibility

Theme

On This Page

startstop
\ No newline at end of file diff --git a/functions/index.createVerifiedFetch.html b/functions/index.createVerifiedFetch.html deleted file mode 100644 index 70156163..00000000 --- a/functions/index.createVerifiedFetch.html +++ /dev/null @@ -1,2 +0,0 @@ -createVerifiedFetch | @helia/verified-fetch

Function createVerifiedFetch

Settings

Member Visibility

Theme

\ No newline at end of file diff --git a/functions/index.dirIndexHtmlPluginFactory.html b/functions/index.dirIndexHtmlPluginFactory.html deleted file mode 100644 index 312bc40d..00000000 --- a/functions/index.dirIndexHtmlPluginFactory.html +++ /dev/null @@ -1 +0,0 @@ -dirIndexHtmlPluginFactory | @helia/verified-fetch

Function dirIndexHtmlPluginFactory

Settings

Member Visibility

Theme

\ No newline at end of file diff --git a/hierarchy.html b/hierarchy.html index 4b437445..e362e93a 100644 --- a/hierarchy.html +++ b/hierarchy.html @@ -1 +1 @@ -@helia/verified-fetch

@helia/verified-fetch

Class Hierarchy

Settings

Member Visibility

Theme

\ No newline at end of file +Helia Verified Fetch

Helia Verified Fetch

Class Hierarchy

Settings

Member Visibility

Theme

\ No newline at end of file diff --git a/index.html b/index.html index 041fe611..25d5fb2f 100644 --- a/index.html +++ b/index.html @@ -1,376 +1,22 @@ -@helia/verified-fetch

@helia/verified-fetch

+Helia Verified Fetch

Helia Verified Fetch

Helia logo

-

@helia/verified-fetch

ipfs.tech +

helia-verified-fetch

ipfs.tech Discuss codecov CI

-
-

A fetch-like API for obtaining verified & trustless IPFS content on the web

-
-

About

- -

@helia/verified-fetch provides a fetch-like API for retrieving content from the IPFS network.

-

All content is retrieved in a trustless manner, and the integrity of all bytes are verified by comparing hashes of the data.

-

By default, providers for CIDs are found using delegated routing endpoints.

-

Data is retrieved using the following strategies:

-
    -
  • Directly from providers, using Bitswap over WebSockets and WebRTC if available.
    • -
  • Directly from providers exposing a trustless gateway over HTTPS.
    • -
  • As a fallback, if no providers reachable from a browser are found, data is retrieved using recursive gateways, e.g. trustless-gateway.link which can be configured.
    • -
-

This is a marked improvement over fetch which offers no such protections and is vulnerable to all sorts of attacks like Content Spoofing, DNS Hijacking, etc.

-

A verifiedFetch function is exported to get up and running quickly, and a createVerifiedFetch function is also available that allows customizing the underlying Helia node for complete control over how content is retrieved.

-

Browser-cache-friendly Response objects are returned which should be instantly familiar to web developers.

+

About

This monorepo contains the @helia/verified-fetch package and its corresponding interop tests.

+

Getting started

See the @helia/verified-fetch package for how to get started with the package including usage examples.

Learn more in the announcement blog post and check out the ready-to-run example.

-

You may use any supported resource argument to fetch content:

-
    -
  • CID instance
    • -
  • IPFS URL
    • -
  • IPNS URL
    • -
-

Example - Getting started

import { verifiedFetch } from '@helia/verified-fetch'

const resp = await verifiedFetch('ipfs://bafy...')

const json = await resp.json()
-
-

Example - Using a CID instance to fetch JSON

import { verifiedFetch } from '@helia/verified-fetch'
import { CID } from 'multiformats/cid'

const cid = CID.parse('bafyFoo') // some json file
const response = await verifiedFetch(cid)
const json = await response.json()
-
-

Example - Using IPFS protocol to fetch an image

import { verifiedFetch } from '@helia/verified-fetch'

const response = await verifiedFetch('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

import { verifiedFetch } from '@helia/verified-fetch'

const response = await verifiedFetch('ipns://mydomain.com/path/to/very-long-file.log')
const bigFileStreamReader = await response.body?.getReader()
-
-

Configuration

Custom HTTP gateways and routers

Out of the box @helia/verified-fetch uses a default set of trustless gateways for fetching blocks and HTTP delegated routers for performing routing tasks - looking up peers, resolving/publishing IPNS names, etc.

-

It's possible to override these by passing gateways and routers keys to the createVerifiedFetch function:

-

Example - Configuring gateways and routers

import { createVerifiedFetch } from '@helia/verified-fetch'

const fetch = await createVerifiedFetch({
  gateways: ['https://trustless-gateway.link'],
  routers: ['http://delegated-ipfs.dev']
})

const resp = await fetch('ipfs://bafy...')

const json = await resp.json()
-
-

Usage with customized Helia

For full control of how @helia/verified-fetch fetches content from the distributed web you can pass a preconfigured Helia node to createVerifiedFetch.

-

The helia module is configured with a libp2p node that is suited for decentralized applications, alternatively @helia/http is available which uses HTTP gateways for all network operations.

-

You can see variations of Helia and js-libp2p configuration options at https://ipfs.github.io/helia/interfaces/helia.HeliaInit.html.

-
import { trustlessGateway } from '@helia/block-brokers'
import { createHeliaHTTP } from '@helia/http'
import { delegatedHTTPRouting, httpGatewayRouting } from '@helia/routers'
import { createVerifiedFetch } from '@helia/verified-fetch'

const fetch = await createVerifiedFetch(
  await createHeliaHTTP({
    blockBrokers: [
      trustlessGateway()
    ],
    routers: [
      delegatedHTTPRouting('http://delegated-ipfs.dev'),
      httpGatewayRouting({
        gateways: ['https://mygateway.example.net', 'https://trustless-gateway.link']
      })
    ]
  })
)

const resp = await fetch('ipfs://bafy...')

const json = await resp.json()
-
-

Custom content-type parsing

By default, if the response can be parsed as JSON, @helia/verified-fetch sets the Content-Type header as application/json, otherwise it sets it as application/octet-stream - this is because the .json(), .text(), .blob(), and .arrayBuffer() methods will usually work as expected without a detailed content type.

-

If you require an accurate content-type you can provide a contentTypeParser function as an option to createVerifiedFetch to handle parsing the content type.

-

The function you provide will be called with the first chunk of bytes from the file and should return a string or a promise of a string.

-

Example - Customizing content-type parsing

import { createVerifiedFetch } from '@helia/verified-fetch'
import { fileTypeFromBuffer } from '@sgtpooki/file-type'

const fetch = await createVerifiedFetch({
  gateways: ['https://trustless-gateway.link'],
  routers: ['http://delegated-ipfs.dev']
}, {
  contentTypeParser: async (bytes) => {
    // call to some magic-byte recognition library like magic-bytes, file-type, or your own custom byte recognition
    const result = await fileTypeFromBuffer(bytes)
    return result?.mime
  }
})
-
-

Custom DNS resolvers

If you don't want to leak DNS queries to the default resolvers, you can provide your own list of DNS resolvers to createVerifiedFetch.

-

Note that you do not need to provide both a DNS-over-HTTPS and a DNS-over-JSON resolver, and you should prefer dnsJsonOverHttps resolvers for usage in the browser for a smaller bundle size. See https://github.com/ipfs/helia/tree/main/packages/ipns#example---using-dns-json-over-https for more information.

-

Example - Customizing DNS resolvers

import { createVerifiedFetch } from '@helia/verified-fetch'
import { dnsJsonOverHttps, dnsOverHttps } from '@multiformats/dns/resolvers'

const fetch = await createVerifiedFetch({
  gateways: ['https://trustless-gateway.link'],
  routers: ['http://delegated-ipfs.dev'],
  dnsResolvers: [
    dnsJsonOverHttps('https://my-dns-resolver.example.com/dns-json'),
    dnsOverHttps('https://my-dns-resolver.example.com/dns-query')
  ]
})
-
-

Example - Customizing DNS per-TLD resolvers

DNS resolvers can be configured to only service DNS queries for specific -TLDs:

-
import { createVerifiedFetch } from '@helia/verified-fetch'
import { dnsJsonOverHttps, dnsOverHttps } from '@multiformats/dns/resolvers'

const fetch = await createVerifiedFetch({
  gateways: ['https://trustless-gateway.link'],
  routers: ['http://delegated-ipfs.dev'],
  dnsResolvers: {
    // this resolver will only be used for `.com` domains (note - this could
    // also be an array of resolvers)
    'com.': dnsJsonOverHttps('https://my-dns-resolver.example.com/dns-json'),
    // this resolver will be used for everything else (note - this could
    // also be an array of resolvers)
    '.': dnsOverHttps('https://my-dns-resolver.example.com/dns-query')
  }
})
-
-

Custom Hashers

By default, @helia/verified-fetch supports sha256, sha512, and identity hashers.

-

If you need to use a different hasher, you can provide a custom hasher function as an option to createVerifiedFetch.

-

Example - Passing a custom hashing function

import { createVerifiedFetch } from '@helia/verified-fetch'
import { blake2b256 } from '@multiformats/blake2/blake2b'

const verifiedFetch = await createVerifiedFetch({
  gateways: ['https://ipfs.io'],
  hashers: [blake2b256]
})

const resp = await verifiedFetch('ipfs://cid-using-blake2b256')
-
-

IPLD codec handling

IPFS supports several data formats (typically referred to as codecs) which are included in the CID. @helia/verified-fetch attempts to abstract away some of the details for easier consumption.

-

DAG-PB

DAG-PB is the codec we are most likely to encounter, it is what UnixFS uses under the hood.

-
Using the DAG-PB codec as a Blob
import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://Qmfoo')
const blob = await res.blob()

console.info(blob) // Blob { size: x, type: 'application/octet-stream' }
-
-
Using the DAG-PB codec as an ArrayBuffer
import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://Qmfoo')
const buf = await res.arrayBuffer()

console.info(buf) // ArrayBuffer { [Uint8Contents]: < ... >, byteLength: x }
-
-
Using the DAG-PB codec as a stream
import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://Qmfoo')
const reader = res.body?.getReader()

if (reader == null) {
  throw new Error('Could not create reader from response body')
}

while (true) {
  const next = await reader.read()

  if (next?.done === true) {
    break
  }

  if (next?.value != null) {
    console.info(next.value) // Uint8Array(x) [ ... ]
  }
}
-
-
Content-Type

When fetching DAG-PB data, the content type will be set to application/octet-stream unless a custom content-type parser is configured.

-

JSON

The JSON codec is a very simple codec, a block parseable with this codec is a JSON string encoded into a Uint8Array.

-
Using the JSON codec
import * as json from 'multiformats/codecs/json'

const block = new TextEncoder().encode('{ "hello": "world" }')
const obj = json.decode(block)

console.info(obj) // { hello: 'world' }
-
-
Content-Type

When the JSON codec is encountered, the Content-Type header of the response will be set to application/json.

-

DAG-JSON

DAG-JSON expands on the JSON codec, adding the ability to contain CIDs which act as links to other blocks, and byte arrays.

-

CIDs and byte arrays are represented using special object structures with a single "/" property.

-

Using DAG-JSON has two important caveats:

-
    -
  1. Your JSON structure cannot contain an object with only a "/" property, as it will be interpreted as a special type.
    2. -
  2. Since JSON has no technical limit on number sizes, DAG-JSON also allows numbers larger than Number.MAX_SAFE_INTEGER. JavaScript requires use of BigInts to represent numbers larger than this, and JSON.parse does not support them, so precision will be lost.
    3. -
-

Otherwise this codec follows the same rules as the JSON codec.

-
Using the DAG-JSON codec
import * as dagJson from '@ipld/dag-json'

const block = new TextEncoder().encode(`{
  "hello": "world",
  "cid": {
    "/": "baeaaac3imvwgy3zao5xxe3de"
  },
  "buf": {
    "/": {
      "bytes": "AAECAwQ"
    }
  }
}`)

const obj = dagJson.decode(block)

console.info(obj)
// {
// hello: 'world',
// cid: CID(baeaaac3imvwgy3zao5xxe3de),
// buf: Uint8Array(5) [ 0, 1, 2, 3, 4 ]
// }
-
-
Content-Type

When the DAG-JSON codec is encountered in the requested CID, the Content-Type header of the response will be set to application/json.

-

DAG-JSON data can be parsed from the response by using the .json() function, which will return CIDs/byte arrays as plain { "/": ... } objects:

-
import { verifiedFetch } from '@helia/verified-fetch'
import * as dagJson from '@ipld/dag-json'

const res = await verifiedFetch('ipfs://bafyDAGJSON')

// either:
const obj = await res.json()
console.info(obj.cid) // { "/": "baeaaac3imvwgy3zao5xxe3de" }
console.info(obj.buf) // { "/": { "bytes": "AAECAwQ" } }
-
-

Alternatively, it can be decoded using the @ipld/dag-json module and the .arrayBuffer() method, in which case you will get CID objects and Uint8Arrays:

-
import { verifiedFetch } from '@helia/verified-fetch'
import * as dagJson from '@ipld/dag-json'

const res = await verifiedFetch('ipfs://bafyDAGJSON')

// or:
const obj = dagJson.decode<any>(await res.arrayBuffer())
console.info(obj.cid) // CID(baeaaac3imvwgy3zao5xxe3de)
console.info(obj.buf) // Uint8Array(5) [ 0, 1, 2, 3, 4 ]
-
-

DAG-CBOR

DAG-CBOR uses the Concise Binary Object Representation format for serialization instead of JSON.

-

This supports more datatypes in a safer way than JSON and is smaller on the wire to boot so is usually preferable to JSON or DAG-JSON.

-
Content-Type

Not all data types supported by DAG-CBOR can be successfully turned into JSON and back into the same binary form.

-

When a decoded block can be round-tripped to JSON, the Content-Type will be set to application/json. In this case the .json() method on the Response object can be used to obtain an object representation of the response.

-

When it cannot, the Content-Type will be application/octet-stream - in this case the @ipld/dag-json module must be used to deserialize the return value from .arrayBuffer().

-
Detecting JSON-safe DAG-CBOR

If the Content-Type header of the response is application/json, the .json() method may be used to access the response body in object form, otherwise the .arrayBuffer() method must be used to decode the raw bytes using the @ipld/dag-cbor module.

-
import { verifiedFetch } from '@helia/verified-fetch'
import * as dagCbor from '@ipld/dag-cbor'

const res = await verifiedFetch('ipfs://bafyDagCborCID')
let obj

if (res.headers.get('Content-Type') === 'application/json') {
  // DAG-CBOR data can be safely decoded as JSON
  obj = await res.json()
} else {
  // response contains non-JSON friendly data types
  obj = dagCbor.decode(await res.arrayBuffer())
}

console.info(obj) // ...
-
-

The Accept header

The Accept header can be passed to override certain response processing, or to ensure that the final Content-Type of the response is the one that is expected.

-

If the final Content-Type does not match the Accept header, or if the content cannot be represented in the format dictated by the Accept header, or you have configured a custom content type parser, and that parser returns a value that isn't in the accept header, a 406: Not Acceptable response will be returned:

-
import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://bafyJPEGImageCID', {
  headers: {
    accept: 'image/png'
  }
})

console.info(res.status) // 406 - the image was a JPEG but we specified PNG as the accept header
-
-

It can also be used to skip processing the data from some formats such as DAG-CBOR if you wish to handle decoding it yourself:

-
import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://bafyDAGCBORCID', {
  headers: {
    accept: 'application/octet-stream'
  }
})

console.info(res.headers.get('accept')) // application/octet-stream
const buf = await res.arrayBuffer() // raw bytes, not processed as JSON
-
-

Redirects

If a requested URL contains a path component, that path component resolves to -a UnixFS directory, but the URL does not have a trailing slash, one will be -added to form a canonical URL for that resource, otherwise the request will -be resolved as normal.

-
import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://bafyfoo/path/to/dir')

console.info(res.url) // ipfs://bafyfoo/path/to/dir/
-
-

It's possible to prevent this behaviour and/or handle a redirect manually -through use of the redirect -option.

-

Example - Redirect: follow

This is the default value and is what happens if no value is specified.

-
import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://bafyfoo/path/to/dir', {
  redirect: 'follow'
})

console.info(res.status) // 200
console.info(res.url) // ipfs://bafyfoo/path/to/dir/
console.info(res.redirected) // true
-
-

Example - Redirect: error

This causes a TypeError to be thrown if a URL would cause a redirect.

-

import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://bafyfoo/path/to/dir', {
  redirect: 'error'
})
// throw TypeError('Failed to fetch')
-
-

Example - Redirect: manual

Manual redirects allow the user to process the redirect. A 301 -is returned, and the location to redirect to is available as the "location" -response header.

-

This differs slightly from HTTP fetch which returns an opaque response as the -browser itself is expected to process the redirect and hide all details from -the user.

-

import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://bafyfoo/path/to/dir', {
  redirect: 'manual'
})

console.info(res.status) // 301
console.info(res.url) // ipfs://bafyfoo/path/to/dir
console.info(res.redirected) // false
console.info(res.headers.get('location')) // ipfs://bafyfoo/path/to/dir/
-
-

Comparison to fetch

This module attempts to act as similarly to the fetch() API as possible.

-

The fetch() API takes two parameters:

-
    -
  1. A resource
    2. -
  2. An options object
    3. -
-

Resource argument

This library supports the following methods of fetching web3 content from IPFS:

-
    -
  1. IPFS protocol: ipfs://<cidv0> & ipfs://<cidv1>
    2. -
  2. IPNS protocol: ipns://<peerId> & ipns://<publicKey> & ipns://<hostUri_Supporting_DnsLink_TxtRecords>
    3. -
  3. CID instances: An actual CID instance CID.parse('bafy...')
    4. -
-

As well as support for pathing & params for items 1 & 2 above according to IPFS - Path Gateway Specification & IPFS - Trustless Gateway Specification. Further refinement of those specifications specifically for web-based scenarios can be found in the Web Pathing Specification IPIP.

-

If you pass a CID instance, it assumes you want the content for that specific CID only, and does 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 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. -
  2. https://specs.ipfs.tech/http-gateways/trustless-gateway/#request-headers
    3. -
  3. https://specs.ipfs.tech/http-gateways/subdomain-gateway/#request-headers
    4. -
-

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. -
  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 parameter.
    3. -
  3. headers - An object of headers to be sent with the request. Best effort to adhere to the Fetch API headers parameter. -
    4. -
  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 parameter.
    5. -
  5. body - An object that specifies the body of the request. Best effort to adhere to the Fetch API body parameter.
    6. -
  6. cache - Will basically act as force-cache for the request. Best effort to adhere to the Fetch API cache parameter.
    7. -
-

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.
      • -
    -
    2. -
-

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
    2. -
  2. IPIP-0402: Partial CAR Support on Trustless Gateways
    3. -
  3. IPIP-0386: Subdomain Gateway Interop with _redirects
    4. -
  4. IPIP-0328: JSON and CBOR Response Formats on HTTP Gateways
    5. -
  5. IPIP-0288: TAR Response Format on HTTP Gateways
    6. -
-

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 via a ReadableStream 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, this library will not support it, but you can use the helia library directly for those use cases. See 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.
    • -
-

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. Instead, users should request aplication/vnd.ipld.car or use the helia library directly for this use case.
    • -
  • Others? Open an issue or PR!
    • -
-

Response headers

This library will set the HTTP Response headers to the appropriate values for the content type according to the appropriate IPFS Specifications.

-

Some known header specifications:

- -

Server Timing headers

By default, we do not include Server Timing headers in responses. If you want to include them, you can pass an -withServerTiming option to the createVerifiedFetch function to include them in all future responses. You can -also pass the withServerTiming option to each fetch call to include them only for that specific response.

-

See PR where this was added, https://github.com/ipfs/helia-verified-fetch/pull/164, for more information.

-

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. -
  2. TypeError - If the options argument is passed and not an object.
    3. -
  3. TypeError - If the options argument is passed and is malformed.
    4. -
  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.
    5. -
-

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. -

  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:

    -
    3. -
-
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]
-
-
    -
  1. 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.
      • -
    -
    2. -
-

Please see the original discussion on extensibility in Issue #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>
      • -
    -
    2. -
-

Example - custom plugin

   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)
-
-
    -

  1. Integrate Your Plugin:

    -

    Add your custom plugin to Verified‑Fetch’s plugin list when instantiating Verified‑Fetch:

    -
    2. -
-

Example - Integrate custom plugin

   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

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.
      • -
    -
    • +

    Packages

    -

    For a detailed explanation of the pipeline, please refer to the discussion in Issue #167.

    -

    Install

    $ npm i @helia/verified-fetch
-
    -

    Browser <script> tag

    Loading this module through a script tag will make it's exports available as HeliaVerifiedFetch in the global namespace.

    -
    <script src="https://unpkg.com/@helia/verified-fetch/dist/index.min.js"></script>
-

    API Docs

    License

    Licensed under either of

      @@ -382,4 +28,4 @@

      Please be aware that all interactions related to this repo are subject to the IPFS Code of Conduct.

      Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

      -

Settings

Member Visibility

Theme

On This Page

@helia/verified-fetchAboutInstallAPI DocsLicenseContribute
\ No newline at end of file +

Settings

Member Visibility

Theme

On This Page

helia-verified-fetchGetting startedPackagesAPI DocsLicenseContribute
\ No newline at end of file diff --git a/interfaces/_helia_verified_fetch.CIDDetail.html b/interfaces/_helia_verified_fetch.CIDDetail.html new file mode 100644 index 00000000..c05926b6 --- /dev/null +++ b/interfaces/_helia_verified_fetch.CIDDetail.html @@ -0,0 +1,3 @@ +CIDDetail | Helia Verified Fetch

Interface CIDDetail

interface CIDDetail {
    cid: CID<unknown, number, number, Version>;
    path: string;
}

Hierarchy (view full)

Properties

cid +path +

Properties

cid

cid: CID<unknown, number, number, Version>

path

path: string

Settings

Member Visibility

Theme

On This Page

cidpath
\ No newline at end of file diff --git a/interfaces/_helia_verified_fetch.CIDDetailError.html b/interfaces/_helia_verified_fetch.CIDDetailError.html new file mode 100644 index 00000000..1f23ccbf --- /dev/null +++ b/interfaces/_helia_verified_fetch.CIDDetailError.html @@ -0,0 +1,4 @@ +CIDDetailError | Helia Verified Fetch

Interface CIDDetailError

interface CIDDetailError {
    cid: CID<unknown, number, number, Version>;
    error: Error;
    path: string;
}

Hierarchy (view full)

Properties

cid +error +path +

Properties

cid

cid: CID<unknown, number, number, Version>

error

error: Error

path

path: string

Settings

Member Visibility

Theme

On This Page

ciderrorpath
\ No newline at end of file diff --git a/interfaces/index.ContentTypeParser.html b/interfaces/_helia_verified_fetch.ContentTypeParser.html similarity index 72% rename from interfaces/index.ContentTypeParser.html rename to interfaces/_helia_verified_fetch.ContentTypeParser.html index cda5958a..58fba985 100644 --- a/interfaces/index.ContentTypeParser.html +++ b/interfaces/_helia_verified_fetch.ContentTypeParser.html @@ -1,7 +1,7 @@ -ContentTypeParser | @helia/verified-fetch

Interface ContentTypeParser

A ContentTypeParser attempts to return the mime type of a given file. It +ContentTypeParser | Helia Verified Fetch

Interface ContentTypeParser

A ContentTypeParser attempts to return the mime type of a given file. It receives the first chunk of the file data and the file name, if it is available. The function can be sync or async and if it returns/resolves to undefined, application/octet-stream will be used.

interface ContentTypeParser ((bytes, fileName?) => undefined | string | Promise<undefined | string>)
  • ContentTypeParser(bytes, fileName?): undefined | string | Promise<undefined | string>

  • Attempt to determine a mime type, either via of the passed bytes or the filename if it is available.

    -

    Parameters

    Returns undefined | string | Promise<undefined | string>

Settings

Member Visibility

Theme

\ No newline at end of file +

Parameters

Returns undefined | string | Promise<undefined | string>

Settings

Member Visibility

Theme

\ No newline at end of file diff --git a/interfaces/index.CreateVerifiedFetchInit.html b/interfaces/_helia_verified_fetch.CreateVerifiedFetchInit.html similarity index 54% rename from interfaces/index.CreateVerifiedFetchInit.html rename to interfaces/_helia_verified_fetch.CreateVerifiedFetchInit.html index b49f7d88..623902d0 100644 --- a/interfaces/index.CreateVerifiedFetchInit.html +++ b/interfaces/_helia_verified_fetch.CreateVerifiedFetchInit.html @@ -1,40 +1,40 @@ -CreateVerifiedFetchInit | @helia/verified-fetch

Interface CreateVerifiedFetchInit

Instead of passing a Helia instance, you can pass a list of gateways and +CreateVerifiedFetchInit | Helia Verified Fetch

Interface CreateVerifiedFetchInit

Instead of passing a Helia instance, you can pass a list of gateways and routers, and a HeliaHTTP instance will be created for you.

-
interface CreateVerifiedFetchInit {
    allowInsecure?: boolean;
    allowLocal?: boolean;
    dnsResolvers?: DNSResolver[] | DNSResolvers;
    gateways: string[];
    hashers?: MultihashHasher<number>[];
    libp2pConfig?: Partial<Libp2pOptions<ServiceMap>>;
    routers?: string[];
}

Properties

allowInsecure? -allowLocal? -dnsResolvers? -gateways -hashers? -libp2pConfig? -routers? +
interface CreateVerifiedFetchInit {
    allowInsecure?: boolean;
    allowLocal?: boolean;
    dnsResolvers?: DNSResolver[] | DNSResolvers;
    gateways: string[];
    hashers?: MultihashHasher<number>[];
    libp2pConfig?: Partial<Libp2pOptions<ServiceMap>>;
    routers?: string[];
}

Properties

allowInsecure? +allowLocal? +dnsResolvers? +gateways +hashers? +libp2pConfig? +routers?

Properties

Optional allowInsecure

allowInsecure?: boolean

By default we will not connect to any gateways over HTTP addresses, requring HTTPS connections instead. This is because it will cause "mixed-content" errors to appear in the console when running in secure browser contexts.

Pass true here to connect to insecure Gateways as well, this may be useful in testing environments.

-

Default

false
+

Default

false

Optional allowLocal

allowLocal?: boolean

By default we will not connect to any HTTP Gateways providers over local or loopback addresses, this is because they are typically running on remote peers that have published private addresses by mistate.

Pass true here to connect to local Gateways as well, this may be useful in testing environments.

-

Default

false
+

Default

false
-

Optional dnsResolvers

dnsResolvers?: DNSResolver[] | DNSResolvers

In order to parse DNSLink records, we need to resolve DNS queries. You can +

Optional dnsResolvers

dnsResolvers?: DNSResolver[] | DNSResolvers

In order to parse DNSLink records, we need to resolve DNS queries. You can pass a list of DNS resolvers that we will provide to the @helia/ipns instance for you. You must construct them using the dnsJsonOverHttps or dnsOverHttps functions exported from @helia/ipns/dns-resolvers.

We use cloudflare and google's dnsJsonOverHttps resolvers by default.

-

Default

[dnsJsonOverHttps('https://cloudflare-dns.com/dns-query'),dnsJsonOverHttps('https://dns.google/resolve')]
+

Default

[dnsJsonOverHttps('https://cloudflare-dns.com/dns-query'),dnsJsonOverHttps('https://dns.google/resolve')]
-

gateways

gateways: string[]

Optional hashers

hashers?: MultihashHasher<number>[]

By default sha256, sha512 and identity hashes are supported for +

gateways

gateways: string[]

Optional hashers

hashers?: MultihashHasher<number>[]

By default sha256, sha512 and identity hashes are supported for retrieval operations. To retrieve blocks by CIDs using other hashes pass appropriate MultihashHashers here.

-

Optional libp2pConfig

libp2pConfig?: Partial<Libp2pOptions<ServiceMap>>

We will instantiate a libp2p node for you, but if you want to override the libp2p configuration, +

Optional libp2pConfig

libp2pConfig?: Partial<Libp2pOptions<ServiceMap>>

We will instantiate a libp2p node for you, but if you want to override the libp2p configuration, you can pass it here.

WARNING: We use Object.assign to merge the default libp2p configuration from Helia with the one you pass here, which results in a shallow merge. If you need a deep merge, you should do it yourself before passing the configuration here.

-

Optional routers

routers?: string[]

Settings

Member Visibility

Theme

On This Page

allowInsecureallowLocaldnsResolversgatewayshasherslibp2pConfigrouters
\ No newline at end of file +

Optional routers

routers?: string[]

Settings

Member Visibility

Theme

On This Page

allowInsecureallowLocaldnsResolversgatewayshasherslibp2pConfigrouters
\ No newline at end of file diff --git a/interfaces/index.CreateVerifiedFetchOptions.html b/interfaces/_helia_verified_fetch.CreateVerifiedFetchOptions.html similarity index 56% rename from interfaces/index.CreateVerifiedFetchOptions.html rename to interfaces/_helia_verified_fetch.CreateVerifiedFetchOptions.html index 740a5d72..a3a2ea62 100644 --- a/interfaces/index.CreateVerifiedFetchOptions.html +++ b/interfaces/_helia_verified_fetch.CreateVerifiedFetchOptions.html @@ -1,26 +1,26 @@ -CreateVerifiedFetchOptions | @helia/verified-fetch

Interface CreateVerifiedFetchOptions

interface CreateVerifiedFetchOptions {
    contentTypeParser?: ContentTypeParser;
    plugins?: VerifiedFetchPluginFactory[];
    sessionCacheSize?: number;
    sessionTTLms?: number;
    withServerTiming?: boolean;
}

Properties

contentTypeParser? -plugins? -sessionCacheSize? -sessionTTLms? -withServerTiming? -

Properties

Optional contentTypeParser

contentTypeParser?: ContentTypeParser

A function to handle parsing content type from bytes. The function you +CreateVerifiedFetchOptions | Helia Verified Fetch

Interface CreateVerifiedFetchOptions

interface CreateVerifiedFetchOptions {
    contentTypeParser?: ContentTypeParser;
    plugins?: VerifiedFetchPluginFactory[];
    sessionCacheSize?: number;
    sessionTTLms?: number;
    withServerTiming?: boolean;
}

Properties

contentTypeParser? +plugins? +sessionCacheSize? +sessionTTLms? +withServerTiming? +

Properties

Optional contentTypeParser

contentTypeParser?: ContentTypeParser

A function to handle parsing content type from bytes. The function you provide will be passed the first set of bytes we receive from the network, and should return a string that will be used as the value for the Content-Type header in the response.

-

Default

undefined
+

Default

undefined
-

Optional plugins

plugins?: VerifiedFetchPluginFactory[]

Plugins to use with the verified-fetch instance. Note that we have a set of default plugins that are always used. +

Optional plugins

plugins?: VerifiedFetchPluginFactory[]

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.

Optional sessionCacheSize

sessionCacheSize?: number

Blockstore sessions are cached for reuse with requests with the same base URL or CID. This parameter controls how many to cache. Once this limit is reached older/less used sessions will be evicted from the cache.

-

Default

100
+

Default

100

Optional sessionTTLms

sessionTTLms?: number

How long each blockstore session should stay in the cache for.

-

Default

60000
+

Default

60000

Optional withServerTiming

withServerTiming?: boolean

Whether to include server-timing headers in responses. This option can be overridden on a per-request basis.

-

Default

false
+

Default

false

See

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Server-Timing

-

Settings

Member Visibility

Theme

On This Page

contentTypeParserpluginssessionCacheSizesessionTTLmswithServerTiming
\ No newline at end of file +

Settings

Member Visibility

Theme

On This Page

contentTypeParserpluginssessionCacheSizesessionTTLmswithServerTiming
\ No newline at end of file diff --git a/interfaces/_helia_verified_fetch.PluginContext.html b/interfaces/_helia_verified_fetch.PluginContext.html new file mode 100644 index 00000000..d69b67c2 --- /dev/null +++ b/interfaces/_helia_verified_fetch.PluginContext.html @@ -0,0 +1,23 @@ +PluginContext | Helia Verified Fetch

Interface PluginContext

Represents the ephemeral, modifiable state used by the pipeline.

+
    +
  • Mutable: Evolves as you walk the plugin chain.
    • +
  • Shared Data: Allows plugins to communicate partial results, discovered data, or interim errors.
    • +
  • Ephemeral: Typically discarded once fetch(...) completes.
    • +
+
interface PluginContext {
    accept?: string;
    cid: CID<unknown, number, number, Version>;
    directoryEntries?: UnixFSEntry[];
    errors?: PluginError[];
    isDirectory?: boolean;
    modified: number;
    options?: Omit<VerifiedFetchInit, "signal"> & AbortOptions;
    path: string;
    pathDetails?: PathWalkerResponse;
    query: ParsedUrlQuery;
    reqFormat?: RequestFormatShorthand;
    resource: string;
    withServerTiming?: boolean;
    onProgress?(evt): void;
    [key: string]: unknown;
}

Indexable

[key: string]: unknown

Properties

accept? +cid +directoryEntries? +errors? +isDirectory? +modified +options? +path +pathDetails? +query +reqFormat? +resource +withServerTiming? +

Methods

onProgress? +

Properties

Optional Readonly accept

accept?: string

Readonly cid

cid: CID<unknown, number, number, Version>

Optional directoryEntries

directoryEntries?: UnixFSEntry[]

Optional errors

errors?: PluginError[]

Optional isDirectory

isDirectory?: boolean

modified

modified: number

The last time the context is modified, so we know whether a plugin has modified it. +A plugin should increment this value if it modifies the context.

+

Optional options

options?: Omit<VerifiedFetchInit, "signal"> & AbortOptions

Readonly path

path: string

Optional pathDetails

pathDetails?: PathWalkerResponse

query

query: ParsedUrlQuery

Optional reqFormat

reqFormat?: RequestFormatShorthand

Readonly resource

resource: string

Optional withServerTiming

withServerTiming?: boolean

Methods

Optional onProgress

Settings

Member Visibility

Theme

On This Page

acceptciddirectoryEntrieserrorsisDirectorymodifiedoptionspathpathDetailsqueryreqFormatresourcewithServerTimingonProgress
\ No newline at end of file diff --git a/interfaces/_helia_verified_fetch.PluginOptions.html b/interfaces/_helia_verified_fetch.PluginOptions.html new file mode 100644 index 00000000..5efb6a73 --- /dev/null +++ b/interfaces/_helia_verified_fetch.PluginOptions.html @@ -0,0 +1,11 @@ +PluginOptions | Helia Verified Fetch

Interface PluginOptions

Contains common components and functions required by plugins to handle a request.

+
    +
  • Read-Only: Plugins can read but shouldn’t rewrite them.
    • +
  • Persistent: Relevant even after the request completes (e.g., logging or metrics).
    • +
+
interface PluginOptions {
    contentTypeParser?: ContentTypeParser;
    helia: Helia;
    logger: ComponentLogger;
    getBlockstore(cid, resource, useSession?, options?): Blockstore<{}, {}, {}, {}, {}, {}, {}, {}>;
    handleServerTiming<T>(name, description, fn, withServerTiming): Promise<T>;
}

Properties

contentTypeParser? +helia +logger +

Methods

getBlockstore +handleServerTiming +

Properties

Optional contentTypeParser

contentTypeParser?: ContentTypeParser

helia

helia: Helia

logger

logger: ComponentLogger

Methods

getBlockstore

handleServerTiming

Settings

Member Visibility

Theme

On This Page

contentTypeParserhelialoggergetBlockstorehandleServerTiming
\ No newline at end of file diff --git a/interfaces/_helia_verified_fetch.ResourceDetail.html b/interfaces/_helia_verified_fetch.ResourceDetail.html new file mode 100644 index 00000000..03b2bb56 --- /dev/null +++ b/interfaces/_helia_verified_fetch.ResourceDetail.html @@ -0,0 +1,2 @@ +ResourceDetail | Helia Verified Fetch

Interface ResourceDetail

interface ResourceDetail {
    resource: Resource;
}

Properties

resource +

Properties

resource

resource: Resource

Settings

Member Visibility

Theme

On This Page

resource
\ No newline at end of file diff --git a/interfaces/index.VerifiedFetch.html b/interfaces/_helia_verified_fetch.VerifiedFetch.html similarity index 50% rename from interfaces/index.VerifiedFetch.html rename to interfaces/_helia_verified_fetch.VerifiedFetch.html index c5f45932..351f1e5c 100644 --- a/interfaces/index.VerifiedFetch.html +++ b/interfaces/_helia_verified_fetch.VerifiedFetch.html @@ -1,3 +1,3 @@ -VerifiedFetch | @helia/verified-fetch

Interface VerifiedFetch

interface VerifiedFetch {
    start(): Promise<void>;
    stop(): Promise<void>;
    (resource, options?): Promise<Response>;
}

Methods

start -stop -

Methods

start

stop

Settings

Member Visibility

Theme

On This Page

startstop
\ No newline at end of file +VerifiedFetch | Helia Verified Fetch

Interface VerifiedFetch

interface VerifiedFetch {
    start(): Promise<void>;
    stop(): Promise<void>;
    (resource, options?): Promise<Response>;
}

Methods

start +stop +

Methods

start

stop

Settings

Member Visibility

Theme

On This Page

startstop
\ No newline at end of file diff --git a/interfaces/index.VerifiedFetchInit.html b/interfaces/_helia_verified_fetch.VerifiedFetchInit.html similarity index 62% rename from interfaces/index.VerifiedFetchInit.html rename to interfaces/_helia_verified_fetch.VerifiedFetchInit.html index e4cb408b..4f124427 100644 --- a/interfaces/index.VerifiedFetchInit.html +++ b/interfaces/_helia_verified_fetch.VerifiedFetchInit.html @@ -1,40 +1,40 @@ -VerifiedFetchInit | @helia/verified-fetch

Interface VerifiedFetchInit

Options for the fetch function returned by createVerifiedFetch.

+VerifiedFetchInit | Helia Verified Fetch

Interface VerifiedFetchInit

Options for the fetch function returned by createVerifiedFetch.

This interface contains all the same fields as the options object passed to fetch in browsers, plus an onProgress option to listen for progress events.

-
interface VerifiedFetchInit {
    allowInsecure?: boolean;
    allowLocal?: boolean;
    body?: null | BodyInit;
    cache?: RequestCache;
    credentials?: RequestCredentials;
    headers?: HeadersInit;
    integrity?: string;
    keepalive?: boolean;
    method?: string;
    mode?: RequestMode;
    onProgress?: ((evt) => void);
    priority?: RequestPriority;
    redirect?: RequestRedirect;
    referrer?: string;
    referrerPolicy?: ReferrerPolicy;
    session?: boolean;
    signal?: null | AbortSignal;
    window?: null;
    withServerTiming?: boolean;
}

Hierarchy

Properties

allowInsecure? -allowLocal? -body? -cache? -credentials? -headers? -integrity? -keepalive? -method? -mode? -onProgress? -priority? -redirect? -referrer? -referrerPolicy? -session? -signal? -window? -withServerTiming? +
interface VerifiedFetchInit {
    allowInsecure?: boolean;
    allowLocal?: boolean;
    body?: null | BodyInit;
    cache?: RequestCache;
    credentials?: RequestCredentials;
    headers?: HeadersInit;
    integrity?: string;
    keepalive?: boolean;
    method?: string;
    mode?: RequestMode;
    onProgress?: ((evt) => void);
    priority?: RequestPriority;
    redirect?: RequestRedirect;
    referrer?: string;
    referrerPolicy?: ReferrerPolicy;
    session?: boolean;
    signal?: null | AbortSignal;
    window?: null;
    withServerTiming?: boolean;
}

Hierarchy

Properties

allowInsecure? +allowLocal? +body? +cache? +credentials? +headers? +integrity? +keepalive? +method? +mode? +onProgress? +priority? +redirect? +referrer? +referrerPolicy? +session? +signal? +window? +withServerTiming?

Properties

Optional allowInsecure

allowInsecure?: boolean

By default we will not connect to any gateways over HTTP addresses, requring HTTPS connections instead. This is because it will cause "mixed-content" errors to appear in the console when running in secure browser contexts.

Pass true here to connect to insecure Gateways as well, this may be useful in testing environments.

-

Default

false
+

Default

false

Optional allowLocal

allowLocal?: boolean

By default we will not connect to any HTTP Gateways providers over local or loopback addresses, this is because they are typically running on remote peers that have published private addresses by mistate.

Pass true here to connect to local Gateways as well, this may be useful in testing environments.

-

Default

false
+

Default

false

Optional body

body?: null | BodyInit

A BodyInit object or null to set request's body.

Optional cache

cache?: RequestCache

A string indicating how the request will interact with the browser's cache to set request's cache.

@@ -44,7 +44,7 @@

Optional keepalive

keepalive?: boolean

A boolean to set request's keepalive.

Optional method

method?: string

A string to set request's method.

Optional mode

mode?: RequestMode

A string to indicate whether the request will use CORS, or will be restricted to same-origin URLs. Sets request's mode.

-

Optional onProgress

onProgress?: ((evt) => void)

Type declaration

Optional priority

priority?: RequestPriority

Optional redirect

redirect?: RequestRedirect

A string indicating whether request follows redirects, results in an error upon encountering a redirect, or returns the redirect (in an opaque fashion). Sets request's redirect.

+

Optional onProgress

onProgress?: ((evt) => void)

Type declaration

Optional priority

priority?: RequestPriority

Optional redirect

redirect?: RequestRedirect

A string indicating whether request follows redirects, results in an error upon encountering a redirect, or returns the redirect (in an opaque fashion). Sets request's redirect.

Optional referrer

referrer?: string

A string whose value is a same-origin URL, "about:client", or the empty string, to set request's referrer.

Optional referrerPolicy

referrerPolicy?: ReferrerPolicy

A referrer policy to set request's referrerPolicy.

Optional session

session?: boolean

If true, try to create a blockstore session - this can reduce overall @@ -56,12 +56,12 @@ is, requests for https://qmfoo.ipfs.localhost/bar.txt and https://qmfoo.ipfs.localhost/baz.txt would use the same session, if this argument is true for both fetch requests.

-

Default

true
+

Default

true

Optional signal

signal?: null | AbortSignal

An AbortSignal to set request's signal.

Optional window

window?: null

Can only be null. Used to disassociate request from any Window.

Optional withServerTiming

withServerTiming?: boolean

Whether to include server-timing headers in the response for an individual request.

-

Default

false
+

Default

false

See

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Server-Timing

-

Settings

Member Visibility

Theme

On This Page

allowInsecureallowLocalbodycachecredentialsheadersintegritykeepalivemethodmodeonProgresspriorityredirectreferrerreferrerPolicysessionsignalwindowwithServerTiming
\ No newline at end of file +

Settings

Member Visibility

Theme

On This Page

allowInsecureallowLocalbodycachecredentialsheadersintegritykeepalivemethodmodeonProgresspriorityredirectreferrerreferrerPolicysessionsignalwindowwithServerTiming
\ No newline at end of file diff --git a/interfaces/_helia_verified_fetch.VerifiedFetchPluginFactory.html b/interfaces/_helia_verified_fetch.VerifiedFetchPluginFactory.html new file mode 100644 index 00000000..9293766f --- /dev/null +++ b/interfaces/_helia_verified_fetch.VerifiedFetchPluginFactory.html @@ -0,0 +1 @@ +VerifiedFetchPluginFactory | Helia Verified Fetch

Interface VerifiedFetchPluginFactory

interface VerifiedFetchPluginFactory ((options) => VerifiedFetchPlugin)

Settings

Member Visibility

Theme

\ No newline at end of file diff --git a/interfaces/index.CIDDetail.html b/interfaces/index.CIDDetail.html deleted file mode 100644 index 75c78304..00000000 --- a/interfaces/index.CIDDetail.html +++ /dev/null @@ -1,3 +0,0 @@ -CIDDetail | @helia/verified-fetch

Interface CIDDetail

interface CIDDetail {
    cid: CID<unknown, number, number, Version>;
    path: string;
}

Hierarchy (view full)

Properties

cid -path -

Properties

cid

cid: CID<unknown, number, number, Version>

path

path: string

Settings

Member Visibility

Theme

On This Page

cidpath
\ No newline at end of file diff --git a/interfaces/index.CIDDetailError.html b/interfaces/index.CIDDetailError.html deleted file mode 100644 index 06322777..00000000 --- a/interfaces/index.CIDDetailError.html +++ /dev/null @@ -1,4 +0,0 @@ -CIDDetailError | @helia/verified-fetch

Interface CIDDetailError

interface CIDDetailError {
    cid: CID<unknown, number, number, Version>;
    error: Error;
    path: string;
}

Hierarchy (view full)

Properties

cid -error -path -

Properties

cid

cid: CID<unknown, number, number, Version>

error

error: Error

path

path: string

Settings

Member Visibility

Theme

On This Page

ciderrorpath
\ No newline at end of file diff --git a/interfaces/index.PluginContext.html b/interfaces/index.PluginContext.html deleted file mode 100644 index 80247e39..00000000 --- a/interfaces/index.PluginContext.html +++ /dev/null @@ -1,23 +0,0 @@ -PluginContext | @helia/verified-fetch

Interface PluginContext

Represents the ephemeral, modifiable state used by the pipeline.

-
    -
  • Mutable: Evolves as you walk the plugin chain.
    • -
  • Shared Data: Allows plugins to communicate partial results, discovered data, or interim errors.
    • -
  • Ephemeral: Typically discarded once fetch(...) completes.
    • -
-
interface PluginContext {
    accept?: string;
    cid: CID<unknown, number, number, Version>;
    directoryEntries?: UnixFSEntry[];
    errors?: PluginError[];
    isDirectory?: boolean;
    modified: number;
    options?: Omit<VerifiedFetchInit, "signal"> & AbortOptions;
    path: string;
    pathDetails?: PathWalkerResponse;
    query: ParsedUrlQuery;
    reqFormat?: RequestFormatShorthand;
    resource: string;
    withServerTiming?: boolean;
    onProgress?(evt): void;
    [key: string]: unknown;
}

Indexable

[key: string]: unknown

Properties

accept? -cid -directoryEntries? -errors? -isDirectory? -modified -options? -path -pathDetails? -query -reqFormat? -resource -withServerTiming? -

Methods

onProgress? -

Properties

Optional Readonly accept

accept?: string

Readonly cid

cid: CID<unknown, number, number, Version>

Optional directoryEntries

directoryEntries?: UnixFSEntry[]

Optional errors

errors?: PluginError[]

Optional isDirectory

isDirectory?: boolean

modified

modified: number

The last time the context is modified, so we know whether a plugin has modified it. -A plugin should increment this value if it modifies the context.

-

Optional options

options?: Omit<VerifiedFetchInit, "signal"> & AbortOptions

Readonly path

path: string

Optional pathDetails

pathDetails?: PathWalkerResponse

query

query: ParsedUrlQuery

Optional reqFormat

reqFormat?: RequestFormatShorthand

Readonly resource

resource: string

Optional withServerTiming

withServerTiming?: boolean

Methods

Optional onProgress

Settings

Member Visibility

Theme

On This Page

acceptciddirectoryEntrieserrorsisDirectorymodifiedoptionspathpathDetailsqueryreqFormatresourcewithServerTimingonProgress
\ No newline at end of file diff --git a/interfaces/index.PluginOptions.html b/interfaces/index.PluginOptions.html deleted file mode 100644 index 422412de..00000000 --- a/interfaces/index.PluginOptions.html +++ /dev/null @@ -1,11 +0,0 @@ -PluginOptions | @helia/verified-fetch

Interface PluginOptions

Contains common components and functions required by plugins to handle a request.

-
    -
  • Read-Only: Plugins can read but shouldn’t rewrite them.
    • -
  • Persistent: Relevant even after the request completes (e.g., logging or metrics).
    • -
-
interface PluginOptions {
    contentTypeParser?: ContentTypeParser;
    helia: Helia;
    logger: ComponentLogger;
    getBlockstore(cid, resource, useSession?, options?): Blockstore<{}, {}, {}, {}, {}, {}, {}, {}>;
    handleServerTiming<T>(name, description, fn, withServerTiming): Promise<T>;
}

Properties

contentTypeParser? -helia -logger -

Methods

getBlockstore -handleServerTiming -

Properties

Optional contentTypeParser

contentTypeParser?: ContentTypeParser

helia

helia: Helia

logger

logger: ComponentLogger

Methods

getBlockstore

handleServerTiming

Settings

Member Visibility

Theme

On This Page

contentTypeParserhelialoggergetBlockstorehandleServerTiming
\ No newline at end of file diff --git a/interfaces/index.ResourceDetail.html b/interfaces/index.ResourceDetail.html deleted file mode 100644 index 861ca36e..00000000 --- a/interfaces/index.ResourceDetail.html +++ /dev/null @@ -1,2 +0,0 @@ -ResourceDetail | @helia/verified-fetch

Interface ResourceDetail

interface ResourceDetail {
    resource: Resource;
}

Properties

resource -

Properties

resource

resource: Resource

Settings

Member Visibility

Theme

On This Page

resource
\ No newline at end of file diff --git a/interfaces/index.VerifiedFetchPluginFactory.html b/interfaces/index.VerifiedFetchPluginFactory.html deleted file mode 100644 index f615c1a0..00000000 --- a/interfaces/index.VerifiedFetchPluginFactory.html +++ /dev/null @@ -1 +0,0 @@ -VerifiedFetchPluginFactory | @helia/verified-fetch

Interface VerifiedFetchPluginFactory

interface VerifiedFetchPluginFactory ((options) => VerifiedFetchPlugin)

Settings

Member Visibility

Theme

\ No newline at end of file diff --git a/modules/_helia_verified_fetch.html b/modules/_helia_verified_fetch.html new file mode 100644 index 00000000..4df6b768 --- /dev/null +++ b/modules/_helia_verified_fetch.html @@ -0,0 +1,744 @@ +@helia/verified-fetch | Helia Verified Fetch

Module @helia/verified-fetch

@helia/verified-fetch provides a fetch-like API for retrieving content from the IPFS network.

+

All content is retrieved in a trustless manner, and the integrity of all bytes are verified by comparing hashes of the data.

+

By default, providers for CIDs are found using delegated routing endpoints.

+

Data is retrieved using the following strategies:

+
    +
  • Directly from providers, using Bitswap over WebSockets and WebRTC if available.
    • +
  • Directly from providers exposing a trustless gateway over HTTPS.
    • +
  • As a fallback, if no providers reachable from a browser are found, data is retrieved using recursive gateways, e.g. trustless-gateway.link which can be configured.
    • +
+

This is a marked improvement over fetch which offers no such protections and is vulnerable to all sorts of attacks like Content Spoofing, DNS Hijacking, etc.

+

A verifiedFetch function is exported to get up and running quickly, and a createVerifiedFetch function is also available that allows customizing the underlying Helia node for complete control over how content is retrieved.

+

Browser-cache-friendly Response objects are returned which should be instantly familiar to web developers.

+

Learn more in the announcement blog post and check out the ready-to-run example.

+

You may use any supported resource argument to fetch content:

+
    +
  • CID instance
    • +
  • IPFS URL
    • +
  • IPNS URL
    • +
+

Example: Getting started

import { verifiedFetch } from '@helia/verified-fetch'

const resp = await verifiedFetch('ipfs://bafy...')

const json = await resp.json()
+
+

Example: Using a CID instance to fetch JSON

import { verifiedFetch } from '@helia/verified-fetch'
import { CID } from 'multiformats/cid'

const cid = CID.parse('bafyFoo') // some json file
const response = await verifiedFetch(cid)
const json = await response.json()
+
+

Example: Using IPFS protocol to fetch an image

import { verifiedFetch } from '@helia/verified-fetch'

const response = await verifiedFetch('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

import { verifiedFetch } from '@helia/verified-fetch'

const response = await verifiedFetch('ipns://mydomain.com/path/to/very-long-file.log')
const bigFileStreamReader = await response.body?.getReader()
+
+

Configuration

Custom HTTP gateways and routers

Out of the box @helia/verified-fetch uses a default set of trustless gateways for fetching blocks and HTTP delegated routers for performing routing tasks - looking up peers, resolving/publishing IPNS names, etc.

+

It's possible to override these by passing gateways and routers keys to the createVerifiedFetch function:

+

Example: Configuring gateways and routers

import { createVerifiedFetch } from '@helia/verified-fetch'

const fetch = await createVerifiedFetch({
  gateways: ['https://trustless-gateway.link'],
  routers: ['http://delegated-ipfs.dev']
})

const resp = await fetch('ipfs://bafy...')

const json = await resp.json()
+
+

Usage with customized Helia

For full control of how @helia/verified-fetch fetches content from the distributed web you can pass a preconfigured Helia node to createVerifiedFetch.

+

The helia module is configured with a libp2p node that is suited for decentralized applications, alternatively @helia/http is available which uses HTTP gateways for all network operations.

+

You can see variations of Helia and js-libp2p configuration options at https://ipfs.github.io/helia/interfaces/helia.HeliaInit.html.

+
import { trustlessGateway } from '@helia/block-brokers'
import { createHeliaHTTP } from '@helia/http'
import { delegatedHTTPRouting, httpGatewayRouting } from '@helia/routers'
import { createVerifiedFetch } from '@helia/verified-fetch'

const fetch = await createVerifiedFetch(
  await createHeliaHTTP({
    blockBrokers: [
      trustlessGateway()
    ],
    routers: [
      delegatedHTTPRouting('http://delegated-ipfs.dev'),
      httpGatewayRouting({
        gateways: ['https://mygateway.example.net', 'https://trustless-gateway.link']
      })
    ]
  })
)

const resp = await fetch('ipfs://bafy...')

const json = await resp.json()
+
+

Custom content-type parsing

By default, if the response can be parsed as JSON, @helia/verified-fetch sets the Content-Type header as application/json, otherwise it sets it as application/octet-stream - this is because the .json(), .text(), .blob(), and .arrayBuffer() methods will usually work as expected without a detailed content type.

+

If you require an accurate content-type you can provide a contentTypeParser function as an option to createVerifiedFetch to handle parsing the content type.

+

The function you provide will be called with the first chunk of bytes from the file and should return a string or a promise of a string.

+

Example: Customizing content-type parsing

import { createVerifiedFetch } from '@helia/verified-fetch'
import { fileTypeFromBuffer } from '@sgtpooki/file-type'

const fetch = await createVerifiedFetch({
  gateways: ['https://trustless-gateway.link'],
  routers: ['http://delegated-ipfs.dev']
}, {
  contentTypeParser: async (bytes) => {
    // call to some magic-byte recognition library like magic-bytes, file-type, or your own custom byte recognition
    const result = await fileTypeFromBuffer(bytes)
    return result?.mime
  }
})
+
+

Custom DNS resolvers

If you don't want to leak DNS queries to the default resolvers, you can provide your own list of DNS resolvers to createVerifiedFetch.

+

Note that you do not need to provide both a DNS-over-HTTPS and a DNS-over-JSON resolver, and you should prefer dnsJsonOverHttps resolvers for usage in the browser for a smaller bundle size. See https://github.com/ipfs/helia/tree/main/packages/ipns#example---using-dns-json-over-https for more information.

+

Example: Customizing DNS resolvers

import { createVerifiedFetch } from '@helia/verified-fetch'
import { dnsJsonOverHttps, dnsOverHttps } from '@multiformats/dns/resolvers'

const fetch = await createVerifiedFetch({
  gateways: ['https://trustless-gateway.link'],
  routers: ['http://delegated-ipfs.dev'],
  dnsResolvers: [
    dnsJsonOverHttps('https://my-dns-resolver.example.com/dns-json'),
    dnsOverHttps('https://my-dns-resolver.example.com/dns-query')
  ]
})
+
+

Example: Customizing DNS per-TLD resolvers

DNS resolvers can be configured to only service DNS queries for specific +TLDs:

+
import { createVerifiedFetch } from '@helia/verified-fetch'
import { dnsJsonOverHttps, dnsOverHttps } from '@multiformats/dns/resolvers'

const fetch = await createVerifiedFetch({
  gateways: ['https://trustless-gateway.link'],
  routers: ['http://delegated-ipfs.dev'],
  dnsResolvers: {
    // this resolver will only be used for `.com` domains (note - this could
    // also be an array of resolvers)
    'com.': dnsJsonOverHttps('https://my-dns-resolver.example.com/dns-json'),
    // this resolver will be used for everything else (note - this could
    // also be an array of resolvers)
    '.': dnsOverHttps('https://my-dns-resolver.example.com/dns-query')
  }
})
+
+

Custom Hashers

By default, @helia/verified-fetch supports sha256, sha512, and identity hashers.

+

If you need to use a different hasher, you can provide a custom hasher function as an option to createVerifiedFetch.

+

Example: Passing a custom hashing function

import { createVerifiedFetch } from '@helia/verified-fetch'
import { blake2b256 } from '@multiformats/blake2/blake2b'

const verifiedFetch = await createVerifiedFetch({
  gateways: ['https://ipfs.io'],
  hashers: [blake2b256]
})

const resp = await verifiedFetch('ipfs://cid-using-blake2b256')
+
+

IPLD codec handling

IPFS supports several data formats (typically referred to as codecs) which are included in the CID. @helia/verified-fetch attempts to abstract away some of the details for easier consumption.

+

DAG-PB

DAG-PB is the codec we are most likely to encounter, it is what UnixFS uses under the hood.

+
Using the DAG-PB codec as a Blob
import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://Qmfoo')
const blob = await res.blob()

console.info(blob) // Blob { size: x, type: 'application/octet-stream' }
+
+
Using the DAG-PB codec as an ArrayBuffer
import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://Qmfoo')
const buf = await res.arrayBuffer()

console.info(buf) // ArrayBuffer { [Uint8Contents]: < ... >, byteLength: x }
+
+
Using the DAG-PB codec as a stream
import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://Qmfoo')
const reader = res.body?.getReader()

if (reader == null) {
  throw new Error('Could not create reader from response body')
}

while (true) {
  const next = await reader.read()

  if (next?.done === true) {
    break
  }

  if (next?.value != null) {
    console.info(next.value) // Uint8Array(x) [ ... ]
  }
}
+
+
Content-Type

When fetching DAG-PB data, the content type will be set to application/octet-stream unless a custom content-type parser is configured.

+

JSON

The JSON codec is a very simple codec, a block parseable with this codec is a JSON string encoded into a Uint8Array.

+
Using the JSON codec
import * as json from 'multiformats/codecs/json'

const block = new TextEncoder().encode('{ "hello": "world" }')
const obj = json.decode(block)

console.info(obj) // { hello: 'world' }
+
+
Content-Type

When the JSON codec is encountered, the Content-Type header of the response will be set to application/json.

+

DAG-JSON

DAG-JSON expands on the JSON codec, adding the ability to contain CIDs which act as links to other blocks, and byte arrays.

+

CIDs and byte arrays are represented using special object structures with a single "/" property.

+

Using DAG-JSON has two important caveats:

+
    +
  1. Your JSON structure cannot contain an object with only a "/" property, as it will be interpreted as a special type.
    2. +
  2. Since JSON has no technical limit on number sizes, DAG-JSON also allows numbers larger than Number.MAX_SAFE_INTEGER. JavaScript requires use of BigInts to represent numbers larger than this, and JSON.parse does not support them, so precision will be lost.
    3. +
+

Otherwise this codec follows the same rules as the JSON codec.

+
Using the DAG-JSON codec
import * as dagJson from '@ipld/dag-json'

const block = new TextEncoder().encode(`{
  "hello": "world",
  "cid": {
    "/": "baeaaac3imvwgy3zao5xxe3de"
  },
  "buf": {
    "/": {
      "bytes": "AAECAwQ"
    }
  }
}`)

const obj = dagJson.decode(block)

console.info(obj)
// {
// hello: 'world',
// cid: CID(baeaaac3imvwgy3zao5xxe3de),
// buf: Uint8Array(5) [ 0, 1, 2, 3, 4 ]
// }
+
+
Content-Type

When the DAG-JSON codec is encountered in the requested CID, the Content-Type header of the response will be set to application/json.

+

DAG-JSON data can be parsed from the response by using the .json() function, which will return CIDs/byte arrays as plain { "/": ... } objects:

+
import { verifiedFetch } from '@helia/verified-fetch'
import * as dagJson from '@ipld/dag-json'

const res = await verifiedFetch('ipfs://bafyDAGJSON')

// either:
const obj = await res.json()
console.info(obj.cid) // { "/": "baeaaac3imvwgy3zao5xxe3de" }
console.info(obj.buf) // { "/": { "bytes": "AAECAwQ" } }
+
+

Alternatively, it can be decoded using the @ipld/dag-json module and the .arrayBuffer() method, in which case you will get CID objects and Uint8Arrays:

+
import { verifiedFetch } from '@helia/verified-fetch'
import * as dagJson from '@ipld/dag-json'

const res = await verifiedFetch('ipfs://bafyDAGJSON')

// or:
const obj = dagJson.decode<any>(await res.arrayBuffer())
console.info(obj.cid) // CID(baeaaac3imvwgy3zao5xxe3de)
console.info(obj.buf) // Uint8Array(5) [ 0, 1, 2, 3, 4 ]
+
+

DAG-CBOR

DAG-CBOR uses the Concise Binary Object Representation format for serialization instead of JSON.

+

This supports more datatypes in a safer way than JSON and is smaller on the wire to boot so is usually preferable to JSON or DAG-JSON.

+
Content-Type

Not all data types supported by DAG-CBOR can be successfully turned into JSON and back into the same binary form.

+

When a decoded block can be round-tripped to JSON, the Content-Type will be set to application/json. In this case the .json() method on the Response object can be used to obtain an object representation of the response.

+

When it cannot, the Content-Type will be application/octet-stream - in this case the @ipld/dag-json module must be used to deserialize the return value from .arrayBuffer().

+
Detecting JSON-safe DAG-CBOR

If the Content-Type header of the response is application/json, the .json() method may be used to access the response body in object form, otherwise the .arrayBuffer() method must be used to decode the raw bytes using the @ipld/dag-cbor module.

+
import { verifiedFetch } from '@helia/verified-fetch'
import * as dagCbor from '@ipld/dag-cbor'

const res = await verifiedFetch('ipfs://bafyDagCborCID')
let obj

if (res.headers.get('Content-Type') === 'application/json') {
  // DAG-CBOR data can be safely decoded as JSON
  obj = await res.json()
} else {
  // response contains non-JSON friendly data types
  obj = dagCbor.decode(await res.arrayBuffer())
}

console.info(obj) // ...
+
+

The Accept header

The Accept header can be passed to override certain response processing, or to ensure that the final Content-Type of the response is the one that is expected.

+

If the final Content-Type does not match the Accept header, or if the content cannot be represented in the format dictated by the Accept header, or you have configured a custom content type parser, and that parser returns a value that isn't in the accept header, a 406: Not Acceptable response will be returned:

+
import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://bafyJPEGImageCID', {
  headers: {
    accept: 'image/png'
  }
})

console.info(res.status) // 406 - the image was a JPEG but we specified PNG as the accept header
+
+

It can also be used to skip processing the data from some formats such as DAG-CBOR if you wish to handle decoding it yourself:

+
import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://bafyDAGCBORCID', {
  headers: {
    accept: 'application/octet-stream'
  }
})

console.info(res.headers.get('accept')) // application/octet-stream
const buf = await res.arrayBuffer() // raw bytes, not processed as JSON
+
+

Redirects

If a requested URL contains a path component, that path component resolves to +a UnixFS directory, but the URL does not have a trailing slash, one will be +added to form a canonical URL for that resource, otherwise the request will +be resolved as normal.

+
import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://bafyfoo/path/to/dir')

console.info(res.url) // ipfs://bafyfoo/path/to/dir/
+
+

It's possible to prevent this behaviour and/or handle a redirect manually +through use of the redirect +option.

+

Example: Redirect: follow

This is the default value and is what happens if no value is specified.

+
import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://bafyfoo/path/to/dir', {
  redirect: 'follow'
})

console.info(res.status) // 200
console.info(res.url) // ipfs://bafyfoo/path/to/dir/
console.info(res.redirected) // true
+
+

Example: Redirect: error

This causes a TypeError to be thrown if a URL would cause a redirect.

+

import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://bafyfoo/path/to/dir', {
  redirect: 'error'
})
// throw TypeError('Failed to fetch')
+
+

Example: Redirect: manual

Manual redirects allow the user to process the redirect. A 301 +is returned, and the location to redirect to is available as the "location" +response header.

+

This differs slightly from HTTP fetch which returns an opaque response as the +browser itself is expected to process the redirect and hide all details from +the user.

+

import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://bafyfoo/path/to/dir', {
  redirect: 'manual'
})

console.info(res.status) // 301
console.info(res.url) // ipfs://bafyfoo/path/to/dir
console.info(res.redirected) // false
console.info(res.headers.get('location')) // ipfs://bafyfoo/path/to/dir/
+
+

Comparison to fetch

This module attempts to act as similarly to the fetch() API as possible.

+

The fetch() API takes two parameters:

+
    +
  1. A resource
    2. +
  2. An options object
    3. +
+

Resource argument

This library supports the following methods of fetching web3 content from IPFS:

+
    +
  1. IPFS protocol: ipfs://<cidv0> & ipfs://<cidv1>
    2. +
  2. IPNS protocol: ipns://<peerId> & ipns://<publicKey> & ipns://<hostUri_Supporting_DnsLink_TxtRecords>
    3. +
  3. CID instances: An actual CID instance CID.parse('bafy...')
    4. +
+

As well as support for pathing & params for items 1 & 2 above according to IPFS - Path Gateway Specification & IPFS - Trustless Gateway Specification. Further refinement of those specifications specifically for web-based scenarios can be found in the Web Pathing Specification IPIP.

+

If you pass a CID instance, it assumes you want the content for that specific CID only, and does 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 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. +
  2. https://specs.ipfs.tech/http-gateways/trustless-gateway/#request-headers
    3. +
  3. https://specs.ipfs.tech/http-gateways/subdomain-gateway/#request-headers
    4. +
+

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. +
  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 parameter.
    3. +
  3. headers - An object of headers to be sent with the request. Best effort to adhere to the Fetch API headers parameter. +
    4. +
  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 parameter.
    5. +
  5. body - An object that specifies the body of the request. Best effort to adhere to the Fetch API body parameter.
    6. +
  6. cache - Will basically act as force-cache for the request. Best effort to adhere to the Fetch API cache parameter.
    7. +
+

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.
      • +
    +
    2. +
+

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
    2. +
  2. IPIP-0402: Partial CAR Support on Trustless Gateways
    3. +
  3. IPIP-0386: Subdomain Gateway Interop with _redirects
    4. +
  4. IPIP-0328: JSON and CBOR Response Formats on HTTP Gateways
    5. +
  5. IPIP-0288: TAR Response Format on HTTP Gateways
    6. +
+

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 via a ReadableStream 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, this library will not support it, but you can use the helia library directly for those use cases. See 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.
    • +
+

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. Instead, users should request aplication/vnd.ipld.car or use the helia library directly for this use case.
    • +
  • Others? Open an issue or PR!
    • +
+

Response headers

This library will set the HTTP Response headers to the appropriate values for the content type according to the appropriate IPFS Specifications.

+

Some known header specifications:

+ +

Server Timing headers

By default, we do not include Server Timing headers in responses. If you want to include them, you can pass an +withServerTiming option to the createVerifiedFetch function to include them in all future responses. You can +also pass the withServerTiming option to each fetch call to include them only for that specific response.

+

See PR where this was added, https://github.com/ipfs/helia-verified-fetch/pull/164, for more information.

+

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. +
  2. TypeError - If the options argument is passed and not an object.
    3. +
  3. TypeError - If the options argument is passed and is malformed.
    4. +
  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.
    5. +
+

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. +

  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:

    +
    3. +
+
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]
+
+
    +
  1. 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.
      • +
    +
    2. +
+

Please see the original discussion on extensibility in Issue #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>
      • +
    +
    2. +
+

Example: custom plugin

   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)
+
+
    +

  1. Integrate Your Plugin:

    +

    Add your custom plugin to Verified‑Fetch’s plugin list when instantiating Verified‑Fetch:

    +
    2. +
+

Example: Integrate custom plugin

   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

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.

+

+ + Helia logo + +

+ +

@helia/verified-fetch

ipfs.tech +Discuss +codecov +CI

+
+

A fetch-like API for obtaining verified & trustless IPFS content on the web

+
+

About

+ +

@helia/verified-fetch provides a fetch-like API for retrieving content from the IPFS network.

+

All content is retrieved in a trustless manner, and the integrity of all bytes are verified by comparing hashes of the data.

+

By default, providers for CIDs are found using delegated routing endpoints.

+

Data is retrieved using the following strategies:

+
    +
  • Directly from providers, using Bitswap over WebSockets and WebRTC if available.
    • +
  • Directly from providers exposing a trustless gateway over HTTPS.
    • +
  • As a fallback, if no providers reachable from a browser are found, data is retrieved using recursive gateways, e.g. trustless-gateway.link which can be configured.
    • +
+

This is a marked improvement over fetch which offers no such protections and is vulnerable to all sorts of attacks like Content Spoofing, DNS Hijacking, etc.

+

A verifiedFetch function is exported to get up and running quickly, and a createVerifiedFetch function is also available that allows customizing the underlying Helia node for complete control over how content is retrieved.

+

Browser-cache-friendly Response objects are returned which should be instantly familiar to web developers.

+

Learn more in the announcement blog post and check out the ready-to-run example.

+

You may use any supported resource argument to fetch content:

+
    +
  • CID instance
    • +
  • IPFS URL
    • +
  • IPNS URL
    • +
+

Example - Getting started

import { verifiedFetch } from '@helia/verified-fetch'

const resp = await verifiedFetch('ipfs://bafy...')

const json = await resp.json()
+
+

Example - Using a CID instance to fetch JSON

import { verifiedFetch } from '@helia/verified-fetch'
import { CID } from 'multiformats/cid'

const cid = CID.parse('bafyFoo') // some json file
const response = await verifiedFetch(cid)
const json = await response.json()
+
+

Example - Using IPFS protocol to fetch an image

import { verifiedFetch } from '@helia/verified-fetch'

const response = await verifiedFetch('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

import { verifiedFetch } from '@helia/verified-fetch'

const response = await verifiedFetch('ipns://mydomain.com/path/to/very-long-file.log')
const bigFileStreamReader = await response.body?.getReader()
+
+

Configuration

Custom HTTP gateways and routers

Out of the box @helia/verified-fetch uses a default set of trustless gateways for fetching blocks and HTTP delegated routers for performing routing tasks - looking up peers, resolving/publishing IPNS names, etc.

+

It's possible to override these by passing gateways and routers keys to the createVerifiedFetch function:

+

Example - Configuring gateways and routers

import { createVerifiedFetch } from '@helia/verified-fetch'

const fetch = await createVerifiedFetch({
  gateways: ['https://trustless-gateway.link'],
  routers: ['http://delegated-ipfs.dev']
})

const resp = await fetch('ipfs://bafy...')

const json = await resp.json()
+
+

Usage with customized Helia

For full control of how @helia/verified-fetch fetches content from the distributed web you can pass a preconfigured Helia node to createVerifiedFetch.

+

The helia module is configured with a libp2p node that is suited for decentralized applications, alternatively @helia/http is available which uses HTTP gateways for all network operations.

+

You can see variations of Helia and js-libp2p configuration options at https://ipfs.github.io/helia/interfaces/helia.HeliaInit.html.

+
import { trustlessGateway } from '@helia/block-brokers'
import { createHeliaHTTP } from '@helia/http'
import { delegatedHTTPRouting, httpGatewayRouting } from '@helia/routers'
import { createVerifiedFetch } from '@helia/verified-fetch'

const fetch = await createVerifiedFetch(
  await createHeliaHTTP({
    blockBrokers: [
      trustlessGateway()
    ],
    routers: [
      delegatedHTTPRouting('http://delegated-ipfs.dev'),
      httpGatewayRouting({
        gateways: ['https://mygateway.example.net', 'https://trustless-gateway.link']
      })
    ]
  })
)

const resp = await fetch('ipfs://bafy...')

const json = await resp.json()
+
+

Custom content-type parsing

By default, if the response can be parsed as JSON, @helia/verified-fetch sets the Content-Type header as application/json, otherwise it sets it as application/octet-stream - this is because the .json(), .text(), .blob(), and .arrayBuffer() methods will usually work as expected without a detailed content type.

+

If you require an accurate content-type you can provide a contentTypeParser function as an option to createVerifiedFetch to handle parsing the content type.

+

The function you provide will be called with the first chunk of bytes from the file and should return a string or a promise of a string.

+

Example - Customizing content-type parsing

import { createVerifiedFetch } from '@helia/verified-fetch'
import { fileTypeFromBuffer } from '@sgtpooki/file-type'

const fetch = await createVerifiedFetch({
  gateways: ['https://trustless-gateway.link'],
  routers: ['http://delegated-ipfs.dev']
}, {
  contentTypeParser: async (bytes) => {
    // call to some magic-byte recognition library like magic-bytes, file-type, or your own custom byte recognition
    const result = await fileTypeFromBuffer(bytes)
    return result?.mime
  }
})
+
+

Custom DNS resolvers

If you don't want to leak DNS queries to the default resolvers, you can provide your own list of DNS resolvers to createVerifiedFetch.

+

Note that you do not need to provide both a DNS-over-HTTPS and a DNS-over-JSON resolver, and you should prefer dnsJsonOverHttps resolvers for usage in the browser for a smaller bundle size. See https://github.com/ipfs/helia/tree/main/packages/ipns#example---using-dns-json-over-https for more information.

+

Example - Customizing DNS resolvers

import { createVerifiedFetch } from '@helia/verified-fetch'
import { dnsJsonOverHttps, dnsOverHttps } from '@multiformats/dns/resolvers'

const fetch = await createVerifiedFetch({
  gateways: ['https://trustless-gateway.link'],
  routers: ['http://delegated-ipfs.dev'],
  dnsResolvers: [
    dnsJsonOverHttps('https://my-dns-resolver.example.com/dns-json'),
    dnsOverHttps('https://my-dns-resolver.example.com/dns-query')
  ]
})
+
+

Example - Customizing DNS per-TLD resolvers

DNS resolvers can be configured to only service DNS queries for specific +TLDs:

+
import { createVerifiedFetch } from '@helia/verified-fetch'
import { dnsJsonOverHttps, dnsOverHttps } from '@multiformats/dns/resolvers'

const fetch = await createVerifiedFetch({
  gateways: ['https://trustless-gateway.link'],
  routers: ['http://delegated-ipfs.dev'],
  dnsResolvers: {
    // this resolver will only be used for `.com` domains (note - this could
    // also be an array of resolvers)
    'com.': dnsJsonOverHttps('https://my-dns-resolver.example.com/dns-json'),
    // this resolver will be used for everything else (note - this could
    // also be an array of resolvers)
    '.': dnsOverHttps('https://my-dns-resolver.example.com/dns-query')
  }
})
+
+

Custom Hashers

By default, @helia/verified-fetch supports sha256, sha512, and identity hashers.

+

If you need to use a different hasher, you can provide a custom hasher function as an option to createVerifiedFetch.

+

Example - Passing a custom hashing function

import { createVerifiedFetch } from '@helia/verified-fetch'
import { blake2b256 } from '@multiformats/blake2/blake2b'

const verifiedFetch = await createVerifiedFetch({
  gateways: ['https://ipfs.io'],
  hashers: [blake2b256]
})

const resp = await verifiedFetch('ipfs://cid-using-blake2b256')
+
+

IPLD codec handling

IPFS supports several data formats (typically referred to as codecs) which are included in the CID. @helia/verified-fetch attempts to abstract away some of the details for easier consumption.

+

DAG-PB

DAG-PB is the codec we are most likely to encounter, it is what UnixFS uses under the hood.

+
Using the DAG-PB codec as a Blob
import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://Qmfoo')
const blob = await res.blob()

console.info(blob) // Blob { size: x, type: 'application/octet-stream' }
+
+
Using the DAG-PB codec as an ArrayBuffer
import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://Qmfoo')
const buf = await res.arrayBuffer()

console.info(buf) // ArrayBuffer { [Uint8Contents]: < ... >, byteLength: x }
+
+
Using the DAG-PB codec as a stream
import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://Qmfoo')
const reader = res.body?.getReader()

if (reader == null) {
  throw new Error('Could not create reader from response body')
}

while (true) {
  const next = await reader.read()

  if (next?.done === true) {
    break
  }

  if (next?.value != null) {
    console.info(next.value) // Uint8Array(x) [ ... ]
  }
}
+
+
Content-Type

When fetching DAG-PB data, the content type will be set to application/octet-stream unless a custom content-type parser is configured.

+

JSON

The JSON codec is a very simple codec, a block parseable with this codec is a JSON string encoded into a Uint8Array.

+
Using the JSON codec
import * as json from 'multiformats/codecs/json'

const block = new TextEncoder().encode('{ "hello": "world" }')
const obj = json.decode(block)

console.info(obj) // { hello: 'world' }
+
+
Content-Type

When the JSON codec is encountered, the Content-Type header of the response will be set to application/json.

+

DAG-JSON

DAG-JSON expands on the JSON codec, adding the ability to contain CIDs which act as links to other blocks, and byte arrays.

+

CIDs and byte arrays are represented using special object structures with a single "/" property.

+

Using DAG-JSON has two important caveats:

+
    +
  1. Your JSON structure cannot contain an object with only a "/" property, as it will be interpreted as a special type.
    2. +
  2. Since JSON has no technical limit on number sizes, DAG-JSON also allows numbers larger than Number.MAX_SAFE_INTEGER. JavaScript requires use of BigInts to represent numbers larger than this, and JSON.parse does not support them, so precision will be lost.
    3. +
+

Otherwise this codec follows the same rules as the JSON codec.

+
Using the DAG-JSON codec
import * as dagJson from '@ipld/dag-json'

const block = new TextEncoder().encode(`{
  "hello": "world",
  "cid": {
    "/": "baeaaac3imvwgy3zao5xxe3de"
  },
  "buf": {
    "/": {
      "bytes": "AAECAwQ"
    }
  }
}`)

const obj = dagJson.decode(block)

console.info(obj)
// {
// hello: 'world',
// cid: CID(baeaaac3imvwgy3zao5xxe3de),
// buf: Uint8Array(5) [ 0, 1, 2, 3, 4 ]
// }
+
+
Content-Type

When the DAG-JSON codec is encountered in the requested CID, the Content-Type header of the response will be set to application/json.

+

DAG-JSON data can be parsed from the response by using the .json() function, which will return CIDs/byte arrays as plain { "/": ... } objects:

+
import { verifiedFetch } from '@helia/verified-fetch'
import * as dagJson from '@ipld/dag-json'

const res = await verifiedFetch('ipfs://bafyDAGJSON')

// either:
const obj = await res.json()
console.info(obj.cid) // { "/": "baeaaac3imvwgy3zao5xxe3de" }
console.info(obj.buf) // { "/": { "bytes": "AAECAwQ" } }
+
+

Alternatively, it can be decoded using the @ipld/dag-json module and the .arrayBuffer() method, in which case you will get CID objects and Uint8Arrays:

+
import { verifiedFetch } from '@helia/verified-fetch'
import * as dagJson from '@ipld/dag-json'

const res = await verifiedFetch('ipfs://bafyDAGJSON')

// or:
const obj = dagJson.decode<any>(await res.arrayBuffer())
console.info(obj.cid) // CID(baeaaac3imvwgy3zao5xxe3de)
console.info(obj.buf) // Uint8Array(5) [ 0, 1, 2, 3, 4 ]
+
+

DAG-CBOR

DAG-CBOR uses the Concise Binary Object Representation format for serialization instead of JSON.

+

This supports more datatypes in a safer way than JSON and is smaller on the wire to boot so is usually preferable to JSON or DAG-JSON.

+
Content-Type

Not all data types supported by DAG-CBOR can be successfully turned into JSON and back into the same binary form.

+

When a decoded block can be round-tripped to JSON, the Content-Type will be set to application/json. In this case the .json() method on the Response object can be used to obtain an object representation of the response.

+

When it cannot, the Content-Type will be application/octet-stream - in this case the @ipld/dag-json module must be used to deserialize the return value from .arrayBuffer().

+
Detecting JSON-safe DAG-CBOR

If the Content-Type header of the response is application/json, the .json() method may be used to access the response body in object form, otherwise the .arrayBuffer() method must be used to decode the raw bytes using the @ipld/dag-cbor module.

+
import { verifiedFetch } from '@helia/verified-fetch'
import * as dagCbor from '@ipld/dag-cbor'

const res = await verifiedFetch('ipfs://bafyDagCborCID')
let obj

if (res.headers.get('Content-Type') === 'application/json') {
  // DAG-CBOR data can be safely decoded as JSON
  obj = await res.json()
} else {
  // response contains non-JSON friendly data types
  obj = dagCbor.decode(await res.arrayBuffer())
}

console.info(obj) // ...
+
+

The Accept header

The Accept header can be passed to override certain response processing, or to ensure that the final Content-Type of the response is the one that is expected.

+

If the final Content-Type does not match the Accept header, or if the content cannot be represented in the format dictated by the Accept header, or you have configured a custom content type parser, and that parser returns a value that isn't in the accept header, a 406: Not Acceptable response will be returned:

+
import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://bafyJPEGImageCID', {
  headers: {
    accept: 'image/png'
  }
})

console.info(res.status) // 406 - the image was a JPEG but we specified PNG as the accept header
+
+

It can also be used to skip processing the data from some formats such as DAG-CBOR if you wish to handle decoding it yourself:

+
import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://bafyDAGCBORCID', {
  headers: {
    accept: 'application/octet-stream'
  }
})

console.info(res.headers.get('accept')) // application/octet-stream
const buf = await res.arrayBuffer() // raw bytes, not processed as JSON
+
+

Redirects

If a requested URL contains a path component, that path component resolves to +a UnixFS directory, but the URL does not have a trailing slash, one will be +added to form a canonical URL for that resource, otherwise the request will +be resolved as normal.

+
import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://bafyfoo/path/to/dir')

console.info(res.url) // ipfs://bafyfoo/path/to/dir/
+
+

It's possible to prevent this behaviour and/or handle a redirect manually +through use of the redirect +option.

+

Example - Redirect: follow

This is the default value and is what happens if no value is specified.

+
import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://bafyfoo/path/to/dir', {
  redirect: 'follow'
})

console.info(res.status) // 200
console.info(res.url) // ipfs://bafyfoo/path/to/dir/
console.info(res.redirected) // true
+
+

Example - Redirect: error

This causes a TypeError to be thrown if a URL would cause a redirect.

+

import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://bafyfoo/path/to/dir', {
  redirect: 'error'
})
// throw TypeError('Failed to fetch')
+
+

Example - Redirect: manual

Manual redirects allow the user to process the redirect. A 301 +is returned, and the location to redirect to is available as the "location" +response header.

+

This differs slightly from HTTP fetch which returns an opaque response as the +browser itself is expected to process the redirect and hide all details from +the user.

+

import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://bafyfoo/path/to/dir', {
  redirect: 'manual'
})

console.info(res.status) // 301
console.info(res.url) // ipfs://bafyfoo/path/to/dir
console.info(res.redirected) // false
console.info(res.headers.get('location')) // ipfs://bafyfoo/path/to/dir/
+
+

Comparison to fetch

This module attempts to act as similarly to the fetch() API as possible.

+

The fetch() API takes two parameters:

+
    +
  1. A resource
    2. +
  2. An options object
    3. +
+

Resource argument

This library supports the following methods of fetching web3 content from IPFS:

+
    +
  1. IPFS protocol: ipfs://<cidv0> & ipfs://<cidv1>
    2. +
  2. IPNS protocol: ipns://<peerId> & ipns://<publicKey> & ipns://<hostUri_Supporting_DnsLink_TxtRecords>
    3. +
  3. CID instances: An actual CID instance CID.parse('bafy...')
    4. +
+

As well as support for pathing & params for items 1 & 2 above according to IPFS - Path Gateway Specification & IPFS - Trustless Gateway Specification. Further refinement of those specifications specifically for web-based scenarios can be found in the Web Pathing Specification IPIP.

+

If you pass a CID instance, it assumes you want the content for that specific CID only, and does 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 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. +
  2. https://specs.ipfs.tech/http-gateways/trustless-gateway/#request-headers
    3. +
  3. https://specs.ipfs.tech/http-gateways/subdomain-gateway/#request-headers
    4. +
+

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. +
  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 parameter.
    3. +
  3. headers - An object of headers to be sent with the request. Best effort to adhere to the Fetch API headers parameter. +
    4. +
  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 parameter.
    5. +
  5. body - An object that specifies the body of the request. Best effort to adhere to the Fetch API body parameter.
    6. +
  6. cache - Will basically act as force-cache for the request. Best effort to adhere to the Fetch API cache parameter.
    7. +
+

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.
      • +
    +
    2. +
+

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
    2. +
  2. IPIP-0402: Partial CAR Support on Trustless Gateways
    3. +
  3. IPIP-0386: Subdomain Gateway Interop with _redirects
    4. +
  4. IPIP-0328: JSON and CBOR Response Formats on HTTP Gateways
    5. +
  5. IPIP-0288: TAR Response Format on HTTP Gateways
    6. +
+

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 via a ReadableStream 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, this library will not support it, but you can use the helia library directly for those use cases. See 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.
    • +
+

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. Instead, users should request aplication/vnd.ipld.car or use the helia library directly for this use case.
    • +
  • Others? Open an issue or PR!
    • +
+

Response headers

This library will set the HTTP Response headers to the appropriate values for the content type according to the appropriate IPFS Specifications.

+

Some known header specifications:

+ +

Server Timing headers

By default, we do not include Server Timing headers in responses. If you want to include them, you can pass an +withServerTiming option to the createVerifiedFetch function to include them in all future responses. You can +also pass the withServerTiming option to each fetch call to include them only for that specific response.

+

See PR where this was added, https://github.com/ipfs/helia-verified-fetch/pull/164, for more information.

+

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. +
  2. TypeError - If the options argument is passed and not an object.
    3. +
  3. TypeError - If the options argument is passed and is malformed.
    4. +
  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.
    5. +
+

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. +

  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:

    +
    3. +
+
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]
+
+
    +
  1. 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.
      • +
    +
    2. +
+

Please see the original discussion on extensibility in Issue #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>
      • +
    +
    2. +
+

Example - custom plugin

   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)
+
+
    +

  1. Integrate Your Plugin:

    +

    Add your custom plugin to Verified‑Fetch’s plugin list when instantiating Verified‑Fetch:

    +
    2. +
+

Example - Integrate custom plugin

   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

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.

+

Install

$ npm i @helia/verified-fetch
+
+

Browser <script> tag

Loading this module through a script tag will make it's exports available as HeliaVerifiedFetch in the global namespace.

+
<script src="https://unpkg.com/@helia/verified-fetch/dist/index.min.js"></script>
+
+

API Docs

+

License

Licensed under either of

+ +

Contribute

Contributions welcome! Please check out the issues.

+

Also see our contributing document for more information on how we work, and about contributing in general.

+

Please be aware that all interactions related to this repo are subject to the IPFS Code of Conduct.

+

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

+

+

Index

Classes

BasePlugin +DirIndexHtmlPlugin +PluginError +PluginFatalError +

Interfaces

CIDDetail +CIDDetailError +ContentTypeParser +CreateVerifiedFetchInit +CreateVerifiedFetchOptions +PluginContext +PluginOptions +ResourceDetail +VerifiedFetch +VerifiedFetchInit +VerifiedFetchPluginFactory +

Type Aliases

BubbledProgressEvents +Resource +VerifiedFetchProgressEvents +

Functions

createVerifiedFetch +dirIndexHtmlPluginFactory +verifiedFetch +

Settings

Member Visibility

Theme

On This Page

@helia/verified-fetchAboutInstallAPI DocsLicenseContribute
\ No newline at end of file diff --git a/modules/_helia_verified_fetch_gateway_conformance.html b/modules/_helia_verified_fetch_gateway_conformance.html new file mode 100644 index 00000000..fd952559 --- /dev/null +++ b/modules/_helia_verified_fetch_gateway_conformance.html @@ -0,0 +1,32 @@ +@helia/verified-fetch-gateway-conformance | Helia Verified Fetch

Module @helia/verified-fetch-gateway-conformance

+ + Helia logo + +

+ +

@helia/verified-fetch-gateway-conformance

ipfs.tech +Discuss +codecov +CI

+
+

Gateway Conformance tests for @helia/verified-fetch

+
+

About

Runs Gateway Conformance tests against @helia/verified-fetch using Kubo as a backing trustless-gateway.

+

Example - Testing a new Kubo release

$ npm i @helia/verified-fetch-gateway-conformance
$ KUBO_BINARY=/path/to/kubo verified-fetch-gateway-conformance
+
+

Install

$ npm i @helia/verified-fetch-gateway-conformance
+
+

Browser <script> tag

Loading this module through a script tag will make it's exports available as HeliaInterop in the global namespace.

+
<script src="https://unpkg.com/@helia/verified-fetch-gateway-conformance/dist/index.min.js"></script>
+
+

License

Licensed under either of

+ +

Contribute

Contributions welcome! Please check out the issues.

+

Also see our contributing document for more information on how we work, and about contributing in general.

+

Please be aware that all interactions related to this repo are subject to the IPFS Code of Conduct.

+

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

+

+

Settings

Member Visibility

Theme

On This Page

@helia/verified-fetch-gateway-conformanceAboutInstallLicenseContribute
\ No newline at end of file diff --git a/modules/index.html b/modules/index.html deleted file mode 100644 index 0b2c67f3..00000000 --- a/modules/index.html +++ /dev/null @@ -1,360 +0,0 @@ -index | @helia/verified-fetch

Module index

@helia/verified-fetch provides a fetch-like API for retrieving content from the IPFS network.

-

All content is retrieved in a trustless manner, and the integrity of all bytes are verified by comparing hashes of the data.

-

By default, providers for CIDs are found using delegated routing endpoints.

-

Data is retrieved using the following strategies:

-
    -
  • Directly from providers, using Bitswap over WebSockets and WebRTC if available.
    • -
  • Directly from providers exposing a trustless gateway over HTTPS.
    • -
  • As a fallback, if no providers reachable from a browser are found, data is retrieved using recursive gateways, e.g. trustless-gateway.link which can be configured.
    • -
-

This is a marked improvement over fetch which offers no such protections and is vulnerable to all sorts of attacks like Content Spoofing, DNS Hijacking, etc.

-

A verifiedFetch function is exported to get up and running quickly, and a createVerifiedFetch function is also available that allows customizing the underlying Helia node for complete control over how content is retrieved.

-

Browser-cache-friendly Response objects are returned which should be instantly familiar to web developers.

-

Learn more in the announcement blog post and check out the ready-to-run example.

-

You may use any supported resource argument to fetch content:

-
    -
  • CID instance
    • -
  • IPFS URL
    • -
  • IPNS URL
    • -
-

Example: Getting started

import { verifiedFetch } from '@helia/verified-fetch'

const resp = await verifiedFetch('ipfs://bafy...')

const json = await resp.json()
-
-

Example: Using a CID instance to fetch JSON

import { verifiedFetch } from '@helia/verified-fetch'
import { CID } from 'multiformats/cid'

const cid = CID.parse('bafyFoo') // some json file
const response = await verifiedFetch(cid)
const json = await response.json()
-
-

Example: Using IPFS protocol to fetch an image

import { verifiedFetch } from '@helia/verified-fetch'

const response = await verifiedFetch('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

import { verifiedFetch } from '@helia/verified-fetch'

const response = await verifiedFetch('ipns://mydomain.com/path/to/very-long-file.log')
const bigFileStreamReader = await response.body?.getReader()
-
-

Configuration

Custom HTTP gateways and routers

Out of the box @helia/verified-fetch uses a default set of trustless gateways for fetching blocks and HTTP delegated routers for performing routing tasks - looking up peers, resolving/publishing IPNS names, etc.

-

It's possible to override these by passing gateways and routers keys to the createVerifiedFetch function:

-

Example: Configuring gateways and routers

import { createVerifiedFetch } from '@helia/verified-fetch'

const fetch = await createVerifiedFetch({
  gateways: ['https://trustless-gateway.link'],
  routers: ['http://delegated-ipfs.dev']
})

const resp = await fetch('ipfs://bafy...')

const json = await resp.json()
-
-

Usage with customized Helia

For full control of how @helia/verified-fetch fetches content from the distributed web you can pass a preconfigured Helia node to createVerifiedFetch.

-

The helia module is configured with a libp2p node that is suited for decentralized applications, alternatively @helia/http is available which uses HTTP gateways for all network operations.

-

You can see variations of Helia and js-libp2p configuration options at https://ipfs.github.io/helia/interfaces/helia.HeliaInit.html.

-
import { trustlessGateway } from '@helia/block-brokers'
import { createHeliaHTTP } from '@helia/http'
import { delegatedHTTPRouting, httpGatewayRouting } from '@helia/routers'
import { createVerifiedFetch } from '@helia/verified-fetch'

const fetch = await createVerifiedFetch(
  await createHeliaHTTP({
    blockBrokers: [
      trustlessGateway()
    ],
    routers: [
      delegatedHTTPRouting('http://delegated-ipfs.dev'),
      httpGatewayRouting({
        gateways: ['https://mygateway.example.net', 'https://trustless-gateway.link']
      })
    ]
  })
)

const resp = await fetch('ipfs://bafy...')

const json = await resp.json()
-
-

Custom content-type parsing

By default, if the response can be parsed as JSON, @helia/verified-fetch sets the Content-Type header as application/json, otherwise it sets it as application/octet-stream - this is because the .json(), .text(), .blob(), and .arrayBuffer() methods will usually work as expected without a detailed content type.

-

If you require an accurate content-type you can provide a contentTypeParser function as an option to createVerifiedFetch to handle parsing the content type.

-

The function you provide will be called with the first chunk of bytes from the file and should return a string or a promise of a string.

-

Example: Customizing content-type parsing

import { createVerifiedFetch } from '@helia/verified-fetch'
import { fileTypeFromBuffer } from '@sgtpooki/file-type'

const fetch = await createVerifiedFetch({
  gateways: ['https://trustless-gateway.link'],
  routers: ['http://delegated-ipfs.dev']
}, {
  contentTypeParser: async (bytes) => {
    // call to some magic-byte recognition library like magic-bytes, file-type, or your own custom byte recognition
    const result = await fileTypeFromBuffer(bytes)
    return result?.mime
  }
})
-
-

Custom DNS resolvers

If you don't want to leak DNS queries to the default resolvers, you can provide your own list of DNS resolvers to createVerifiedFetch.

-

Note that you do not need to provide both a DNS-over-HTTPS and a DNS-over-JSON resolver, and you should prefer dnsJsonOverHttps resolvers for usage in the browser for a smaller bundle size. See https://github.com/ipfs/helia/tree/main/packages/ipns#example---using-dns-json-over-https for more information.

-

Example: Customizing DNS resolvers

import { createVerifiedFetch } from '@helia/verified-fetch'
import { dnsJsonOverHttps, dnsOverHttps } from '@multiformats/dns/resolvers'

const fetch = await createVerifiedFetch({
  gateways: ['https://trustless-gateway.link'],
  routers: ['http://delegated-ipfs.dev'],
  dnsResolvers: [
    dnsJsonOverHttps('https://my-dns-resolver.example.com/dns-json'),
    dnsOverHttps('https://my-dns-resolver.example.com/dns-query')
  ]
})
-
-

Example: Customizing DNS per-TLD resolvers

DNS resolvers can be configured to only service DNS queries for specific -TLDs:

-
import { createVerifiedFetch } from '@helia/verified-fetch'
import { dnsJsonOverHttps, dnsOverHttps } from '@multiformats/dns/resolvers'

const fetch = await createVerifiedFetch({
  gateways: ['https://trustless-gateway.link'],
  routers: ['http://delegated-ipfs.dev'],
  dnsResolvers: {
    // this resolver will only be used for `.com` domains (note - this could
    // also be an array of resolvers)
    'com.': dnsJsonOverHttps('https://my-dns-resolver.example.com/dns-json'),
    // this resolver will be used for everything else (note - this could
    // also be an array of resolvers)
    '.': dnsOverHttps('https://my-dns-resolver.example.com/dns-query')
  }
})
-
-

Custom Hashers

By default, @helia/verified-fetch supports sha256, sha512, and identity hashers.

-

If you need to use a different hasher, you can provide a custom hasher function as an option to createVerifiedFetch.

-

Example: Passing a custom hashing function

import { createVerifiedFetch } from '@helia/verified-fetch'
import { blake2b256 } from '@multiformats/blake2/blake2b'

const verifiedFetch = await createVerifiedFetch({
  gateways: ['https://ipfs.io'],
  hashers: [blake2b256]
})

const resp = await verifiedFetch('ipfs://cid-using-blake2b256')
-
-

IPLD codec handling

IPFS supports several data formats (typically referred to as codecs) which are included in the CID. @helia/verified-fetch attempts to abstract away some of the details for easier consumption.

-

DAG-PB

DAG-PB is the codec we are most likely to encounter, it is what UnixFS uses under the hood.

-
Using the DAG-PB codec as a Blob
import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://Qmfoo')
const blob = await res.blob()

console.info(blob) // Blob { size: x, type: 'application/octet-stream' }
-
-
Using the DAG-PB codec as an ArrayBuffer
import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://Qmfoo')
const buf = await res.arrayBuffer()

console.info(buf) // ArrayBuffer { [Uint8Contents]: < ... >, byteLength: x }
-
-
Using the DAG-PB codec as a stream
import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://Qmfoo')
const reader = res.body?.getReader()

if (reader == null) {
  throw new Error('Could not create reader from response body')
}

while (true) {
  const next = await reader.read()

  if (next?.done === true) {
    break
  }

  if (next?.value != null) {
    console.info(next.value) // Uint8Array(x) [ ... ]
  }
}
-
-
Content-Type

When fetching DAG-PB data, the content type will be set to application/octet-stream unless a custom content-type parser is configured.

-

JSON

The JSON codec is a very simple codec, a block parseable with this codec is a JSON string encoded into a Uint8Array.

-
Using the JSON codec
import * as json from 'multiformats/codecs/json'

const block = new TextEncoder().encode('{ "hello": "world" }')
const obj = json.decode(block)

console.info(obj) // { hello: 'world' }
-
-
Content-Type

When the JSON codec is encountered, the Content-Type header of the response will be set to application/json.

-

DAG-JSON

DAG-JSON expands on the JSON codec, adding the ability to contain CIDs which act as links to other blocks, and byte arrays.

-

CIDs and byte arrays are represented using special object structures with a single "/" property.

-

Using DAG-JSON has two important caveats:

-
    -
  1. Your JSON structure cannot contain an object with only a "/" property, as it will be interpreted as a special type.
    2. -
  2. Since JSON has no technical limit on number sizes, DAG-JSON also allows numbers larger than Number.MAX_SAFE_INTEGER. JavaScript requires use of BigInts to represent numbers larger than this, and JSON.parse does not support them, so precision will be lost.
    3. -
-

Otherwise this codec follows the same rules as the JSON codec.

-
Using the DAG-JSON codec
import * as dagJson from '@ipld/dag-json'

const block = new TextEncoder().encode(`{
  "hello": "world",
  "cid": {
    "/": "baeaaac3imvwgy3zao5xxe3de"
  },
  "buf": {
    "/": {
      "bytes": "AAECAwQ"
    }
  }
}`)

const obj = dagJson.decode(block)

console.info(obj)
// {
// hello: 'world',
// cid: CID(baeaaac3imvwgy3zao5xxe3de),
// buf: Uint8Array(5) [ 0, 1, 2, 3, 4 ]
// }
-
-
Content-Type

When the DAG-JSON codec is encountered in the requested CID, the Content-Type header of the response will be set to application/json.

-

DAG-JSON data can be parsed from the response by using the .json() function, which will return CIDs/byte arrays as plain { "/": ... } objects:

-
import { verifiedFetch } from '@helia/verified-fetch'
import * as dagJson from '@ipld/dag-json'

const res = await verifiedFetch('ipfs://bafyDAGJSON')

// either:
const obj = await res.json()
console.info(obj.cid) // { "/": "baeaaac3imvwgy3zao5xxe3de" }
console.info(obj.buf) // { "/": { "bytes": "AAECAwQ" } }
-
-

Alternatively, it can be decoded using the @ipld/dag-json module and the .arrayBuffer() method, in which case you will get CID objects and Uint8Arrays:

-
import { verifiedFetch } from '@helia/verified-fetch'
import * as dagJson from '@ipld/dag-json'

const res = await verifiedFetch('ipfs://bafyDAGJSON')

// or:
const obj = dagJson.decode<any>(await res.arrayBuffer())
console.info(obj.cid) // CID(baeaaac3imvwgy3zao5xxe3de)
console.info(obj.buf) // Uint8Array(5) [ 0, 1, 2, 3, 4 ]
-
-

DAG-CBOR

DAG-CBOR uses the Concise Binary Object Representation format for serialization instead of JSON.

-

This supports more datatypes in a safer way than JSON and is smaller on the wire to boot so is usually preferable to JSON or DAG-JSON.

-
Content-Type

Not all data types supported by DAG-CBOR can be successfully turned into JSON and back into the same binary form.

-

When a decoded block can be round-tripped to JSON, the Content-Type will be set to application/json. In this case the .json() method on the Response object can be used to obtain an object representation of the response.

-

When it cannot, the Content-Type will be application/octet-stream - in this case the @ipld/dag-json module must be used to deserialize the return value from .arrayBuffer().

-
Detecting JSON-safe DAG-CBOR

If the Content-Type header of the response is application/json, the .json() method may be used to access the response body in object form, otherwise the .arrayBuffer() method must be used to decode the raw bytes using the @ipld/dag-cbor module.

-
import { verifiedFetch } from '@helia/verified-fetch'
import * as dagCbor from '@ipld/dag-cbor'

const res = await verifiedFetch('ipfs://bafyDagCborCID')
let obj

if (res.headers.get('Content-Type') === 'application/json') {
  // DAG-CBOR data can be safely decoded as JSON
  obj = await res.json()
} else {
  // response contains non-JSON friendly data types
  obj = dagCbor.decode(await res.arrayBuffer())
}

console.info(obj) // ...
-
-

The Accept header

The Accept header can be passed to override certain response processing, or to ensure that the final Content-Type of the response is the one that is expected.

-

If the final Content-Type does not match the Accept header, or if the content cannot be represented in the format dictated by the Accept header, or you have configured a custom content type parser, and that parser returns a value that isn't in the accept header, a 406: Not Acceptable response will be returned:

-
import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://bafyJPEGImageCID', {
  headers: {
    accept: 'image/png'
  }
})

console.info(res.status) // 406 - the image was a JPEG but we specified PNG as the accept header
-
-

It can also be used to skip processing the data from some formats such as DAG-CBOR if you wish to handle decoding it yourself:

-
import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://bafyDAGCBORCID', {
  headers: {
    accept: 'application/octet-stream'
  }
})

console.info(res.headers.get('accept')) // application/octet-stream
const buf = await res.arrayBuffer() // raw bytes, not processed as JSON
-
-

Redirects

If a requested URL contains a path component, that path component resolves to -a UnixFS directory, but the URL does not have a trailing slash, one will be -added to form a canonical URL for that resource, otherwise the request will -be resolved as normal.

-
import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://bafyfoo/path/to/dir')

console.info(res.url) // ipfs://bafyfoo/path/to/dir/
-
-

It's possible to prevent this behaviour and/or handle a redirect manually -through use of the redirect -option.

-

Example: Redirect: follow

This is the default value and is what happens if no value is specified.

-
import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://bafyfoo/path/to/dir', {
  redirect: 'follow'
})

console.info(res.status) // 200
console.info(res.url) // ipfs://bafyfoo/path/to/dir/
console.info(res.redirected) // true
-
-

Example: Redirect: error

This causes a TypeError to be thrown if a URL would cause a redirect.

-

import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://bafyfoo/path/to/dir', {
  redirect: 'error'
})
// throw TypeError('Failed to fetch')
-
-

Example: Redirect: manual

Manual redirects allow the user to process the redirect. A 301 -is returned, and the location to redirect to is available as the "location" -response header.

-

This differs slightly from HTTP fetch which returns an opaque response as the -browser itself is expected to process the redirect and hide all details from -the user.

-

import { verifiedFetch } from '@helia/verified-fetch'

const res = await verifiedFetch('ipfs://bafyfoo/path/to/dir', {
  redirect: 'manual'
})

console.info(res.status) // 301
console.info(res.url) // ipfs://bafyfoo/path/to/dir
console.info(res.redirected) // false
console.info(res.headers.get('location')) // ipfs://bafyfoo/path/to/dir/
-
-

Comparison to fetch

This module attempts to act as similarly to the fetch() API as possible.

-

The fetch() API takes two parameters:

-
    -
  1. A resource
    2. -
  2. An options object
    3. -
-

Resource argument

This library supports the following methods of fetching web3 content from IPFS:

-
    -
  1. IPFS protocol: ipfs://<cidv0> & ipfs://<cidv1>
    2. -
  2. IPNS protocol: ipns://<peerId> & ipns://<publicKey> & ipns://<hostUri_Supporting_DnsLink_TxtRecords>
    3. -
  3. CID instances: An actual CID instance CID.parse('bafy...')
    4. -
-

As well as support for pathing & params for items 1 & 2 above according to IPFS - Path Gateway Specification & IPFS - Trustless Gateway Specification. Further refinement of those specifications specifically for web-based scenarios can be found in the Web Pathing Specification IPIP.

-

If you pass a CID instance, it assumes you want the content for that specific CID only, and does 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 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. -
  2. https://specs.ipfs.tech/http-gateways/trustless-gateway/#request-headers
    3. -
  3. https://specs.ipfs.tech/http-gateways/subdomain-gateway/#request-headers
    4. -
-

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. -
  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 parameter.
    3. -
  3. headers - An object of headers to be sent with the request. Best effort to adhere to the Fetch API headers parameter. -
    4. -
  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 parameter.
    5. -
  5. body - An object that specifies the body of the request. Best effort to adhere to the Fetch API body parameter.
    6. -
  6. cache - Will basically act as force-cache for the request. Best effort to adhere to the Fetch API cache parameter.
    7. -
-

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.
      • -
    -
    2. -
-

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
    2. -
  2. IPIP-0402: Partial CAR Support on Trustless Gateways
    3. -
  3. IPIP-0386: Subdomain Gateway Interop with _redirects
    4. -
  4. IPIP-0328: JSON and CBOR Response Formats on HTTP Gateways
    5. -
  5. IPIP-0288: TAR Response Format on HTTP Gateways
    6. -
-

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 via a ReadableStream 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, this library will not support it, but you can use the helia library directly for those use cases. See 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.
    • -
-

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. Instead, users should request aplication/vnd.ipld.car or use the helia library directly for this use case.
    • -
  • Others? Open an issue or PR!
    • -
-

Response headers

This library will set the HTTP Response headers to the appropriate values for the content type according to the appropriate IPFS Specifications.

-

Some known header specifications:

- -

Server Timing headers

By default, we do not include Server Timing headers in responses. If you want to include them, you can pass an -withServerTiming option to the createVerifiedFetch function to include them in all future responses. You can -also pass the withServerTiming option to each fetch call to include them only for that specific response.

-

See PR where this was added, https://github.com/ipfs/helia-verified-fetch/pull/164, for more information.

-

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. -
  2. TypeError - If the options argument is passed and not an object.
    3. -
  3. TypeError - If the options argument is passed and is malformed.
    4. -
  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.
    5. -
-

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. -

  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:

    -
    3. -
-
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]
-
-
    -
  1. 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.
      • -
    -
    2. -
-

Please see the original discussion on extensibility in Issue #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>
      • -
    -
    2. -
-

Example: custom plugin

   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)
-
-
    -

  1. Integrate Your Plugin:

    -

    Add your custom plugin to Verified‑Fetch’s plugin list when instantiating Verified‑Fetch:

    -
    2. -
-

Example: Integrate custom plugin

   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

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.

-

Index

Classes

BasePlugin -DirIndexHtmlPlugin -PluginError -PluginFatalError -

Interfaces

CIDDetail -CIDDetailError -ContentTypeParser -CreateVerifiedFetchInit -CreateVerifiedFetchOptions -PluginContext -PluginOptions -ResourceDetail -VerifiedFetch -VerifiedFetchInit -VerifiedFetchPluginFactory -

Type Aliases

BubbledProgressEvents -Resource -VerifiedFetchProgressEvents -

Functions

createVerifiedFetch -dirIndexHtmlPluginFactory -verifiedFetch -

Settings

Member Visibility

Theme

On This Page

ConfigurationThe Accept headerRedirectsComparison to fetchPluggability and Extensibility
\ No newline at end of file diff --git a/modules/plugins_plugins.html b/modules/plugins_plugins.html deleted file mode 100644 index 5e5d39c2..00000000 --- a/modules/plugins_plugins.html +++ /dev/null @@ -1,3 +0,0 @@ -plugins/plugins | @helia/verified-fetch

Module plugins/plugins

References

DirIndexHtmlPlugin -dirIndexHtmlPluginFactory -

References

DirIndexHtmlPlugin

Re-exports DirIndexHtmlPlugin

dirIndexHtmlPluginFactory

Re-exports dirIndexHtmlPluginFactory

Settings

Member Visibility

Theme

On This Page

DirIndexHtmlPlugindirIndexHtmlPluginFactory
\ No newline at end of file diff --git a/types/_helia_verified_fetch.BubbledProgressEvents.html b/types/_helia_verified_fetch.BubbledProgressEvents.html new file mode 100644 index 00000000..0568731e --- /dev/null +++ b/types/_helia_verified_fetch.BubbledProgressEvents.html @@ -0,0 +1 @@ +BubbledProgressEvents | Helia Verified Fetch

Type alias BubbledProgressEvents

BubbledProgressEvents: ExporterProgressEvents | GetBlockProgressEvents | ResolveDNSLinkProgressEvents

Settings

Member Visibility

Theme

\ No newline at end of file diff --git a/types/index.Resource.html b/types/_helia_verified_fetch.Resource.html similarity index 52% rename from types/index.Resource.html rename to types/_helia_verified_fetch.Resource.html index 9bb3e58e..ef0ee310 100644 --- a/types/index.Resource.html +++ b/types/_helia_verified_fetch.Resource.html @@ -1,2 +1,2 @@ -Resource | @helia/verified-fetch

Type alias Resource

Resource: string | CID

The types for the first argument of the verifiedFetch function.

-

Settings

Member Visibility

Theme

\ No newline at end of file +Resource | Helia Verified Fetch

Type alias Resource

Resource: string | CID

The types for the first argument of the verifiedFetch function.

+

Settings

Member Visibility

Theme

\ No newline at end of file diff --git a/types/_helia_verified_fetch.VerifiedFetchProgressEvents.html b/types/_helia_verified_fetch.VerifiedFetchProgressEvents.html new file mode 100644 index 00000000..66f82af6 --- /dev/null +++ b/types/_helia_verified_fetch.VerifiedFetchProgressEvents.html @@ -0,0 +1 @@ +VerifiedFetchProgressEvents | Helia Verified Fetch

Type alias VerifiedFetchProgressEvents

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>

Settings

Member Visibility

Theme

\ No newline at end of file diff --git a/types/index.BubbledProgressEvents.html b/types/index.BubbledProgressEvents.html deleted file mode 100644 index 493d4869..00000000 --- a/types/index.BubbledProgressEvents.html +++ /dev/null @@ -1 +0,0 @@ -BubbledProgressEvents | @helia/verified-fetch

Type alias BubbledProgressEvents

BubbledProgressEvents: ExporterProgressEvents | GetBlockProgressEvents | ResolveDNSLinkProgressEvents

Settings

Member Visibility

Theme

\ No newline at end of file diff --git a/types/index.VerifiedFetchProgressEvents.html b/types/index.VerifiedFetchProgressEvents.html deleted file mode 100644 index 136be068..00000000 --- a/types/index.VerifiedFetchProgressEvents.html +++ /dev/null @@ -1 +0,0 @@ -VerifiedFetchProgressEvents | @helia/verified-fetch

Type alias VerifiedFetchProgressEvents

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>

Settings

Member Visibility

Theme

\ No newline at end of file