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). Conversion 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
- Variables
- func CidsToStrings(cids []cid.Cid) []string
- func Libp2pMultiaddrSplit(addr ma.Multiaddr) (peer.ID, ma.Multiaddr, error)
- func MustLibp2pMultiaddrJoin(addr ma.Multiaddr, p peer.ID) ma.Multiaddr
- func PeersToStrings(peers []peer.ID) []string
- func StringsToCidSet(strs []string) *cid.Set
- func StringsToPeers(strs []string) []peer.ID
- type AddParams
- type AddedOutput
- type Alert
- type ConnectGraph
- type ConnectGraphSerial
- type Error
- type GlobalPinInfo
- type GlobalPinInfoSerial
- type ID
- type IDSerial
- type IPFSID
- type IPFSIDSerial
- type IPFSPinStatus
- type IPFSRepoStat
- type Metric
- type MetricSerial
- type MultiaddrSerial
- type MultiaddrsSerial
- type NodeWithMeta
- type Pin
- type PinInfo
- type PinInfoSerial
- type PinOptions
- type PinSerial
- type PinType
- type SwarmPeers
- type SwarmPeersSerial
- type TrackerStatus
- type Version
Constants ¶
const ( TrackerStatusError = TrackerStatusClusterError | TrackerStatusPinError | TrackerStatusUnpinError TrackerStatusQueued = TrackerStatusPinQueued | TrackerStatusUnpinQueued )
Composite TrackerStatus.
Variables ¶
var DefaultShardSize = uint64(100 * 1024 * 1024) // 100 MB
DefaultShardSize is the shard size for params objects created with DefaultParams().
Functions ¶
func CidsToStrings ¶ added in v0.5.0
CidsToStrings encodes cid.Cids to strings.
func Libp2pMultiaddrSplit ¶ added in v0.3.5
Libp2pMultiaddrSplit takes a LibP2P multiaddress (/<multiaddr>/ipfs/<peerID>) and decapsulates it, parsing the peer ID. Returns an error if there is any problem (for example, the provided address not being a Libp2p one).
func MustLibp2pMultiaddrJoin ¶ added in v0.3.5
MustLibp2pMultiaddrJoin takes a LibP2P multiaddress and a peer ID and encapsulates a new /ipfs/<peerID> address. It will panic if the given peer ID is bad.
func PeersToStrings ¶ added in v0.3.1
PeersToStrings IDB58Encodes a list of peers.
func StringsToCidSet ¶ added in v0.5.0
StringsToCidSet decodes cid.Cids from strings.
func StringsToPeers ¶ added in v0.3.1
StringsToPeers decodes peer.IDs from strings.
Types ¶
type AddParams ¶ added in v0.5.0
type AddParams struct { PinOptions Recursive bool Layout string Chunker string RawLeaves bool Hidden bool Wrap bool Shard bool Progress bool CidVersion int HashFun string StreamChannels bool }
AddParams contains all of the configurable parameters needed to specify the importing process of a file being added to an ipfs-cluster
func AddParamsFromQuery ¶ added in v0.5.0
AddParamsFromQuery parses the AddParams object from a URL.Query().
func DefaultAddParams ¶ added in v0.5.0
func DefaultAddParams() *AddParams
DefaultAddParams returns a AddParams object with standard defaults
func (*AddParams) ToQueryString ¶ added in v0.5.0
ToQueryString returns a url query string (key=value&key2=value2&...)
type AddedOutput ¶ added in v0.5.0
type AddedOutput struct { Name string `json:"name"` Cid string `json:"cid,omitempty"` Bytes uint64 `json:"bytes,omitempty"` Size uint64 `json:"size,omitempty"` }
AddedOutput carries information for displaying the standard ipfs output indicating a node of a file has been added.
type ConnectGraph ¶ added in v0.3.3
type ConnectGraph struct { ClusterID peer.ID IPFSLinks map[peer.ID][]peer.ID // ipfs to ipfs links ClusterLinks map[peer.ID][]peer.ID // cluster to cluster links ClustertoIPFS map[peer.ID]peer.ID // cluster to ipfs links }
ConnectGraph holds information about the connectivity of the cluster
To read, traverse the keys of ClusterLinks. Each such id is one of the peers of the "ClusterID" peer running the query. ClusterLinks[id] in turn lists the ids that peer "id" sees itself connected to. It is possible that id is a peer of ClusterID, but ClusterID can not reach id over rpc, in which case ClusterLinks[id] == [], as id's view of its connectivity can not be retrieved. Iff there was an error reading the IPFSID of the peer then id will not be a key of ClustertoIPFS or IPFSLinks. Finally iff id is a key of ClustertoIPFS then id will be a key of IPFSLinks. In the event of a SwarmPeers error IPFSLinks[id] == [].
func (ConnectGraph) ToSerial ¶ added in v0.3.3
func (cg ConnectGraph) ToSerial() ConnectGraphSerial
ToSerial converts a ConnectGraph to its Go-serializable version
type ConnectGraphSerial ¶ added in v0.3.3
type ConnectGraphSerial struct { ClusterID string IPFSLinks map[string][]string `json:"ipfs_links"` ClusterLinks map[string][]string `json:"cluster_links"` ClustertoIPFS map[string]string `json:"cluster_to_ipfs"` }
ConnectGraphSerial is the serializable ConnectGraph counterpart for RPC requests
func (ConnectGraphSerial) ToConnectGraph ¶ added in v0.3.3
func (cgs ConnectGraphSerial) ToConnectGraph() ConnectGraph
ToConnectGraph converts a ConnectGraphSerial to a ConnectGraph
type GlobalPinInfo ¶
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 []peer.ID ClusterPeersAddresses []ma.Multiaddr Version string Commit string RPCProtocolVersion protocol.ID Error string IPFS IPFSID Peername string }
ID holds information about the Cluster peer
type IDSerial ¶
type IDSerial struct { ID string `json:"id"` Addresses MultiaddrsSerial `json:"addresses"` ClusterPeers []string `json:"cluster_peers"` ClusterPeersAddresses MultiaddrsSerial `json:"cluster_peers_addresses"` Version string `json:"version"` Commit string `json:"commit"` RPCProtocolVersion string `json:"rpc_protocol_version"` Error string `json:"error"` IPFS IPFSIDSerial `json:"ipfs"` Peername string `json:"peername"` }
IDSerial is the serializable ID counterpart for RPC requests
type IPFSID ¶
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.)
const ( IPFSPinStatusBug IPFSPinStatus = iota IPFSPinStatusError IPFSPinStatusDirect IPFSPinStatusRecursive IPFSPinStatusIndirect IPFSPinStatusUnpinned )
IPFSPinStatus values FIXME include maxdepth
func IPFSPinStatusFromString ¶
func IPFSPinStatusFromString(t string) IPFSPinStatus
IPFSPinStatusFromString parses a string and returns the matching IPFSPinStatus.
func (IPFSPinStatus) IsPinned ¶
func (ips IPFSPinStatus) IsPinned(maxDepth int) bool
IsPinned returns true if the item is pinned as expected by the maxDepth parameter.
func (IPFSPinStatus) ToTrackerStatus ¶ added in v0.4.0
func (ips IPFSPinStatus) ToTrackerStatus() TrackerStatus
ToTrackerStatus converts the IPFSPinStatus value to the appropriate TrackerStatus value.
type IPFSRepoStat ¶ added in v0.5.0
IPFSRepoStat wraps information about the IPFS repository.
type Metric ¶
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) MarshalJSON ¶ added in v0.7.0
MarshalJSON allows a Metric to produce a JSON representation of itself.
func (*Metric) UnmarshalJSON ¶ added in v0.7.0
UnmarshalJSON decodes JSON on top of the Metric.
type MetricSerial ¶ added in v0.8.0
type MetricSerial struct { Name string `json:"name"` Peer string `json:"peer"` Value string `json:"value"` Expire int64 `json:"expire"` Valid bool `json:"valid"` }
MetricSerial is a helper for JSON marshaling. The Metric type is already serializable, but not pretty to humans (API).
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 NodeWithMeta ¶ added in v0.5.0
NodeWithMeta specifies a block of data and a set of optional metadata fields carrying information about the encoded ipld node
func (*NodeWithMeta) Size ¶ added in v0.5.0
func (n *NodeWithMeta) Size() uint64
Size returns how big is the block. It is different from CumSize, which records the size of the underlying tree.
type Pin ¶ added in v0.0.6
type Pin struct { PinOptions Cid cid.Cid // See PinType comments Type PinType // The peers to which this pin is allocated Allocations []peer.ID // MaxDepth associated to this pin. -1 means // recursive. MaxDepth int // We carry a reference CID to this pin. For // ClusterDAGs, it is the MetaPin CID. For the // MetaPin it is the ClusterDAG CID. For Shards, // it is the previous shard CID. Reference cid.Cid }
Pin carries all the information associated to a CID that is pinned in IPFS Cluster.
func PinCid ¶ added in v0.0.6
PinCid is a shortcut to create a Pin only with a Cid. Default is for pin to be recursive and the pin to be of DataType.
func PinWithOpts ¶ added in v0.5.0
func PinWithOpts(c cid.Cid, opts PinOptions) Pin
PinWithOpts creates a new Pin calling PinCid(c) and then sets its PinOptions fields with the given options.
func (Pin) Equals ¶ added in v0.3.2
Equals checks if two pins are the same (with the same allocations). If allocations are the same but in different order, they are still considered equivalent.
func (Pin) IsRemotePin ¶ added in v0.5.0
IsRemotePin determines whether a Pin's ReplicationFactor has been met, so as to either pin or unpin it from the peer.
type PinInfo ¶
type PinInfo struct { Cid cid.Cid Peer peer.ID PeerName string Status TrackerStatus TS time.Time Error string }
PinInfo holds information about local pins.
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"` PeerName string `json:"peername"` 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 PinOptions ¶ added in v0.5.0
type PinOptions struct { ReplicationFactorMin int `json:"replication_factor_min"` ReplicationFactorMax int `json:"replication_factor_max"` Name string `json:"name"` ShardSize uint64 `json:"shard_size"` }
PinOptions wraps user-defined options for Pins
type PinSerial ¶ added in v0.0.6
type PinSerial struct { PinOptions Cid string `json:"cid"` Type uint64 `json:"type"` Allocations []string `json:"allocations"` MaxDepth int `json:"max_depth"` Reference string `json:"reference"` }
PinSerial is a serializable version of Pin
type PinType ¶ added in v0.5.0
type PinType uint64
PinType specifies which sort of Pin object we are dealing with. In practice, the PinType decides how a Pin object is treated by the PinTracker. See descriptions above. A sharded Pin would look like:
[ Meta ] (not pinned on IPFS, only present in cluster state)
| v
[ Cluster DAG ] (pinned everywhere in "direct")
| .. | v v
[Shard1] .. [ShardN] (allocated to peers and pinned with max-depth=1 | | .. | | | .. | v v .. v v v .. v [][]..[] [][]..[] Blocks (indirectly pinned on ipfs, not tracked in cluster)
const ( // BadType type showing up anywhere indicates a bug BadType PinType = 1 << iota // DataType is a regular, non-sharded pin. It is pinned recursively. // It has no associated reference. DataType // MetaType tracks the original CID of a sharded DAG. Its Reference // points to the Cluster DAG CID. MetaType // ClusterDAGType pins carry the CID of the root node that points to // all the shard-root-nodes of the shards in which a DAG has been // divided. Its Reference carries the MetaType CID. // ClusterDAGType pins are pinned directly everywhere. ClusterDAGType // ShardType pins carry the root CID of a shard, which points // to individual blocks on the original DAG that the user is adding, // which has been sharded. // They carry a Reference to the previous shard. // ShardTypes are pinned with MaxDepth=1 (root and // direct children only). ShardType )
PinType values. See PinType documentation for further explanation.
const AllType PinType = DataType | MetaType | ClusterDAGType | ShardType
AllType is a PinType used for filtering all pin types
func PinTypeFromString ¶ added in v0.5.0
PinTypeFromString is the inverse of String. It returns the PinType value corresponding to the input string
type SwarmPeers ¶ added in v0.3.3
SwarmPeers lists an ipfs daemon's peers
func (SwarmPeers) ToSerial ¶ added in v0.3.3
func (swarm SwarmPeers) ToSerial() SwarmPeersSerial
ToSerial converts SwarmPeers to its Go-serializeable version
type SwarmPeersSerial ¶ added in v0.3.3
type SwarmPeersSerial []string
SwarmPeersSerial is the serialized form of SwarmPeers for RPC use
func (SwarmPeersSerial) ToSwarmPeers ¶ added in v0.3.3
func (swarmS SwarmPeersSerial) ToSwarmPeers() SwarmPeers
ToSwarmPeers converts a SwarmPeersSerial object to SwarmPeers.
type TrackerStatus ¶
type TrackerStatus int
TrackerStatus represents the status of a tracked Cid in the PinTracker
const ( // IPFSStatus should never take this value. // When used as a filter. It means "all". TrackerStatusUndefined TrackerStatus = 0 // The cluster node is offline or not responding TrackerStatusClusterError TrackerStatus = 1 << iota // 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 daemon is not pinning the item but it is being tracked TrackerStatusRemote // The item has been queued for pinning on the IPFS daemon TrackerStatusPinQueued // The item has been queued for unpinning on the IPFS daemon TrackerStatusUnpinQueued // The IPFS daemon is not pinning the item through this cid but it is // tracked in a cluster dag TrackerStatusSharded )
TrackerStatus values
func TrackerStatusAll ¶ added in v0.8.0
func TrackerStatusAll() []TrackerStatus
TrackerStatusAll all known TrackerStatus values.
func TrackerStatusFromString ¶
func TrackerStatusFromString(str string) TrackerStatus
TrackerStatusFromString parses a string and returns the matching TrackerStatus value. The string can be a comma-separated list representing a TrackerStatus filter. Unknown status names are ignored.
func (TrackerStatus) Match ¶ added in v0.8.0
func (st TrackerStatus) Match(filter TrackerStatus) bool
Match returns true if the tracker status matches the given filter. For example TrackerStatusPinError will match TrackerStatusPinError and TrackerStatusError
func (TrackerStatus) String ¶
func (st TrackerStatus) String() string
String converts a TrackerStatus into a readable string. If the given TrackerStatus is a filter (with several bits set), it will return a comma-separated list.
Directories ¶
Path | Synopsis |
---|---|
Package rest implements an IPFS Cluster API component.
|
Package rest implements an IPFS Cluster API component. |
client
Package client provides a Go Client for the IPFS Cluster API provided by the "api/rest" component.
|
Package client provides a Go Client for the IPFS Cluster API provided by the "api/rest" component. |