Documentation

Overview

Package naming defines types and utilities associated with naming.

Concept: https://vanadium.github.io/concepts/naming.html
Tutorial: (forthcoming)

Object names are 'resolved' using a MountTable to obtain a MountedServer that RPC method invocations can be directed at. MountTables may be mounted on each other to typically create a hierarchy. The name resolution process can thus involve multiple MountTables. Although it is expected that a hierarchy will be the typical use, it is nonetheless possible to create a cyclic graph of MountTables which will lead to name resolution errors at runtime.

Object names are strings with / used to separate the components of a name. Names may be started with / and the address of a MountTable or server, in which case they are considered 'rooted', otherwise they are 'relative' to the MountTable used to resolve them. Rooted names, unlike relative ones, have the same meaning regardless of the context in which they are accessed.

The first component of a rooted name is the address of the MountTable to use for resolving the remaining components of the name. The address may be the string representation of an Endpoint, a <host>:<port>, or <ip>:<port>. In addition, <host> or <ip> may be used without a <port> being specified in which case a default port is used. The portion of the name following the address is a relative name.

Thus:

/host:port/a/b/c/d means starting at host:port resolve a/b/c/d and return the terminating server and the relative path from that server.

Index

Examples

Constants

View Source
const Leaf = MountFlag(4) // Leaf means that the target server is a leaf.
View Source
const MT = MountFlag(2) // MT means that the target server is a mount table.
View Source
const Replace = MountFlag(1) // Replace means the mount should replace what is currently at the mount point
View Source
const ReservedNamePrefix = "__"

When this prefix is present at the beginning of an object name suffix, the server may intercept the request and handle it internally. This is used to provide debugging, monitoring and other common functionality across all servers. Applications cannot use any name component that starts with this prefix.

View Source
const (
	UnknownProtocol = ""
)

Variables

View Source
var (
	ErrNameExists              = verror.NewID("nameExists")
	ErrNoSuchName              = verror.NewID("nameDoesntExist")
	ErrNoSuchNameRoot          = verror.NewID("rootNameDoesntExist")
	ErrResolutionDepthExceeded = verror.NewID("resolutionDepthExceeded")
	ErrNoMountTable            = verror.NewID("noMounttable")
)
View Source
var (

	// DefaultEndpointVersion is the default of endpoints that we will create
	// when the version is otherwise unspecified.
	DefaultEndpointVersion = 6
)
View Source
var (
	// NullRoutingID is a special value representing the nil route.
	NullRoutingID = FixedRoutingID(0)
)

Functions

func Clean

func Clean(name string) string

Clean reduces multiple adjacent slashes to a single slash. It also removes any trailing slash.

func Compare

func Compare(a, b RoutingID) bool

func DecodeFromNameElement

func DecodeFromNameElement(s string) (string, bool)

DecodeFromNameElement decodes an encoded name element. If s is correctly encoded return the decoded string and true. Otherwise return the original string and false.

Note that this is more than the inverse of EncodeAsNameElement since it cn handle more hex encodings than / and %. This is intentional since we'll most likely want to add other letters to the set to be encoded.

func EncodeAsNameElement

func EncodeAsNameElement(s string) string

EncodeAsNameElement makes a string representable as a name element by escaping slashes.

func Escape

func Escape(s, special string) string

Escape encodes a string replacing the characters in <special> and % with a %<hex> escape. For efficiency we assume that special contains only single byte characters. If we need to escape runes, we'll have to rethink.

func FormatEndpoint

func FormatEndpoint(network, address string, opts ...EndpointOpt) string

FormatEndpoint creates a string representation of an Endpoint using the supplied parameters. Network and address are always required, RoutingID, RPCVersionRange and ServesMountTable can be specified as options.

func IsReserved

func IsReserved(name string) bool

IsReserved returns true if name is a reserved name.

func Join

func Join(elems ...string) string

Join takes a variable number of name fragments and concatenates them together using '/'. The returned name is cleaned of multiple adjacent '/'s.

func JoinAddressName

