ipfs-cluster / js-cluster-client

A client library for the IPFS Cluster HTTP API, implemented in JavaScript.

IPFS Cluster

Pinset orchestration for IPFS

IPFS Cluster provides data orchestration across a swarm of IPFS daemons by allocating, replicating and tracking a global pinset distributed among multiple peers.

There are 3 different applications:

• A cluster peer application: ipfs-cluster-service, to be run along with kubo (go-ipfs) as a sidecar.
• A client CLI application: ipfs-cluster-ctl, which allows easily interacting with the peer's HTTP API.
• An additional "follower" peer application: ipfs-cluster-follow, focused on simplifying the process of configuring and running follower peers.

---

Are you using IPFS Cluster?

Please participate in the IPFS Cluster user registry.

---

Table of Contents

• Documentation
• News & Roadmap
• Install
• Usage
• Contribute
• License

Documentation

Please visit https://ipfscluster.io/documentation/ to access user documentation, guides and any other resources, including detailed download and usage instructions.

News & Roadmap

We regularly post project updates to https://ipfscluster.io/news/ .

The most up-to-date Roadmap is available at https://ipfscluster.io/roadmap/ .

Install

Instructions for different installation methods (including from source) are available at https://ipfscluster.io/download .

Usage

Extensive usage information is provided at https://ipfscluster.io/documentation/ , including:

• Docs for ipfs-cluster-service
• Docs for ipfs-cluster-ctl
• Docs for ipfs-cluster-follow

Contribute

PRs accepted. As part of the IPFS project, we have some contribution guidelines.

License

This library is dual-licensed under Apache 2.0 and MIT terms.

© 2022. Protocol Labs, Inc.

js-cluster-client's Issues

cluster.pin.ls throws error when used with 'filter' option

I can't see the route for listing the pins in the Go implementation.
The listed GET method for '/pins' returns the response for the 'status' command.

improve documentation

Add more detailed docs on how to use the methods exposed by the repo.

[NodeJs] Not able to import

// or connect with multiaddr
var cluster = ipfsCluster('/ip4/127.0.0.1/tcp/9094')

// or using options
var cluster = ipfsCluster({ host: 'localhost', port: '9094', protocol: 'http' })

// or specifying a specific API path
var cluster = ipfsCluster({ host: '1.1.1.1', port: '80', 'api-path': '/some/api/path' })

The lib throws an error while importing using the above 3 methods.

Not able to ADD peer to a cluster using HTTP endpoint

Adding a peer throws error decoding peer_id error.
Postman request

cluster.recover local=true limitation?

From reading the documentation, under the cluster.recover section, I noticed that it says:
"For now, ONLY requests with parameter local=true are supported"

From brief testing, passing in local=false seems to work fine, am I missing something here, or is this outdated information @vasa-develop ?

Add function return [] when pass Buffer.

I try to use cluster library against my local ipfs cluster, but Add is not working in cluster. pin add and pin remove have worked successfully.

example :

let ref = await ipfsCluster.add(Buffer.from("hello"));

I am using this test cluster using docker-compose. https://cluster.ipfs.io/documentation/quickstart/

When i pass following object, it worked :
const obj = {
path: './test.html',
content: Buffer.from(fs.readFileSync('./test.html'))
}

But for followings not working. Return [ ] .

1. Buffer.from("Hello");

2. {name: "name", age: 23}

remove `peers.add`

As discussed in this thread, the only safe way to add peers to a cluster is bootstrapping the node to a current cluster member(healthy).

Add more tests

Add tests

• Tests using all possible options for the following commands:

  • add
  • pin.add

• Negative tests

Release 0.0.7

#8 remove peers.add
#7 Add more test

changing the repo name to `js-cluster-api`

Are we expecting other language implementations for this API in the future?
If yes, then I think it's better to name this repo js-cluster-api. Or if there are no such plans, then let's leave it.

Even if we change the repo name we will still keep the npm module name: ipfs-cluster-api

@hsanjuan what are your thoughts?

Cloud add typescript types?

as title, cloud add the types files for typescript development?

addFromFS

An addFromFs functionality would be very useful (similar in functionality to the addFromFS functionality from the js-ipfs-http-client: https://github.com/ipfs/interface-js-ipfs-core/blob/master/SPEC/FILES.md#addfromfs

I'm not sure how challenging this would be as I haven't dove too much into this library's codebase, but having the ability to add directories directly to cluster (though something like this) would be awesome.

'add' command doesn't return the CID for the added data.

In v0.0.3 when we do:

cluster.add(CID, (err, res) => {
    console.log(res)
})

We get an empty array: []

Somehow we aren't getting the CID object(which can be accessed using a normal POST request).

Here is what I have found:

• On running the test for 'add', this line is supposed to get the CIDs. But it's NOT getting any CIDs.

Add GLOBAL options

Following Flags are supported in ipfs-cluster-ctl CLI.

 --host value, -l value         Cluster's HTTP or LibP2P-HTTP API endpoint (default: "/ip4/127.0.0.1/tcp/9094")
   --secret value                 cluster secret (32 byte pnet-key) as needed. Only when using the LibP2P endpoint
   --https, -s                    use https to connect to the API
   --no-check-certificate         do not verify server TLS certificate. only valid with --https flag
   --encoding value, --enc value  output format encoding [text, json] (default: "text")
   --timeout value, -t value      number of seconds to wait before timing out a request (default: 0)
   --debug, -d                    set debug log level
   --basic-auth value             <username>[:<password>] specify BasicAuth credentials for server that
requires authorization. implies --https, which you can disable with --force-http [$CLUSTER_CREDENTIALS]
   --force-http, -f  force HTTP. only valid when using BasicAuth
   --help, -h        show help
   --version, -v     print the version

Check which of these can be passed in the cluster initialization script(as headers).