interface.go 9.93 KB
Newer Older
1 2
// Package iface defines IPFS Core API which is a set of interfaces used to
// interact with IPFS nodes.
3 4 5 6 7 8
package iface

import (
	"context"
	"errors"
	"io"
Łukasz Magiera's avatar
Łukasz Magiera committed
9
	"time"
10

11 12
	options "github.com/ipfs/go-ipfs/core/coreapi/interface/options"

Steven Allen's avatar
Steven Allen committed
13 14
	cid "gx/ipfs/QmcZfnkapfECQGcLZaf9B79NRg7cRa9EnZh4LSbkCzwNvY/go-cid"
	ipld "gx/ipfs/Qme5bWv7wtjUNGsK2BNGVUFPKiuxWrsqrtvYwCLRw8YFES/go-ipld-format"
15 16
)

17 18
// Path is a generic wrapper for paths used in the API. A path can be resolved
// to a CID using one of Resolve functions in the API.
19
type Path interface {
20
	// String returns the path as a string.
21
	String() string
22
	// Cid returns cid referred to by path
23
	Cid() *cid.Cid
24
	// Root returns cid of root path
25
	Root() *cid.Cid
26
	// Resolved returns whether path has been fully resolved
27 28 29 30
	Resolved() bool
}

// TODO: should we really copy these?
31
//       if we didn't, godoc would generate nice links straight to go-ipld-format
32
type Node ipld.Node
Lars Gierth's avatar
Lars Gierth committed
33
type Link ipld.Link
34 35 36 37 38 39

type Reader interface {
	io.ReadSeeker
	io.Closer
}

40
// IpnsEntry specifies the interface to IpnsEntries
41
type IpnsEntry interface {
42
	// Name returns IpnsEntry name
43
	Name() string
44
	// Value returns IpnsEntry value
45 46 47
	Value() Path
}

48
// Key specifies the interface to Keys in KeyAPI Keystore
49
type Key interface {
50
	// Key returns key name
51
	Name() string
52
	// Path returns key path
53 54 55
	Path() Path
}

Łukasz Magiera's avatar
Łukasz Magiera committed
56 57 58 59 60
type BlockStat interface {
	Size() int
	Path() Path
}

61
// CoreAPI defines an unified interface to IPFS for Go programs.
62
type CoreAPI interface {
63
	// Unixfs returns an implementation of Unixfs API.
64
	Unixfs() UnixfsAPI
65
	// Dag returns an implementation of Dag API.
Łukasz Magiera's avatar
Łukasz Magiera committed
66
	Dag() DagAPI
67
	// Name returns an implementation of Name API.
Łukasz Magiera's avatar
Łukasz Magiera committed
68
	Name() NameAPI
69
	// Key returns an implementation of Key API.
70
	Key() KeyAPI
71

72 73 74
	// ObjectAPI returns an implementation of Object API
	Object() ObjectAPI

75
	// ResolvePath resolves the path using Unixfs resolver
76
	ResolvePath(context.Context, Path) (Path, error)
77 78 79

	// ResolveNode resolves the path (if not resolved already) using Unixfs
	// resolver, gets and returns the resolved Node
Łukasz Magiera's avatar
Łukasz Magiera committed
80
	ResolveNode(context.Context, Path) (Node, error)
81 82
}

83
// UnixfsAPI is the basic interface to immutable files in IPFS
84
type UnixfsAPI interface {
85
	// Add imports the data from the reader into merkledag file
86
	Add(context.Context, io.Reader) (Path, error)
87 88

	// Cat returns a reader for the file
89
	Cat(context.Context, Path) (Reader, error)
90 91

	// Ls returns the list of links in a directory
92
	Ls(context.Context, Path) ([]*Link, error)
93 94
}

Łukasz Magiera's avatar
Łukasz Magiera committed
95 96 97 98 99 100 101 102 103 104 105 106 107
type BlockAPI interface {
	Put(context.Context, io.Reader) (Path, error)
	WithCodec(codec uint64) options.BlockPutOption
	WithHash(mhType uint64, mhLen int) options.BlockPutOption

	Get(context.Context) (io.Reader, error)

	Rm(context.Context) error
	WithForce(force bool) options.BlockRmOption

	Stat(context.Context) (BlockStat, error)
}

