v1.0.1 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: May 6, 2022 License: Apache-2.0, MIT, Apache-2.0, + 1 more Imports: 40 Imported by: 0


ipfs-cluster client

Made by Main project IRC channel standard-readme compliant GoDoc Go Report Card Build Status Coverage Status

Go client for ipfs-cluster HTTP API.

This is a Go client library to use the ipfs-cluster REST HTTP API.

Table of Contents


You can import in your code.

The code can be downloaded and tested with:

$ go get -u -d
$ cd $GOPATH/src/
$ go test -v


Documentation can be read at Godoc.


PRs accepted.


MIT © Protocol Labs



Package client provides a Go Client for the IPFS Cluster API provided by the "api/rest" component. It supports both the HTTP(s) endpoint and the libp2p-http endpoint.



This section is empty.


View Source
var (
	DefaultTimeout   = 0
	DefaultAPIAddr   = "/ip4/"
	DefaultLogLevel  = "info"
	DefaultProxyPort = 9095
	ResolveTimeout   = 30 * time.Second
	DefaultPort      = 9094

Configuration defaults


func IsPeerAddress added in v0.5.0

func IsPeerAddress(addr ma.Multiaddr) bool

IsPeerAddress detects if the given multiaddress identifies a libp2p peer, either because it has the /p2p/ protocol or because it uses /dnsaddr/

func WaitFor added in v0.6.0

WaitFor is a utility function that allows for a caller to wait until a CID status target is reached (as given in StatusFilterParams). It returns the final status for that CID and an error, if there was one.

WaitFor works by calling Status() repeatedly and checking that returned peers have transitioned to the target TrackerStatus. It immediately returns an error when the an error is among the statuses (and an empty GlobalPinInfo).

A special case exists for TrackerStatusPinned targets: in this case, TrackerStatusRemote statuses are ignored, so WaitFor will return when all Statuses are Pinned or Remote by default.

The Limit parameter allows to specify finer-grained control to, for example, only wait until a number of peers reaches a status.


type Client

type Client interface {
	// ID returns information about the cluster Peer.
	ID(context.Context) (api.ID, error)

	// Peers requests ID information for all cluster peers.
	Peers(context.Context, chan<- api.ID) error
	// PeerAdd adds a new peer to the cluster.
	PeerAdd(ctx context.Context, pid peer.ID) (api.ID, error)
	// PeerRm removes a current peer from the cluster
	PeerRm(ctx context.Context, pid peer.ID) error

	// Add imports files to the cluster from the given paths.
	Add(ctx context.Context, paths []string, params api.AddParams, out chan<- api.AddedOutput) error
	// AddMultiFile imports new files from a MultiFileReader.
	AddMultiFile(ctx context.Context, multiFileR *files.MultiFileReader, params api.AddParams, out chan<- api.AddedOutput) error

	// Pin tracks a Cid with the given replication factor and a name for
	// human-friendliness.
	Pin(ctx context.Context, ci api.Cid, opts api.PinOptions) (api.Pin, error)
	// Unpin untracks a Cid from cluster.
	Unpin(ctx context.Context, ci api.Cid) (api.Pin, error)

	// PinPath resolves given path into a cid and performs the pin operation.
	PinPath(ctx context.Context, path string, opts api.PinOptions) (api.Pin, error)
	// UnpinPath resolves given path into a cid and performs the unpin operation.
	// It returns api.Pin of the given cid before it is unpinned.
	UnpinPath(ctx context.Context, path string) (api.Pin, error)

	// Allocations returns the consensus state listing all tracked items
	// and the peers that should be pinning them.
	Allocations(ctx context.Context, filter api.PinType, out chan<- api.Pin) error
	// Allocation returns the current allocations for a given Cid.
	Allocation(ctx context.Context, ci api.Cid) (api.Pin, error)

	// Status returns the current ipfs state for a given Cid. If local is true,
	// the information affects only the current peer, otherwise the information
	// is fetched from all cluster peers.
	Status(ctx context.Context, ci api.Cid, local bool) (api.GlobalPinInfo, error)
	// StatusCids status information for the requested CIDs.
	StatusCids(ctx context.Context, cids []api.Cid, local bool, out chan<- api.GlobalPinInfo) error
	// StatusAll gathers Status() for all tracked items.
	StatusAll(ctx context.Context, filter api.TrackerStatus, local bool, out chan<- api.GlobalPinInfo) error

	// Recover retriggers pin or unpin ipfs operations for a Cid in error
	// state.  If local is true, the operation is limited to the current
	// peer, otherwise it happens on every cluster peer.
	Recover(ctx context.Context, ci api.Cid, local bool) (api.GlobalPinInfo, error)
	// RecoverAll triggers Recover() operations on all tracked items. If
	// local is true, the operation is limited to the current peer.
	// Otherwise, it happens everywhere.
	RecoverAll(ctx context.Context, local bool, out chan<- api.GlobalPinInfo) error

	// Alerts returns information health events in the cluster (expired
	// metrics etc.).
	Alerts(ctx context.Context) ([]api.Alert, error)

	// Version returns the ipfs-cluster peer's version.
	Version(context.Context) (api.Version, error)

	// IPFS returns an instance of go-ipfs-api's Shell, pointing to a
	// Cluster's IPFS proxy endpoint.
	IPFS(context.Context) *shell.Shell

	// GetConnectGraph returns an ipfs-cluster connection graph.
	GetConnectGraph(context.Context) (api.ConnectGraph, error)

	// Metrics returns a map with the latest metrics of matching name
	// for the current cluster peers.
	Metrics(ctx context.Context, name string) ([]api.Metric, error)

	// MetricNames returns the list of metric types.
	MetricNames(ctx context.Context) ([]string, error)

	// RepoGC runs garbage collection on IPFS daemons of cluster peers and
	// returns collected CIDs. If local is true, it would garbage collect
	// only on contacted peer, otherwise on all peers' IPFS daemons.
	RepoGC(ctx context.Context, local bool) (api.GlobalRepoGC, error)

Client interface defines the interface to be used by API clients to interact with the ipfs-cluster-service. All methods take a context.Context as their first parameter, this allows for timing out and cancelling of requests as well as recording metrics and tracing of requests through the API.

func NewDefaultClient added in v0.6.0

func NewDefaultClient(cfg *Config) (Client, error)

NewDefaultClient initializes a client given a Config.

func NewLBClient added in v0.11.0

func NewLBClient(strategy LBStrategy, cfgs []*Config, retries int) (Client, error)

NewLBClient returns a new client that would load balance requests among clients.

type Config

type Config struct {
	// Enable SSL support. Only valid without APIAddr.
	SSL bool
	// Skip certificate verification (insecure)
	NoVerifyCert bool

	// Username and password for basic authentication
	Username string
	Password string

	// The ipfs-cluster REST API endpoint in multiaddress form
	// (takes precedence over host:port). It this address contains
	// an /ipfs/, /p2p/ or /dnsaddr, the API will be contacted
	// through a libp2p tunnel, thus getting encryption for
	// free. Using the libp2p tunnel will ignore any configurations.
	APIAddr ma.Multiaddr

	// REST API endpoint host and port. Only valid without
	// APIAddr.
	Host string
	Port string

	// If APIAddr is provided, and the peer uses private networks (pnet),
	// then we need to provide the key. If the peer is the cluster peer,
	// this corresponds to the cluster secret.
	ProtectorKey pnet.PSK

	// ProxyAddr is used to obtain a go-ipfs-api Shell instance pointing
	// to the ipfs proxy endpoint of ipfs-cluster. If empty, the location
	// will be guessed from one of APIAddr/Host,
	// and the port used will be ipfs-cluster's proxy default port (9095)
	ProxyAddr ma.Multiaddr

	// Define timeout for network operations
	Timeout time.Duration

	// Specifies if we attempt to re-use connections to the same
	// hosts.
	DisableKeepAlives bool

	// LogLevel defines the verbosity of the logging facility
	LogLevel string

Config allows to configure the parameters to connect to the ipfs-cluster REST API.

func (*Config) AsTemplateFor added in v0.13.1

func (c *Config) AsTemplateFor(addrs []ma.Multiaddr) []*Config

AsTemplateFor creates client configs from resolved multiaddresses

func (*Config) AsTemplateForResolvedAddress added in v0.13.1

func (c *Config) AsTemplateForResolvedAddress(ctx context.Context, addr ma.Multiaddr) ([]*Config, error)

AsTemplateForResolvedAddress creates client configs from a multiaddress

type Failover added in v0.11.0

type Failover struct {
	// contains filtered or unexported fields

Failover is a load balancing strategy that would try the first cluster peer first. If the first call fails it would try other clients for that call in a round robin fashion.

func (*Failover) Next added in v0.11.0

func (f *Failover) Next(count int) Client

Next returns the next client to be used.

func (*Failover) SetClients added in v0.11.0

func (f *Failover) SetClients(cl []Client)

SetClients sets a list of clients for this strategy.

type LBStrategy added in v0.11.0

type LBStrategy interface {
	Next(count int) Client
	SetClients(clients []Client)

LBStrategy is a strategy to load balance requests among clients.

type RoundRobin added in v0.11.0

type RoundRobin struct {
	// contains filtered or unexported fields

RoundRobin is a load balancing strategy that would use clients in a sequence for all methods, throughout the lifetime of the lb client.

func (*RoundRobin) Next added in v0.11.0

func (r *RoundRobin) Next(count int) Client

Next return the next client to be used.

func (*RoundRobin) SetClients added in v0.11.0

func (r *RoundRobin) SetClients(cl []Client)

SetClients sets a list of clients for this strategy.

type StatusFilterParams added in v0.3.5

type StatusFilterParams struct {
	Cid       api.Cid
	Local     bool // query status from the local peer only
	Target    api.TrackerStatus
	Limit     int // wait for N peers reaching status. 0 == all
	CheckFreq time.Duration

StatusFilterParams contains the parameters required to filter a stream of status results.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL