interface.go 6.85 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 20 21 22 23 24 25 26
type Path interface {
	String() string
	Cid() *cid.Cid
	Root() *cid.Cid
	Resolved() bool
}

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

type Reader interface {
	io.ReadSeeker
	io.Closer
}

36 37 38 39 40 41 42 43 44 45
type IpnsEntry interface {
	Name() string
	Value() Path
}

type Key interface {
	Name() string
	Path() Path
}

46
// CoreAPI defines an unified interface to IPFS for Go programs.
47
type CoreAPI interface {
48
	// Unixfs returns an implementation of Unixfs API
49
	Unixfs() UnixfsAPI
Łukasz Magiera's avatar
Łukasz Magiera committed
50
	Dag() DagAPI
Łukasz Magiera's avatar
Łukasz Magiera committed
51
	Name() NameAPI
52
	Key() KeyAPI
53 54

	// ResolvePath resolves the path using Unixfs resolver
55
	ResolvePath(context.Context, Path) (Path, error)
56 57 58

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

62
// UnixfsAPI is the basic interface to immutable files in IPFS
63
type UnixfsAPI interface {
64
	// Add imports the data from the reader into merkledag file
65
	Add(context.Context, io.Reader) (Path, error)
66 67

	// Cat returns a reader for the file
68
	Cat(context.Context, Path) (Reader, error)
69 70

	// Ls returns the list of links in a directory
71
	Ls(context.Context, Path) ([]*Link, error)
72 73
}

Łukasz Magiera's avatar
Łukasz Magiera committed
74
// DagAPI specifies the interface to IPLD
Łukasz Magiera's avatar
Łukasz Magiera committed
75
type DagAPI interface {
Łukasz Magiera's avatar
Łukasz Magiera committed
76
	// Put inserts data using specified format and input encoding.
Łukasz Magiera's avatar
Łukasz Magiera committed
77 78 79
	// 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)
80 81 82 83 84 85 86 87 88 89 90 91 92 93

	// 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
94 95

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

	// Tree returns list of paths within a node specified by the path.
99 100 101 102 103
	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
104 105
}

106 107 108 109 110 111 112 113
// 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
114
type NameAPI interface {
115
	// Publish announces new IPNS name
116
	Publish(ctx context.Context, path Path, opts ...options.NamePublishOption) (IpnsEntry, error)
117 118 119

	// WithValidTime is an option for Publish which specifies for how long the
	// entry will remain valid. Default value is 24h
120
	WithValidTime(validTime time.Duration) options.NamePublishOption
121 122 123

	// 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.
124
	// The key parameter must be either PeerID or keystore key alias.
125
	//
126
	// You can use KeyAPI to list and generate more names and their respective keys.
127 128
	WithKey(key string) options.NamePublishOption

129
	// Resolve attempts to resolve the newest version of the specified name
130
	Resolve(ctx context.Context, name string, opts ...options.NameResolveOption) (Path, error)
131 132 133

	// WithRecursive is an option for Resolve which specifies whether to perform a
	// recursive lookup. Default value is false
134
	WithRecursive(recursive bool) options.NameResolveOption
135 136 137

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

140 141 142
	// 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
143 144
}

145
// KeyAPI specifies the interface to Keystore
146
type KeyAPI interface {
147 148
	// Generate generates new key, stores it in the keystore under the specified
	// name and returns a base58 encoded multihash of it's public key
149
	Generate(ctx context.Context, name string, opts ...options.KeyGenerateOption) (Key, error)
150

Łukasz Magiera's avatar
Łukasz Magiera committed
151
	// WithType is an option for Generate which specifies which algorithm
152
	// should be used for the key. Default is options.RSAKey
153
	//
Łukasz Magiera's avatar
Łukasz Magiera committed
154
	// Supported key types:
155 156
	// * options.RSAKey
	// * options.Ed25519Key
Łukasz Magiera's avatar
Łukasz Magiera committed
157
	WithType(algorithm string) options.KeyGenerateOption
158 159 160

	// WithSize is an option for Generate which specifies the size of the key to
	// generated. Default is 0
161 162
	WithSize(size int) options.KeyGenerateOption

163 164 165
	// 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)
166 167 168

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

171
	// List lists keys stored in keystore
172
	List(ctx context.Context) ([]Key, error)
173

174 175
	// 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
176 177
}

178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201
// type ObjectAPI interface {
// 	New() (cid.Cid, Object)
// 	Get(string) (Object, error)
// 	Links(string) ([]*Link, error)
// 	Data(string) (Reader, error)
// 	Stat(string) (ObjectStat, error)
// 	Put(Object) (cid.Cid, error)
// 	SetData(string, Reader) (cid.Cid, error)
// 	AppendData(string, Data) (cid.Cid, error)
// 	AddLink(string, string, string) (cid.Cid, error)
// 	RmLink(string, string) (cid.Cid, error)
// }

// type ObjectStat struct {
// 	Cid            cid.Cid
// 	NumLinks       int
// 	BlockSize      int
// 	LinksSize      int
// 	DataSize       int
// 	CumulativeSize int
// }

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