client

README

ipfs-cluster client

Go client for ipfs-cluster HTTP API.

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

Table of Contents

• Install
• Usage
• Contribute
• License

Install

You can import github.com/ipfs/ipfs-cluster/api/rest/client in your code. If you wish to use gx for dependency management, it can be imported with:

$ gx import github.com/ipfs/ipfs-cluster/

The code can be downloaded and tested with:

$ go get -u -d github.com/ipfs/ipfs-cluster
$ cd $GOPATH/src/github.com/ipfs/ipfs-cluster/rest/api/client
$ go test -v

Usage

Documentation can be read at Godoc.

Contribute

PRs accepted.

License

MIT © Protocol Labs

Documentation

Overview

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.

Index

• Variables
• func IsPeerAddress(addr ma.Multiaddr) bool
• func WaitFor(ctx context.Context, c Client, fp StatusFilterParams) (api.GlobalPinInfo, error)
• type Client
  • func NewDefaultClient(cfg *Config) (Client, error)
• type Config
• type StatusFilterParams

Variables

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

Configuration defaults

Functions

func IsPeerAddress

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

func WaitFor(ctx context.Context, c Client, fp StatusFilterParams) (api.GlobalPinInfo, error)

WaitFor is a utility function that allows for a caller to wait for a paticular status for a CID. It returns a channel upon which the caller can wait for the targetStatus.

Types

type Client

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

	// Peers requests ID information for all cluster peers.
	Peers() ([]api.ID, error)
	// PeerAdd adds a new peer to the cluster.
	PeerAdd(pid peer.ID) (api.ID, error)
	// PeerRm removes a current peer from the cluster
	PeerRm(pid peer.ID) error

	// Add imports files to the cluster from the given paths.
	Add(paths []string, params *api.AddParams, out chan<- *api.AddedOutput) error
	// AddMultiFile imports new files from a MultiFileReader.
	AddMultiFile(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(ci cid.Cid, replicationFactorMin, replicationFactorMax int, name string) error
	// Unpin untracks a Cid from cluster.
	Unpin(ci cid.Cid) error

	// Allocations returns the consensus state listing all tracked items
	// and the peers that should be pinning them.
	Allocations(filter api.PinType) ([]api.Pin, error)
	// Allocation returns the current allocations for a given Cid.
	Allocation(ci cid.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(ci cid.Cid, local bool) (api.GlobalPinInfo, error)
	// StatusAll gathers Status() for all tracked items.
	StatusAll(local bool) ([]api.GlobalPinInfo, error)

	// Sync makes sure the state of a Cid corresponds to the state reported
	// by the ipfs daemon, and returns it. If local is true, this operation
	// only happens on the current peer, otherwise it happens on every
	// cluster peer.
	Sync(ci cid.Cid, local bool) (api.GlobalPinInfo, error)
	// SyncAll triggers Sync() operations for all tracked items. It only
	// returns informations for items that were de-synced or have an error
	// state. If local is true, the operation is limited to the current
	// peer. Otherwise it happens on every cluster peer.
	SyncAll(local bool) ([]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(ci cid.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(local bool) ([]api.GlobalPinInfo, error)

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

	// GetConnectGraph returns an ipfs-cluster connection graph.  The
	// serialized version, strings instead of pids, is returned
	GetConnectGraph() (api.ConnectGraphSerial, error)
}

Client interface defines the interface to be used by API clients to interact with the ipfs-cluster-service

func NewDefaultClient

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

NewDefaultClient initializes a client given a Config.

type Config

type Config struct {
	// Enable SSL support. Only valid without PeerAddr.
	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

	// PeerAddr is deprecated. It's aliased to APIAddr
	PeerAddr ma.Multiaddr

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

	// If PeerAddr 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 []byte

	// 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.

type StatusFilterParams

type StatusFilterParams struct {
	Cid       cid.Cid
	Local     bool
	Target    api.TrackerStatus
	CheckFreq time.Duration
}

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