diff --git a/LICENSE b/LICENSE new file mode 100644 index 000000000..20ce483c8 --- /dev/null +++ b/LICENSE @@ -0,0 +1,4 @@ +This project is dual licensed under MIT and Apache-2.0. + +MIT: https://www.opensource.org/licenses/mit +Apache-2.0: https://www.apache.org/licenses/license-2.0 diff --git a/LICENSE-MIT b/LICENSE-MIT index 2b7661ee4..72dc60d84 100644 --- a/LICENSE-MIT +++ b/LICENSE-MIT @@ -1,7 +1,5 @@ The MIT License (MIT) -Copyright (c) 2016 Protocol Labs, Inc. - Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights @@ -9,14 +7,13 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. - +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. diff --git a/README.md b/README.md index 3f5a97697..666171ca7 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,20 @@ -

- IPFS http client lib logo -

+# ipfs-http-client -

The JavaScript HTTP RPC API client library for IPFS implementations.

+[![ipfs.io](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](http://ipfs.io) +[![IRC](https://img.shields.io/badge/freenode-%23ipfs-blue.svg?style=flat-square)](http://webchat.freenode.net/?channels=%23ipfs) +[![Discord](https://img.shields.io/discord/806902334369824788?style=flat-square)](https://discord.gg/ipfs) +[![codecov](https://img.shields.io/codecov/c/github/ipfs/js-ipfs.svg?style=flat-square)](https://codecov.io/gh/ipfs/js-ipfs) +[![CI](https://img.shields.io/github/workflow/status/ipfs/js-ipfs/test%20&%20maybe%20release/master?style=flat-square)](https://github.com/ipfs/js-ipfs/actions/workflows/js-test-and-release.yml) -

- - - - -

+> A client library for the IPFS HTTP API -

- - - - -
- - - - - - - -
-

- -> A client library for the IPFS HTTP RPC API (`/api/v0/*`), implemented in JavaScript. This client library implements the IPFS [Core API](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api) enabling applications to change between an embedded js-ipfs node and any remote IPFS node without having to change the code. In addition, this client library implements a set of utility functions. - -## Table of Contents +## Table of contents +- [Install](#install) - [Getting Started](#getting-started) - - [Install](#install) - [Next Steps](#next-steps) - [Usage](#usage) - - [`create([options])`](#createoptions) + - - [`create([options])`](#createoptions) - [Parameters](#parameters) - [Options](#options) - [Returns](#returns) @@ -57,17 +36,48 @@ - [Global Timeouts](#global-timeouts) - [Development](#development) - [Testing](#testing) -- [Contribute](#contribute) - [Historical context](#historical-context) - [License](#license) +- [Contribute](#contribute) -## Getting Started +## Install -We've come a long way, but this project is still in Alpha, lots of development is happening, APIs might change, beware of 🐉.. +```console +$ npm i ipfs-http-client +``` + +

+ IPFS http client lib logo +

+ +

The JavaScript HTTP RPC API client library for IPFS implementations.

-### Install +

+ + + + +

-This module uses node.js, and can be installed through npm: +

+ + + + +
+ + + + + + + +
+

+ +## Getting Started + +We've come a long way, but this project is still in Alpha, lots of development is happening, APIs might change, beware of 🐉.. ```bash npm install --save ipfs-http-client @@ -77,14 +87,14 @@ Both the Current and Active LTS versions of Node.js are supported. Please see [n ### Next Steps -* Read the [docs](https://github.com/ipfs/js-ipfs/tree/master/docs) -* Look into the [examples](https://github.com/ipfs-examples/js-ipfs-examples) to learn how to spawn an IPFS node in Node.js and in the Browser -* Consult the [Core API docs](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api) to see what you can do with an IPFS node -* Visit https://dweb-primer.ipfs.io to learn about IPFS and the concepts that underpin it -* Head over to https://proto.school to take interactive tutorials that cover core IPFS APIs -* Check out https://docs.ipfs.io for tips, how-tos and more -* See https://blog.ipfs.io for news and more -* Need help? Please ask 'How do I?' questions on https://discuss.ipfs.io +- Read the [docs](https://github.com/ipfs/js-ipfs/tree/master/docs) +- Look into the [examples](https://github.com/ipfs-examples/js-ipfs-examples) to learn how to spawn an IPFS node in Node.js and in the Browser +- Consult the [Core API docs](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api) to see what you can do with an IPFS node +- Visit to learn about IPFS and the concepts that underpin it +- Head over to to take interactive tutorials that cover core IPFS APIs +- Check out for tips, how-tos and more +- See for news and more +- Need help? Please ask 'How do I?' questions on ## Usage @@ -102,19 +112,19 @@ None Alternatively it can be an object which may have the following keys: -| Name | Type | Default | Description | -| ---- | ---- | ------- | ----------- | -| url | `String` or `URL` or `Multiaddr` | `'http://localhost:5001/api/v0'` | A URL that resolves to a running instance of the IPFS [HTTP RPC API](https://docs.ipfs.io/reference/http/api/) | -| protocol | `String` | `'http'` | The protocol to used (ignored if url is specified) | -| host | `String` | `'localhost'` | The host to used (ignored if url is specified) | -| port | `number` | `5001` | The port to used (ignored if url is specified) | -| path | `String` | `'api/v0'` | The path to used (ignored if url is specified) | -| agent | [http.Agent](https://nodejs.org/api/http.html#http_class_http_agent) | `http.Agent({ keepAlive: true, maxSockets: 6 })` | An `http.Agent` used to control client behaviour (node.js only) | +| Name | Type | Default | Description | +| -------- | -------------------------------------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | +| url | `String` or `URL` or `Multiaddr` | `'http://localhost:5001/api/v0'` | A URL that resolves to a running instance of the IPFS [HTTP RPC API](https://docs.ipfs.io/reference/http/api/) | +| protocol | `String` | `'http'` | The protocol to used (ignored if url is specified) | +| host | `String` | `'localhost'` | The host to used (ignored if url is specified) | +| port | `number` | `5001` | The port to used (ignored if url is specified) | +| path | `String` | `'api/v0'` | The path to used (ignored if url is specified) | +| agent | [http.Agent](https://nodejs.org/api/http.html#http_class_http_agent) | `http.Agent({ keepAlive: true, maxSockets: 6 })` | An `http.Agent` used to control client behaviour (node.js only) | #### Returns -| Type | Description | -| ---- | ----------- | +| Type | Description | +| -------- | --------------------------------------------------------------------------------------------------------- | | `Object` | An object that conforms to the [IPFS Core API](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api) | #### Example @@ -143,10 +153,10 @@ const { cid } = await client.add('Hello world!') ### Additional Options -All core API methods take _additional_ `options` specific to the HTTP API: +All core API methods take *additional* `options` specific to the HTTP API: -* `headers` - An object or [Headers](https://developer.mozilla.org/en-US/docs/Web/API/Headers) instance that can be used to set custom HTTP headers. Note that this option can also be [configured globally](#custom-headers) via the constructor options. -* `searchParams` - An object or [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) instance that can be used to add additional query parameters to the query string sent with each request. +- `headers` - An object or [Headers](https://developer.mozilla.org/en-US/docs/Web/API/Headers) instance that can be used to set custom HTTP headers. Note that this option can also be [configured globally](#custom-headers) via the constructor options. +- `searchParams` - An object or [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) instance that can be used to add additional query parameters to the query string sent with each request. ### Instance Utils @@ -299,9 +309,9 @@ To always request the latest version, use one of the following examples: For maximum security you may also decide to: -* reference a specific version of IPFS API (to prevent unexpected breaking changes when a newer latest version is published) -* [generate a SRI hash](https://www.srihash.org/) of that version and use it to ensure integrity. Learn more also at the [jsdelivr website](https://www.jsdelivr.com/using-sri-with-dynamic-files) -* set the [CORS settings attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_settings_attributes) to make anonymous requests to CDN +- reference a specific version of IPFS API (to prevent unexpected breaking changes when a newer latest version is published) +- [generate a SRI hash](https://www.srihash.org/) of that version and use it to ensure integrity. Learn more also at the [jsdelivr website](https://www.jsdelivr.com/using-sri-with-dynamic-files) +- set the [CORS settings attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_settings_attributes) to make anonymous requests to CDN Example: @@ -342,7 +352,7 @@ const ipfs = create({ ### Global Timeouts -To set a global timeout for _all_ requests pass a value for the `timeout` option: +To set a global timeout for *all* requests pass a value for the `timeout` option: ```js // Timeout after 10 seconds @@ -358,24 +368,25 @@ const ipfs = create({ timeout: '2m' }) We run tests by executing `npm test` in a terminal window. This will run both Node.js and Browser tests, both in Chrome and PhantomJS. To ensure that the module conforms with the [`interface-ipfs-core`](https://github.com/ipfs/js-ipfs/tree/master/packages/interface-ipfs-core) spec, we run the batch of tests provided by the interface module, which can be found [here](https://github.com/ipfs/js-ipfs/tree/master/packages/interface-ipfs-core/src). -## Contribute +## Historical context -The js-ipfs-http-client is a work in progress. As such, there's a few things you can do right now to help out: +This module started as a direct mapping from the go-ipfs cli to a JavaScript implementation, although this was useful and familiar to a lot of developers that were coming to IPFS for the first time, it also created some confusion on how to operate the core of IPFS and have access to the full capacity of the protocol. After much consideration, we decided to create `interface-ipfs-core` with the goal of standardizing the interface of a core implementation of IPFS, and keep the utility functions the IPFS community learned to use and love, such as reading files from disk and storing them directly to IPFS. -- **[Check out the existing issues](https://github.com/ipfs/js-ipfs-http-client/issues)**! -- **Perform code reviews**. More eyes will help a) speed the project along b) ensure quality and c) reduce possible future bugs. -- **Add tests**. There can never be enough tests. Note that interface tests exist inside [`interface-ipfs-core`](https://github.com/ipfs/js-ipfs/tree/master/packages/interface-ipfs-core/src). +## License -**Want to hack on IPFS?** +Licensed under either of -[![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md) +- Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) +- MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Historical context +## Contribute -This module started as a direct mapping from the go-ipfs cli to a JavaScript implementation, although this was useful and familiar to a lot of developers that were coming to IPFS for the first time, it also created some confusion on how to operate the core of IPFS and have access to the full capacity of the protocol. After much consideration, we decided to create `interface-ipfs-core` with the goal of standardizing the interface of a core implementation of IPFS, and keep the utility functions the IPFS community learned to use and love, such as reading files from disk and storing them directly to IPFS. +Contributions welcome! Please check out [the issues](https://github.com/ipfs/js-ipfs/issues). -## License +Also see our [contributing document](https://github.com/ipfs/community/blob/master/CONTRIBUTING_JS.md) for more information on how we work, and about contributing in general. -[MIT](LICENSE) +Please be aware that all interactions related to this repo are subject to the IPFS [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md). -[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fipfs%2Fjs-ipfs-http-client.svg?type=large)](https://app.fossa.io/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fipfs%2Fjs-ipfs-http-client?ref=badge_large) +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. + +[![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md) diff --git a/package.json b/package.json index 884466f15..f6b0e24b4 100644 --- a/package.json +++ b/package.json @@ -2,21 +2,49 @@ "name": "ipfs-http-client", "version": "57.0.3", "description": "A client library for the IPFS HTTP API", + "license": "Apache-2.0 OR MIT", + "homepage": "https://github.com/ipfs/js-ipfs/tree/master/packages/ipfs-http-client#readme", + "repository": { + "type": "git", + "url": "git+https://github.com/ipfs/js-ipfs.git" + }, + "bugs": { + "url": "https://github.com/ipfs/js-ipfs/issues" + }, "keywords": [ "ipfs" ], - "homepage": "https://github.com/ipfs/js-ipfs/tree/master/packages/ipfs-http-client#readme", - "bugs": "https://github.com/ipfs/js-ipfs/issues", - "license": "(Apache-2.0 OR MIT)", + "engines": { + "node": ">=16.0.0", + "npm": ">=7.0.0" + }, "type": "module", - "types": "dist/src/index.d.ts", + "types": "./dist/src/index.d.ts", + "typesVersions": { + "*": { + "*": [ + "*", + "dist/*", + "dist/src/*", + "dist/src/*/index" + ], + "src/*": [ + "*", + "dist/*", + "dist/src/*", + "dist/src/*/index" + ] + } + }, "files": [ - "dist", "src", + "dist", + "!dist/test", "!**/*.tsbuildinfo" ], "exports": { ".": { + "types": "./dist/src/index.d.ts", "import": "./src/index.js" } }, @@ -26,17 +54,6 @@ "sourceType": "module" } }, - "browser": { - "ipfs-utils/src/files/glob-source": false, - "go-ipfs": false, - "ipfs-core-utils/src/files/normalise-input": "ipfs-core-utils/src/files/normalise-input/index.browser.js", - "http": false, - "https": false - }, - "repository": { - "type": "git", - "url": "git+https://github.com/ipfs/js-ipfs.git" - }, "scripts": { "build": "aegir build", "test": "aegir test", @@ -53,18 +70,18 @@ "@ipld/dag-cbor": "^7.0.0", "@ipld/dag-json": "^8.0.1", "@ipld/dag-pb": "^2.1.3", - "@libp2p/logger": "^1.1.4", + "@libp2p/logger": "^2.0.0", "@libp2p/peer-id": "^1.1.10", + "@multiformats/multiaddr": "^10.1.8", "any-signal": "^3.0.0", - "dag-jose": "^1.0.0", + "dag-jose": "^2.0.1", "err-code": "^3.0.1", - "ipfs-core-types": "^0.11.1", - "ipfs-core-utils": "^0.15.1", + "ipfs-core-types": "^0.11.0", + "ipfs-core-utils": "^0.15.0", "ipfs-utils": "^9.0.6", "it-first": "^1.0.6", "it-last": "^1.0.4", "merge-options": "^3.0.4", - "@multiformats/multiaddr": "^10.0.0", "multiformats": "^9.5.1", "parse-duration": "^1.0.0", "stream-to-it": "^0.2.2", @@ -74,117 +91,17 @@ "aegir": "^37.0.11", "delay": "^5.0.0", "go-ipfs": "^0.12.1", - "ipfsd-ctl": "^11.0.0", + "ipfsd-ctl": "^12.0.0", "it-all": "^1.0.4", "it-first": "^1.0.4", "nock": "^13.0.2", "p-defer": "^4.0.0" }, - "engines": { - "node": ">=15.0.0", - "npm": ">=3.0.0" - }, - "contributors": [ - "Alan Shaw ", - "Alan Shaw ", - "Alex Mingoia ", - "Alex Potsides ", - "Antonio Tenorio-Fornés ", - "Bruno Barbieri ", - "Clemo ", - "Connor Keenan ", - "Daniel Constantin ", - "Danny ", - "David Braun ", - "David Dias ", - "Dietrich Ayala ", - "Diogo Silva ", - "Dmitriy Ryajov ", - "Dmitry Nikulin ", - "Donatas Stundys ", - "Fil ", - "Filip Š ", - "Francisco Baio Dias ", - "Friedel Ziegelmayer ", - "Gar ", - "Gavin McDermott ", - "Gopalakrishna Palem ", - "Greenkeeper ", - "Haad ", - "Harlan T Wood ", - "Harlan T Wood ", - "Henrique Dias ", - "Holodisc ", - "Hugo Dias ", - "Hugo Dias ", - "JGAntunes ", - "Jacob Heun ", - "James Halliday ", - "Jason Carver ", - "Jason Papakostas ", - "Jeff Downie ", - "Jeromy ", - "Jeromy ", - "Jim Pick ", - "Joe Turgeon ", - "Jonathan ", - "Juan Batiz-Benet ", - "Kevin Wang ", - "Kristoffer Ström ", - "Marcin Rataj ", - "Matt Bell ", - "Matt Ober ", - "Maxime Lathuilière ", - "Michael Bradley ", - "Michael Muré ", - "Michael Muré ", - "Mikeal Rogers ", - "Mitar ", - "Mithgol ", - "Mohamed Abdulaziz ", - "Nitin Patel <31539366+niinpatel@users.noreply.github.com>", - "Nuno Nogueira ", - "Níckolas Goline ", - "Oli Evans ", - "Orie Steele ", - "Paul Cowgill ", - "Pedro Santos ", - "Pedro Santos ", - "Pedro Teixeira ", - "Pete Thomas ", - "Richard Littauer ", - "Richard Schneider ", - "Roman Khafizianov ", - "SeungWon ", - "Stephen Whitmore ", - "Tara Vancil ", - "Teri Chadbourne ", - "Travis Person ", - "Travis Person ", - "Vasco Santos ", - "Vasco Santos ", - "Victor Bjelkholm ", - "Volker Mische ", - "Zhiyuan Lin ", - "dirkmc ", - "dmitriy ryajov ", - "elsehow ", - "ethers ", - "greenkeeper[bot] <23040076+greenkeeper[bot]@users.noreply.github.com>", - "greenkeeper[bot] ", - "haad ", - "kumavis ", - "leekt216 ", - "nginnever ", - "noah the goodra ", - "phillmac ", - "priecint ", - "samuli ", - "sarthak khandelwal ", - "shunkin ", - "victorbjelkholm ", - "Łukasz Magiera ", - "Łukasz Magiera ", - "Xmader " - ] + "browser": { + "ipfs-utils/src/files/glob-source": false, + "go-ipfs": false, + "ipfs-core-utils/src/files/normalise-input": "ipfs-core-utils/src/files/normalise-input/index.browser.js", + "http": false, + "https": false + } } diff --git a/src/dht/map-event.js b/src/dht/map-event.js index 7a8777759..c08cd50f3 100644 --- a/src/dht/map-event.js +++ b/src/dht/map-event.js @@ -13,7 +13,7 @@ import { Multiaddr } from '@multiformats/multiaddr' import { peerIdFromString } from '@libp2p/peer-id' /** - * @typedef {import('@libp2p/interfaces/peer-id').PeerId} PeerId + * @typedef {import('@libp2p/interface-peer-id').PeerId} PeerId */ /** @@ -46,7 +46,7 @@ export const mapEvent = (event) => { if (event.Type === FinalPeer) { // dht.query ends with a FinalPeer event with no Responses - /** @type {import('@libp2p/interfaces/peer-info').PeerInfo} */ + /** @type {import('@libp2p/interface-peer-info').PeerInfo} */ let peer = { // @ts-expect-error go-ipfs does not return this id: event.ID ?? peerIdFromString(event.ID), diff --git a/src/pubsub/subscribe.js b/src/pubsub/subscribe.js index 8646747a2..38fd85dce 100644 --- a/src/pubsub/subscribe.js +++ b/src/pubsub/subscribe.js @@ -7,7 +7,7 @@ const log = logger('ipfs-http-client:pubsub:subscribe') /** * @typedef {import('../types').HTTPClientExtraOptions} HTTPClientExtraOptions - * @typedef {import('@libp2p/interfaces/pubsub').Message} Message + * @typedef {import('@libp2p/interface-pubsub').Message} Message * @typedef {(err: Error, fatal: boolean, msg?: Message) => void} ErrorHandlerFn * @typedef {import('ipfs-core-types/src/pubsub').API} PubsubAPI * @typedef {import('../types').Options} Options @@ -107,12 +107,23 @@ async function readMessages (response, { onMessage, onEnd, onError }) { continue } - onMessage({ - from: peerIdFromString(msg.from), - data: rpcToBytes(msg.data), - sequenceNumber: rpcToBigInt(msg.seqno), - topic: rpcToText(msg.topicIDs[0]) - }) + if (msg.from != null && msg.seqno != null) { + onMessage({ + type: 'signed', + from: peerIdFromString(msg.from), + data: rpcToBytes(msg.data), + sequenceNumber: rpcToBigInt(msg.seqno), + topic: rpcToText(msg.topicIDs[0]), + key: rpcToBytes(msg.key ?? 'u'), + signature: rpcToBytes(msg.signature ?? 'u') + }) + } else { + onMessage({ + type: 'unsigned', + data: rpcToBytes(msg.data), + topic: rpcToText(msg.topicIDs[0]) + }) + } } catch (/** @type {any} */ err) { err.message = `Failed to parse pubsub message: ${err.message}` onError(err, false, msg) // Not fatal diff --git a/src/pubsub/subscription-tracker.js b/src/pubsub/subscription-tracker.js index 3cc0dd5a0..52bb1db9b 100644 --- a/src/pubsub/subscription-tracker.js +++ b/src/pubsub/subscription-tracker.js @@ -1,6 +1,6 @@ /** - * @typedef {import('@libp2p/interfaces/pubsub').Message} Message + * @typedef {import('@libp2p/interface-pubsub').Message} Message * @typedef {import('@libp2p/interfaces/events').EventHandler} MessageHandlerFn * * @typedef {object} Subscription