api

Documentation

Overview

Package api holds declarations for types used in ipfs-cluster APIs to make them re-usable across differen tools. This include RPC API "Serial[izable]" versions for types. The Go API uses natives types, while RPC API, REST APIs etc use serializable types (i.e. json format). Converstion methods exists between types.

Note that all conversion methods ignore any parsing errors. All values must be validated first before initializing any of the types defined here.

Index

• Constants
• type Alert
• type GlobalPinInfo
  • func (gpi GlobalPinInfo) ToSerial() GlobalPinInfoSerial
• type GlobalPinInfoSerial
  • func (gpis GlobalPinInfoSerial) ToGlobalPinInfo() GlobalPinInfo
• type ID
  • func (id ID) ToSerial() IDSerial
• type IDSerial
  • func (ids IDSerial) ToID() ID
• type IPFSID
  • func (id *IPFSID) ToSerial() IPFSIDSerial
• type IPFSIDSerial
  • func (ids *IPFSIDSerial) ToIPFSID() IPFSID
• type IPFSPinStatus
  • func IPFSPinStatusFromString(t string) IPFSPinStatus
  • func (ips IPFSPinStatus) IsPinned() bool
• type Metric
  • func (m *Metric) Discard() bool
  • func (m *Metric) Expired() bool
  • func (m *Metric) GetTTL() time.Duration
  • func (m *Metric) SetTTL(seconds int)
• type MultiaddrSerial
  • func MultiaddrToSerial(addr ma.Multiaddr) MultiaddrSerial
  • func (addrS MultiaddrSerial) ToMultiaddr() ma.Multiaddr
• type MultiaddrsSerial
  • func MultiaddrsToSerial(addrs []ma.Multiaddr) MultiaddrsSerial
  • func (addrsS MultiaddrsSerial) ToMultiaddrs() []ma.Multiaddr
• type Pin
  • func PinCid(c *cid.Cid) Pin
  • func (pin Pin) ToSerial() PinSerial
• type PinInfo
  • func (pi PinInfo) ToSerial() PinInfoSerial
• type PinInfoSerial
  • func (pis PinInfoSerial) ToPinInfo() PinInfo
• type PinSerial
  • func (pins PinSerial) ToPin() Pin
• type TrackerStatus
  • func TrackerStatusFromString(str string) TrackerStatus
  • func (st TrackerStatus) String() string
• type Version

Constants

const (
	// IPFSStatus should never take this value
	TrackerStatusBug = iota
	// The cluster node is offline or not responding
	TrackerStatusClusterError
	// An error occurred pinning
	TrackerStatusPinError
	// An error occurred unpinning
	TrackerStatusUnpinError
	// The IPFS daemon has pinned the item
	TrackerStatusPinned
	// The IPFS daemon is currently pinning the item
	TrackerStatusPinning
	// The IPFS daemon is currently unpinning the item
	TrackerStatusUnpinning
	// The IPFS daemon is not pinning the item
	TrackerStatusUnpinned
	// The IPFS deamon is not pinning the item but it is being tracked
	TrackerStatusRemote
)

TrackerStatus values

const (
	IPFSPinStatusBug = iota
	IPFSPinStatusError
	IPFSPinStatusDirect
	IPFSPinStatusRecursive
	IPFSPinStatusIndirect
	IPFSPinStatusUnpinned
)

IPFSPinStatus values

Types

type Alert

type Alert struct {
	Peer       peer.ID
	MetricName string
}

Alert carries alerting information about a peer. WIP.

type GlobalPinInfo

type GlobalPinInfo struct {
	Cid     *cid.Cid
	PeerMap map[peer.ID]PinInfo
}

GlobalPinInfo contains cluster-wide status information about a tracked Cid, indexed by cluster peer.

func (GlobalPinInfo) ToSerial

func (gpi GlobalPinInfo) ToSerial() GlobalPinInfoSerial

ToSerial converts a GlobalPinInfo to its serializable version.

type GlobalPinInfoSerial

type GlobalPinInfoSerial struct {
	Cid     string                   `json:"cid"`
	PeerMap map[string]PinInfoSerial `json:"peer_map"`
}

GlobalPinInfoSerial is the serializable version of GlobalPinInfo.

func (GlobalPinInfoSerial) ToGlobalPinInfo

func (gpis GlobalPinInfoSerial) ToGlobalPinInfo() GlobalPinInfo

ToGlobalPinInfo converts a GlobalPinInfoSerial to its native version.

type ID

type ID struct {
	ID                 peer.ID
	Addresses          []ma.Multiaddr
	ClusterPeers       []ma.Multiaddr
	Version            string
	Commit             string
	RPCProtocolVersion protocol.ID
	Error              string
	IPFS               IPFSID
}

ID holds information about the Cluster peer

func (ID) ToSerial

func (id ID) ToSerial() IDSerial

ToSerial converts an ID to its Go-serializable version

type IDSerial

type IDSerial struct {
	ID                 string           `json:"id"`
	Addresses          MultiaddrsSerial `json:"addresses"`
	ClusterPeers       MultiaddrsSerial `json:"cluster_peers"`
	Version            string           `json:"version"`
	Commit             string           `json:"commit"`
	RPCProtocolVersion string           `json:"rpc_protocol_version"`
	Error              string           `json:"error"`
	IPFS               IPFSIDSerial     `json:"ipfs"`
}

IDSerial is the serializable ID counterpart for RPC requests

func (IDSerial) ToID

func (ids IDSerial) ToID() ID

ToID converts an IDSerial object to ID. It will ignore any errors when parsing the fields.

