interface.go 7.76 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
	ipld "gx/ipfs/QmNwUEK7QbwSqyKBu3mMtToo8SUc6wQJ7gdZq4gGGJqfnf/go-ipld-format"
	cid "gx/ipfs/QmeSrf6pzut73u6zLQkRFQ3ygt3k6XFT2kjdYP8Tnkwwyg/go-cid"
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
}

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

	// ResolvePath resolves the path using Unixfs resolver
68
	ResolvePath(context.Context, Path) (Path, error)
69 70 71

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

75
// UnixfsAPI is the basic interface to immutable files in IPFS
76
type UnixfsAPI interface {
77
	// Add imports the data from the reader into merkledag file
78
	Add(context.Context, io.Reader) (Path, error)
79 80

	// Cat returns a reader for the file
81
	Cat(context.Context, Path) (Reader, error)
82 83

	// Ls returns the list of links in a directory
84
	Ls(context.Context, Path) ([]*Link, error)
85 86
}

Łukasz Magiera's avatar
Łukasz Magiera committed
87
// DagAPI specifies the interface to IPLD
Łukasz Magiera's avatar
Łukasz Magiera committed
88
type DagAPI interface {
Łukasz Magiera's avatar
Łukasz Magiera committed
89
	// Put inserts data using specified format and input encoding.
Łukasz Magiera's avatar
Łukasz Magiera committed
90 91 92
	// 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)
93 94 95 96 97 98 99 100 101 102 103 104 105 106

	// 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
107 108

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

	// Tree returns list of paths within a node specified by the path.
112 113 114 115 116
	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
117 118
}

119 120 121 122 123 124 125 126
// 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
127
type NameAPI interface {
128
	// Publish announces new IPNS name
129
	Publish(ctx context.Context, path Path, opts ...options.NamePublishOption) (IpnsEntry, error)
130 131 132

	// WithValidTime is an option for Publish which specifies for how long the
	// entry will remain valid. Default value is 24h
133
	WithValidTime(validTime time.Duration) options.NamePublishOption
134 135 136

	// 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.
137
	// The key parameter must be either PeerID or keystore key alias.
138
	//
139
	// You can use KeyAPI to list and generate more names and their respective keys.
140 141
	WithKey(key string) options.NamePublishOption

142
	// Resolve attempts to resolve the newest version of the specified name
143
	Resolve(ctx context.Context, name string, opts ...options.NameResolveOption) (Path, error)
144 145 146

	// WithRecursive is an option for Resolve which specifies whether to perform a
	// recursive lookup. Default value is false
147
	WithRecursive(recursive bool) options.NameResolveOption
148 149 150

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

153 154 155
	// 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
156 157
}

158
// KeyAPI specifies the interface to Keystore
159
type KeyAPI interface {
160 161
	// Generate generates new key, stores it in the keystore under the specified
	// name and returns a base58 encoded multihash of it's public key
162
	Generate(ctx context.Context, name string, opts ...options.KeyGenerateOption) (Key, error)
163

Łukasz Magiera's avatar
Łukasz Magiera committed
164
	// WithType is an option for Generate which specifies which algorithm
165
	// should be used for the key. Default is options.RSAKey
166
	//
Łukasz Magiera's avatar
Łukasz Magiera committed
167
	// Supported key types:
168 169
	// * options.RSAKey
	// * options.Ed25519Key
Łukasz Magiera's avatar
Łukasz Magiera committed
170
	WithType(algorithm string) options.KeyGenerateOption
171 172

	// WithSize is an option for Generate which specifies the size of the key to
Łukasz Magiera's avatar
Łukasz Magiera committed
173 174 175 176
	// generated. Default is -1
	//
	// value of -1 means 'use default size for key type':
	//  * 2048 for RSA
177 178
	WithSize(size int) options.KeyGenerateOption

179 180 181
	// 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)
182 183 184

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

187
	// List lists keys stored in keystore
188
	List(ctx context.Context) ([]Key, error)
189

190 191
	// 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
192 193
}

194 195
//TODO: Should this use paths instead of cids?
type ObjectAPI interface {
Łukasz Magiera's avatar
Łukasz Magiera committed
196 197 198 199
	New(context.Context, ...options.ObjectNewOption) (Node, error)
	WithType(string) options.ObjectNewOption

	Put(context.Context, Node) (Path, error)
200 201 202 203 204
	Get(context.Context, Path) (Node, error)
	Data(context.Context, Path) (io.Reader, error)
	Links(context.Context, Path) ([]*Link, error)
	Stat(context.Context, Path) (*ObjectStat, error)

Łukasz Magiera's avatar
Łukasz Magiera committed
205 206 207
	AddLink(ctx context.Context, base Path, name string, child Path, opts ...options.ObjectAddLinkOption) (Node, error)
	WithCreate(create bool) options.ObjectAddLinkOption

208 209 210 211 212 213 214 215 216 217 218 219 220
	RmLink(context.Context, Path, string) (Node, error)
	AppendData(context.Context, Path, io.Reader) (Node, error)
	SetData(context.Context, Path, io.Reader) (Node, error)
}

type ObjectStat struct {
	Cid            *cid.Cid
	NumLinks       int
	BlockSize      int
	LinksSize      int
	DataSize       int
	CumulativeSize int
}
221 222 223

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