iface

README

interface-go-ipfs-core

The CoreAPI interfaces for go-ipfs.

❗ This repo is no longer maintained.

👉 We highly recommend switching to the maintained version at https://github.com/ipfs/boxo/tree/main/coreiface. 🏎️ Good news! There is tooling and documentation to expedite a switch in your repo.

⚠️ If you continue using this repo, please note that security fixes will not be provided (unless someone steps in to maintain it).

📚 Learn more, including how to take the maintainership mantle or ask questions, here.

Table of Contents

• [Background](#background
• License

License

MIT © Protocol Labs

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
  • func (t FileType) String() string
• 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

Variables

var (
	// Deprecated: use github.com/ipfs/boxo/coreiface.ErrIsDir
	ErrIsDir = errors.New("this dag node is a directory")
	// Deprecated: use github.com/ipfs/boxo/coreiface.ErrNotFile
	ErrNotFile = errors.New("this dag node is not a regular file")
	// Deprecated: use github.com/ipfs/boxo/coreiface.ErrOffline
	ErrOffline = errors.New("this action must be run in online mode, try running 'ipfs daemon' first")
	// Deprecated: use github.com/ipfs/boxo/coreiface.ErrNotSupported
	ErrNotSupported = errors.New("operation not supported")
)

var (
	// Deprecated: use github.com/ipfs/boxo/coreiface.ErrNotConnected
	ErrNotConnected = errors.New("not connected")
	// Deprecated: use github.com/ipfs/boxo/coreiface.ErrConnNotFound
	ErrConnNotFound = errors.New("conn not found")
)

var ErrResolveFailed = errors.New("could not resolve name")

Deprecated: use github.com/ipfs/boxo/coreiface.ErrResolveFailed

Functions

func FormatKey

func FormatKey(key Key) string

FormatKey formats the given IPNS key in a canonical way.

Deprecated: use github.com/ipfs/boxo/coreiface.FormatKey

func FormatKeyID

func FormatKeyID(id peer.ID) string

Deprecated: use github.com/ipfs/boxo/coreiface.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

Deprecated: use github.com/ipfs/boxo/coreiface.APIDagService

type AddEvent

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

Deprecated: use github.com/ipfs/boxo/coreiface.AddEvent

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

Deprecated: use github.com/ipfs/boxo/coreiface.BadPinNode

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

Deprecated: use github.com/ipfs/boxo/coreiface.BlockAPI

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

Deprecated: use github.com/ipfs/boxo/coreiface.BlockStat

type ChangeType

type ChangeType int

ChangeType denotes type of change in ObjectChange

Deprecated: use github.com/ipfs/boxo/coreiface.ChangeType

const (
	// DiffAdd is set when a link was added to the graph
	//
	// Deprecated: use github.com/ipfs/boxo/coreiface.DiffAdd
	DiffAdd ChangeType = iota

	// DiffRemove is set when a link was removed from the graph
	//
	// Deprecated: use github.com/ipfs/boxo/coreiface.DiffRemove
	DiffRemove

	// DiffMod is set when a link was changed in the graph
	//
	// Deprecated: use github.com/ipfs/boxo/coreiface.DiffMod
	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

Deprecated: use github.com/ipfs/boxo/coreiface.ConnectionInfo

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

Deprecated: use github.com/ipfs/boxo/coreiface.CoreAPI

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.

Deprecated: use github.com/ipfs/boxo/coreiface.DhtAPI

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

Deprecated: use github.com/ipfs/boxo/coreiface.DirEntry

type FileType

type FileType int32

FileType is an enum of possible UnixFS file types.

Deprecated: use github.com/ipfs/boxo/coreiface.FileType

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

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

Deprecated: use github.com/ipfs/boxo/coreiface.IpnsEntry

type IpnsResult

type IpnsResult struct {
	path.Path
	Err error
}

Deprecated: use github.com/ipfs/boxo/coreiface.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

Deprecated: use github.com/ipfs/boxo/coreiface.Key

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

Deprecated: use github.com/ipfs/boxo/coreiface.KeyAPI

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.

Deprecated: use github.com/ipfs/boxo/coreiface.NameAPI

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.

Deprecated: use github.com/ipfs/boxo/coreiface.ObjectAPI

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

Deprecated: use github.com/ipfs/boxo/coreiface.ObjectChange

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

Deprecated: use github.com/ipfs/boxo/coreiface.ObjectStat

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

Deprecated: use github.com/ipfs/boxo/coreiface.Pin

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

Deprecated: use github.com/ipfs/boxo/coreiface.PinAPI

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

Deprecated: use github.com/ipfs/boxo/coreiface.PinStatus

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

Deprecated: use github.com/ipfs/boxo/coreiface.PubSubAPI

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

Deprecated: use github.com/ipfs/boxo/coreiface.PubSubMessage

type PubSubSubscription

type PubSubSubscription interface {
	io.Closer

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

PubSubSubscription is an active PubSub subscription

Deprecated: use github.com/ipfs/boxo/coreiface.PubSubSubscription

type ReadSeekCloser

type ReadSeekCloser interface {
	io.Reader
	io.Seeker
	io.Closer
	io.WriterTo
}

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

Deprecated: use github.com/ipfs/boxo/coreiface.ReadSeekCloser

type Reader

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

Deprecated: use github.com/ipfs/boxo/coreiface.Reader

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) error
}

RoutingAPI specifies the interface to the routing layer.

Deprecated: use github.com/ipfs/boxo/coreiface.RoutingAPI

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

Deprecated: use github.com/ipfs/boxo/coreiface.SwarmAPI

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

Deprecated: use github.com/ipfs/boxo/coreiface.UnixfsAPI