naming

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 17, 2023 License: BSD-3-Clause Imports: 13 Imported by: 194

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.

This file was auto-generated by the vanadium vdl tool. Package: naming

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, the empty string, is used when a protocol is specified
	// in an Endpoint.
	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 a copy of 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 a copy of 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 routes, 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

Type definitions ================ 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()

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.