api

package
v0.0.0-...-6646f2c Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 15, 2019 License: MIT Imports: 17 Imported by: 0

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

Composite TrackerStatus.

Variables

View Source
var DefaultShardSize = uint64(100 * 1024 * 1024) // 100 MB

DefaultShardSize is the shard size for params objects created with DefaultParams().

Functions

func CidsToStrings

func CidsToStrings(cids []cid.Cid) []string

CidsToStrings encodes cid.Cids to strings.

func Libp2pMultiaddrSplit

func Libp2pMultiaddrSplit(addr ma.Multiaddr) (peer.ID, ma.Multiaddr, error)

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

func MustLibp2pMultiaddrJoin(addr ma.Multiaddr, p peer.ID) ma.Multiaddr

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

func PeersToStrings(peers []peer.ID) []string

PeersToStrings IDB58Encodes a list of peers.

func StringsToCidSet

func StringsToCidSet(strs []string) *cid.Set

StringsToCidSet decodes cid.Cids from strings.

func StringsToPeers

func StringsToPeers(strs []string) []peer.ID

StringsToPeers decodes peer.IDs from strings.

Types

type AddParams

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

func AddParamsFromQuery(query url.Values) (*AddParams, error)

AddParamsFromQuery parses the AddParams object from a URL.Query().

func DefaultAddParams

func DefaultAddParams() *AddParams

DefaultAddParams returns a AddParams object with standard defaults

func (*AddParams) Equals

func (p *AddParams) Equals(p2 *AddParams) bool

Equals checks if p equals p2.

func (*AddParams) ToQueryString

func (p *AddParams) ToQueryString() string

ToQueryString returns a url query string (key=value&key2=value2&...)

type AddedOutput

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 Alert

type Alert struct {
	Peer       peer.ID
	MetricName string
}

Alert carries alerting information about a peer. WIP.

type ConnectGraph

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

func (cg ConnectGraph) ToSerial() ConnectGraphSerial

ToSerial converts a ConnectGraph to its Go-serializable version

type ConnectGraphSerial

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

func (cgs ConnectGraphSerial) ToConnectGraph() ConnectGraph

ToConnectGraph converts a ConnectGraphSerial to a ConnectGraph

type Error

type Error struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
}

Error can be used by APIs to return errors.

func (*Error) Error

func (e *Error) Error() string

Error implements the error interface and returns the error's message.

type FileLsEntrie

type FileLsEntrie struct {
	Name string
	Type int
	Size uint64
	Hash string
}

type FilesLs

type FilesLs struct {
	Entries []FileLsEntrie
}

FilesLs wraps files/ls entries in the Hive Cluster.

type FilesStat

type FilesStat struct {
	Hash           string
	Size           uint64
	CumulativeSize uint64
	Blocks         int
	Type           string
	WithLocality   bool
	Local          bool
	SizeLocal      uint64
}

type FilesWrite

type FilesWrite struct {
	ContentType string
	BodyBuf     *bytes.Buffer
	Params      []string
}

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          []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

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          []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

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

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

func (ips IPFSPinStatus) ToTrackerStatus() TrackerStatus

ToTrackerStatus converts the IPFSPinStatus value to the appropriate TrackerStatus value.

type IPFSRepoStat

type IPFSRepoStat struct {
	RepoSize   uint64
	StorageMax uint64
}

IPFSRepoStat wraps information about the IPFS repository.

type Metric

type Metric struct {
	Name   string
	Peer   peer.ID
	Value  string
	Expire int64
	Valid  bool
}

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) MarshalJSON

func (m *Metric) MarshalJSON() ([]byte, error)

MarshalJSON allows a Metric to produce a JSON representation of itself.

func (*Metric) SetTTL

func (m *Metric) SetTTL(d time.Duration)

SetTTL sets Metric to expire after the given time.Duration

func (*Metric) UnmarshalJSON

func (m *Metric) UnmarshalJSON(j []byte) error

UnmarshalJSON decodes JSON on top of the Metric.

type MetricSerial

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 NamePublish

type NamePublish struct {
	Name  string
	Value string
}

type NodeWithMeta

type NodeWithMeta struct {
	Data    []byte
	Cid     string
	CumSize uint64 // Cumulative size
	Format  string
}

NodeWithMeta specifies a block of data and a set of optional metadata fields carrying information about the encoded ipld node

func (*NodeWithMeta) Size

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

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

func PinCid(c cid.Cid) Pin

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

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

func (pin Pin) Equals(pin2 Pin) bool

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

func (pin Pin) IsRemotePin(pid peer.ID) bool

IsRemotePin determines whether a Pin's ReplicationFactor has been met, so as to either pin or unpin it from the peer.

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

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

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

func (PinSerial) Clone

func (pins PinSerial) Clone() PinSerial

Clone returns a deep copy of the PinSerial.

func (PinSerial) DecodeCid

func (pins PinSerial) DecodeCid() cid.Cid

DecodeCid retrieves just the cid from a PinSerial without allocating a Pin.

func (PinSerial) ToPin

func (pins PinSerial) ToPin() Pin

ToPin converts a PinSerial to its native form.

type PinType

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.

AllType is a PinType used for filtering all pin types

func PinTypeFromString

func PinTypeFromString(str string) PinType

PinTypeFromString is the inverse of String. It returns the PinType value corresponding to the input string

func (PinType) String

func (pT PinType) String() string

String returns a printable value to identify the PinType

type SwarmPeers

type SwarmPeers []peer.ID

SwarmPeers lists an ipfs daemon's peers

func (SwarmPeers) ToSerial

func (swarm SwarmPeers) ToSerial() SwarmPeersSerial

ToSerial converts SwarmPeers to its Go-serializeable version

type SwarmPeersSerial

type SwarmPeersSerial []string

SwarmPeersSerial is the serialized form of SwarmPeers for RPC use

func (SwarmPeersSerial) ToSwarmPeers

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

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

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.

type UIDKey

type UIDKey struct {
	UID  string
	Key  []byte
	Root string
}

UIDKey wraps secret private key.

type UIDRenew

type UIDRenew struct {
	UID    string
	OldUID string
	PeerID string
}

UIDRenew wraps node keys renaming in the Hive Cluster.

type UIDSecret

type UIDSecret struct {
	UID    string
	PeerID string
}

UIDSecret wraps node register keys in the Hive Cluster.

type Version

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

Version holds version information

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL