@helia/verified-fetch 0.0.0-5c0c39c → 0.0.0-6c88ee1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/README.md +56 -43
  2. package/dist/index.min.js +6 -6
  3. package/dist/src/index.d.ts +59 -47
  4. package/dist/src/index.d.ts.map +1 -1
  5. package/dist/src/index.js +59 -47
  6. package/dist/src/index.js.map +1 -1
  7. package/dist/src/singleton.d.ts +3 -0
  8. package/dist/src/singleton.d.ts.map +1 -0
  9. package/dist/src/singleton.js +15 -0
  10. package/dist/src/singleton.js.map +1 -0
  11. package/package.json +11 -11
  12. package/src/index.ts +60 -47
  13. package/src/singleton.ts +20 -0
package/dist/src/index.d.ts CHANGED
@@ -1,57 +1,49 @@
1
1
  /**
2
2
  * @packageDocumentation
3
3
  *
4
- * `@helia/verified-fetch` is a library that provides a fetch-like API for fetching trustless content from IPFS and verifying it.
4
+ * `@helia/verified-fetch` provides a [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)-like API for retrieving content from the [IPFS](https://ipfs.tech/) network.
5
5
  *
6
- * This library should act as a replacement for the `fetch()` API for fetching content from IPFS, and will return a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) object that can be used in a similar manner to the `fetch()` API. This means browser and HTTP caching inside browser main threads, web-workers, and service workers, as well as other features of the `fetch()` API should work in a way familiar to developers.
6
+ * All content is retrieved in a [trustless manner](https://www.techopedia.com/definition/trustless), and the integrity of all bytes are verified by comparing hashes of the data.
7
7
  *
8
- * Exports a `createVerifiedFetch` function that returns a `fetch()` like API method {@link Helia} for fetching IPFS content.
8
+ * This is a marked improvement over `fetch` which offers no such protections and is vulnerable to all sorts of attacks like [Content Spoofing](https://owasp.org/www-community/attacks/Content_Spoofing), [DNS Hijacking](https://en.wikipedia.org/wiki/DNS_hijacking), etc.
9
+ *
10
+ * A `verifiedFetch` function is exported to get up and running quickly, and a `createVerifiedFetch` function is also available that allows customizing the underlying [Helia](https://helia.io/) node for complete control over how content is retrieved.
11
+ *
12
+ * Browser-cache-friendly [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) objects are returned which should be instantly familiar to web developers.
9
13
  *
10
14
  * You may use any supported resource argument to fetch content:
11
15
  *
12
- * - CID instance
16
+ * - [CID](https://multiformats.github.io/js-multiformats/classes/cid.CID.html) instance
13
17
  * - IPFS URL
14
18
  * - IPNS URL
15
19
  *
16
- * @example
20
+ * @example Getting started
17
21
  *
18
22
  * ```typescript
19
- * import { createVerifiedFetch } from '@helia/verified-fetch'
23
+ * import { verifiedFetch } from '@helia/verified-fetch'
20
24
  *
21
- * const fetch = await createVerifiedFetch({
22
- * gateways: ['https://mygateway.example.net', 'https://trustless-gateway.link']
23
- *})
24
- *
25
- * const resp = await fetch('ipfs://bafy...')
25
+ * const resp = await verifiedFetch('ipfs://bafy...')
26
26
  *
27
27
  * const json = await resp.json()
28
28
  *```
29
29
  *
30
- *
31
30
  * @example Using a CID instance to fetch JSON
32
31
  *
33
32
  * ```typescript
34
- * import { createVerifiedFetch } from '@helia/verified-fetch'
33
+ * import { verifiedFetch } from '@helia/verified-fetch'
35
34
  * import { CID } from 'multiformats/cid'
36
35
  *
37
- * const fetch = await createVerifiedFetch({
38
- * gateways: ['https://mygateway.example.net', 'https://trustless-gateway.link']
39
- * })
40
- *
41
36
  * const cid = CID.parse('bafyFoo') // some image file
42
- * const response = await fetch(cid)
37
+ * const response = await verifiedFetch(cid)
43
38
  * const json = await response.json()
44
39
  * ```
45
40
  *
46
41
  * @example Using IPFS protocol to fetch an image
47
42
  *
48
43
  * ```typescript
49
- * import { createVerifiedFetch } from '@helia/verified-fetch'
44
+ * import { verifiedFetch } from '@helia/verified-fetch'
50
45
  *
51
- * const fetch = await createVerifiedFetch({
52
- * gateways: ['https://mygateway.example.net', 'https://trustless-gateway.link']
53
- * })
54
- * const response = await fetch('ipfs://bafyFoo') // CID for some image file
46
+ * const response = await verifiedFetch('ipfs://bafyFoo') // CID for some image file
55
47
  * const blob = await response.blob()
56
48
  * const image = document.createElement('img')
57
49
  * image.src = URL.createObjectURL(blob)
@@ -61,22 +53,42 @@
61
53
  * @example Using IPNS protocol to stream a big file
62
54
  *
63
55
  * ```typescript
64
- * import { createVerifiedFetch } from '@helia/verified-fetch'
56
+ * import { verifiedFetch } from '@helia/verified-fetch'
65
57
  *
66
- * const fetch = await createVerifiedFetch({
67
- * gateways: ['https://mygateway.example.net', 'https://trustless-gateway.link']
68
- * })
69
- * const response = await fetch('ipns://mydomain.com/path/to/very-long-file.log')
58
+ * const response = await verifiedFetch('ipns://mydomain.com/path/to/very-long-file.log')
70
59
  * const bigFileStreamReader = await response.body.getReader()
71
60
  * ```
72
61
  *
73
- * ### Configuration
62
+ * ## Configuration
74
63
  *
75
- * #### Usage with customized Helia
64
+ * ### Custom HTTP gateways and routers
76
65
  *
77
- * You can see variations of Helia and js-libp2p configuration options at https://helia.io/interfaces/helia.index.HeliaInit.html.
66
+ * Out of the box `@helia/verified-fetch` uses a default set of [trustless gateways](https://specs.ipfs.tech/http-gateways/trustless-gateway/) for fetching blocks and [HTTP delegated routers](https://specs.ipfs.tech/routing/http-routing-v1/) for performing routing tasks - looking up peers, resolving/publishing [IPNS](https://docs.ipfs.tech/concepts/ipns/) names, etc.
67
+ *
68
+ * It's possible to override these by passing `gateways` and `routers` keys to the `createVerifiedFetch` function:
78
69
  *
79
- * The `@helia/http` module is currently in-progress, but the init options should be a subset of the `helia` module's init options. See https://github.com/ipfs/helia/issues/289 for more information.
70
+ * @example Configuring gateways and routers
71
+ *
72
+ * ```typescript
73
+ * import { createVerifiedFetch } from '@helia/verified-fetch'
74
+ *
75
+ * const fetch = await createVerifiedFetch({
76
+ * gateways: ['https://trustless-gateway.link'],
77
+ * routers: ['http://delegated-ipfs.dev']
78
+ *})
79
+ *
80
+ * const resp = await fetch('ipfs://bafy...')
81
+ *
82
+ * const json = await resp.json()
83
+ *```
84
+ *
85
+ * ### Usage with customized Helia
86
+ *
87
+ * For full control of how `@helia/verified-fetch` fetches content from the distributed web you can pass a preconfigured Helia node to `createVerifiedFetch`.
88
+ *
89
+ * The [helia](https://www.npmjs.com/package/helia) module is configured with a libp2p node that is suited for decentralized applications, alternatively [@helia/http](https://www.npmjs.com/package/@helia/http) is available which uses HTTP gateways for all network operations.
90
+ *
91
+ * You can see variations of Helia and js-libp2p configuration options at https://helia.io/interfaces/helia.index.HeliaInit.html.
80
92
  *
81
93
  * ```typescript
82
94
  * import { trustlessGateway } from '@helia/block-brokers'
@@ -100,28 +112,28 @@
100
112
  * const json = await resp.json()
101
113
  * ```
102
114
  *
103
- * ### Comparison to fetch
115
+ * ## Comparison to fetch
104
116
  *
105
- * First, this library will require instantiation in order to configure the gateways and delegated routers, or potentially a custom Helia instance. Secondly, once your verified-fetch method is created, it will act as similar to the `fetch()` API as possible.
117
+ * This module attempts to act as similarly to the `fetch()` API as possible.
106
118
  *
107
119
  * [The `fetch()` API](https://developer.mozilla.org/en-US/docs/Web/API/fetch) takes two parameters:
108
120
  *
109
121
  * 1. A [resource](https://developer.mozilla.org/en-US/docs/Web/API/fetch#resource)
110
122
  * 2. An [options object](https://developer.mozilla.org/en-US/docs/Web/API/fetch#options)
111
123
  *
112
- * #### Resource argument
124
+ * ### Resource argument
113
125
  *
114
- * This library intends to support the following methods of fetching web3 content from IPFS:
126
+ * This library supports the following methods of fetching web3 content from IPFS:
115
127
  *
116
128
  * 1. IPFS protocol: `ipfs://<cidv0>` & `ipfs://<cidv0>`
117
129
  * 2. IPNS protocol: `ipns://<peerId>` & `ipns://<publicKey>` & `ipns://<hostUri_Supporting_DnsLink_TxtRecords>`
118
130
  * 3. CID instances: An actual CID instance `CID.parse('bafy...')`
119
131
  *
120
- * As well as support for pathing & params for item 1&2 above according to [IPFS - Path Gateway Specification](https://specs.ipfs.tech/http-gateways/path-gateway) & [IPFS - Trustless Gateway Specification](https://specs.ipfs.tech/http-gateways/trustless-gateway/). Further refinement of those specifications specifically for web-based scenarios can be found in the [Web Pathing Specification IPIP](https://github.com/ipfs/specs/pull/453).
132
+ * As well as support for pathing & params for item 1 & 2 above according to [IPFS - Path Gateway Specification](https://specs.ipfs.tech/http-gateways/path-gateway) & [IPFS - Trustless Gateway Specification](https://specs.ipfs.tech/http-gateways/trustless-gateway/). Further refinement of those specifications specifically for web-based scenarios can be found in the [Web Pathing Specification IPIP](https://github.com/ipfs/specs/pull/453).
121
133
  *
122
- * If you pass a CID instance, we assume you want the content for that specific CID only, and do not support pathing or params for that CID.
134
+ * 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.
123
135
  *
124
- * #### Options argument
136
+ * ### Options argument
125
137
  *
126
138
  * This library does not plan to support the exact Fetch API options object, as some of the arguments don't make sense. Instead, it will only support options necessary to meet [IPFS specs](https://specs.ipfs.tech/) related to specifying the resultant shape of desired content.
127
139
  *
@@ -146,7 +158,6 @@
146
158
  * 5. `body` - An object that specifies the body of the request. Best effort to adhere to the [Fetch API body](https://developer.mozilla.org/en-US/docs/Web/API/fetch#body) parameter.
147
159
  * 6. `cache` - Will basically act as `force-cache` for the request. Best effort to adhere to the [Fetch API cache](https://developer.mozilla.org/en-US/docs/Web/API/fetch#cache) parameter.
148
160
  *
149
- *
150
161
  * Non-Fetch API options that will be supported:
151
162
  *
152
163
  * 1. `onProgress` - Similar to Helia `onProgress` options, this will be a function that will be called with a progress event. Supported progress events are:
@@ -167,7 +178,7 @@
167
178
  * 4. [IPIP-0328: JSON and CBOR Response Formats on HTTP Gateways](https://specs.ipfs.tech/ipips/ipip-0328/)
168
179
  * 5. [IPIP-0288: TAR Response Format on HTTP Gateways](https://specs.ipfs.tech/ipips/ipip-0288/)
169
180
  *
170
- * #### Response types
181
+ * ### Response types
171
182
  *
172
183
  * 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.
173
184
  *
@@ -175,7 +186,7 @@
175
186
  *
176
187
  * If your content doesn't have a mime-type or an [IPFS spec](https://specs.ipfs.tech), this library will not support it, but you can use the [`helia`](https://github.com/ipfs/helia) library directly for those use cases. See [Unsupported response types](#unsupported-response-types) for more information.
177
188
  *
178
- * ##### Handling response types
189
+ * #### Handling response types
179
190
  *
180
191
  * For handling responses we want to follow conventions/abstractions from Fetch API where possible:
181
192
  *
@@ -184,12 +195,12 @@
184
195
  * - For plain text in utf-8, you would call `.text()`
185
196
  * - For streaming response data, use something like `response.body.getReader()` to get a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API/Using_readable_streams#consuming_a_fetch_as_a_stream).
186
197
  *
187
- * ##### Unsupported response types
198
+ * #### Unsupported response types
188
199
  *
189
200
  * * Returning IPLD nodes or DAGs as JS objects is not supported, as there is no currently well-defined structure for representing this data in an [HTTP Response](https://developer.mozilla.org/en-US/docs/Web/API/Response). Instead, users should request `aplication/vnd.ipld.car` or use the [`helia`](https://github.com/ipfs/helia) library directly for this use case.
190
201
  * * Others? Open an issue or PR!
191
202
  *
192
- * #### Response headers
203
+ * ### Response headers
193
204
  *
194
205
  * This library will set the [HTTP Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) headers to the appropriate values for the content type according to the appropriate [IPFS Specifications](https://specs.ipfs.tech/).
195
206
  *
@@ -199,13 +210,13 @@
199
210
  * * https://specs.ipfs.tech/http-gateways/trustless-gateway/#response-headers
200
211
  * * https://specs.ipfs.tech/http-gateways/subdomain-gateway/#response-headers
201
212
  *
202
- * #### Possible Scenarios that could cause confusion
213
+ * ### Possible Scenarios that could cause confusion
203
214
  *
204
- * ##### Attempting to fetch the CID for content that does not make sense
215
+ * #### Attempting to fetch the CID for content that does not make sense
205
216
  *
206
217
  * If you request `bafybeiaysi4s6lnjev27ln5icwm6tueaw2vdykrtjkwiphwekaywqhcjze`, which points to the root of the en.wikipedia.org mirror, a response object does not make sense.
207
218
  *
208
- * #### Errors
219
+ * ### Errors
209
220
  *
210
221
  * Known Errors that can be thrown:
211
222
  *
@@ -256,4 +267,5 @@ export interface VerifiedFetchInit extends RequestInit, ProgressOptions<BubbledP
256
267
  * Create and return a Helia node
257
268
  */
