Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ipfs-shipyard/ipfs-provider
Connect to IPFS via an available provider
https://github.com/ipfs-shipyard/ipfs-provider
ipfs p2p provider
Last synced: 2 months ago
JSON representation
Connect to IPFS via an available provider
- Host: GitHub
- URL: https://github.com/ipfs-shipyard/ipfs-provider
- Owner: ipfs-shipyard
- License: mit
- Created: 2019-06-03T15:31:25.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-03-04T03:51:36.000Z (almost 2 years ago)
- Last Synced: 2024-11-04T19:41:58.154Z (2 months ago)
- Topics: ipfs, p2p, provider
- Language: JavaScript
- Homepage:
- Size: 2.5 MB
- Stars: 33
- Watchers: 14
- Forks: 9
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-ccamel - ipfs-shipyard/ipfs-provider - Connect to IPFS via an available provider (JavaScript)
README
# ipfs-provider
[](https://github.com/ipfs-shipyard/ipfs-provider/releases/latest)
[](https://protocol.ai)
[](http://ipfs.io/)
[](https://travis-ci.com/ipfs-shipyard/ipfs-provider)
[](https://david-dm.org/ipfs-shipyard/ipfs-provider)
> Returns IPFS API object by trying multiple [providers](#providers) in a custom fallback order.
>
> This is a general-purpose replacement for [ipfs-redux-bundle](https://github.com/ipfs-shipyard/ipfs-redux-bundle).
- [Install](#install)
- [Usage](#usage)
- [Examples](#examples)
- [Providers](#providers)
- [`httpClient`](#httpclient) (remote/local HTTP API)
- [`jsIpfs`](#jsipfs) (embedded js-ipfs node)
- [Test](#test)
## Install
### via NPM
```console
$ npm install ipfs-provider
```
### via prebuilt browser bundles
```html
const { getIpfs, providers } = window.IpfsProvider
const { ipfs, provider, apiAddress } = await getIpfs({
loadHttpClientModule: () => window.IpfsHttpClient,
loadJsIpfsModule: () => window.IpfsCore,
providers: [ /* see Usage below */ ]
})
```
**Note:** when using prebuilt bundles in production use explicit versions and SRI hashes.
Details [here](https://github.com/ipfs/js-ipfs/tree/master/packages/ipfs-http-client#in-a-web-browser).
## Usage
```js
const { getIpfs, providers } = require('ipfs-provider')
const { httpClient, jsIpfs } = providers
const { ipfs, provider, apiAddress } = await getIpfs({
// when httpClient provider is used multiple times
// define its constructor once, at the top level
loadHttpClientModule: () => require('ipfs-http-client'),
// note this is an array, providers are tried in order:
providers: [
// try various HTTP endpoints (best-effort),
httpClient({
// (1) try multiaddr of a local node
apiAddress: '/ip4/127.0.0.1/tcp/5001'
}),
httpClient(), // (2) try "/api/v0/" on the same Origin as the page
httpClient({
// (3) try arbitrary API from URL string
apiAddress: 'https://some.example.com:8080'
}),
httpClient({
// (4) try API defined by a custom http client config
apiAddress: {
host: 'apis.example.com',
port: '443',
protocol: 'https',
apiPath: 'custom/path/to/api/v0',
headers: {
authorization: 'Basic dXNlcjpwYXNz'
}
}
}),
// (5) final fallback to spawning embedded js-ipfs running in-page
jsIpfs({
// js-ipfs package is used only once, as a last resort
loadJsIpfsModule: () => require('ipfs-core'),
options: { } // pass config: https://github.com/ipfs/js-ipfs/blob/master/packages/ipfs/docs/MODULE.md#ipfscreateoptions
})
]
})
for await (const file of ipfs.add("text")) {
if (file && file.cid) {
console.log(`successfully stored at ${file.cid}`)
} else {
console.error('unable to ipfs.add', file)
}
}
```
- `ipfs` – returned instance of IPFS API (see [SPEC](https://github.com/ipfs/js-ipfs/blob/master/docs/core-api/README.md))
- `provider` – a string with a name of the first successful provider.
- built-in names match constants from `providers`: `httpClient`, `jsIpfs`, `windowIpfs` and `webExt`.
- `apiAddress` – returned only when `httpClient` provider is used, provides information which HTTP endpoint succeded
## Examples
See [`examples/`](./examples) for sample code and demonstration of advanced fallback strategies.
## Providers
You can customize the order of the providers by passing a different array order to the `providers` array.
For example, if you want to try `httpClient` and then `jsIpfs`, you should run it like this:
```js
const { getIpfs, providers } = require('ipfs-provider')
const { httpClient, jsIpfs } = providers
const { ipfs, provider } = await getIpfs({
providers: [
httpClient(),
jsIpfs()
]
})
```
#### Customizing connection test
```js
const { ipfs, provider } = await getIpfs({
providers: [ /* array of providers to try in order */ ],
connectionTest: () => { /* boolean function to test the connection to IPFS, default one tries to ipfs.get the CID of an empty directory */ },
})
```
### `httpClient`
Tries to connect to HTTP API via [`js-ipfs-http-client`](https://github.com/ipfs/js-ipfs/tree/master/packages/ipfs-http-client):
```js
const { ipfs, provider } = await getIpfs({
providers: [
httpClient({
loadHttpClientModule: () => require('ipfs-http-client'),
apiAddress: 'https://api.example.com:8080/'
})
]
})
```
This provider will attempt to establish connection with (in order):
1. `apiAddress` (if provided)
2. `/api/` at the current Origin
3. the default local API (`/ip4/127.0.0.1/tcp/5001`)
It supports lazy-loading and small bundle sizes. The client library is initialized using constructor (in order):
1. one returned by `loadHttpClientModule` async function (if provided)
2. one exposed at `window.IpfsHttpClient` (if present)
Value passed in `apiAddress` can be:
- a multiaddr (string like `/ip4/127.0.0.1/tcp/5001` or an [object](https://github.com/multiformats/js-multiaddr/))
- a String with an URL (`https://api.example.com:8080/`)
- a configuration object supported by the [constructor](https://github.com/ipfs/js-ipfs/tree/master/packages/ipfs-http-client#importing-the-module-and-usage)
(`{ host: '1.1.1.1', port: '80', apiPath: '/ipfs/api/v0' }`)
To try multiple endpoints, simply use this provider multiple times.
See [`examples/browser-browserify/src/index.js`](./examples/browser-browserify/src/index.js) for real world example.
### `jsIpfs`
Spawns embedded [`js-ipfs`](https://github.com/ipfs/js-ipfs/tree/master/packages/ipfs) (a full IPFS node in JavaScript)
in the context of the current page using customizable constructor:
```js
const { ipfs, provider } = await getIpfs({
providers: [
jsIpfs({
loadJsIpfsModule: () => require('ipfs-core'),
options: { /* advanced config */ }
})
]
})
```
- `loadJsIpfsModule` should be a function that returns a promise that resolves to a js-ipfs constructor
- `options` should be an object which specifies [advanced configurations](https://github.com/ipfs/js-ipfs#ipfs-constructor) to the node.
- **TIP:** when used in a browser context, use `ipfs-core` for a smaller browser bundle
### `windowIpfs`
[`window.ipfs`](https://github.com/ipfs-shipyard/ipfs-companion/blob/master/docs/window.ipfs.md) was an experiment created by [ipfs-companion](https://github.com/ipfs/ipfs-companion) browser extension.
It supported passing an optional list of permissions to [display a single ACL prompt](https://github.com/ipfs-shipyard/ipfs-companion/blob/master/docs/window.ipfs.md#do-i-need-to-confirm-every-api-call) the first time it is used:
```js
const { ipfs, provider } = await getIpfs({
providers: [
windowIpfs({
// example
permissions: { commands: ['add','cat','id', 'version'] }
})
]
})
```
### `webExt`
`webExt` looks for an instance in the [background page of a WebExtension](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/extension/getBackgroundPage)
(useful only in browser extensions, not regular pages, disabled by default)
```js
const { ipfs, provider } = await getIpfs({
providers: [
webExt()
]
})
```
## Test
```console
$ npm test
```
## Lint
Perform [`standard`](https://standardjs.com/) linting on the code:
```console
$ npm run lint
```
## Contribute
Feel free to dive in! [Open an issue](https://github.com/ipfs-shipyard/ipfs-provider/issues/new) or submit PRs.
To contribute to IPFS in general, see the [contributing guide](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md).
[](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md)
## License
[MIT](LICENSE) © Protocol Labs