ns

Documentation

Overview

Package ns defines the qri dataset naming system This package is currently an experiment while we try to settle the distinction between a dataset.datasetPod and a reference. This code is extracted from

github.com/qri-io/qri/repo/ref.go

This package will either move to a new location or be removed entirely before 2019-04-01

initial RFC is here: https://github.com/qri-io/rfcs/blob/master/text/0006-dataset_naming.md

Index

• Variables
• func CompareRef(a, b Ref) error
• func HTTPPathToQriPath(path string) string
• type QriCtxKey
• type Ref
  • func MustParseRef(refstr string) Ref
  • func ParseRef(ref string) (Ref, error)
  • func RefFromCtx(ctx context.Context) Ref
  • func RefFromHTTPPath(path string) (Ref, error)
  • func RefFromReq(r *http.Request) (Ref, error)
  • func (r Ref) AliasString() (s string)
  • func (r Ref) Equal(b Ref) bool
  • func (r Ref) IsEmpty() bool
  • func (r Ref) IsPeerRef() bool
  • func (r Ref) Match(b Ref) bool
  • func (r Ref) String() (s string)

Variables

var (
	// ErrEmptyRef indicates that the given reference is empty
	ErrEmptyRef = fmt.Errorf("repo: empty dataset reference")
)

Functions

func CompareRef

func CompareRef(a, b Ref) error

CompareRef compares two Dataset Refs, returning an error describing any difference between the two references

func HTTPPathToQriPath

func HTTPPathToQriPath(path string) string

HTTPPathToQriPath converts a http path to a qri path

Types

type QriCtxKey

type QriCtxKey string

QriCtxKey defines a distinct type for keys for context values should always use custom types to avoid collissions. see comment on context.WithValue for more info

const RefCtxKey QriCtxKey = "datasetRef"

RefCtxKey is the key for adding a dataset reference to a context.Context

type Ref

type Ref struct {
	// Peername of dataset owner
	Peername string `json:"peername,omitempty"`
	// ProfileID of dataset owner
	ProfileID string `json:"profileID,omitempty"`
	// Unique name reference for this dataset
	Name string `json:"name,omitempty"`
	// Content-addressed path for this dataset
	Path string `json:"path,omitempty"`
}

Ref encapsulates a reference to a dataset. This needs to exist to bind ways of referring to a dataset to a dataset itself, as datasets can't easily contain their own hash information, and names are unique on a per-repository basis. It's tempting to think this needs to be "bigger", supporting more fields, keep in mind that if the information is important at all, it should be stored as metadata within the dataset itself.

func MustParseRef

func MustParseRef(refstr string) Ref

MustParseRef panics if the reference is invalid. Useful for testing

func ParseRef

func ParseRef(ref string) (Ref, error)

ParseRef decodes a dataset reference from a string value It’s possible to refer to a dataset in a number of ways. The full definition of a dataset reference is as follows:

dataset_reference = peer_name/dataset_name@peer_id/network/hash

we swap in defaults as follows, all of which are represented as empty strings:

network - defaults to /ipfs/
hash - tip of version history (latest known commit)

these defaults are currently enforced by convention. TODO - make Dataset Ref parsing the responisiblity of the repo.Repo interface, replacing empty strings with actual defaults

dataset names & hashes are disambiguated by checking if the input parses to a valid multihash after base58 decoding. through defaults & base58 checking the following should all parse:

peer_name/dataset_name
/network/hash
peername
peer_id
@peer_id
@peer_id/network/hash

see tests for more exmples

TODO - add validation that prevents peernames from being valid base58 multihashes and makes sure hashes are actually valid base58 multihashes TODO - figure out how IPFS CID's play into this

func RefFromCtx

func RefFromCtx(ctx context.Context) Ref

RefFromCtx extracts a Dataset reference from a given context if one is set, returning nil otherwise

func RefFromHTTPPath

func RefFromHTTPPath(path string) (Ref, error)

RefFromHTTPPath parses a path and returns a datasetRef

func RefFromReq

func RefFromReq(r *http.Request) (Ref, error)

RefFromReq examines the path element of a request URL to

func (Ref) AliasString

func (r Ref) AliasString() (s string)

AliasString returns the alias components of a Ref as a string

func (Ref) Equal

func (r Ref) Equal(b Ref) bool

Equal returns true only if Peername Name and Path are equal

func (Ref) IsEmpty

func (r Ref) IsEmpty() bool

IsEmpty returns true if none of it's fields are set

func (Ref) IsPeerRef

func (r Ref) IsPeerRef() bool

IsPeerRef returns true if only Peername is set

func (Ref) Match

func (r Ref) Match(b Ref) bool

Match checks returns true if Peername and Name are equal, and/or path is equal

func (Ref) String

func (r Ref) String() (s string)

String implements the Stringer interface for Ref