func JoinAddressName(address, name string) string

JoinAddressName takes an address and a relative name and returns a rooted or relative name. If a valid address is supplied then the returned name will always be a rooted name (i.e. starting with /), otherwise it may be relative. Address should not start with a / and if it does, that prefix will be stripped.

func Rooted

func Rooted(name string) bool

Rooted returns true for any name that is considered to be rooted. A rooted name is one that starts with a single / followed by a non /. / on its own is considered rooted.

func SplitAddressName

func SplitAddressName(name string) (string, string)

SplitAddressName takes an object name and returns the server address and the name relative to the server. The name parameter may be a rooted name or a relative name; an empty string address is returned for the latter case. The returned address may be in endpoint format or host:port format.

func StripReserved

func StripReserved(name string) string

StripReserved returns the name stripped of the reserved prefix.

func TrimSuffix

func TrimSuffix(name, suffix string) string

TrimSuffix removes the suffix (and any connecting '/') from the name.

func Unescape

func Unescape(s string) (string, bool)

Unescape decodes %<hex> encodings in a string into the relevant character. It returns false on error.

func VDLReadGlobChildrenReply

func VDLReadGlobChildrenReply(dec vdl.Decoder, x *GlobChildrenReply) error

func VDLReadGlobReply

func VDLReadGlobReply(dec vdl.Decoder, x *GlobReply) error

Types

type BlessingOpt

type BlessingOpt string

BlessingOpt is used to add a blessing name to the endpoint.

func (BlessingOpt) EndpointOpt

func (BlessingOpt) EndpointOpt()

type CacheCtl

type CacheCtl interface {
	CacheCtl()
}

CacheCtl is a cache control for the resolution cache.

type DisableCache

type DisableCache bool

DisbleCache disables the resolution cache when set to true and enables if false. As a side effect one can flush the cache by disabling and then reenabling it.

func (DisableCache) CacheCtl

func (DisableCache) CacheCtl()

type Endpoint

type Endpoint struct {
	Protocol string
	Address  string
	// RoutingID returns the RoutingID associated with this Endpoint.
	RoutingID RoutingID

	// ServesMountTable is true if this endpoint serves a mount table.
	// TODO(mattr): Remove it?
	ServesMountTable bool
	// contains filtered or unexported fields
}

Endpoint represents unique identifiers for entities communicating over a network. End users don't use endpoints - they deal solely with object names, with the MountTable providing translation of object names to endpoints.

Example
package main

import (
	"fmt"

	"v.io/v23/naming"
)

func main() {
	// Create an endpoint string for any tcp port on localhost.
	endPoint := naming.FormatEndpoint("tcp", "localhost:0")

	// Create a name for a service, 'example/foo', served on that endpoint.
	name := naming.JoinAddressName(endPoint, "example/foo")
	fmt.Printf("Name: %q\n", name)

	// Create an endpoint string for a global mounttable
	globalMT := naming.FormatEndpoint("tcp", "v.google.com:8080")

	// Create a name for service, published to the mounttable at
	// point 'users/you' serving names with the prefix
	// 'yourservice'
	nameForYou := naming.JoinAddressName(globalMT, naming.Join("users/you", "yourservice"))
	sameNameForYou := naming.JoinAddressName(globalMT, "users/you/yourservice")

	fmt.Printf("Name for you: %q\n", nameForYou)
	fmt.Printf("Same name for you: %q\n", sameNameForYou)

	// Names can be concatenated taking care to handle / correctly.
	fmt.Printf("Simple join: %q\n", naming.Join("a", "b"))
	fmt.Printf("Rooted join: %q\n", naming.Join("/a", "b"))

}
Output:

Name: "/@6@tcp@localhost:0@@@@@@/example/foo"
Name for you: "/@6@tcp@v.google.com:8080@@@@@@/users/you/yourservice"
Same name for you: "/@6@tcp@v.google.com:8080@@@@@@/users/you/yourservice"
Simple join: "a/b"
Rooted join: "/a/b"

func ParseEndpoint

