v.io: v.io/v23/naming Index | Examples | Files

package naming

import "v.io/v23/naming"

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.

nolint:golint

Index

Examples

Package Files

doc.go endpoint.go model.go naming.vdl.go parse.go routingid.go util.go

Constants

const Leaf = MountFlag(4) // Leaf means that the target server is a leaf.
const MT = MountFlag(2) // MT means that the target server is a mount table.
const Replace = MountFlag(1) // Replace means the mount should replace what is currently at the mount point
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.

const (
    UnknownProtocol = ""
)

Variables

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

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

func Clean Uses

func Clean(name string) string

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

func Compare Uses

func Compare(a, b RoutingID) bool

func DecodeFromNameElement Uses

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 Uses

func EncodeAsNameElement(s string) string

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

func Escape Uses

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 Uses

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 Uses

func IsReserved(name string) bool

IsReserved returns true if name is a reserved name.

func Join Uses

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 Uses

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 Uses

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 Uses

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 Uses

func StripReserved(name string) string

StripReserved returns the name stripped of the reserved prefix.

func TrimSuffix Uses

func TrimSuffix(name, suffix string) string

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

func Unescape Uses

func Unescape(s string) (string, bool)

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

func VDLReadGlobChildrenReply Uses

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

func VDLReadGlobReply Uses

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

type BlessingOpt Uses

type BlessingOpt string

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

func (BlessingOpt) EndpointOpt Uses

func (BlessingOpt) EndpointOpt()

type CacheCtl Uses

type CacheCtl interface {
    CacheCtl()
}

CacheCtl is a cache control for the resolution cache.

type DisableCache Uses

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 Uses

func (DisableCache) CacheCtl()

type Endpoint Uses

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.

Code:

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

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 Uses

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 Uses

func (e Endpoint) BlessingNames() []string

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

func (Endpoint) IsZero Uses

func (e Endpoint) IsZero() bool

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

func (Endpoint) Name Uses

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 Uses

func (e Endpoint) Routes() []string

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

func (Endpoint) String Uses

func (e Endpoint) String() string

func (Endpoint) VersionedString Uses

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 Uses

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 Uses

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

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

type EndpointOpt Uses

type EndpointOpt interface {
    EndpointOpt()
}

EndpointOpt must be implemented by all optional parameters to FormatEndpoint

type GlobChildrenReply Uses

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 Uses

type GlobChildrenReplyError struct{ Value GlobError }

GlobChildrenReplyError represents field Error of the GlobChildrenReply union type.

func (GlobChildrenReplyError) Index Uses

func (x GlobChildrenReplyError) Index() int

func (GlobChildrenReplyError) Interface Uses

func (x GlobChildrenReplyError) Interface() interface{}

func (GlobChildrenReplyError) Name Uses

func (x GlobChildrenReplyError) Name() string

func (GlobChildrenReplyError) VDLIsZero Uses

func (x GlobChildrenReplyError) VDLIsZero() bool

func (GlobChildrenReplyError) VDLReflect Uses

func (x GlobChildrenReplyError) VDLReflect(vdlGlobChildrenReplyReflect)

func (GlobChildrenReplyError) VDLWrite Uses

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

type GlobChildrenReplyName Uses

type GlobChildrenReplyName struct{ Value string }

GlobChildrenReplyName represents field Name of the GlobChildrenReply union type.

func (GlobChildrenReplyName) Index Uses

func (x GlobChildrenReplyName) Index() int

func (GlobChildrenReplyName) Interface Uses

func (x GlobChildrenReplyName) Interface() interface{}

func (GlobChildrenReplyName) Name Uses

func (x GlobChildrenReplyName) Name() string

func (GlobChildrenReplyName) VDLIsZero Uses

func (x GlobChildrenReplyName) VDLIsZero() bool

func (GlobChildrenReplyName) VDLReflect Uses

func (x GlobChildrenReplyName) VDLReflect(vdlGlobChildrenReplyReflect)

func (GlobChildrenReplyName) VDLWrite Uses

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

type GlobError Uses

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 Uses

func (x GlobError) VDLIsZero() bool

func (*GlobError) VDLRead Uses

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

func (GlobError) VDLReflect Uses

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

