Documentation ¶
Overview ¶
Package iface defines IPFS Core API which is a set of interfaces used to interact with IPFS nodes.
Index ¶
- Variables
- func FormatKey(key Key) string
- func FormatKeyID(id peer.ID) string
- type APIDagService
- type AddEvent
- type BadPinNode
- type BlockAPI
- type BlockStat
- type ChangeType
- type ConnectionInfo
- type CoreAPI
- type DhtAPI
- type DirEntry
- type FileType
- type IpnsEntry
- type IpnsResult
- type Key
- type KeyAPI
- type NameAPI
- type ObjectAPI
- type ObjectChange
- type ObjectStat
- type Pin
- type PinAPI
- type PinStatus
- type PubSubAPI
- type PubSubMessage
- type PubSubSubscription
- type ReadSeekCloser
- type Reader
- type RoutingAPI
- type SwarmAPI
- type UnixfsAPI
Constants ¶
This section is empty.
Variables ¶
var ( ErrIsDir = errors.New("this dag node is a directory") ErrNotFile = errors.New("this dag node is not a regular file") ErrOffline = errors.New("this action must be run in online mode, try running 'ipfs daemon' first") ErrNotSupported = errors.New("operation not supported") )
var ( ErrNotConnected = errors.New("not connected") ErrConnNotFound = errors.New("conn not found") )
var ErrResolveFailed = errors.New("could not resolve name")
Functions ¶
func FormatKeyID ¶
Types ¶
type APIDagService ¶
type APIDagService interface { ipld.DAGService // Pinning returns special NodeAdder which recursively pins added nodes Pinning() ipld.NodeAdder }
APIDagService extends ipld.DAGService
type BadPinNode ¶
type BadPinNode interface { // Path is the path of the node Path() path.Resolved // Err is the reason why the node has been marked as bad Err() error }
BadPinNode is a node that has been marked as bad by Pin.Verify
type BlockAPI ¶
type BlockAPI interface { // Put imports raw block data, hashing it using specified settings. Put(context.Context, io.Reader, ...options.BlockPutOption) (BlockStat, error) // Get attempts to resolve the path and return a reader for data in the block Get(context.Context, path.Path) (io.Reader, error) // Rm removes the block specified by the path from local blockstore. // By default an error will be returned if the block can't be found locally. // // NOTE: If the specified block is pinned it won't be removed and no error // will be returned Rm(context.Context, path.Path, ...options.BlockRmOption) error // Stat returns information on Stat(context.Context, path.Path) (BlockStat, error) }
BlockAPI specifies the interface to the block layer
type BlockStat ¶
type BlockStat interface { // Size is the size of a block Size() int // Path returns path to the block Path() path.Resolved }
BlockStat contains information about a block
type ChangeType ¶
type ChangeType int
ChangeType denotes type of change in ObjectChange
const ( // DiffAdd is set when a link was added to the graph DiffAdd ChangeType = iota // DiffRemove is set when a link was removed from the graph DiffRemove // DiffMod is set when a link was changed in the graph DiffMod )
type ConnectionInfo ¶
type ConnectionInfo interface { // ID returns PeerID ID() peer.ID // Address returns the multiaddress via which we are connected with the peer Address() ma.Multiaddr // Direction returns which way the connection was established Direction() network.Direction // Latency returns last known round trip time to the peer Latency() (time.Duration, error) // Streams returns list of streams established with the peer Streams() ([]protocol.ID, error) }
ConnectionInfo contains information about a peer
type CoreAPI ¶
type CoreAPI interface { // Unixfs returns an implementation of Unixfs API Unixfs() UnixfsAPI // Block returns an implementation of Block API Block() BlockAPI // Dag returns an implementation of Dag API Dag() APIDagService // Name returns an implementation of Name API Name() NameAPI // Key returns an implementation of Key API Key() KeyAPI // Pin returns an implementation of Pin API Pin() PinAPI // Object returns an implementation of Object API Object() ObjectAPI // Dht returns an implementation of Dht API Dht() DhtAPI // Swarm returns an implementation of Swarm API Swarm() SwarmAPI // PubSub returns an implementation of PubSub API PubSub() PubSubAPI // Routing returns an implementation of Routing API Routing() RoutingAPI // ResolvePath resolves the path using Unixfs resolver ResolvePath(context.Context, path.Path) (path.Resolved, error) // ResolveNode resolves the path (if not resolved already) using Unixfs // resolver, gets and returns the resolved Node ResolveNode(context.Context, path.Path) (ipld.Node, error) // WithOptions creates new instance of CoreAPI based on this instance with // a set of options applied WithOptions(...options.ApiOption) (CoreAPI, error) }
CoreAPI defines an unified interface to IPFS for Go programs
type DhtAPI ¶
type DhtAPI interface { // FindPeer queries the DHT for all of the multiaddresses associated with a // Peer ID FindPeer(context.Context, peer.ID) (peer.AddrInfo, error) // FindProviders finds peers in the DHT who can provide a specific value // given a key. FindProviders(context.Context, path.Path, ...options.DhtFindProvidersOption) (<-chan peer.AddrInfo, error) // Provide announces to the network that you are providing given values Provide(context.Context, path.Path, ...options.DhtProvideOption) error }
DhtAPI specifies the interface to the DHT Note: This API will likely get deprecated in near future, see https://github.com/ipfs/interface-ipfs-core/issues/249 for more context.
type DirEntry ¶
type DirEntry struct { Name string Cid cid.Cid // Only filled when asked to resolve the directory entry. Size uint64 // The size of the file in bytes (or the size of the symlink). Type FileType // The type of the file. Target string // The symlink target (if a symlink). Err error }
DirEntry is a directory entry returned by `Ls`.
type IpnsEntry ¶
type IpnsEntry interface { // Name returns IpnsEntry name Name() string // Value returns IpnsEntry value Value() path.Path }
IpnsEntry specifies the interface to IpnsEntries
type IpnsResult ¶
type Key ¶
type Key interface { // Key returns key name Name() string // Path returns key path Path() path.Path // ID returns key PeerID ID() peer.ID }
Key specifies the interface to Keys in KeyAPI Keystore
type KeyAPI ¶
type KeyAPI interface { // Generate generates new key, stores it in the keystore under the specified // name and returns a base58 encoded multihash of it's public key Generate(ctx context.Context, name string, opts ...options.KeyGenerateOption) (Key, error) // Rename renames oldName key to newName. Returns the key and whether another // key was overwritten, or an error Rename(ctx context.Context, oldName string, newName string, opts ...options.KeyRenameOption) (Key, bool, error) // List lists keys stored in keystore List(ctx context.Context) ([]Key, error) // Self returns the 'main' node key Self(ctx context.Context) (Key, error) // Remove removes keys from keystore. Returns ipns path of the removed key Remove(ctx context.Context, name string) (Key, error) }
KeyAPI specifies the interface to Keystore
type NameAPI ¶
type NameAPI interface { // Publish announces new IPNS name Publish(ctx context.Context, path path.Path, opts ...options.NamePublishOption) (IpnsEntry, error) // Resolve attempts to resolve the newest version of the specified name Resolve(ctx context.Context, name string, opts ...options.NameResolveOption) (path.Path, error) // Search is a version of Resolve which outputs paths as they are discovered, // reducing the time to first entry // // Note: by default, all paths read from the channel are considered unsafe, // except the latest (last path in channel read buffer). Search(ctx context.Context, name string, opts ...options.NameResolveOption) (<-chan IpnsResult, error) }
NameAPI specifies the interface to IPNS.
IPNS is a PKI namespace, where names are the hashes of public keys, and the private key enables publishing new (signed) values. In both publish and resolve, the default name used is the node's own PeerID, which is the hash of its public key.
You can use .Key API to list and generate more names and their respective keys.
type ObjectAPI ¶
type ObjectAPI interface { // New creates new, empty (by default) dag-node. New(context.Context, ...options.ObjectNewOption) (ipld.Node, error) // Put imports the data into merkledag Put(context.Context, io.Reader, ...options.ObjectPutOption) (path.Resolved, error) // Get returns the node for the path Get(context.Context, path.Path) (ipld.Node, error) // Data returns reader for data of the node Data(context.Context, path.Path) (io.Reader, error) // Links returns lint or links the node contains Links(context.Context, path.Path) ([]*ipld.Link, error) // Stat returns information about the node Stat(context.Context, path.Path) (*ObjectStat, error) // AddLink adds a link under the specified path. child path can point to a // subdirectory within the patent which must be present (can be overridden // with WithCreate option). AddLink(ctx context.Context, base path.Path, name string, child path.Path, opts ...options.ObjectAddLinkOption) (path.Resolved, error) // RmLink removes a link from the node RmLink(ctx context.Context, base path.Path, link string) (path.Resolved, error) // AppendData appends data to the node AppendData(context.Context, path.Path, io.Reader) (path.Resolved, error) // SetData sets the data contained in the node SetData(context.Context, path.Path, io.Reader) (path.Resolved, error) // Diff returns a set of changes needed to transform the first object into the // second. Diff(context.Context, path.Path, path.Path) ([]ObjectChange, error) }
ObjectAPI specifies the interface to MerkleDAG and contains useful utilities for manipulating MerkleDAG data structures.
type ObjectChange ¶
type ObjectChange struct { // Type of the change, either: // * DiffAdd - Added a link // * DiffRemove - Removed a link // * DiffMod - Modified a link Type ChangeType // Path to the changed link Path string // Before holds the link path before the change. Note that when a link is // added, this will be nil. Before path.Resolved // After holds the link path after the change. Note that when a link is // removed, this will be nil. After path.Resolved }
ObjectChange represents a change ia a graph
type ObjectStat ¶
type ObjectStat struct { // Cid is the CID of the node Cid cid.Cid // NumLinks is number of links the node contains NumLinks int // BlockSize is size of the raw serialized node BlockSize int // LinksSize is size of the links block section LinksSize int // DataSize is the size of data block section DataSize int // CumulativeSize is size of the tree (BlockSize + link sizes) CumulativeSize int }
ObjectStat provides information about dag nodes
type Pin ¶
type Pin interface { // Path to the pinned object Path() path.Resolved // Type of the pin Type() string // if not nil, an error happened. Everything else should be ignored. Err() error }
Pin holds information about pinned resource
type PinAPI ¶
type PinAPI interface { // Add creates new pin, be default recursive - pinning the whole referenced // tree Add(context.Context, path.Path, ...options.PinAddOption) error // Ls returns list of pinned objects on this node Ls(context.Context, ...options.PinLsOption) (<-chan Pin, error) // IsPinned returns whether or not the given cid is pinned // and an explanation of why its pinned IsPinned(context.Context, path.Path, ...options.PinIsPinnedOption) (string, bool, error) // Rm removes pin for object specified by the path Rm(context.Context, path.Path, ...options.PinRmOption) error // Update changes one pin to another, skipping checks for matching paths in // the old tree Update(ctx context.Context, from path.Path, to path.Path, opts ...options.PinUpdateOption) error // Verify verifies the integrity of pinned objects Verify(context.Context) (<-chan PinStatus, error) }
PinAPI specifies the interface to pining
type PinStatus ¶
type PinStatus interface { // Ok indicates whether the pin has been verified to be correct Ok() bool // BadNodes returns any bad (usually missing) nodes from the pin BadNodes() []BadPinNode // if not nil, an error happened. Everything else should be ignored. Err() error }
PinStatus holds information about pin health
type PubSubAPI ¶
type PubSubAPI interface { // Ls lists subscribed topics by name Ls(context.Context) ([]string, error) // Peers list peers we are currently pubsubbing with Peers(context.Context, ...options.PubSubPeersOption) ([]peer.ID, error) // Publish a message to a given pubsub topic Publish(context.Context, string, []byte) error // Subscribe to messages on a given topic Subscribe(context.Context, string, ...options.PubSubSubscribeOption) (PubSubSubscription, error) }
PubSubAPI specifies the interface to PubSub
type PubSubMessage ¶
type PubSubMessage interface { // From returns id of a peer from which the message has arrived From() peer.ID // Data returns the message body Data() []byte // Seq returns message identifier Seq() []byte // Topics returns list of topics this message was set to Topics() []string }
PubSubMessage is a single PubSub message
type PubSubSubscription ¶
type PubSubSubscription interface { io.Closer // Next return the next incoming message Next(context.Context) (PubSubMessage, error) }
PubSubSubscription is an active PubSub subscription
type ReadSeekCloser ¶
A ReadSeekCloser implements interfaces to read, copy, seek and close.
type RoutingAPI ¶
type RoutingAPI interface { // Get retrieves the best value for a given key Get(context.Context, string) ([]byte, error) // Put sets a value for a given key Put(ctx context.Context, key string, value []byte, opts ...options.RoutingPutOption) error }
RoutingAPI specifies the interface to the routing layer.
type SwarmAPI ¶
type SwarmAPI interface { // Connect to a given peer Connect(context.Context, peer.AddrInfo) error // Disconnect from a given address Disconnect(context.Context, ma.Multiaddr) error // Peers returns the list of peers we are connected to Peers(context.Context) ([]ConnectionInfo, error) // KnownAddrs returns the list of all addresses this node is aware of KnownAddrs(context.Context) (map[peer.ID][]ma.Multiaddr, error) // LocalAddrs returns the list of announced listening addresses LocalAddrs(context.Context) ([]ma.Multiaddr, error) // ListenAddrs returns the list of all listening addresses ListenAddrs(context.Context) ([]ma.Multiaddr, error) }
SwarmAPI specifies the interface to libp2p swarm
type UnixfsAPI ¶
type UnixfsAPI interface { // Add imports the data from the reader into merkledag file // // TODO: a long useful comment on how to use this for many different scenarios Add(context.Context, files.Node, ...options.UnixfsAddOption) (path.Resolved, error) // Get returns a read-only handle to a file tree referenced by a path // // Note that some implementations of this API may apply the specified context // to operations performed on the returned file Get(context.Context, path.Path) (files.Node, error) // Ls returns the list of links in a directory. Links aren't guaranteed to be // returned in order Ls(context.Context, path.Path, ...options.UnixfsLsOption) (<-chan DirEntry, error) }
UnixfsAPI is the basic interface to immutable files in IPFS NOTE: This API is heavily WIP, things are guaranteed to break frequently