Merge commits from ipfs/boxo/main

core/coreiface/block.go

@@ -0,0 +1,37 @@
+package iface
+
+import (
+	"context"
+	"io"
+
+	"github.com/ipfs/boxo/coreiface/options"
+	"github.com/ipfs/boxo/path"
+)
+
+// BlockStat contains information about a block
+type BlockStat interface {
+	// Size is the size of a block
+	Size() int
+
+	// Path returns path to the block
+	Path() path.ImmutablePath
+}
+
+// BlockAPI specifies the interface to the block layer
+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)
+}

core/coreiface/coreapi.go

@@ -0,0 +1,61 @@
+// Package iface defines IPFS Core API which is a set of interfaces used to
+// interact with IPFS nodes.
+package iface
+
+import (
+	"context"
+
+	"github.com/ipfs/boxo/coreiface/options"
+	"github.com/ipfs/boxo/path"
+
+	ipld "github.com/ipfs/go-ipld-format"
+)
+
+// CoreAPI defines an unified interface to IPFS for Go programs
+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, and returns the resolved
+	// immutable path, and the remainder of the path segments that cannot be resolved
+	// within UnixFS.
+	ResolvePath(context.Context, path.Path) (path.ImmutablePath, []string, 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)
+}

core/coreiface/dag.go

@@ -0,0 +1,13 @@
+package iface
+
+import (
+	ipld "github.com/ipfs/go-ipld-format"
+)
+
+// APIDagService extends ipld.DAGService
+type APIDagService interface {
+	ipld.DAGService
+
+	// Pinning returns special NodeAdder which recursively pins added nodes
+	Pinning() ipld.NodeAdder
+}

core/coreiface/dht.go

@@ -0,0 +1,27 @@
+package iface
+
+import (
+	"context"
+
+	"github.com/ipfs/boxo/path"
+
+	"github.com/ipfs/boxo/coreiface/options"
+
+	"github.com/libp2p/go-libp2p/core/peer"
+)
+
+// 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 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
+}

core/coreiface/errors.go

@@ -0,0 +1,10 @@
+package iface
+
+import "errors"
+
+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")
+)

core/coreiface/idfmt.go

@@ -0,0 +1,19 @@
+package iface
+
+import (
+	"github.com/libp2p/go-libp2p/core/peer"
+	mbase "github.com/multiformats/go-multibase"
+)
+
+func FormatKeyID(id peer.ID) string {
+	if s, err := peer.ToCid(id).StringOfBase(mbase.Base36); err != nil {
+		panic(err)
+	} else {
+		return s
+	}
+}
+
+// FormatKey formats the given IPNS key in a canonical way.
+func FormatKey(key Key) string {
+	return FormatKeyID(key.ID())
+}

core/coreiface/key.go

@@ -0,0 +1,43 @@
+package iface
+
+import (
+	"context"
+
+	"github.com/ipfs/boxo/path"
+
+	"github.com/ipfs/boxo/coreiface/options"
+
+	"github.com/libp2p/go-libp2p/core/peer"
+)
+
+// Key specifies the interface to Keys in KeyAPI Keystore
+type Key interface {
+	// Key returns key name
+	Name() string
+
+	// Path returns key path
+	Path() path.Path
+
+	// ID returns key PeerID
+	ID() peer.ID
+}
+
+// KeyAPI specifies the interface to Keystore
+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)
+}

core/coreiface/name.go

@@ -0,0 +1,40 @@
+package iface
+
+import (
+	"context"
+	"errors"
+
+	"github.com/ipfs/boxo/coreiface/options"
+	"github.com/ipfs/boxo/ipns"
+	"github.com/ipfs/boxo/path"
+)
+
+var ErrResolveFailed = errors.New("could not resolve name")
+
+type IpnsResult struct {
+	path.Path
+	Err 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 NameAPI interface {
+	// Publish announces new IPNS name
+	Publish(ctx context.Context, path path.Path, opts ...options.NamePublishOption) (ipns.Name, 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)
+}

core/coreiface/object.go

@@ -0,0 +1,107 @@
+package iface
+
+import (
+	"context"
+	"io"
+
+	"github.com/ipfs/boxo/coreiface/options"
+	"github.com/ipfs/boxo/path"
+
+	"github.com/ipfs/go-cid"
+	ipld "github.com/ipfs/go-ipld-format"
+)
+
+// ObjectStat provides information about dag nodes
+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
+}
+
+// ChangeType denotes type of change in ObjectChange
+type ChangeType int
+
+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
+)
+
+// ObjectChange represents a change ia a graph
+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.ImmutablePath
+
+	// After holds the link path after the change. Note that when a link is
+	// removed, this will be nil.
+	After path.ImmutablePath
+}
+
+// ObjectAPI specifies the interface to MerkleDAG and contains useful utilities
+// for manipulating MerkleDAG data structures.
+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.ImmutablePath, 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.ImmutablePath, error)
+
+	// RmLink removes a link from the node
+	RmLink(ctx context.Context, base path.Path, link string) (path.ImmutablePath, error)
+
+	// AppendData appends data to the node
+	AppendData(context.Context, path.Path, io.Reader) (path.ImmutablePath, error)
+
+	// SetData sets the data contained in the node
+	SetData(context.Context, path.Path, io.Reader) (path.ImmutablePath, 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)
+}