func (GlobError) VDLWrite Uses

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

type GlobReply Uses

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 Uses

type GlobReplyEntry struct{ Value MountEntry }

GlobReplyEntry represents field Entry of the GlobReply union type.

func (GlobReplyEntry) Index Uses

func (x GlobReplyEntry) Index() int

func (GlobReplyEntry) Interface Uses

func (x GlobReplyEntry) Interface() interface{}

func (GlobReplyEntry) Name Uses

func (x GlobReplyEntry) Name() string

func (GlobReplyEntry) VDLIsZero Uses

func (x GlobReplyEntry) VDLIsZero() bool

func (GlobReplyEntry) VDLReflect Uses

func (x GlobReplyEntry) VDLReflect(vdlGlobReplyReflect)

func (GlobReplyEntry) VDLWrite Uses

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

type GlobReplyError Uses

type GlobReplyError struct{ Value GlobError }

GlobReplyError represents field Error of the GlobReply union type.

func (GlobReplyError) Index Uses

func (x GlobReplyError) Index() int

func (GlobReplyError) Interface Uses

func (x GlobReplyError) Interface() interface{}

func (GlobReplyError) Name Uses

func (x GlobReplyError) Name() string

func (GlobReplyError) VDLIsZero Uses

func (x GlobReplyError) VDLIsZero() bool

func (GlobReplyError) VDLReflect Uses

func (x GlobReplyError) VDLReflect(vdlGlobReplyReflect)

func (GlobReplyError) VDLWrite Uses

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

type IsLeaf Uses

type IsLeaf bool

IsLeaf means the target is a leaf

func (IsLeaf) NSOpt Uses

func (IsLeaf) NSOpt()

type MountEntry Uses

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 Uses

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

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

func (MountEntry) VDLIsZero Uses

func (x MountEntry) VDLIsZero() bool

func (*MountEntry) VDLRead Uses

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

func (MountEntry) VDLReflect Uses

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

func (MountEntry) VDLWrite Uses

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

type MountFlag Uses

type MountFlag uint32

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

func (MountFlag) VDLIsZero Uses

func (x MountFlag) VDLIsZero() bool

func (*MountFlag) VDLRead Uses

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

func (MountFlag) VDLReflect Uses

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

func (MountFlag) VDLWrite Uses

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

type MountedServer Uses

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 Uses

func (x MountedServer) VDLIsZero() bool

func (*MountedServer) VDLRead Uses

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

func (MountedServer) VDLReflect Uses

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

func (MountedServer) VDLWrite Uses

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

type NamespaceOpt Uses

type NamespaceOpt interface {
    NSOpt()
}

NamespaceOpt is the interface for all Namespace options.

type ReplaceMount Uses

type ReplaceMount bool

ReplaceMount requests the mount to replace the previous mount.

func (ReplaceMount) NSOpt Uses

func (ReplaceMount) NSOpt()

type RouteOpt Uses

type RouteOpt string

RouteOpt is used to add a route to the endpoint.

func (RouteOpt) EndpointOpt Uses

func (RouteOpt) EndpointOpt()

type RoutingID Uses

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 Uses

func FixedRoutingID(i uint64) RoutingID

FixedRoutingID returns a routing ID from a constant.

func NewRoutingID Uses

func NewRoutingID() (RoutingID, error)

func ReadRoutingID Uses

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

Read a RoutingID from an io.Reader.

func (RoutingID) EndpointOpt Uses

func (RoutingID) EndpointOpt()

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

func (*RoutingID) FromString Uses

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 Uses

func (rid RoutingID) IsReserved() bool

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

func (RoutingID) String Uses

func (rid RoutingID) String() string

String returns a print representation of the RoutingID.

func (RoutingID) Write Uses

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

Write a RoutingID to an io.Writer.

type ServesMountTable Uses

type ServesMountTable bool

ServesMountTable means the target is a mount table.

func (ServesMountTable) EndpointOpt Uses

func (ServesMountTable) EndpointOpt()

func (ServesMountTable) NSOpt Uses

func (ServesMountTable) NSOpt()

Package naming imports 14 packages (graph) and is imported by 190 packages. Updated 2020-09-28. Refresh now. Tools for package owners.