path.go 4.47 KB
Newer Older
1 2 3
package iface

import (
Kevin Atkinson's avatar
Kevin Atkinson committed
4
	ipfspath "gx/ipfs/QmYh33CFYYEgQNSZ9PEP7ZN57dhErRZ7NfLS1BUA9GBBRk/go-path"
5

6
	cid "gx/ipfs/QmPSQnBKM9g7BaUcZCvswUJVscQ1ipjmwxN5PXCjkp9EQ7/go-cid"
7 8
)

9 10
//TODO: merge with ipfspath so we don't depend on it

11 12
// 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.
Łukasz Magiera's avatar
Łukasz Magiera committed
13 14 15 16 17 18 19
//
// Paths must be prefixed with a valid prefix:
//
// * /ipfs - Immutable unixfs path (files)
// * /ipld - Immutable ipld path (data)
// * /ipns - Mutable names. Usually resolves to one of the immutable paths
//TODO: /local (MFS)
20 21 22
type Path interface {
	// String returns the path as a string.
	String() string
23

24 25 26
	// Namespace returns the first component of the path.
	//
	// For example path "/ipfs/QmHash", calling Namespace() will return "ipfs"
27
	Namespace() string
Łukasz Magiera's avatar
Łukasz Magiera committed
28 29 30 31 32 33

	// Mutable returns false if the data pointed to by this path in guaranteed
	// to not change.
	//
	// Note that resolved mutable path can be immutable.
	Mutable() bool
34 35
}

36
// ResolvedPath is a path which was resolved to the last resolvable node
37
type ResolvedPath interface {
38 39
	// Cid returns the CID of the node referenced by the path. Remainder of the
	// path is guaranteed to be within the node.
40
	//
41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67
	// Examples:
	// If you have 3 linked objects: QmRoot -> A -> B:
	//
	// cidB := {"foo": {"bar": 42 }}
	// cidA := {"B": {"/": cidB }}
	// cidRoot := {"A": {"/": cidA }}
	//
	// And resolve paths:
	// * "/ipfs/${cidRoot}"
	//   * Calling Cid() will return `cidRoot`
	//   * Calling Root() will return `cidRoot`
	//   * Calling Remainder() will return ``
	//
	// * "/ipfs/${cidRoot}/A"
	//   * Calling Cid() will return `cidA`
	//   * Calling Root() will return `cidRoot`
	//   * Calling Remainder() will return ``
	//
	// * "/ipfs/${cidRoot}/A/B/foo"
	//   * Calling Cid() will return `cidB`
	//   * Calling Root() will return `cidRoot`
	//   * Calling Remainder() will return `foo`
	//
	// * "/ipfs/${cidRoot}/A/B/foo/bar"
	//   * Calling Cid() will return `cidB`
	//   * Calling Root() will return `cidRoot`
	//   * Calling Remainder() will return `foo/bar`
68
	Cid() cid.Cid
69

70 71 72 73 74
	// Root returns the CID of the root object of the path
	//
	// Example:
	// If you have 3 linked objects: QmRoot -> A -> B, and resolve path
	// "/ipfs/QmRoot/A/B", the Root method will return the CID of object QmRoot
75 76
	//
	// For more examples see the documentation of Cid() method
77
	Root() cid.Cid
78

Łukasz Magiera's avatar
Łukasz Magiera committed
79
	// Remainder returns unresolved part of the path
80 81 82 83 84
	//
	// Example:
	// If you have 2 linked objects: QmRoot -> A, where A is a CBOR node
	// containing the following data:
	//
85
	// {"foo": {"bar": 42 }}
86 87
	//
	// When resolving "/ipld/QmRoot/A/foo/bar", Remainder will return "foo/bar"
88 89
	//
	// For more examples see the documentation of Cid() method
Łukasz Magiera's avatar
Łukasz Magiera committed
90
	Remainder() string
91 92

	Path
93
}
94 95 96 97 98 99 100 101 102

// path implements coreiface.Path
type path struct {
	path ipfspath.Path
}

// resolvedPath implements coreiface.resolvedPath
type resolvedPath struct {
	path
103 104
	cid       cid.Cid
	root      cid.Cid
105 106 107 108
	remainder string
}

// IpfsPath creates new /ipfs path from the provided CID
109
func IpfsPath(c cid.Cid) ResolvedPath {
110 111 112 113 114 115 116 117 118
	return &resolvedPath{
		path:      path{ipfspath.Path("/ipfs/" + c.String())},
		cid:       c,
		root:      c,
		remainder: "",
	}
}

// IpldPath creates new /ipld path from the provided CID
119
func IpldPath(c cid.Cid) ResolvedPath {
120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140
	return &resolvedPath{
		path:      path{ipfspath.Path("/ipld/" + c.String())},
		cid:       c,
		root:      c,
		remainder: "",
	}
}

// ParsePath parses string path to a Path
func ParsePath(p string) (Path, error) {
	pp, err := ipfspath.ParsePath(p)
	if err != nil {
		return nil, err
	}

	return &path{path: pp}, nil
}

// NewResolvedPath creates new ResolvedPath. This function performs no checks
// and is intended to be used by resolver implementations. Incorrect inputs may
// cause panics. Handle with care.
141
func NewResolvedPath(ipath ipfspath.Path, c cid.Cid, root cid.Cid, remainder string) ResolvedPath {
142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165
	return &resolvedPath{
		path:      path{ipath},
		cid:       c,
		root:      root,
		remainder: remainder,
	}
}

func (p *path) String() string {
	return p.path.String()
}

func (p *path) Namespace() string {
	if len(p.path.Segments()) < 1 {
		panic("path without namespace") //this shouldn't happen under any scenario
	}
	return p.path.Segments()[0]
}

func (p *path) Mutable() bool {
	//TODO: MFS: check for /local
	return p.Namespace() == "ipns"
}

166
func (p *resolvedPath) Cid() cid.Cid {
167 168 169
	return p.cid
}

170
func (p *resolvedPath) Root() cid.Cid {
171 172 173 174 175 176
	return p.root
}

func (p *resolvedPath) Remainder() string {
	return p.remainder
}