ipfs

Documentation

Overview

Package ipfs abstracts the IPFS implementation, Kubo, exposing commonly required functionality without the need for in-depth understanding of the IPFS API.

Index

• Variables
• func InitFS(repoPath string, cfg *config.Config) error
• func LoadPlugins(repoPath string) (_ *loader.PluginLoader, retErr error)
• func ParsePeerAddresses(addrs ...string) ([]*peer.AddrInfo, error)
• func ResetDefaultPeers(extra ...string) error
• type FSRootHandling
• type IPFS
  • func FromFS(ctx context.Context, repoPath string, nodeCfg *core.BuildCfg, ...) (*IPFS, error)
  • func (ipfs *IPFS) AddFS(ctx context.Context, fsys fs.FS, root string, rh FSRootHandling, ...) (path.Resolved, error)
  • func (ipfs *IPFS) TryConnect(ctx context.Context, peers []*peer.AddrInfo) uint64
  • func (ipfs *IPFS) WaitForConnections(ctx context.Context, min int) error

Variables

var DefaultPeers []*peer.AddrInfo

DefaultPeers are a commonly used set of default peers to use for bootstrapping p2p connections. They are a parsed version of the default addresses provided by Kubo's config package.

Functions

func InitFS

func InitFS(repoPath string, cfg *config.Config) error

InitFS initialises a filesystem-based repository at the specified path.

Note that the filesystem refers to the IPFS repository layout, not the content to be served.

func LoadPlugins

func LoadPlugins(repoPath string) (_ *loader.PluginLoader, retErr error)

LoadPlugins loads and initialises all plugins from the repoPath, which MAY be an empty string, in which case only "preload" plugins are loaded. It MUST be called before either InitFS() or FromFS(). If calling before InitFS(), the repoPath SHOULD be the empty string; if calling before FromFS(), the repoPath passed to each function MUST be the same.

func ParsePeerAddresses

func ParsePeerAddresses(addrs ...string) ([]*peer.AddrInfo, error)

PrasePeerAdddresses parses the address strings as multiaddr.NewMultiAddr values, groups them by peer.ID, and returns the groups as libp2p peer.AddrInfos. The adress strings MAY therefore have overlapping peer IDs.

func ResetDefaultPeers

func ResetDefaultPeers(extra ...string) error

ResetDefaultPeers resets the global DefaultPeers variable, adding optional extra addresses. See ParsePeerAddresses() for treatment of the extra addresses.

Note: see the security advice re adding extra nodes: https://docs.ipfs.tech/how-to/modify-bootstrap-list/.

Types

type FSRootHandling

type FSRootHandling bool

FSRootHandling defines how to treat the root of an fs.FS when adding its contents.

const (
	// KeepFSRoot results in files being added with the root directory
	// maintained, such that all files have it as a path prefix.
	KeepFSRoot FSRootHandling = true
	// StripFSRoot is the opposite of KeepFSRoot, equivalent to adding an fs.FS
	// obtained via `fs.Sub(…,root)`, thus stripping the root prefix.
	StripFSRoot FSRootHandling = false
)

type IPFS

type IPFS struct {
	iface.CoreAPI
	// contains filtered or unexported fields
}

IPFS wraps an implementation of the core IPFS API, providing convenience methods for common functionality.

func FromFS

func FromFS(ctx context.Context, repoPath string, nodeCfg *core.BuildCfg, opts ...options.ApiOption) (*IPFS, error)

FromFS returns an IPFS instance using a filesystem-based node at the specified path. The same path MUST have already been initialised with InitFS() or similar functionality, such as the CLI command `ipfs init`.

See the note on InitFS() re filesystem.

func (*IPFS) AddFS

func (ipfs *IPFS) AddFS(ctx context.Context, fsys fs.FS, root string, rh FSRootHandling, opts ...options.UnixfsAddOption) (path.Resolved, error)

AddFS walks the provided filesystem from the provided root, collecting all non-directory entries, and adding them to ipfs.Unixfs() as a files.Directory.

Unlike InitFS() and NewFS() that refer to a filesystem-based IPFS repository, this method refers to the actual files being added to the system.

func (*IPFS) TryConnect

func (ipfs *IPFS) TryConnect(ctx context.Context, peers []*peer.AddrInfo) uint64

TryConnect attempts to connect to all provided peers, typically expecting DefaultPeers, and returns the number of successful connections. If at least one connection is successful, the p2p network will begin sharing other peer information. See ipfs.Swarm().Peers() for the number of connections, even before TryConnect() returns.

func (*IPFS) WaitForConnections

func (ipfs *IPFS) WaitForConnections(ctx context.Context, min int) error

WaitForConnections repeatedly checks for all connected peers and returns when either the Context is Done() or the number of peers exceeds the minimum.