interface.go 4.29 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

Łukasz Magiera's avatar
Łukasz Magiera committed
31 32 33 34 35
type IpnsEntry struct {
	Name  string
	Value Path
}

36 37 38 39 40
type Reader interface {
	io.ReadSeeker
	io.Closer
}

41
// CoreAPI defines an unified interface to IPFS for Go programs.
42
type CoreAPI interface {
43
	// Unixfs returns an implementation of Unixfs API
44
	Unixfs() UnixfsAPI
Łukasz Magiera's avatar
Łukasz Magiera committed
45
	Dag() DagAPI
Łukasz Magiera's avatar
Łukasz Magiera committed
46
	Name() NameAPI
47 48

	// ResolvePath resolves the path using Unixfs resolver
49
	ResolvePath(context.Context, Path) (Path, error)
50 51 52

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

56
// UnixfsAPI is the basic interface to immutable files in IPFS
57
type UnixfsAPI interface {
58
	// Add imports the data from the reader into merkledag file
59
	Add(context.Context, io.Reader) (Path, error)
60 61

	// Cat returns a reader for the file
62
	Cat(context.Context, Path) (Reader, error)
63 64

	// Ls returns the list of links in a directory
65
	Ls(context.Context, Path) ([]*Link, error)
66 67
}

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

	// 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
88 89

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

	// Tree returns list of paths within a node specified by the path.
93 94 95 96 97
	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
98 99
}

Łukasz Magiera's avatar
Łukasz Magiera committed
100 101 102 103 104 105 106 107 108 109 110 111
type NameAPI interface {
	Publish(ctx context.Context, path Path, validTime time.Duration, key string) (*IpnsEntry, error)
	Resolve(ctx context.Context, name string, recursive bool, local bool, nocache bool) (Path, error)
}

type KeyApi interface {
	Generate(ctx context.Context, name string, algorithm string, size int) error
	List(ctx context.Context) (map[string]string, error) //TODO: better key type?
	Rename(ctx context.Context, oldName string, newName string) error
	Remove(ctx context.Context, name string) error
}

112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135
// 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")