func ParseEndpoint(input string) (Endpoint, error)

ParseEndpoint returns an Endpoint by parsing the supplied endpoint string as per the format described above. It can be used to test a string to see if it's in valid endpoint format.

NewEndpoint will accept strings both in the @ format described above and in internet host:port format.

All implementations of NewEndpoint should provide appropriate defaults for any endpoint subfields not explicitly provided as follows: - a missing protocol will default to a protocol appropriate for the

implementation hosting NewEndpoint

- a missing host:port will default to :0 - i.e. any port on all

interfaces

- a missing routing id should default to the null routing id - a missing codec version should default to AnyCodec - a missing RPC version should default to the highest version

supported by the runtime implementation hosting NewEndpoint

func (Endpoint) Addr

func (e Endpoint) Addr() net.Addr

Addr returns a net.Addr whose String method will return the the underlying network address encoded in the endpoint rather than the endpoint string itself. For example, for TCP based endpoints it will return a net.Addr whose network is "tcp" and string representation is <host>:<port>, than the full Vanadium endpoint as per the String method above.

func (Endpoint) BlessingNames

func (e Endpoint) BlessingNames() []string

BlessingNames returns the blessings that the process associated with this Endpoint will present.

func (Endpoint) IsZero

func (e Endpoint) IsZero() bool

IsZero returns true if the endpoint is equivalent to the zero value.

func (Endpoint) Name

func (e Endpoint) Name() string

Name returns a string reprsentation of this Endpoint that can be used as a name with rpc.StartCall.

func (Endpoint) Routes

func (e Endpoint) Routes() []string

Routes returns the local routing identifiers used for proxying connections with multiple proxies.

func (Endpoint) String

func (e Endpoint) String() string

func (Endpoint) VersionedString

func (e Endpoint) VersionedString(version int) string

VersionedString returns a string in the specified format. If the version number is unsupported, the current 'default' version will be used.

func (Endpoint) WithBlessingNames

func (e Endpoint) WithBlessingNames(names []string) Endpoint

WithBlessingNames derives a new endpoint with the given blessing names, but otherwise identical to e.

func (Endpoint) WithRoutes

func (e Endpoint) WithRoutes(routes []string) Endpoint

WithRoutes derives a new endpoint with the given blessing names, but otherwise identical to e.

type EndpointOpt

type EndpointOpt interface {
	EndpointOpt()
}

EndpointOpt must be implemented by all optional parameters to FormatEndpoint

type GlobChildrenReply

type GlobChildrenReply interface {
	// Index returns the field index.
	Index() int
	// Interface returns the field value as an interface.
	Interface() interface{}
	// Name returns the field name.
	Name() string
	// VDLReflect describes the GlobChildrenReply union type.
	VDLReflect(vdlGlobChildrenReplyReflect)
	VDLIsZero() bool
	VDLWrite(vdl.Encoder) error
}

GlobChildrenReply represents any single field of the GlobChildrenReply union type.

GlobChildrenReply is the data type returned by GlobChildren__.

type GlobChildrenReplyError

type GlobChildrenReplyError struct{ Value GlobError }

GlobChildrenReplyError represents field Error of the GlobChildrenReply union type.

func (GlobChildrenReplyError) Index

func (x GlobChildrenReplyError) Index() int

func (GlobChildrenReplyError) Interface

func (x GlobChildrenReplyError) Interface() interface{}

func (GlobChildrenReplyError) Name

func (x GlobChildrenReplyError) Name() string

func (GlobChildrenReplyError) VDLIsZero

func (x GlobChildrenReplyError) VDLIsZero() bool

func (GlobChildrenReplyError) VDLReflect

func (x GlobChildrenReplyError) VDLReflect(vdlGlobChildrenReplyReflect)

func (GlobChildrenReplyError) VDLWrite

func (x GlobChildrenReplyError) VDLWrite(enc vdl.Encoder) error

type GlobChildrenReplyName

type GlobChildrenReplyName struct{ Value string }

GlobChildrenReplyName represents field Name of the GlobChildrenReply union type.