type IPFSID

type IPFSID struct {
	ID        peer.ID
	Addresses []ma.Multiaddr
	Error     string
}

IPFSID is used to store information about the underlying IPFS daemon

func (*IPFSID) ToSerial

func (id *IPFSID) ToSerial() IPFSIDSerial

ToSerial converts IPFSID to a go serializable object

type IPFSIDSerial

type IPFSIDSerial struct {
	ID        string           `json:"id"`
	Addresses MultiaddrsSerial `json:"addresses"`
	Error     string           `json:"error"`
}

IPFSIDSerial is the serializable IPFSID for RPC requests

func (*IPFSIDSerial) ToIPFSID

func (ids *IPFSIDSerial) ToIPFSID() IPFSID

ToIPFSID converts an IPFSIDSerial to IPFSID

type IPFSPinStatus

type IPFSPinStatus int

IPFSPinStatus represents the status of a pin in IPFS (direct, recursive etc.)

func IPFSPinStatusFromString

func IPFSPinStatusFromString(t string) IPFSPinStatus

IPFSPinStatusFromString parses a string and returns the matching IPFSPinStatus.

func (IPFSPinStatus) IsPinned

func (ips IPFSPinStatus) IsPinned() bool

IsPinned returns true if the status is Direct or Recursive

type Metric

type Metric struct {
	Name   string
	Peer   peer.ID // filled-in by Cluster.
	Value  string
	Expire string // RFC1123
	Valid  bool   // if the metric is not valid it will be discarded
}

Metric transports information about a peer.ID. It is used to decide pin allocations by a PinAllocator. IPFS cluster is agnostic to the Value, which should be interpreted by the PinAllocator.

func (*Metric) Discard

func (m *Metric) Discard() bool

Discard returns if the metric not valid or has expired

func (*Metric) Expired

func (m *Metric) Expired() bool

Expired returns if the Metric has expired

func (*Metric) GetTTL

func (m *Metric) GetTTL() time.Duration

GetTTL returns the time left before the Metric expires

func (*Metric) SetTTL

func (m *Metric) SetTTL(seconds int)

SetTTL sets Metric to expire after the given seconds

type MultiaddrSerial

type MultiaddrSerial string

MultiaddrSerial is a Multiaddress in a serializable form

func MultiaddrToSerial

func MultiaddrToSerial(addr ma.Multiaddr) MultiaddrSerial

MultiaddrToSerial converts a Multiaddress to its serializable form

func (MultiaddrSerial) ToMultiaddr

func (addrS MultiaddrSerial) ToMultiaddr() ma.Multiaddr

ToMultiaddr converts a serializable Multiaddress to its original type. All errors are ignored.

type MultiaddrsSerial

type MultiaddrsSerial []MultiaddrSerial

MultiaddrsSerial is an array of Multiaddresses in serializable form

func MultiaddrsToSerial

func MultiaddrsToSerial(addrs []ma.Multiaddr) MultiaddrsSerial

MultiaddrsToSerial converts a slice of Multiaddresses to its serializable form.

func (MultiaddrsSerial) ToMultiaddrs

func (addrsS MultiaddrsSerial) ToMultiaddrs() []ma.Multiaddr

ToMultiaddrs converts MultiaddrsSerial back to a slice of Multiaddresses

type Pin

type Pin struct {
	Cid               *cid.Cid
	Allocations       []peer.ID
	ReplicationFactor int
}

Pin is an argument that carries a Cid. It may carry more things in the future.

func PinCid

func PinCid(c *cid.Cid) Pin

PinCid is a shorcut to create a Pin only with a Cid.

func (Pin) ToSerial

func (pin Pin) ToSerial() PinSerial

ToSerial converts a Pin to PinSerial.

type PinInfo

type PinInfo struct {
	Cid    *cid.Cid
	Peer   peer.ID
	Status TrackerStatus
	TS     time.Time
	Error  string
}

PinInfo holds information about local pins. PinInfo is serialized when requesting the Global status, therefore we cannot use *cid.Cid.

func (PinInfo) ToSerial

func (pi PinInfo) ToSerial() PinInfoSerial

ToSerial converts a PinInfo to its serializable version.

type PinInfoSerial

type PinInfoSerial struct {
	Cid    string `json:"cid"`
	Peer   string `json:"peer"`
	Status string `json:"status"`
	TS     string `json:"timestamp"`
	Error  string `json:"error"`
}

PinInfoSerial is a serializable version of PinInfo. information is marked as

func (PinInfoSerial) ToPinInfo

func (pis PinInfoSerial) ToPinInfo() PinInfo

ToPinInfo converts a PinInfoSerial to its native version.

type PinSerial

type PinSerial struct {
	Cid               string   `json:"cid"`
	Allocations       []string `json:"allocations"`
	Everywhere        bool     `json:"everywhere,omitempty"` // legacy
	ReplicationFactor int      `json:"replication_factor"`
}

PinSerial is a serializable version of Pin

func (PinSerial) ToPin

func (pins PinSerial) ToPin() Pin

ToPin converts a PinSerial to its native form.

type TrackerStatus

type TrackerStatus int

TrackerStatus represents the status of a tracked Cid in the PinTracker

func TrackerStatusFromString

func TrackerStatusFromString(str string) TrackerStatus

TrackerStatusFromString parses a string and returns the matching TrackerStatus value.

func (TrackerStatus) String

func (st TrackerStatus) String() string

String converts a TrackerStatus into a readable string.

type Version

type Version struct {
	Version string `json:"Version"`
}

Version holds version information