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 ¶
- Constants
- Variables
- func Clean(name string) string
- func Compare(a, b RoutingID) bool
- func DecodeFromNameElement(s string) (string, bool)
- func EncodeAsNameElement(s string) string
- func Escape(s, special string) string
- func FormatEndpoint(network, address string, opts ...EndpointOpt) string
- func IsReserved(name string) bool
- func Join(elems ...string) string
- func JoinAddressName(address, name string) string
- func Rooted(name string) bool
- func SplitAddressName(name string) (string, string)
- func StripReserved(name string) string
- func TrimSuffix(name, suffix string) string
- func Unescape(s string) (string, bool)
- func VDLReadGlobChildrenReply(dec vdl.Decoder, x *GlobChildrenReply) error
- func VDLReadGlobReply(dec vdl.Decoder, x *GlobReply) error
- type BlessingOpt
- type CacheCtl
- type DisableCache
- type Endpoint
- type EndpointOpt
- type GlobChildrenReply
- type GlobChildrenReplyError
- func (m GlobChildrenReplyError) FillVDLTarget(t vdl.Target, tt *vdl.Type) error
- func (x GlobChildrenReplyError) Index() int
- func (x GlobChildrenReplyError) Interface() interface{}
- func (m GlobChildrenReplyError) MakeVDLTarget() vdl.Target
- func (x GlobChildrenReplyError) Name() string
- func (x GlobChildrenReplyError) VDLIsZero() bool
- func (x GlobChildrenReplyError) VDLWrite(enc vdl.Encoder) error
- type GlobChildrenReplyName
- func (m GlobChildrenReplyName) FillVDLTarget(t vdl.Target, tt *vdl.Type) error
- func (x GlobChildrenReplyName) Index() int
- func (x GlobChildrenReplyName) Interface() interface{}
- func (m GlobChildrenReplyName) MakeVDLTarget() vdl.Target
- func (x GlobChildrenReplyName) Name() string
- func (x GlobChildrenReplyName) VDLIsZero() bool
- func (x GlobChildrenReplyName) VDLWrite(enc vdl.Encoder) error
- type GlobChildrenReplyTarget
- func (t *GlobChildrenReplyTarget) FinishField(_, fieldTarget vdl.Target) error
- func (t *GlobChildrenReplyTarget) FinishFields(_ vdl.FieldsTarget) error
- func (t *GlobChildrenReplyTarget) StartField(name string) (key, field vdl.Target, _ error)
- func (t *GlobChildrenReplyTarget) StartFields(tt *vdl.Type) (vdl.FieldsTarget, error)
- type GlobError
- type GlobErrorTarget
- func (t *GlobErrorTarget) FinishField(_, _ vdl.Target) error
- func (t *GlobErrorTarget) FinishFields(_ vdl.FieldsTarget) error
- func (t *GlobErrorTarget) StartField(name string) (key, field vdl.Target, _ error)
- func (t *GlobErrorTarget) StartFields(tt *vdl.Type) (vdl.FieldsTarget, error)
- func (t *GlobErrorTarget) ZeroField(name string) error
- type GlobReply
- type GlobReplyEntry
- func (m GlobReplyEntry) FillVDLTarget(t vdl.Target, tt *vdl.Type) error
- func (x GlobReplyEntry) Index() int
- func (x GlobReplyEntry) Interface() interface{}
- func (m GlobReplyEntry) MakeVDLTarget() vdl.Target
- func (x GlobReplyEntry) Name() string
- func (x GlobReplyEntry) VDLIsZero() bool
- func (x GlobReplyEntry) VDLWrite(enc vdl.Encoder) error
- type GlobReplyError
- func (m GlobReplyError) FillVDLTarget(t vdl.Target, tt *vdl.Type) error
- func (x GlobReplyError) Index() int
- func (x GlobReplyError) Interface() interface{}
- func (m GlobReplyError) MakeVDLTarget() vdl.Target
- func (x GlobReplyError) Name() string
- func (x GlobReplyError) VDLIsZero() bool
- func (x GlobReplyError) VDLWrite(enc vdl.Encoder) error
- type GlobReplyTarget
- type IsLeaf
- type MountEntry
- type MountEntryTarget
- func (t *MountEntryTarget) FinishField(_, _ vdl.Target) error
- func (t *MountEntryTarget) FinishFields(_ vdl.FieldsTarget) error
- func (t *MountEntryTarget) StartField(name string) (key, field vdl.Target, _ error)
- func (t *MountEntryTarget) StartFields(tt *vdl.Type) (vdl.FieldsTarget, error)
- func (t *MountEntryTarget) ZeroField(name string) error
- type MountFlag
- type MountFlagTarget
- type MountedServer
- type MountedServerTarget
- func (t *MountedServerTarget) FinishField(_, _ vdl.Target) error
- func (t *MountedServerTarget) FinishFields(_ vdl.FieldsTarget) error
- func (t *MountedServerTarget) StartField(name string) (key, field vdl.Target, _ error)
- func (t *MountedServerTarget) StartFields(tt *vdl.Type) (vdl.FieldsTarget, error)
- func (t *MountedServerTarget) ZeroField(name string) error
- type NamespaceOpt
- type ReplaceMount
- type RouteOpt
- type RoutingID
- type ServesMountTable
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.Register(pkgPath+".nameExists", verror.NoRetry, "{1} {2} Name exists {_}") ErrNoSuchName = verror.Register(pkgPath+".nameDoesntExist", verror.NoRetry, "{1} {2} Name {3} doesn't exist {_}") ErrNoSuchNameRoot = verror.Register(pkgPath+".rootNameDoesntExist", verror.NoRetry, "{1} {2} Namespace root name {3} doesn't exist {_}") ErrResolutionDepthExceeded = verror.Register(pkgPath+".resolutionDepthExceeded", verror.NoRetry, "{1} {2} Resolution depth exceeded {_}") ErrNoMountTable = verror.Register(pkgPath+".noMounttable", verror.NoRetry, "{1} {2} No mounttable {_}") )
var ( // NullRoutingID is a special value representing the nil route. NullRoutingID = FixedRoutingID(0) )
Functions ¶
func Clean ¶
Clean reduces multiple adjacent slashes to a single slash. It also removes any trailing slash.
func DecodeFromNameElement ¶
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 ¶
EncodeAsNameElement makes a string representable as a name element by escaping slashes.
func Escape ¶
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 ¶
IsReserved returns true if name is a reserved name.
func Join ¶
Join takes a variable number of name fragments and concatenates them together using '/'. The returned name is cleaned of multiple adjacent '/'s.
func JoinAddressName ¶
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 ¶
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 ¶
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 ¶
StripReserved returns the name stripped of the reserved prefix.
func TrimSuffix ¶
TrimSuffix removes the suffix (and any connecting '/') from the name.
func Unescape ¶
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
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 interface { // Network returns "v23" so that Endpoint can implement net.Addr. Network() string // String returns a string representation of the endpoint. // // The String method formats the endpoint as: // @<version>@<version specific fields>@@ // Where version is an unsigned integer. // // Version 6 is the current version for RPC: // @6@<protocol>@<address>@<route>[,<route>]...@<routingid>@m|s@[<blessing>[,<blessing>]...]@@ // // Along with Network, this method ensures that Endpoint implements net.Addr. String() string // Name returns a string reprsentation of this Endpoint that can // be used as a name with rpc.StartCall. Name() string // VersionedString returns a string in the specified format. If the version // number is unsupported, the current 'default' version will be used. VersionedString(version int) string // RoutingID returns the RoutingID associated with this Endpoint. RoutingID() RoutingID // Routes returns the local routing identifiers used for proxying connections // with multiple proxies. Routes() []string // Addrs 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. Addr() net.Addr // ServesMountTable returns true if this endpoint serves a mount table. ServesMountTable() bool // ServesLeaf returns true if this endpoint serves a leaf server. ServesLeaf() bool // BlessingNames returns the blessings that the process associated with // this Endpoint will present. BlessingNames() []string }
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.
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 FillVDLTarget(vdl.Target, *vdl.Type) error VDLIsZero() bool VDLWrite(vdl.Encoder) error // contains filtered or unexported methods }
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) FillVDLTarget ¶
func (GlobChildrenReplyError) Index ¶
func (x GlobChildrenReplyError) Index() int
func (GlobChildrenReplyError) Interface ¶
func (x GlobChildrenReplyError) Interface() interface{}
func (GlobChildrenReplyError) MakeVDLTarget ¶
func (m GlobChildrenReplyError) MakeVDLTarget() vdl.Target
func (GlobChildrenReplyError) Name ¶
func (x GlobChildrenReplyError) Name() string
func (GlobChildrenReplyError) VDLIsZero ¶
func (x GlobChildrenReplyError) VDLIsZero() bool
type GlobChildrenReplyName ¶
type GlobChildrenReplyName struct{ Value string }
GlobChildrenReplyName represents field Name of the GlobChildrenReply union type.
func (GlobChildrenReplyName) FillVDLTarget ¶
func (GlobChildrenReplyName) Index ¶
func (x GlobChildrenReplyName) Index() int
func (GlobChildrenReplyName) Interface ¶
func (x GlobChildrenReplyName) Interface() interface{}
func (GlobChildrenReplyName) MakeVDLTarget ¶
func (m GlobChildrenReplyName) MakeVDLTarget() vdl.Target
func (GlobChildrenReplyName) Name ¶
func (x GlobChildrenReplyName) Name() string
func (GlobChildrenReplyName) VDLIsZero ¶
func (x GlobChildrenReplyName) VDLIsZero() bool
type GlobChildrenReplyTarget ¶
type GlobChildrenReplyTarget struct { Value *GlobChildrenReply vdl.TargetBase vdl.FieldsTargetBase // contains filtered or unexported fields }
func (*GlobChildrenReplyTarget) FinishField ¶
func (t *GlobChildrenReplyTarget) FinishField(_, fieldTarget vdl.Target) error
func (*GlobChildrenReplyTarget) FinishFields ¶
func (t *GlobChildrenReplyTarget) FinishFields(_ vdl.FieldsTarget) error
func (*GlobChildrenReplyTarget) StartField ¶
func (t *GlobChildrenReplyTarget) StartField(name string) (key, field vdl.Target, _ error)
func (*GlobChildrenReplyTarget) StartFields ¶
func (t *GlobChildrenReplyTarget) StartFields(tt *vdl.Type) (vdl.FieldsTarget, 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) FillVDLTarget ¶
func (*GlobError) MakeVDLTarget ¶
type GlobErrorTarget ¶
type GlobErrorTarget struct { Value *GlobError vdl.TargetBase vdl.FieldsTargetBase // contains filtered or unexported fields }
func (*GlobErrorTarget) FinishField ¶
func (t *GlobErrorTarget) FinishField(_, _ vdl.Target) error
func (*GlobErrorTarget) FinishFields ¶
func (t *GlobErrorTarget) FinishFields(_ vdl.FieldsTarget) error
func (*GlobErrorTarget) StartField ¶
func (t *GlobErrorTarget) StartField(name string) (key, field vdl.Target, _ error)
func (*GlobErrorTarget) StartFields ¶
func (t *GlobErrorTarget) StartFields(tt *vdl.Type) (vdl.FieldsTarget, error)
func (*GlobErrorTarget) ZeroField ¶
func (t *GlobErrorTarget) ZeroField(name string) 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 FillVDLTarget(vdl.Target, *vdl.Type) error VDLIsZero() bool VDLWrite(vdl.Encoder) error // contains filtered or unexported methods }
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) FillVDLTarget ¶
func (GlobReplyEntry) Index ¶
func (x GlobReplyEntry) Index() int
func (GlobReplyEntry) Interface ¶
func (x GlobReplyEntry) Interface() interface{}
func (GlobReplyEntry) MakeVDLTarget ¶
func (m GlobReplyEntry) MakeVDLTarget() vdl.Target
func (GlobReplyEntry) Name ¶
func (x GlobReplyEntry) Name() string
func (GlobReplyEntry) VDLIsZero ¶
func (x GlobReplyEntry) VDLIsZero() bool
type GlobReplyError ¶
type GlobReplyError struct{ Value GlobError }
GlobReplyError represents field Error of the GlobReply union type.
func (GlobReplyError) FillVDLTarget ¶
func (GlobReplyError) Index ¶
func (x GlobReplyError) Index() int
func (GlobReplyError) Interface ¶
func (x GlobReplyError) Interface() interface{}
func (GlobReplyError) MakeVDLTarget ¶
func (m GlobReplyError) MakeVDLTarget() vdl.Target
func (GlobReplyError) Name ¶
func (x GlobReplyError) Name() string
func (GlobReplyError) VDLIsZero ¶
func (x GlobReplyError) VDLIsZero() bool
type GlobReplyTarget ¶
type GlobReplyTarget struct { Value *GlobReply vdl.TargetBase vdl.FieldsTargetBase // contains filtered or unexported fields }
func (*GlobReplyTarget) FinishField ¶
func (t *GlobReplyTarget) FinishField(_, fieldTarget vdl.Target) error
func (*GlobReplyTarget) FinishFields ¶
func (t *GlobReplyTarget) FinishFields(_ vdl.FieldsTarget) error
func (*GlobReplyTarget) StartField ¶
func (t *GlobReplyTarget) StartField(name string) (key, field vdl.Target, _ error)
func (*GlobReplyTarget) StartFields ¶
func (t *GlobReplyTarget) StartFields(tt *vdl.Type) (vdl.FieldsTarget, error)
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) FillVDLTarget ¶
func (*MountEntry) MakeVDLTarget ¶
func (m *MountEntry) MakeVDLTarget() vdl.Target
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
type MountEntryTarget ¶
type MountEntryTarget struct { Value *MountEntry vdl.TargetBase vdl.FieldsTargetBase // contains filtered or unexported fields }
func (*MountEntryTarget) FinishField ¶
func (t *MountEntryTarget) FinishField(_, _ vdl.Target) error
func (*MountEntryTarget) FinishFields ¶
func (t *MountEntryTarget) FinishFields(_ vdl.FieldsTarget) error
func (*MountEntryTarget) StartField ¶
func (t *MountEntryTarget) StartField(name string) (key, field vdl.Target, _ error)
func (*MountEntryTarget) StartFields ¶
func (t *MountEntryTarget) StartFields(tt *vdl.Type) (vdl.FieldsTarget, error)
func (*MountEntryTarget) ZeroField ¶
func (t *MountEntryTarget) ZeroField(name string) error
type MountFlag ¶
type MountFlag uint32
MountFlag is a bit mask of options to the mount call.
func (*MountFlag) FillVDLTarget ¶
func (*MountFlag) MakeVDLTarget ¶
type MountFlagTarget ¶
type MountFlagTarget struct { Value *MountFlag vdl.TargetBase }
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) FillVDLTarget ¶
func (*MountedServer) MakeVDLTarget ¶
func (m *MountedServer) MakeVDLTarget() vdl.Target
func (MountedServer) VDLIsZero ¶
func (x MountedServer) VDLIsZero() bool
type MountedServerTarget ¶
type MountedServerTarget struct { Value *MountedServer vdl.TargetBase vdl.FieldsTargetBase // contains filtered or unexported fields }
func (*MountedServerTarget) FinishField ¶
func (t *MountedServerTarget) FinishField(_, _ vdl.Target) error
func (*MountedServerTarget) FinishFields ¶
func (t *MountedServerTarget) FinishFields(_ vdl.FieldsTarget) error
func (*MountedServerTarget) StartField ¶
func (t *MountedServerTarget) StartField(name string) (key, field vdl.Target, _ error)
func (*MountedServerTarget) StartFields ¶
func (t *MountedServerTarget) StartFields(tt *vdl.Type) (vdl.FieldsTarget, error)
func (*MountedServerTarget) ZeroField ¶
func (t *MountedServerTarget) ZeroField(name string) 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 ¶
FixedRoutingID returns a routing ID from a constant.
func NewRoutingID ¶
func ReadRoutingID ¶
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 ¶
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 ¶
IsReserved() returns true iff the RoutingID is in the reserved range.
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()