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

Index

• Variables
• type Client
  • func NewClient(cfg *Config) (*Client, error)
  • func (c *Client) Allocation(ci *cid.Cid) (api.Pin, error)
  • func (c *Client) Allocations() ([]api.Pin, error)
  • func (c *Client) GetConnectGraph() (api.ConnectGraphSerial, error)
  • func (c *Client) ID() (api.ID, error)
  • func (c *Client) IPFS() *shell.Shell
  • func (c *Client) PeerAdd(addr ma.Multiaddr) (api.ID, error)
  • func (c *Client) PeerRm(id peer.ID) error
  • func (c *Client) Peers() ([]api.ID, error)
  • func (c *Client) Pin(ci *cid.Cid, replicationFactorMin, replicationFactorMax int, name string) error
  • func (c *Client) Recover(ci *cid.Cid, local bool) (api.GlobalPinInfo, error)
  • func (c *Client) RecoverAll(local bool) ([]api.GlobalPinInfo, error)
  • func (c *Client) Status(ci *cid.Cid, local bool) (api.GlobalPinInfo, error)
  • func (c *Client) StatusAll(local bool) ([]api.GlobalPinInfo, error)
  • func (c *Client) Sync(ci *cid.Cid, local bool) (api.GlobalPinInfo, error)
  • func (c *Client) SyncAll(local bool) ([]api.GlobalPinInfo, error)
  • func (c *Client) Unpin(ci *cid.Cid) error
  • func (c *Client) Version() (api.Version, error)
  • func (c *Client) WaitFor(ctx context.Context, fp StatusFilterParams) (api.GlobalPinInfo, error)
• type Config
• type StatusFilterParams

Variables

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

Configuration defaults

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client provides methods to interact with the ipfs-cluster API. Use NewClient() to create one.

func NewClient

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

NewClient initializes a client given a Config.

func (*Client) Allocation

func (c *Client) Allocation(ci *cid.Cid) (api.Pin, error)

Allocation returns the current allocations for a given Cid.

func (*Client) Allocations

func (c *Client) Allocations() ([]api.Pin, error)

Allocations returns the consensus state listing all tracked items and the peers that should be pinning them.

func (*Client) GetConnectGraph

func (c *Client) GetConnectGraph() (api.ConnectGraphSerial, error)

GetConnectGraph returns an ipfs-cluster connection graph. The serialized version, strings instead of pids, is returned

func (*Client) ID

func (c *Client) ID() (api.ID, error)

ID returns information about the cluster Peer.

func (*Client) IPFS

func (c *Client) IPFS() *shell.Shell

IPFS returns an instance of go-ipfs-api's Shell, pointing to the configured ProxyAddr (or to the default ipfs-cluster's IPFS proxy port). It re-uses this Client's HTTP client, thus will be constrained by the same configurations affecting it (timeouts...).

func (*Client) PeerAdd

func (c *Client) PeerAdd(addr ma.Multiaddr) (api.ID, error)

PeerAdd adds a new peer to the cluster.

func (*Client) PeerRm

func (c *Client) PeerRm(id peer.ID) error

PeerRm removes a current peer from the cluster

func (*Client) Peers

func (c *Client) Peers() ([]api.ID, error)

Peers requests ID information for all cluster peers.

func (*Client) Pin

func (c *Client) Pin(ci *cid.Cid, replicationFactorMin, replicationFactorMax int, name string) error

Pin tracks a Cid with the given replication factor and a name for human-friendliness.

func (*Client) Recover

func (c *Client) Recover(ci *cid.Cid, 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.

func (*Client) RecoverAll

func (c *Client) RecoverAll(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.

func (*Client) Status

func (c *Client) Status(ci *cid.Cid, local bool) (api.GlobalPinInfo, 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.

func (*Client) StatusAll

func (c *Client) StatusAll(local bool) ([]api.GlobalPinInfo, error)

StatusAll gathers Status() for all tracked items.

func (*Client) Sync

func (c *Client) Sync(ci *cid.Cid, 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.

func (*Client) SyncAll

func (c *Client) SyncAll(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.

func (*Client) Unpin

func (c *Client) Unpin(ci *cid.Cid) error

Unpin untracks a Cid from cluster.

func (*Client) Version

func (c *Client) Version() (api.Version, error)

Version returns the ipfs-cluster peer's version.

func (*Client) WaitFor

func (c *Client) WaitFor(ctx context.Context, 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.

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). Only valid without PeerAddr.
	APIAddr ma.Multiaddr

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

	// The ipfs-cluster REST API peer address (usually
	// the same as the cluster peer). This will use libp2p
	// to tunnel HTTP requests, thus getting encryption for
	// free. It overseeds APIAddr, Host/Port, and SSL configurations.
	PeerAddr ma.Multiaddr

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