func (GlobChildrenReplyName) Index

func (x GlobChildrenReplyName) Index() int

func (GlobChildrenReplyName) Interface

func (x GlobChildrenReplyName) Interface() interface{}

func (GlobChildrenReplyName) Name

func (x GlobChildrenReplyName) Name() string

func (GlobChildrenReplyName) VDLIsZero

func (x GlobChildrenReplyName) VDLIsZero() bool

func (GlobChildrenReplyName) VDLReflect

func (x GlobChildrenReplyName) VDLReflect(vdlGlobChildrenReplyReflect)

func (GlobChildrenReplyName) VDLWrite

func (x GlobChildrenReplyName) VDLWrite(enc vdl.Encoder) error

type GlobError

type GlobError struct {
	// Root of the subtree.
	Name string
	// The error that occurred fulfilling the request.
	Error error
}

GlobError is returned by namespace.Glob to indicate a subtree of the namespace that could not be traversed.

func (GlobError) VDLIsZero

func (x GlobError) VDLIsZero() bool

func (*GlobError) VDLRead

func (x *GlobError) VDLRead(dec vdl.Decoder) error

func (GlobError) VDLReflect

func (GlobError) VDLReflect(struct {
	Name string `vdl:"v.io/v23/naming.GlobError"`
})

func (GlobError) VDLWrite

func (x GlobError) VDLWrite(enc vdl.Encoder) error

type GlobReply

type GlobReply interface {
	// Index returns the field index.
	Index() int
	// Interface returns the field value as an interface.
	Interface() interface{}
	// Name returns the field name.
	Name() string
	// VDLReflect describes the GlobReply union type.
	VDLReflect(vdlGlobReplyReflect)
	VDLIsZero() bool
	VDLWrite(vdl.Encoder) error
}

GlobReply represents any single field of the GlobReply union type.

GlobReply is the data type returned by Glob__.

type GlobReplyEntry

type GlobReplyEntry struct{ Value MountEntry }

GlobReplyEntry represents field Entry of the GlobReply union type.

func (GlobReplyEntry) Index

func (x GlobReplyEntry) Index() int

func (GlobReplyEntry) Interface

func (x GlobReplyEntry) Interface() interface{}

func (GlobReplyEntry) Name

func (x GlobReplyEntry) Name() string

func (GlobReplyEntry) VDLIsZero

func (x GlobReplyEntry) VDLIsZero() bool

func (GlobReplyEntry) VDLReflect

func (x GlobReplyEntry) VDLReflect(vdlGlobReplyReflect)

func (GlobReplyEntry) VDLWrite

func (x GlobReplyEntry) VDLWrite(enc vdl.Encoder) error

type GlobReplyError

type GlobReplyError struct{ Value GlobError }

GlobReplyError represents field Error of the GlobReply union type.

func (GlobReplyError) Index

func (x GlobReplyError) Index() int

func (GlobReplyError) Interface

func (x GlobReplyError) Interface() interface{}

func (GlobReplyError) Name

func (x GlobReplyError) Name() string

func (GlobReplyError) VDLIsZero

func (x GlobReplyError) VDLIsZero() bool

func (GlobReplyError) VDLReflect

func (x GlobReplyError) VDLReflect(vdlGlobReplyReflect)

func (GlobReplyError) VDLWrite

func (x GlobReplyError) VDLWrite(enc vdl.Encoder) error

type IsLeaf

type IsLeaf bool

IsLeaf means the target is a leaf

func (IsLeaf) NSOpt

func (IsLeaf) NSOpt()

type MountEntry

type MountEntry struct {
	// Name is the mounted name.
	Name string
	// Servers (if present) specifies the mounted names.
	Servers []MountedServer
	// ServesMountTable is true if the servers represent mount tables.
	ServesMountTable bool
	// IsLeaf is true if this entry represents a leaf object.
	IsLeaf bool
}

MountEntry represents a given name mounted in the mounttable.

func (*MountEntry) Names

func (e *MountEntry) Names() []string

