Coverage Status

The CoreAPI interfaces for go-ipfs.

Lead Maintainer

Steven Allen

Table of Contents




PRs are welcome!

Small note: If editing the Readme, please conform to the standard-readme specification.


MIT © Protocol Labs

Expand ▾ Collapse ▴



    Package iface defines IPFS Core API which is a set of interfaces used to interact with IPFS nodes.



    This section is empty.


    View Source
    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")
    View Source
    var (
    	ErrNotConnected = errors.New("not connected")
    	ErrConnNotFound = errors.New("conn not found")
    View Source
    var ErrResolveFailed = errors.New("could not resolve name")


    func FormatKey

    func FormatKey(key Key) string

      FormatKey formats the given IPNS key in a canonical way.

      func FormatKeyID

      func FormatKeyID(id peer.ID) string


      type APIDagService

      type APIDagService interface {
      	// Pinning returns special NodeAdder which recursively pins added nodes
      	Pinning() ipld.NodeAdder

        APIDagService extends ipld.DAGService

        type AddEvent

        type AddEvent struct {
        	Name  string
        	Path  path.Resolved `json:",omitempty"`
        	Bytes int64         `json:",omitempty"`
        	Size  string        `json:",omitempty"`

        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
                	// DiffMod is set when a link was changed in the graph

                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
                  	// ObjectAPI 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
                  	// 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 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 FileType

                        type FileType int32

                          FileType is an enum of possible UnixFS file types.

                          const (
                          	// TUnknown means the file type isn't known (e.g., it hasn't been
                          	// resolved).
                          	TUnknown FileType = iota
                          	// TFile is a regular file.
                          	// TDirectory is a directory.
                          	// TSymlink is a symlink.

                          func (FileType) String

                          func (t FileType) String() string

                          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 IpnsResult struct {
                            	Err error

                            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

                                              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 {
                                                  	// Next return the next incoming message
                                                  	Next(context.Context) (PubSubMessage, error)

                                                    PubSubSubscription is an active PubSub subscription

                                                    type ReadSeekCloser

                                                    type ReadSeekCloser interface {

                                                      A ReadSeekCloser implements interfaces to read, copy, seek and close.

                                                      type Reader

                                                      type Reader interface {
                                                      	Size() uint64
                                                      	CtxReadFull(context.Context, []byte) (int, error)

                                                      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


                                                          Path Synopsis