Łukasz Magiera's avatar
Łukasz Magiera committed
108
// DagAPI specifies the interface to IPLD
Łukasz Magiera's avatar
Łukasz Magiera committed
109
type DagAPI interface {
Łukasz Magiera's avatar
Łukasz Magiera committed
110
	// Put inserts data using specified format and input encoding.
Łukasz Magiera's avatar
Łukasz Magiera committed
111 112 113
	// Unless used with WithCodec or WithHash, the defaults "dag-cbor" and
	// "sha256" are used.
	Put(ctx context.Context, src io.Reader, opts ...options.DagPutOption) (Path, error)
114 115 116 117 118 119 120 121 122 123 124 125 126 127

	// WithInputEnc is an option for Put which specifies the input encoding of the
	// data. Default is "json", most formats/codecs support "raw"
	WithInputEnc(enc string) options.DagPutOption

	// WithCodec is an option for Put which specifies the multicodec to use to
	// serialize the object. Default is cid.DagCBOR (0x71)
	WithCodec(codec uint64) options.DagPutOption

	// WithHash is an option for Put which specifies the multihash settings to use
	// when hashing the object. Default is based on the codec used
	// (mh.SHA2_256 (0x12) for DagCBOR). If mhLen is set to -1, default length for
	// the hash will be used
	WithHash(mhType uint64, mhLen int) options.DagPutOption
Łukasz Magiera's avatar
Łukasz Magiera committed
128 129

	// Get attempts to resolve and get the node specified by the path
Łukasz Magiera's avatar
Łukasz Magiera committed
130
	Get(ctx context.Context, path Path) (Node, error)
Łukasz Magiera's avatar
Łukasz Magiera committed
131 132

	// Tree returns list of paths within a node specified by the path.
133 134 135 136 137
	Tree(ctx context.Context, path Path, opts ...options.DagTreeOption) ([]Path, error)

	// WithDepth is an option for Tree which specifies maximum depth of the
	// returned tree. Default is -1 (no depth limit)
	WithDepth(depth int) options.DagTreeOption
Łukasz Magiera's avatar
Łukasz Magiera committed
138 139
}

140 141 142 143 144 145 146 147
// 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.
Łukasz Magiera's avatar
Łukasz Magiera committed
148
type NameAPI interface {
149
	// Publish announces new IPNS name
150
	Publish(ctx context.Context, path Path, opts ...options.NamePublishOption) (IpnsEntry, error)
151 152 153

	// WithValidTime is an option for Publish which specifies for how long the
	// entry will remain valid. Default value is 24h
154
	WithValidTime(validTime time.Duration) options.NamePublishOption
155 156 157

	// WithKey is an option for Publish which specifies the key to use for
	// publishing. Default value is "self" which is the node's own PeerID.
158
	// The key parameter must be either PeerID or keystore key alias.
159
	//
160
	// You can use KeyAPI to list and generate more names and their respective keys.
161 162
	WithKey(key string) options.NamePublishOption

163
	// Resolve attempts to resolve the newest version of the specified name
164
	Resolve(ctx context.Context, name string, opts ...options.NameResolveOption) (Path, error)
165 166 167

	// WithRecursive is an option for Resolve which specifies whether to perform a
	// recursive lookup. Default value is false
168
	WithRecursive(recursive bool) options.NameResolveOption
169 170 171

	// WithLocal is an option for Resolve which specifies if the lookup should be
	// offline. Default value is false
172
	WithLocal(local bool) options.NameResolveOption
173

174 175 176
	// WithCache is an option for Resolve which specifies if cache should be used.
	// Default value is true
	WithCache(cache bool) options.NameResolveOption
Łukasz Magiera's avatar
Łukasz Magiera committed
177 178
}

179
// KeyAPI specifies the interface to Keystore
180
type KeyAPI interface {
181 182
	// Generate generates new key, stores it in the keystore under the specified
	// name and returns a base58 encoded multihash of it's public key
183
	Generate(ctx context.Context, name string, opts ...options.KeyGenerateOption) (Key, error)
184

Łukasz Magiera's avatar
Łukasz Magiera committed
185
	// WithType is an option for Generate which specifies which algorithm
186
	// should be used for the key. Default is options.RSAKey
187
	//
Łukasz Magiera's avatar
Łukasz Magiera committed
188
	// Supported key types:
189 190
	// * options.RSAKey
	// * options.Ed25519Key
Łukasz Magiera's avatar
Łukasz Magiera committed
191
	WithType(algorithm string) options.KeyGenerateOption
192 193

	// WithSize is an option for Generate which specifies the size of the key to
Łukasz Magiera's avatar
Łukasz Magiera committed
194 195 196 197
	// generated. Default is -1
	//
	// value of -1 means 'use default size for key type':
	//  * 2048 for RSA
198 199
	WithSize(size int) options.KeyGenerateOption

200 201 202
	// 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)
203 204 205

	// WithForce is an option for Rename which specifies whether to allow to
	// replace existing keys.
206 207
	WithForce(force bool) options.KeyRenameOption

208
	// List lists keys stored in keystore
209
	List(ctx context.Context) ([]Key, error)
210

211 212
	// Remove removes keys from keystore. Returns ipns path of the removed key
	Remove(ctx context.Context, name string) (Path, error)
Łukasz Magiera's avatar
Łukasz Magiera committed
213 214
}

