ipfs-cluster: github.com/ipfs/ipfs-cluster/api/rest/client Index | Files

package client

import "github.com/ipfs/ipfs-cluster/api/rest/client"

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.


Package Files

client.go methods.go request.go transports.go


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

Configuration defaults

func IsPeerAddress Uses

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 Uses

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 (as defined by StatusFilterParams). It returns the final status for that CID and an error, if there was.

WaitFor works by calling Status() repeatedly and checking that all peers have transitioned to the target TrackerStatus or are Remote. If an error of some type happens, WaitFor returns immediately with an empty GlobalPinInfo.

type Client Uses

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(filter api.TrackerStatus, 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)

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

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

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

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

func NewDefaultClient Uses

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

NewDefaultClient initializes a client given a Config.

type Config Uses

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 Uses

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.

Package client imports 31 packages (graph) and is imported by 2 packages. Updated 2019-01-08. Refresh now. Tools for package owners.