interface.go 3.71 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 9
package iface

import (
	"context"
	"errors"
	"io"

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

Steven Allen's avatar
Steven Allen committed
12 13
	ipld "gx/ipfs/QmNwUEK7QbwSqyKBu3mMtToo8SUc6wQJ7gdZq4gGGJqfnf/go-ipld-format"
	cid "gx/ipfs/QmeSrf6pzut73u6zLQkRFQ3ygt3k6XFT2kjdYP8Tnkwwyg/go-cid"
14 15
)

16 17
// 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.
18 19 20 21 22 23 24 25
type Path interface {
	String() string
	Cid() *cid.Cid
	Root() *cid.Cid
	Resolved() bool
}

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

type Reader interface {
	io.ReadSeeker
	io.Closer
}

35
// CoreAPI defines an unified interface to IPFS for Go programs.
36
type CoreAPI interface {
37
	// Unixfs returns an implementation of Unixfs API
38
	Unixfs() UnixfsAPI
Łukasz Magiera's avatar
Łukasz Magiera committed
39
	Dag() DagAPI
40 41

	// ResolvePath resolves the path using Unixfs resolver
42
	ResolvePath(context.Context, Path) (Path, error)
43 44 45

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

49
// UnixfsAPI is the basic interface to immutable files in IPFS
50
type UnixfsAPI interface {
51
	// Add imports the data from the reader into merkledag file
52
	Add(context.Context, io.Reader) (Path, error)
53 54

	// Cat returns a reader for the file
55
	Cat(context.Context, Path) (Reader, error)
56 57

	// Ls returns the list of links in a directory
58
	Ls(context.Context, Path) ([]*Link, error)
59 60
}

Łukasz Magiera's avatar
Łukasz Magiera committed
61
// DagAPI specifies the interface to IPLD
Łukasz Magiera's avatar
Łukasz Magiera committed
62
type DagAPI interface {
Łukasz Magiera's avatar
Łukasz Magiera committed
63
	// Put inserts data using specified format and input encoding.
Łukasz Magiera's avatar
Łukasz Magiera committed
64 65 66
	// 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)
67 68 69 70 71 72 73 74 75 76 77 78 79 80

	// 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
81 82

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

	// Tree returns list of paths within a node specified by the path.
86 87 88 89 90
	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
91 92
}

93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116
// 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")