258
269
  export declare function createVerifiedFetch(init?: Helia | CreateVerifiedFetchWithOptions): Promise<VerifiedFetch>;
270
+ export { verifiedFetch } from './singleton.js';
259
271
  //# sourceMappingURL=index.d.ts.map
package/dist/src/index.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuNG;AAMH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,4BAA4B,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AACzG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAErE;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,GAAG,CAAA;AAEnC,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,cAAe,SAAQ,SAAS;IAC/C,KAAK,EAAE,KAAK,CAAA;CACb;AAED,MAAM,WAAW,aAAa;IAC5B,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IACpE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,MAAM,MAAM,qBAAqB,GAE/B,SAAS,GAET,qBAAqB,GAAG,4BAA4B,GAAG,iBAAiB,CAAA;AAE1E,MAAM,MAAM,2BAA2B,GACrC,aAAa,CAAC,8BAA8B,EAAE,SAAS,CAAC,GACxD,aAAa,CAAC,6BAA6B,EAAE,MAAM,CAAC,GACpD,aAAa,CAAC,uCAAuC,EAAE,SAAS,CAAC,GACjE,aAAa,CAAC,4BAA4B,EAAE,SAAS,CAAC,GACtD,aAAa,CAAC,8BAA8B,EAAE,cAAc,CAAC,CAAA;AAE/D;;;;;GAKG;AACH,MAAM,WAAW,iBAAkB,SAAQ,WAAW,EAAE,eAAe,CAAC,qBAAqB,GAAG,2BAA2B,CAAC;CAC3H;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CAAE,IAAI,CAAC,EAAE,KAAK,GAAG,8BAA8B,GAAG,OAAO,CAAC,aAAa,CAAC,CAoBhH"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkOG;AAMH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,4BAA4B,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AACzG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAErE;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,GAAG,CAAA;AAEnC,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,cAAe,SAAQ,SAAS;IAC/C,KAAK,EAAE,KAAK,CAAA;CACb;AAED,MAAM,WAAW,aAAa;IAC5B,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IACpE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,MAAM,MAAM,qBAAqB,GAE/B,SAAS,GAET,qBAAqB,GAAG,4BAA4B,GAAG,iBAAiB,CAAA;AAE1E,MAAM,MAAM,2BAA2B,GACrC,aAAa,CAAC,8BAA8B,EAAE,SAAS,CAAC,GACxD,aAAa,CAAC,6BAA6B,EAAE,MAAM,CAAC,GACpD,aAAa,CAAC,uCAAuC,EAAE,SAAS,CAAC,GACjE,aAAa,CAAC,4BAA4B,EAAE,SAAS,CAAC,GACtD,aAAa,CAAC,8BAA8B,EAAE,cAAc,CAAC,CAAA;AAE/D;;;;;GAKG;AACH,MAAM,WAAW,iBAAkB,SAAQ,WAAW,EAAE,eAAe,CAAC,qBAAqB,GAAG,2BAA2B,CAAC;CAC3H;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CAAE,IAAI,CAAC,EAAE,KAAK,GAAG,8BAA8B,GAAG,OAAO,CAAC,aAAa,CAAC,CAoBhH;AAED,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA"}
package/dist/src/index.js CHANGED
@@ -1,57 +1,49 @@
1
1
  /**
2
2
  * @packageDocumentation
3
3
  *
4
- * `@helia/verified-fetch` is a library that provides a fetch-like API for fetching trustless content from IPFS and verifying it.
4
+ * `@helia/verified-fetch` provides a [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)-like API for retrieving content from the [IPFS](https://ipfs.tech/) network.
5
5
  *
6
- * This library should act as a replacement for the `fetch()` API for fetching content from IPFS, and will return a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) object that can be used in a similar manner to the `fetch()` API. This means browser and HTTP caching inside browser main threads, web-workers, and service workers, as well as other features of the `fetch()` API should work in a way familiar to developers.
6
+ * All content is retrieved in a [trustless manner](https://www.techopedia.com/definition/trustless), and the integrity of all bytes are verified by comparing hashes of the data.
7
7
  *
8
- * Exports a `createVerifiedFetch` function that returns a `fetch()` like API method {@link Helia} for fetching IPFS content.
8
+ * This is a marked improvement over `fetch` which offers no such protections and is vulnerable to all sorts of attacks like [Content Spoofing](https://owasp.org/www-community/attacks/Content_Spoofing), [DNS Hijacking](https://en.wikipedia.org/wiki/DNS_hijacking), etc.
9
+ *
10
+ * A `verifiedFetch` function is exported to get up and running quickly, and a `createVerifiedFetch` function is also available that allows customizing the underlying [Helia](https://helia.io/) node for complete control over how content is retrieved.
11
+ *
12
+ * Browser-cache-friendly [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) objects are returned which should be instantly familiar to web developers.
9
13
  *
10
14
  * You may use any supported resource argument to fetch content:
11
15
  *
12
- * - CID instance
16
+ * - [CID](https://multiformats.github.io/js-multiformats/classes/cid.CID.html) instance
13
17
  * - IPFS URL
14
18
  * - IPNS URL
15
19
  *
16
- * @example
20
+ * @example Getting started
17
21
  *
18
22
  * ```typescript
19
- * import { createVerifiedFetch } from '@helia/verified-fetch'
23
+ * import { verifiedFetch } from '@helia/verified-fetch'
20
24
  *
21
- * const fetch = await createVerifiedFetch({
22
- * gateways: ['https://mygateway.example.net', 'https://trustless-gateway.link']
23
- *})
24
- *
25
- * const resp = await fetch('ipfs://bafy...')
25
+ * const resp = await verifiedFetch('ipfs://bafy...')
26
26
  *
27
27
  * const json = await resp.json()
28
28
  *```
29
29
  *
30
- *
31
30
  * @example Using a CID instance to fetch JSON
32
31
  *
33
32
  * ```typescript
34
- * import { createVerifiedFetch } from '@helia/verified-fetch'
33
+ * import { verifiedFetch } from '@helia/verified-fetch'
35
34
  * import { CID } from 'multiformats/cid'
36
35
  *
37
- * const fetch = await createVerifiedFetch({
38
- * gateways: ['https://mygateway.example.net', 'https://trustless-gateway.link']
39
- * })
40
- *
41
36
  * const cid = CID.parse('bafyFoo') // some image file
42
- * const response = await fetch(cid)
37
+ * const response = await verifiedFetch(cid)
43
38
  * const json = await response.json()
44
39
  * ```
45
40
  *
46
41
  * @example Using IPFS protocol to fetch an image
47
42
  *
48
43
  * ```typescript
49
- * import { createVerifiedFetch } from '@helia/verified-fetch'
44
+ * import { verifiedFetch } from '@helia/verified-fetch'
50
45
  *
51
- * const fetch = await createVerifiedFetch({
52
- * gateways: ['https://mygateway.example.net', 'https://trustless-gateway.link']
53
- * })
54
- * const response = await fetch('ipfs://bafyFoo') // CID for some image file
46
+ * const response = await verifiedFetch('ipfs://bafyFoo') // CID for some image file
55
47
  * const blob = await response.blob()
56
48
  * const image = document.createElement('img')
57
49
  * image.src = URL.createObjectURL(blob)
@@ -61,22 +53,42 @@
61
53
  * @example Using IPNS protocol to stream a big file
62
54
  *
63
55
  * ```typescript
64
- * import { createVerifiedFetch } from '@helia/verified-fetch'
56
+ * import { verifiedFetch } from '@helia/verified-fetch'
65
57
  *
66
- * const fetch = await createVerifiedFetch({
67
- * gateways: ['https://mygateway.example.net', 'https://trustless-gateway.link']
68
- * })
69
- * const response = await fetch('ipns://mydomain.com/path/to/very-long-file.log')
58
+ * const response = await verifiedFetch('ipns://mydomain.com/path/to/very-long-file.log')
70
59
  * const bigFileStreamReader = await response.body.getReader()
71
60
  * ```
72
61
  *
73
- * ### Configuration
62
+ * ## Configuration
74
63
  *
75
- * #### Usage with customized Helia
64
+ * ### Custom HTTP gateways and routers
76
65
  *
77
- * You can see variations of Helia and js-libp2p configuration options at https://helia.io/interfaces/helia.index.HeliaInit.html.
66
+ * Out of the box `@helia/verified-fetch` uses a default set of [trustless gateways](https://specs.ipfs.tech/http-gateways/trustless-gateway/) for fetching blocks and [HTTP delegated routers](https://specs.ipfs.tech/routing/http-routing-v1/) for performing routing tasks - looking up peers, resolving/publishing [IPNS](https://docs.ipfs.tech/concepts/ipns/) names, etc.
67
+ *
68
+ * It's possible to override these by passing `gateways` and `routers` keys to the `createVerifiedFetch` function:
78
69
  *
79
- * The `@helia/http` module is currently in-progress, but the init options should be a subset of the `helia` module's init options. See https://github.com/ipfs/helia/issues/289 for more information.
70
+ * @example Configuring gateways and routers
71
+ *
72
+ * ```typescript
73
+ * import { createVerifiedFetch } from '@helia/verified-fetch'
74
+ *
75
+ * const fetch = await createVerifiedFetch({
76
+ * gateways: ['https://trustless-gateway.link'],
77
+ * routers: ['http://delegated-ipfs.dev']
78
+ *})
79
+ *
80
+ * const resp = await fetch('ipfs://bafy...')
81
+ *
82
+ * const json = await resp.json()
83
+ *```
84
+ *
85
+ * ### Usage with customized Helia
86
+ *
87
+ * For full control of how `@helia/verified-fetch` fetches content from the distributed web you can pass a preconfigured Helia node to `createVerifiedFetch`.
88
+ *
89
+ * The [helia](https://www.npmjs.com/package/helia) module is configured with a libp2p node that is suited for decentralized applications, alternatively [@helia/http](https://www.npmjs.com/package/@helia/http) is available which uses HTTP gateways for all network operations.
90
+ *
91
+ * You can see variations of Helia and js-libp2p configuration options at https://helia.io/interfaces/helia.index.HeliaInit.html.
80
92
  *
81
93
  * ```typescript
82
94
  * import { trustlessGateway } from '@helia/block-brokers'
@@ -100,28 +112,28 @@
100
112
  * const json = await resp.json()
101
113
  * ```
102
114
  *
103
- * ### Comparison to fetch
115
+ * ## Comparison to fetch
104
116
  *
105
- * First, this library will require instantiation in order to configure the gateways and delegated routers, or potentially a custom Helia instance. Secondly, once your verified-fetch method is created, it will act as similar to the `fetch()` API as possible.
117
+ * This module attempts to act as similarly to the `fetch()` API as possible.
106
118
  *
107
119
  * [The `fetch()` API](https://developer.mozilla.org/en-US/docs/Web/API/fetch) takes two parameters:
108
120
  *
109
121
  * 1. A [resource](https://developer.mozilla.org/en-US/docs/Web/API/fetch#resource)
110
122
  * 2. An [options object](https://developer.mozilla.org/en-US/docs/Web/API/fetch#options)
111
123
  *
112
- * #### Resource argument
124
+ * ### Resource argument
113
125
  *
114
- * This library intends to support the following methods of fetching web3 content from IPFS:
126
+ * This library supports the following methods of fetching web3 content from IPFS:
115
127
  *
116
128
  * 1. IPFS protocol: `ipfs://<cidv0>` & `ipfs://<cidv0>`
117
129
  * 2. IPNS protocol: `ipns://<peerId>` & `ipns://<publicKey>` & `ipns://<hostUri_Supporting_DnsLink_TxtRecords>`
118
130
  * 3. CID instances: An actual CID instance `CID.parse('bafy...')`
119
131
  *
120
- * As well as support for pathing & params for item 1&2 above according to [IPFS - Path Gateway Specification](https://specs.ipfs.tech/http-gateways/path-gateway) & [IPFS - Trustless Gateway Specification](https://specs.ipfs.tech/http-gateways/trustless-gateway/). Further refinement of those specifications specifically for web-based scenarios can be found in the [Web Pathing Specification IPIP](https://github.com/ipfs/specs/pull/453).
132
+ * As well as support for pathing & params for item 1 & 2 above according to [IPFS - Path Gateway Specification](https://specs.ipfs.tech/http-gateways/path-gateway) & [IPFS - Trustless Gateway Specification](https://specs.ipfs.tech/http-gateways/trustless-gateway/). Further refinement of those specifications specifically for web-based scenarios can be found in the [Web Pathing Specification IPIP](https://github.com/ipfs/specs/pull/453).
121
133
  *
122
- * If you pass a CID instance, we assume you want the content for that specific CID only, and do not support pathing or params for that CID.
134
+ * 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.
123
135
  *
124
- * #### Options argument
136
+ * ### Options argument
125
137
  *
126
138
  * This library does not plan to support the exact Fetch API options object, as some of the arguments don't make sense. Instead, it will only support options necessary to meet [IPFS specs](https://specs.ipfs.tech/) related to specifying the resultant shape of desired content.
127
139
  *
@@ -146,7 +158,6 @@
146
158
  * 5. `body` - An object that specifies the body of the request. Best effort to adhere to the [Fetch API body](https://developer.mozilla.org/en-US/docs/Web/API/fetch#body) parameter.
147
159
  * 6. `cache` - Will basically act as `force-cache` for the request. Best effort to adhere to the [Fetch API cache](https://developer.mozilla.org/en-US/docs/Web/API/fetch#cache) parameter.
148
160
  *
149
- *
150
161
  * Non-Fetch API options that will be supported:
151
162
  *
152
163
  * 1. `onProgress` - Similar to Helia `onProgress` options, this will be a function that will be called with a progress event. Supported progress events are:
@@ -167,7 +178,7 @@
167
178
  * 4. [IPIP-0328: JSON and CBOR Response Formats on HTTP Gateways](https://specs.ipfs.tech/ipips/ipip-0328/)
168
179
  * 5. [IPIP-0288: TAR Response Format on HTTP Gateways](https://specs.ipfs.tech/ipips/ipip-0288/)
169
180
  *
170
- * #### Response types
181
+ * ### Response types
171
182
  *
172
183
  * 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.
173
184
  *
@@ -175,7 +186,7 @@
175
186
  *
176
187
  * If your content doesn't have a mime-type or an [IPFS spec](https://specs.ipfs.tech), this library will not support it, but you can use the [`helia`](https://github.com/ipfs/helia) library directly for those use cases. See [Unsupported response types](#unsupported-response-types) for more information.
177
188
  *
178
- * ##### Handling response types
189
+ * #### Handling response types
179
190
  *
180
191
  * For handling responses we want to follow conventions/abstractions from Fetch API where possible:
181
192
  *
@@ -184,12 +195,12 @@
184
195
  * - For plain text in utf-8, you would call `.text()`
185
196
  * - For streaming response data, use something like `response.body.getReader()` to get a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API/Using_readable_streams#consuming_a_fetch_as_a_stream).
186
197
  *
187
- * ##### Unsupported response types
198
+ * #### Unsupported response types
188
199
  *
189
200
  * * Returning IPLD nodes or DAGs as JS objects is not supported, as there is no currently well-defined structure for representing this data in an [HTTP Response](https://developer.mozilla.org/en-US/docs/Web/API/Response). Instead, users should request `aplication/vnd.ipld.car` or use the [`helia`](https://github.com/ipfs/helia) library directly for this use case.
190
201
  * * Others? Open an issue or PR!
191
202
  *
192
- * #### Response headers
203
+ * ### Response headers
193
204
  *
194
205
  * This library will set the [HTTP Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) headers to the appropriate values for the content type according to the appropriate [IPFS Specifications](https://specs.ipfs.tech/).
195
206
  *
@@ -199,13 +210,13 @@
199
210
  * * https://specs.ipfs.tech/http-gateways/trustless-gateway/#response-headers
200
211
  * * https://specs.ipfs.tech/http-gateways/subdomain-gateway/#response-headers
201
212
  *
202
- * #### Possible Scenarios that could cause confusion
213
+ * ### Possible Scenarios that could cause confusion
203
214
  *
204
- * ##### Attempting to fetch the CID for content that does not make sense
215
+ * #### Attempting to fetch the CID for content that does not make sense
205
216
  *
206
217
  * If you request `bafybeiaysi4s6lnjev27ln5icwm6tueaw2vdykrtjkwiphwekaywqhcjze`, which points to the root of the en.wikipedia.org mirror, a response object does not make sense.
207
218
  *
208
- * #### Errors
219
+ * ### Errors
209
220
  *
210
221
  * Known Errors that can be thrown:
211
222
  *
@@ -240,6 +251,7 @@ export async function createVerifiedFetch(init) {
240
251
  verifiedFetch.start = verifiedFetchInstance.start.bind(verifiedFetchInstance);
241
252
  return verifiedFetch;
242
253
  }
254
+ export { verifiedFetch } from './singleton.js';
243
255
  function isHelia(obj) {
244
256
  // test for the presence of known Helia properties, return a boolean value
245
257
  return obj?.blockstore != null &&
package/dist/src/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuNG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,EAAE,aAAa,IAAI,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAyDzE;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAE,IAA6C;IACtF,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACnB,IAAI,GAAG,MAAM,eAAe,CAAC;YAC3B,YAAY,EAAE;gBACZ,gBAAgB,CAAC;oBACf,QAAQ,EAAE,IAAI,EAAE,QAAQ;iBACzB,CAAC;aACH;YACD,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,IAAI,CAAC,4BAA4B,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,oBAAoB,CAAC,SAAS,CAAC,CAAC;SAC/G,CAAC,CAAA;IACJ,CAAC;IAED,MAAM,qBAAqB,GAAG,IAAI,kBAAkB,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;IACrE,KAAK,UAAU,aAAa,CAAE,QAAkB,EAAE,OAA2B;QAC3E,OAAO,qBAAqB,CAAC,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;IACvD,CAAC;IACD,aAAa,CAAC,IAAI,GAAG,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAA;IAC3E,aAAa,CAAC,KAAK,GAAG,qBAAqB,CAAC,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAA;IAE7E,OAAO,aAAa,CAAA;AACtB,CAAC;AAED,SAAS,OAAO,CAAE,GAAQ;IACxB,0EAA0E;IAC1E,OAAO,GAAG,EAAE,UAAU,IAAI,IAAI;QAC5B,GAAG,EAAE,SAAS,IAAI,IAAI;QACtB,GAAG,EAAE,EAAE,IAAI,IAAI;QACf,GAAG,EAAE,IAAI,IAAI,IAAI;QACjB,GAAG,EAAE,KAAK,IAAI,IAAI,CAAA;AACtB,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkOG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,EAAE,aAAa,IAAI,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAyDzE;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAE,IAA6C;IACtF,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACnB,IAAI,GAAG,MAAM,eAAe,CAAC;YAC3B,YAAY,EAAE;gBACZ,gBAAgB,CAAC;oBACf,QAAQ,EAAE,IAAI,EAAE,QAAQ;iBACzB,CAAC;aACH;YACD,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,IAAI,CAAC,4BAA4B,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,oBAAoB,CAAC,SAAS,CAAC,CAAC;SAC/G,CAAC,CAAA;IACJ,CAAC;IAED,MAAM,qBAAqB,GAAG,IAAI,kBAAkB,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;IACrE,KAAK,UAAU,aAAa,CAAE,QAAkB,EAAE,OAA2B;QAC3E,OAAO,qBAAqB,CAAC,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;IACvD,CAAC;IACD,aAAa,CAAC,IAAI,GAAG,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAA;IAC3E,aAAa,CAAC,KAAK,GAAG,qBAAqB,CAAC,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAA;IAE7E,OAAO,aAAa,CAAA;AACtB,CAAC;AAED,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAE9C,SAAS,OAAO,CAAE,GAAQ;IACxB,0EAA0E;IAC1E,OAAO,GAAG,EAAE,UAAU,IAAI,IAAI;QAC5B,GAAG,EAAE,SAAS,IAAI,IAAI;QACtB,GAAG,EAAE,EAAE,IAAI,IAAI;QACf,GAAG,EAAE,IAAI,IAAI,IAAI;QACjB,GAAG,EAAE,KAAK,IAAI,IAAI,CAAA;AACtB,CAAC"}
package/dist/src/singleton.d.ts ADDED
@@ -0,0 +1,3 @@
1
+ import type { VerifiedFetch } from './index.js';
2
+ export declare const verifiedFetch: VerifiedFetch;
3
+ //# sourceMappingURL=singleton.d.ts.map
package/dist/src/singleton.d.ts.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"singleton.d.ts","sourceRoot":"","sources":["../../src/singleton.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAY,aAAa,EAAqB,MAAM,YAAY,CAAA;AAI5E,eAAO,MAAM,aAAa,EAAE,aAM3B,CAAA"}
package/dist/src/singleton.js ADDED
@@ -0,0 +1,15 @@
1
+ import { createVerifiedFetch } from './index.js';
2
+ let impl;
3
+ export const verifiedFetch = async function verifiedFetch(resource, options) {
4
+ if (impl == null) {
5
+ impl = await createVerifiedFetch();
6
+ }
7
+ return impl(resource, options);
8
+ };
9
+ verifiedFetch.start = async function () {
10
+ await impl?.start();
11
+ };
12
+ verifiedFetch.stop = async function () {
13
+ await impl?.stop();
14
+ };
15
+ //# sourceMappingURL=singleton.js.map
package/dist/src/singleton.js.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"singleton.js","sourceRoot":"","sources":["../../src/singleton.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAGhD,IAAI,IAA+B,CAAA;AAEnC,MAAM,CAAC,MAAM,aAAa,GAAkB,KAAK,UAAU,aAAa,CAAE,QAAkB,EAAE,OAA2B;IACvH,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;QACjB,IAAI,GAAG,MAAM,mBAAmB,EAAE,CAAA;IACpC,CAAC;IAED,OAAO,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;AAChC,CAAC,CAAA;AAED,aAAa,CAAC,KAAK,GAAG,KAAK;IACzB,MAAM,IAAI,EAAE,KAAK,EAAE,CAAA;AACrB,CAAC,CAAA;AAED,aAAa,CAAC,IAAI,GAAG,KAAK;IACxB,MAAM,IAAI,EAAE,IAAI,EAAE,CAAA;AACpB,CAAC,CAAA"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@helia/verified-fetch",
3
- "version": "0.0.0-5c0c39c",
3
+ "version": "0.0.0-6c88ee1",
4
4
  "description": "A fetch-like API for obtaining verified & trustless IPFS content on the web.",
5
5
  "license": "Apache-2.0 OR MIT",
6
6
  "homepage": "https://github.com/ipfs/helia/tree/main/packages/verified-fetch#readme",
@@ -141,15 +141,15 @@
141
141
  "release": "aegir release"
142
142
  },
143
143
  "dependencies": {
144
- "@helia/block-brokers": "2.0.1-5c0c39c",
145
- "@helia/dag-cbor": "3.0.0-5c0c39c",
146
- "@helia/dag-json": "3.0.0-5c0c39c",
147
- "@helia/http": "1.0.1-5c0c39c",
148
- "@helia/interface": "4.0.0-5c0c39c",
149
- "@helia/ipns": "6.0.0-5c0c39c",
150
- "@helia/json": "3.0.0-5c0c39c",
151
- "@helia/routers": "1.0.0-5c0c39c",
152
- "@helia/unixfs": "3.0.0-5c0c39c",
144
+ "@helia/block-brokers": "2.0.1-6c88ee1",
145
+ "@helia/dag-cbor": "3.0.0-6c88ee1",
146
+ "@helia/dag-json": "3.0.0-6c88ee1",
147
+ "@helia/http": "1.0.1-6c88ee1",
148
+ "@helia/interface": "4.0.0-6c88ee1",
149
+ "@helia/ipns": "6.0.0-6c88ee1",
150
+ "@helia/json": "3.0.0-6c88ee1",
151
+ "@helia/routers": "1.0.0-6c88ee1",
152
+ "@helia/unixfs": "3.0.0-6c88ee1",
153
153
  "@ipld/dag-cbor": "^9.1.0",
154
154
  "@ipld/dag-json": "^10.1.7",
155
155
  "@ipld/dag-pb": "^4.0.8",
@@ -167,7 +167,7 @@
167
167
  "@types/mime-types": "^2.1.4",
168
168
  "@types/sinon": "^17.0.3",
169
169
  "aegir": "^42.2.2",
170
- "helia": "4.0.1-5c0c39c",
170
+ "helia": "4.0.1-6c88ee1",
171
171
  "sinon": "^17.0.1",
172
172
  "sinon-ts": "^2.0.0"
173
173
  },