path.go 4.86 KB
Newer Older
Łukasz Magiera's avatar
Łukasz Magiera committed
1 2 3 4 5
package path

import (
	"strings"

6 7
	cid "gitlab.dms3.io/dms3/go-cid"
	dms3path "gitlab.dms3.io/dms3/go-path"
Łukasz Magiera's avatar
Łukasz Magiera committed
8 9 10 11 12 13 14
)

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

	// Namespace returns the first component of the path.
	//
25
	// For example path "/dms3/QmHash", calling Namespace() will return "dms3"
Łukasz Magiera's avatar
Łukasz Magiera committed
26 27 28 29 30 31 32 33 34 35 36
	//
	// Calling this method on invalid paths (IsValid() != nil) will result in
	// empty string
	Namespace() string

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

37
	// IsValid checks if this path is a valid dms3 Path, returning nil iff it is
Łukasz Magiera's avatar
Łukasz Magiera committed
38 39 40 41
	// valid
	IsValid() error
}

42
// Resolved is a path which was resolved to the last resolvable node.
Łukasz Magiera's avatar
Łukasz Magiera committed
43
// ResolvedPaths are guaranteed to return nil from `IsValid`
44
type Resolved interface {
Łukasz Magiera's avatar
Łukasz Magiera committed
45 46 47 48 49 50 51 52 53 54 55 56
	// Cid returns the CID of the node referenced by the path. Remainder of the
	// path is guaranteed to be within the node.
	//
	// Examples:
	// If you have 3 linked objects: QmRoot -> A -> B:
	//
	// cidB := {"foo": {"bar": 42 }}
	// cidA := {"B": {"/": cidB }}
	// cidRoot := {"A": {"/": cidA }}
	//
	// And resolve paths:
	//
57
	// * "/dms3/${cidRoot}"
Łukasz Magiera's avatar
Łukasz Magiera committed
58 59 60 61
	//   * Calling Cid() will return `cidRoot`
	//   * Calling Root() will return `cidRoot`
	//   * Calling Remainder() will return ``
	//
62
	// * "/dms3/${cidRoot}/A"
Łukasz Magiera's avatar
Łukasz Magiera committed
63 64 65 66
	//   * Calling Cid() will return `cidA`
	//   * Calling Root() will return `cidRoot`
	//   * Calling Remainder() will return ``
	//
67
	// * "/dms3/${cidRoot}/A/B/foo"
Łukasz Magiera's avatar
Łukasz Magiera committed
68 69 70 71
	//   * Calling Cid() will return `cidB`
	//   * Calling Root() will return `cidRoot`
	//   * Calling Remainder() will return `foo`
	//
72
	// * "/dms3/${cidRoot}/A/B/foo/bar"
Łukasz Magiera's avatar
Łukasz Magiera committed
73 74 75 76 77 78 79 80 81
	//   * Calling Cid() will return `cidB`
	//   * Calling Root() will return `cidRoot`
	//   * Calling Remainder() will return `foo/bar`
	Cid() cid.Cid

	// Root returns the CID of the root object of the path
	//
	// Example:
	// If you have 3 linked objects: QmRoot -> A -> B, and resolve path
82
	// "/dms3/QmRoot/A/B", the Root method will return the CID of object QmRoot
Łukasz Magiera's avatar
Łukasz Magiera committed
83 84 85 86 87 88 89 90 91 92 93 94
	//
	// For more examples see the documentation of Cid() method
	Root() cid.Cid

	// Remainder returns unresolved part of the path
	//
	// Example:
	// If you have 2 linked objects: QmRoot -> A, where A is a CBOR node
	// containing the following data:
	//
	// {"foo": {"bar": 42 }}
	//
tavit ohanian's avatar
tavit ohanian committed
95
	// When resolving "/ld/QmRoot/A/foo/bar", Remainder will return "foo/bar"
Łukasz Magiera's avatar
Łukasz Magiera committed
96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121
	//
	// For more examples see the documentation of Cid() method
	Remainder() string

	Path
}

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

// resolvedPath implements coreiface.resolvedPath
type resolvedPath struct {
	path
	cid       cid.Cid
	root      cid.Cid
	remainder string
}

// Join appends provided segments to the base path
func Join(base Path, a ...string) Path {
	s := strings.Join(append([]string{base.String()}, a...), "/")
	return &path{path: s}
}

122 123
// Dms3Path creates new /dms3 path from the provided CID
func Dms3Path(c cid.Cid) Resolved {
Łukasz Magiera's avatar
Łukasz Magiera committed
124
	return &resolvedPath{
125
		path:      path{"/dms3/" + c.String()},
Łukasz Magiera's avatar
Łukasz Magiera committed
126 127 128 129 130 131
		cid:       c,
		root:      c,
		remainder: "",
	}
}

tavit ohanian's avatar
tavit ohanian committed
132 133
// LdPath creates new /ld path from the provided CID
func LdPath(c cid.Cid) Resolved {
Łukasz Magiera's avatar
Łukasz Magiera committed
134
	return &resolvedPath{
tavit ohanian's avatar
tavit ohanian committed
135
		path:      path{"/ld/" + c.String()},
Łukasz Magiera's avatar
Łukasz Magiera committed
136 137 138 139 140 141
		cid:       c,
		root:      c,
		remainder: "",
	}
}

142 143
// New parses string path to a Path
func New(p string) Path {
144
	if pp, err := dms3path.ParsePath(p); err == nil {
Łukasz Magiera's avatar
Łukasz Magiera committed
145 146 147 148 149 150
		p = pp.String()
	}

	return &path{path: p}
}

151
// NewResolvedPath creates new Resolved path. This function performs no checks
Łukasz Magiera's avatar
Łukasz Magiera committed
152 153
// and is intended to be used by resolver implementations. Incorrect inputs may
// cause panics. Handle with care.
154
func NewResolvedPath(ipath dms3path.Path, c cid.Cid, root cid.Cid, remainder string) Resolved {
Łukasz Magiera's avatar
Łukasz Magiera committed
155 156 157 158 159 160 161 162 163 164 165 166 167
	return &resolvedPath{
		path:      path{ipath.String()},
		cid:       c,
		root:      root,
		remainder: remainder,
	}
}

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

func (p *path) Namespace() string {
168
	ip, err := dms3path.ParsePath(p.path)
Łukasz Magiera's avatar
Łukasz Magiera committed
169 170 171 172 173 174 175 176 177 178 179 180
	if err != nil {
		return ""
	}

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

func (p *path) Mutable() bool {
	// TODO: MFS: check for /local
181
	return p.Namespace() == "dms3ns"
Łukasz Magiera's avatar
Łukasz Magiera committed
182 183 184
}

func (p *path) IsValid() error {
185
	_, err := dms3path.ParsePath(p.path)
Łukasz Magiera's avatar
Łukasz Magiera committed
186 187 188 189 190 191 192 193 194 195 196 197 198 199
	return err
}

func (p *resolvedPath) Cid() cid.Cid {
	return p.cid
}

func (p *resolvedPath) Root() cid.Cid {
	return p.root
}

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