interface-go-ipfs-core: Index | Files | Directories

package iface

import ""

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


Package Files

block.go coreapi.go dag.go dht.go errors.go idfmt.go key.go name.go object.go pin.go pubsub.go swarm.go unixfs.go util.go


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

func FormatKey Uses

func FormatKey(key Key) string

FormatKey formats the given IPNS key in a canonical way.

func FormatKeyID Uses

func FormatKeyID(id peer.ID) string

type APIDagService Uses

type APIDagService interface {

    // Pinning returns special NodeAdder which recursively pins added nodes
    Pinning() ipld.NodeAdder

APIDagService extends ipld.DAGService

type AddEvent Uses

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

type BadPinNode Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

func (t FileType) String() string

type IpnsEntry Uses

type IpnsEntry interface {
    // Name returns IpnsEntry name
    Name() string
    // Value returns IpnsEntry value
    Value() path.Path

IpnsEntry specifies the interface to IpnsEntries

type IpnsResult Uses

type IpnsResult struct {
    Err error

type Key Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

type PubSubSubscription interface {

    // Next return the next incoming message
    Next(context.Context) (PubSubMessage, error)

PubSubSubscription is an active PubSub subscription

type ReadSeekCloser Uses

type ReadSeekCloser interface {

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

type Reader Uses

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

type SwarmAPI Uses

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 Uses

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



Package iface imports 14 packages (graph) and is imported by 155 packages. Updated 2020-07-30. Refresh now. Tools for package owners.