Names returns the servers represented by MountEntry as names, including the MountedName suffix.

func (MountEntry) VDLIsZero

func (x MountEntry) VDLIsZero() bool

func (*MountEntry) VDLRead

func (x *MountEntry) VDLRead(dec vdl.Decoder) error

func (MountEntry) VDLReflect

func (MountEntry) VDLReflect(struct {
	Name string `vdl:"v.io/v23/naming.MountEntry"`
})

func (MountEntry) VDLWrite

func (x MountEntry) VDLWrite(enc vdl.Encoder) error

type MountFlag

type MountFlag uint32

MountFlag is a bit mask of options to the mount call.

func (MountFlag) VDLIsZero

func (x MountFlag) VDLIsZero() bool

func (*MountFlag) VDLRead

func (x *MountFlag) VDLRead(dec vdl.Decoder) error

func (MountFlag) VDLReflect

func (MountFlag) VDLReflect(struct {
	Name string `vdl:"v.io/v23/naming.MountFlag"`
})

func (MountFlag) VDLWrite

func (x MountFlag) VDLWrite(enc vdl.Encoder) error

type MountedServer

type MountedServer struct {
	// Server is the OA that's mounted.
	Server string
	// Deadline before the mount entry expires.
	Deadline vdltime.Deadline
}

MountedServer represents a server mounted on a specific name.

func (MountedServer) VDLIsZero

func (x MountedServer) VDLIsZero() bool

func (*MountedServer) VDLRead

func (x *MountedServer) VDLRead(dec vdl.Decoder) error

func (MountedServer) VDLReflect

func (MountedServer) VDLReflect(struct {
	Name string `vdl:"v.io/v23/naming.MountedServer"`
})

func (MountedServer) VDLWrite

func (x MountedServer) VDLWrite(enc vdl.Encoder) error

type NamespaceOpt

type NamespaceOpt interface {
	NSOpt()
}

NamespaceOpt is the interface for all Namespace options.

type ReplaceMount

type ReplaceMount bool

ReplaceMount requests the mount to replace the previous mount.

func (ReplaceMount) NSOpt

func (ReplaceMount) NSOpt()

type RouteOpt

type RouteOpt string

RouteOpt is used to add a route to the endpoint.

func (RouteOpt) EndpointOpt

func (RouteOpt) EndpointOpt()

type RoutingID

type RoutingID struct {
	// contains filtered or unexported fields
}

RoutingIDs have one essential property, namely that they are, to a very high probability globally unique. Global uniqueness is required in order to support comparing Endpoints for equality; this is required for sharing connections, for proxying (though global uniqueness is not strictly required) and determining if different names resolve to the same endpoint.

func FixedRoutingID

func FixedRoutingID(i uint64) RoutingID

FixedRoutingID returns a routing ID from a constant.

func NewRoutingID

func NewRoutingID() (RoutingID, error)

func ReadRoutingID

func ReadRoutingID(reader io.Reader) (RoutingID, error)

Read a RoutingID from an io.Reader.

func (RoutingID) EndpointOpt

func (RoutingID) EndpointOpt()

Implement EndpointOpt so that RoutingID can be passed as an optional argument to FormatEndpoint

func (*RoutingID) FromString

func (rid *RoutingID) FromString(s string) error

FromString reads an RoutingID from a hex encoded string. If the argument string is of zero length the RoutingID will be set to NullRoutingID

func (RoutingID) IsReserved

func (rid RoutingID) IsReserved() bool

IsReserved() returns true iff the RoutingID is in the reserved range.

func (RoutingID) String

func (rid RoutingID) String() string

String returns a print representation of the RoutingID.

func (RoutingID) Write

func (rid RoutingID) Write(writer io.Writer) error

Write a RoutingID to an io.Writer.

type ServesMountTable

type ServesMountTable bool

ServesMountTable means the target is a mount table.

func (ServesMountTable) EndpointOpt

func (ServesMountTable) EndpointOpt()

func (ServesMountTable) NSOpt

func (ServesMountTable) NSOpt()