Łukasz Magiera's avatar
Łukasz Magiera committed
215 216
// ObjectAPI specifies the interface to MerkleDAG and contains useful utilities
// for manipulating MerkleDAG data structures.
217
type ObjectAPI interface {
Łukasz Magiera's avatar
Łukasz Magiera committed
218
	// New creates new, empty (by default) dag-node.
Łukasz Magiera's avatar
Łukasz Magiera committed
219
	New(context.Context, ...options.ObjectNewOption) (Node, error)
Łukasz Magiera's avatar
Łukasz Magiera committed
220 221 222 223 224 225 226

	// WithType is an option for New which allows to change the type of created
	// dag node.
	//
	// Supported types:
	// * 'empty' - Empty node
	// * 'unixfs-dir' - Empty UnixFS directory
Łukasz Magiera's avatar
Łukasz Magiera committed
227 228
	WithType(string) options.ObjectNewOption

229 230 231 232 233 234 235 236 237 238
	// Put imports the data into merkledag
	Put(context.Context, io.Reader, ...options.ObjectPutOption) (Path, error)

	// WithInputEnc is an option for Put which specifies the input encoding of the
	// data. Default is "json".
	//
	// Supported encodings:
	// * "protobuf"
	// * "json"
	WithInputEnc(e string) options.ObjectPutOption
Łukasz Magiera's avatar
Łukasz Magiera committed
239

Łukasz Magiera's avatar
Łukasz Magiera committed
240 241 242 243 244 245 246 247
	// WithDataType specifies the encoding of data field when using Josn or XML
	// input encoding.
	//
	// Supported types:
	// * "text" (default)
	// * "base64"
	WithDataType(t string) options.ObjectPutOption

Łukasz Magiera's avatar
Łukasz Magiera committed
248
	// Get returns the node for the path
249
	Get(context.Context, Path) (Node, error)
Łukasz Magiera's avatar
Łukasz Magiera committed
250 251

	// Data returns reader for data of the node
252
	Data(context.Context, Path) (io.Reader, error)
Łukasz Magiera's avatar
Łukasz Magiera committed
253 254

	// Links returns lint or links the node contains
255
	Links(context.Context, Path) ([]*Link, error)
Łukasz Magiera's avatar
Łukasz Magiera committed
256 257

	// Stat returns information about the node
258 259
	Stat(context.Context, Path) (*ObjectStat, error)

Łukasz Magiera's avatar
Łukasz Magiera committed
260 261 262
	// 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).
Łukasz Magiera's avatar
Łukasz Magiera committed
263
	AddLink(ctx context.Context, base Path, name string, child Path, opts ...options.ObjectAddLinkOption) (Path, error)
Łukasz Magiera's avatar
Łukasz Magiera committed
264 265 266

	// WithCreate is an option for AddLink which specifies whether create required
	// directories for the child
Łukasz Magiera's avatar
Łukasz Magiera committed
267 268
	WithCreate(create bool) options.ObjectAddLinkOption

Łukasz Magiera's avatar
Łukasz Magiera committed
269
	// RmLink removes a link from the node
Łukasz Magiera's avatar
Łukasz Magiera committed
270
	RmLink(ctx context.Context, base Path, link string) (Path, error)
Łukasz Magiera's avatar
Łukasz Magiera committed
271 272

	// AppendData appends data to the node
Łukasz Magiera's avatar
Łukasz Magiera committed
273
	AppendData(context.Context, Path, io.Reader) (Path, error)
Łukasz Magiera's avatar
Łukasz Magiera committed
274 275

	// SetData sets the data contained in the node
Łukasz Magiera's avatar
Łukasz Magiera committed
276
	SetData(context.Context, Path, io.Reader) (Path, error)
277 278
}

Łukasz Magiera's avatar
Łukasz Magiera committed
279
// ObjectStat provides information about dag nodes
280
type ObjectStat struct {
Łukasz Magiera's avatar
Łukasz Magiera committed
281 282 283 284 285 286 287 288 289 290 291 292 293 294 295
	// 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

Łukasz Magiera's avatar
Łukasz Magiera committed
296
	// CumulativeSize is size of the tree (BlockSize + link sizes)
297 298
	CumulativeSize int
}
299 300 301

var ErrIsDir = errors.New("object is a directory")
var ErrOffline = errors.New("can't resolve, ipfs node is offline")