v.io: v.io/x/ref/lib/discovery Index | Files | Directories

package discovery

import "v.io/x/ref/lib/discovery"

nolint:golint

Index

Package Files

advertise.go advertise_server.go barrier.go cipher.go directory.go discovery.go discovery.vdl.go encoding.go factory.go plugin.go query.go scan.go session.go trigger.go update.go util.go uuid.go validate.go

Constants

const AdNotReady = AdStatus(1) // Not all information is available for querying against it
const AdPartiallyReady = AdStatus(2) // All information except attachments is available
const AdReady = AdStatus(0) // All information is available
const IbeEncryption = EncryptionAlgorithm(2)
const NoEncryption = EncryptionAlgorithm(0)
const TestEncryption = EncryptionAlgorithm(1)

Variables

var (
    ErrAdvertisementNotFound  = verror.NewIDAction("v.io/x/ref/lib/discovery.AdvertisementNotFound", verror.NoRetry)
    ErrAlreadyBeingAdvertised = verror.NewIDAction("v.io/x/ref/lib/discovery.AlreadyBeingAdvertised", verror.NoRetry)
    ErrBadAdvertisement       = verror.NewIDAction("v.io/x/ref/lib/discovery.BadAdvertisement", verror.NoRetry)
    ErrBadQuery               = verror.NewIDAction("v.io/x/ref/lib/discovery.BadQuery", verror.NoRetry)
    ErrDiscoveryClosed        = verror.NewIDAction("v.io/x/ref/lib/discovery.DiscoveryClosed", verror.NoRetry)
    ErrNoDiscoveryPlugin      = verror.NewIDAction("v.io/x/ref/lib/discovery.NoDiscoveryPlugin", verror.NoRetry)
    ErrTooManyPlugins         = verror.NewIDAction("v.io/x/ref/lib/discovery.TooManyPlugins", verror.NoRetry)
)
var DirectoryDesc rpc.InterfaceDesc = descDirectory

DirectoryDesc describes the Directory interface.

func AdvertiseServer Uses

func AdvertiseServer(ctx *context.T, d discovery.T, server rpc.Server, suffix string, ad *discovery.Advertisement, visibility []security.BlessingPattern) (<-chan struct{}, error)

AdvertiseServer advertises the server with the given advertisement. It uses the server's endpoints and the given suffix as the advertisement addresses, and the addresses will be updated automatically when the underlying network are changed.

The advertisement should not be changed while it is being advertised.

Advertising will continue until the context is canceled or exceeds its deadline and the returned channel will be closed when it stops.

If a discovery instance is not provided, this will create a new one.

func DecodeTimestamp Uses

func DecodeTimestamp(data []byte) (int64, error)

DecodeTimestamp decodes the timestamp from a 8-byte byte slice.

func DecodeWireCiphertext Uses

func DecodeWireCiphertext(data []byte) (*bcrypter.WireCiphertext, error)

DecodeCiphertext decodes the cipher text from a byte slice.

func EncodeTimestamp Uses

func EncodeTimestamp(ts int64) []byte

EncodeTimestamp encodes the timestamp into a 8-byte byte slice.

func EncodeWireCiphertext Uses

func EncodeWireCiphertext(wctext *bcrypter.WireCiphertext) []byte

EncodeCiphertext encodes the cipher text into a byte slice.

func ErrorfAdvertisementNotFound Uses

func ErrorfAdvertisementNotFound(ctx *context.T, format string, id discovery.AdId) error

ErrorfAdvertisementNotFound calls ErrAdvertisementNotFound.Errorf with the supplied arguments.

func ErrorfAlreadyBeingAdvertised Uses

func ErrorfAlreadyBeingAdvertised(ctx *context.T, format string, id discovery.AdId) error

ErrorfAlreadyBeingAdvertised calls ErrAlreadyBeingAdvertised.Errorf with the supplied arguments.

func ErrorfBadAdvertisement Uses

func ErrorfBadAdvertisement(ctx *context.T, format string, err error) error

ErrorfBadAdvertisement calls ErrBadAdvertisement.Errorf with the supplied arguments.

func ErrorfBadQuery Uses

func ErrorfBadQuery(ctx *context.T, format string, err error) error

ErrorfBadQuery calls ErrBadQuery.Errorf with the supplied arguments.

func ErrorfDiscoveryClosed Uses

func ErrorfDiscoveryClosed(ctx *context.T, format string) error

ErrorfDiscoveryClosed calls ErrDiscoveryClosed.Errorf with the supplied arguments.

func ErrorfNoDiscoveryPlugin Uses

func ErrorfNoDiscoveryPlugin(ctx *context.T, format string) error

ErrorfNoDiscoveryPlugin calls ErrNoDiscoveryPlugin.Errorf with the supplied arguments.

func ErrorfTooManyPlugins Uses

func ErrorfTooManyPlugins(ctx *context.T, format string, actual int32, limit int32) error

ErrorfTooManyPlugins calls ErrTooManyPlugins.Errorf with the supplied arguments.

func MessageAdvertisementNotFound Uses

func MessageAdvertisementNotFound(ctx *context.T, message string, id discovery.AdId) error

MessageAdvertisementNotFound calls ErrAdvertisementNotFound.Message with the supplied arguments.

func MessageAlreadyBeingAdvertised Uses

func MessageAlreadyBeingAdvertised(ctx *context.T, message string, id discovery.AdId) error

MessageAlreadyBeingAdvertised calls ErrAlreadyBeingAdvertised.Message with the supplied arguments.

func MessageBadAdvertisement Uses

func MessageBadAdvertisement(ctx *context.T, message string, err error) error

MessageBadAdvertisement calls ErrBadAdvertisement.Message with the supplied arguments.

func MessageBadQuery Uses

func MessageBadQuery(ctx *context.T, message string, err error) error

MessageBadQuery calls ErrBadQuery.Message with the supplied arguments.

func MessageDiscoveryClosed Uses

func MessageDiscoveryClosed(ctx *context.T, message string) error

MessageDiscoveryClosed calls ErrDiscoveryClosed.Message with the supplied arguments.

func MessageNoDiscoveryPlugin Uses

func MessageNoDiscoveryPlugin(ctx *context.T, message string) error

MessageNoDiscoveryPlugin calls ErrNoDiscoveryPlugin.Message with the supplied arguments.

func MessageTooManyPlugins Uses

func MessageTooManyPlugins(ctx *context.T, message string, actual int32, limit int32) error

MessageTooManyPlugins calls ErrTooManyPlugins.Message with the supplied arguments.

func NewErrAdvertisementNotFound Uses

func NewErrAdvertisementNotFound(ctx *context.T, id discovery.AdId) error

NewErrAdvertisementNotFound returns an error with the ErrAdvertisementNotFound ID. Deprecated: this function will be removed in the future, use ErrorfAdvertisementNotFound or MessageAdvertisementNotFound instead.

func NewErrAlreadyBeingAdvertised Uses

func NewErrAlreadyBeingAdvertised(ctx *context.T, id discovery.AdId) error

NewErrAlreadyBeingAdvertised returns an error with the ErrAlreadyBeingAdvertised ID. Deprecated: this function will be removed in the future, use ErrorfAlreadyBeingAdvertised or MessageAlreadyBeingAdvertised instead.

func NewErrBadAdvertisement Uses

func NewErrBadAdvertisement(ctx *context.T, err error) error

NewErrBadAdvertisement returns an error with the ErrBadAdvertisement ID. Deprecated: this function will be removed in the future, use ErrorfBadAdvertisement or MessageBadAdvertisement instead.

func NewErrBadQuery Uses

func NewErrBadQuery(ctx *context.T, err error) error

NewErrBadQuery returns an error with the ErrBadQuery ID. Deprecated: this function will be removed in the future, use ErrorfBadQuery or MessageBadQuery instead.

func NewErrDiscoveryClosed Uses

func NewErrDiscoveryClosed(ctx *context.T) error

NewErrDiscoveryClosed returns an error with the ErrDiscoveryClosed ID. Deprecated: this function will be removed in the future, use ErrorfDiscoveryClosed or MessageDiscoveryClosed instead.

func NewErrNoDiscoveryPlugin Uses

func NewErrNoDiscoveryPlugin(ctx *context.T) error

NewErrNoDiscoveryPlugin returns an error with the ErrNoDiscoveryPlugin ID. Deprecated: this function will be removed in the future, use ErrorfNoDiscoveryPlugin or MessageNoDiscoveryPlugin instead.

func NewErrTooManyPlugins Uses

func NewErrTooManyPlugins(ctx *context.T, actual int32, limit int32) error

NewErrTooManyPlugins returns an error with the ErrTooManyPlugins ID. Deprecated: this function will be removed in the future, use ErrorfTooManyPlugins or MessageTooManyPlugins instead.

func NewUpdate Uses

func NewUpdate(adinfo *AdInfo) discovery.Update

NewUpdate returns a new update with the given advertisement information.

func PackAddresses Uses

func PackAddresses(addrs []string) []byte

PackAddresses packs addresses into a byte slice.

func PackEncryptionKeys Uses

func PackEncryptionKeys(algo EncryptionAlgorithm, keys []EncryptionKey) []byte

PackEncryptionKeys packs encryption algorithm and keys into a byte slice.

func ParamsErrAdvertisementNotFound Uses

func ParamsErrAdvertisementNotFound(argumentError error) (verrorComponent string, verrorOperation string, id discovery.AdId, returnErr error)

ParamsErrAdvertisementNotFound extracts the expected parameters from the error's ParameterList.

func ParamsErrAlreadyBeingAdvertised Uses

func ParamsErrAlreadyBeingAdvertised(argumentError error) (verrorComponent string, verrorOperation string, id discovery.AdId, returnErr error)

ParamsErrAlreadyBeingAdvertised extracts the expected parameters from the error's ParameterList.

func ParamsErrBadAdvertisement Uses

func ParamsErrBadAdvertisement(argumentError error) (verrorComponent string, verrorOperation string, err error, returnErr error)

ParamsErrBadAdvertisement extracts the expected parameters from the error's ParameterList.

func ParamsErrBadQuery Uses

func ParamsErrBadQuery(argumentError error) (verrorComponent string, verrorOperation string, err error, returnErr error)

ParamsErrBadQuery extracts the expected parameters from the error's ParameterList.

func ParamsErrDiscoveryClosed Uses

func ParamsErrDiscoveryClosed(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

ParamsErrDiscoveryClosed extracts the expected parameters from the error's ParameterList.

func ParamsErrNoDiscoveryPlugin Uses

func ParamsErrNoDiscoveryPlugin(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

ParamsErrNoDiscoveryPlugin extracts the expected parameters from the error's ParameterList.

func ParamsErrTooManyPlugins Uses

func ParamsErrTooManyPlugins(argumentError error) (verrorComponent string, verrorOperation string, actual int32, limit int32, returnErr error)

ParamsErrTooManyPlugins extracts the expected parameters from the error's ParameterList.

func UnpackAddresses Uses

func UnpackAddresses(data []byte) ([]string, error)

UnpackAddresses unpacks addresses from a byte slice.

func UnpackEncryptionKeys Uses

func UnpackEncryptionKeys(data []byte) (EncryptionAlgorithm, []EncryptionKey, error)

UnpackEncryptionKeys unpacks encryption algorithm and keys from a byte slice.

type AdHash Uses

type AdHash [8]byte

An AdHash is a hash of an advertisement.

func (AdHash) VDLIsZero Uses

func (x AdHash) VDLIsZero() bool

func (*AdHash) VDLRead Uses

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

func (AdHash) VDLReflect Uses

func (AdHash) VDLReflect(struct {
    Name string `vdl:"v.io/x/ref/lib/discovery.AdHash"`
})

func (AdHash) VDLWrite Uses

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

type AdInfo Uses

type AdInfo struct {
    Ad  discovery.Advertisement
    // Type of encryption applied to the advertisement so that it can
    // only be decoded by authorized principals.
    EncryptionAlgorithm EncryptionAlgorithm
    // If the advertisement is encrypted, then the data required to
    // decrypt it. The format of this data is a function of the algorithm.
    EncryptionKeys []EncryptionKey
    // Hash of the current advertisement. This does not include the fields below.
    Hash AdHash
    // Unix time in nanoseconds at which the advertisement was created.
    TimestampNs int64
    // The addresses (vanadium object names) that the advertisement directory service
    // is served on. See directory.vdl.
    DirAddrs []string
    // Status of the current advertisement. Valid for scanned advertisements.
    Status AdStatus
    // TODO(jhahn): Add proximity.
    // TODO(jhahn): Use proximity for Lost.
    Lost bool
}

AdInfo represents advertisement information for discovery.

func (AdInfo) VDLIsZero Uses

func (x AdInfo) VDLIsZero() bool

func (*AdInfo) VDLRead Uses

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

func (AdInfo) VDLReflect Uses

func (AdInfo) VDLReflect(struct {
    Name string `vdl:"v.io/x/ref/lib/discovery.AdInfo"`
})

func (AdInfo) VDLWrite Uses

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

type AdStatus Uses

type AdStatus byte

func (AdStatus) VDLIsZero Uses

func (x AdStatus) VDLIsZero() bool

func (*AdStatus) VDLRead Uses

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

func (AdStatus) VDLReflect Uses

func (AdStatus) VDLReflect(struct {
    Name string `vdl:"v.io/x/ref/lib/discovery.AdStatus"`
})

func (AdStatus) VDLWrite Uses

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

type Barrier Uses

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

A Barrier is a simple incremental barrier that runs a done closure after all closures returned by Add() have been invoked. The done closure will run only once and run in a separate goroutine.

func NewBarrier Uses

func NewBarrier(done func()) *Barrier

func (*Barrier) Add Uses

func (b *Barrier) Add() func()

Add increments the barrier. Each closure returned by Add() should eventually be run once, otherwise 'done' will never be run. It returns no-op function if the done closure has been already called.

type DirectoryClientMethods Uses

type DirectoryClientMethods interface {
    // Lookup returns the advertisement of the given service instance.
    //
    // The returned advertisement may not include all attachments.
    Lookup(_ *context.T, id discovery.AdId, _ ...rpc.CallOpt) (AdInfo, error)
    // GetAttachment returns the named attachment. Accessing non-existent attachment
    // is not an error - nil data is returned if not found.
    //
    // TODO(jhahn): Consider to return an error if not found.
    GetAttachment(_ *context.T, id discovery.AdId, name string, _ ...rpc.CallOpt) ([]byte, error)
}

DirectoryClientMethods is the client interface containing Directory methods.

Directory is the interface for advertisement directory service.

type DirectoryClientStub Uses

type DirectoryClientStub interface {
    DirectoryClientMethods
}

DirectoryClientStub embeds DirectoryClientMethods and is a placeholder for additional management operations.

func DirectoryClient Uses

func DirectoryClient(name string) DirectoryClientStub

DirectoryClient returns a client stub for Directory.

type DirectoryServerMethods Uses

type DirectoryServerMethods interface {
    // Lookup returns the advertisement of the given service instance.
    //
    // The returned advertisement may not include all attachments.
    Lookup(_ *context.T, _ rpc.ServerCall, id discovery.AdId) (AdInfo, error)
    // GetAttachment returns the named attachment. Accessing non-existent attachment
    // is not an error - nil data is returned if not found.
    //
    // TODO(jhahn): Consider to return an error if not found.
    GetAttachment(_ *context.T, _ rpc.ServerCall, id discovery.AdId, name string) ([]byte, error)
}

DirectoryServerMethods is the interface a server writer implements for Directory.

Directory is the interface for advertisement directory service.

type DirectoryServerStub Uses

type DirectoryServerStub interface {
    DirectoryServerStubMethods
    // DescribeInterfaces the Directory interfaces.
    Describe__() []rpc.InterfaceDesc
}

DirectoryServerStub adds universal methods to DirectoryServerStubMethods.

func DirectoryServer Uses

func DirectoryServer(impl DirectoryServerMethods) DirectoryServerStub

DirectoryServer returns a server stub for Directory. It converts an implementation of DirectoryServerMethods into an object that may be used by rpc.Server.

type DirectoryServerStubMethods Uses

type DirectoryServerStubMethods DirectoryServerMethods

DirectoryServerStubMethods is the server interface containing Directory methods, as expected by rpc.Server. There is no difference between this interface and DirectoryServerMethods since there are no streaming methods.

type EncodingBuffer Uses

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

EncodingBuffer is used to encode and decode advertisements.

func NewEncodingBuffer Uses

func NewEncodingBuffer(data []byte) *EncodingBuffer

NewEncodingBuffer returns a new encoding buffer.

func (*EncodingBuffer) Bytes Uses

func (e *EncodingBuffer) Bytes() []byte

Bytes returns a byte slice holding the unread portion of the buffer.

func (*EncodingBuffer) Len Uses

func (e *EncodingBuffer) Len() int

Len returns the number of bytes of the unread portion of the buffer.

func (*EncodingBuffer) Next Uses

func (e *EncodingBuffer) Next(n int) []byte

Next returns a slice containing the next n bytes from the buffer. If there are fewer than n bytes in the buffer, it returns the entire buffer.

func (*EncodingBuffer) Read Uses

func (e *EncodingBuffer) Read(p []byte) error

Read reads the next len(p) bytes from the buffer. If the buffer has no enough data, io.EOF is returned.

func (*EncodingBuffer) ReadBytes Uses

func (e *EncodingBuffer) ReadBytes() ([]byte, error)

ReadBytes reads a byte slice with its length from the buffer.

func (*EncodingBuffer) ReadInt Uses

func (e *EncodingBuffer) ReadInt() (int, error)

ReadInt reads an integer from the buffer.

func (*EncodingBuffer) ReadString Uses

func (e *EncodingBuffer) ReadString() (string, error)

ReadString reads a string from the buffer.

func (*EncodingBuffer) Write Uses

func (e *EncodingBuffer) Write(p []byte)

Write appends a byte slice to the buffer.

func (*EncodingBuffer) WriteBytes Uses

func (e *EncodingBuffer) WriteBytes(p []byte)

WriteBytes appends a byte slice to the buffer with its length.

func (*EncodingBuffer) WriteInt Uses

func (e *EncodingBuffer) WriteInt(x int)

WriteInt appends an integer to the buffer.

func (*EncodingBuffer) WriteString Uses

func (e *EncodingBuffer) WriteString(s string)

WriteString appends a string to the buffer.

type EncryptionAlgorithm Uses

type EncryptionAlgorithm int32

func (EncryptionAlgorithm) VDLIsZero Uses

func (x EncryptionAlgorithm) VDLIsZero() bool

func (*EncryptionAlgorithm) VDLRead Uses

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

func (EncryptionAlgorithm) VDLReflect Uses

func (EncryptionAlgorithm) VDLReflect(struct {
    Name string `vdl:"v.io/x/ref/lib/discovery.EncryptionAlgorithm"`
})

func (EncryptionAlgorithm) VDLWrite Uses

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

type EncryptionKey Uses

type EncryptionKey []byte

func (EncryptionKey) VDLIsZero Uses

func (x EncryptionKey) VDLIsZero() bool

func (*EncryptionKey) VDLRead Uses

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

func (EncryptionKey) VDLReflect Uses

func (EncryptionKey) VDLReflect(struct {
    Name string `vdl:"v.io/x/ref/lib/discovery.EncryptionKey"`
})

func (EncryptionKey) VDLWrite Uses

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

type Factory Uses

type Factory interface {
    // New creates a new Discovery.T instance.
    New(*context.T) (discovery.T, error)

    // Shutdown closes all Discovery.T instances and shutdowns the factory.
    Shutdown()
}

Factory is the interface for creating a new discovery.T instance.

func NewFactory Uses

func NewFactory(ctx *context.T, plugins ...Plugin) (Factory, error)

NewFactory returns a new discovery factory with the given plugins.

For internal use only.

type Matcher Uses

type Matcher interface {
    // Match returns true if the matcher matches the advertisement.
    Match(ad *discovery.Advertisement) (bool, error)

    // TargetKey returns the key if a single key is being queried; otherwise
    // an empty string is returned.
    TargetKey() string

    // TargetInterfaceName returns the interface name if a single interface name
    // is being queried; otherwise an empty string is returned.
    TargetInterfaceName() string
}

Matcher is the interface for matching advertisements against a query.

func NewMatcher Uses

func NewMatcher(ctx *context.T, query string) (Matcher, error)

type Plugin Uses

type Plugin interface {
    // Advertise advertises the advertisement.
    //
    // The advertisement will not be changed while it is being advertised.
    //
    // If the advertisement is too large, the plugin may drop any information
    // except Id, InterfaceName, Hash, Timestamp, and DirAddrs.
    //
    // Advertising should continue until the context is canceled or exceeds
    // its deadline. done should be called once when advertising is done or
    // canceled.
    Advertise(ctx *context.T, adinfo *AdInfo, done func()) error

    // Scan scans advertisements that match the interface name and returns scanned
    // advertisements via the callback.
    //
    // An empty interface name means any advertisements.
    //
    // The callback takes ownership of the provided AdInfo, and the plugin
    // should not use the advertisement after invoking the callback.
    //
    // Scanning should continue until the context is canceled or exceeds its
    // deadline. done should be called once when scanning is done or canceled.
    Scan(ctx *context.T, interfaceName string, callback func(*AdInfo), done func()) error

    // Close closes the plugin.
    //
    // This will be called after all active tasks have been cancelled.
    Close()
}

Plugin is the basic interface for discovery plugins.

All implementation should be goroutine-safe.

type Trigger Uses

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

A Trigger is a simple multi-channel receiver. It triggers callbacks when it receives signals from the corresponding channels. Each callback will run only once and run in a separate goroutine.

func NewTrigger Uses

func NewTrigger() *Trigger

func (*Trigger) Add Uses

func (tr *Trigger) Add(callback func(), ch <-chan struct{})

Add enqueues callback to be invoked on the next event on ch.

func (*Trigger) Stop Uses

func (tr *Trigger) Stop()

Stop stops the trigger.

type Uuid Uses

type Uuid []byte

func NewAttributeUUID Uses

func NewAttributeUUID(name string) Uuid

NewAttributeUUID returns a version 5 UUID for the given name.

TODO(jhahn): rename to NewAttributeUuid.

func NewServiceUUID Uses

func NewServiceUUID(interfaceName string) Uuid

NewServiceUUID returns a version 5 UUID for the given interface name.

func (Uuid) String Uses

func (u Uuid) String() string

String returns the string form of uuid 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'.

func (Uuid) VDLIsZero Uses

func (x Uuid) VDLIsZero() bool

func (*Uuid) VDLRead Uses

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

func (Uuid) VDLReflect Uses

func (Uuid) VDLReflect(struct {
    Name string `vdl:"v.io/x/ref/lib/discovery.Uuid"`
})

func (Uuid) VDLWrite Uses

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

Directories

PathSynopsis
factory
globalTODO(jhahn): This is an experimental work to see its feasibility and set the long-term goal, and can be changed without notice.
plugins/mdnsPackage mdns implements mDNS plugin for discovery service.
plugins/mock
plugins/testutil
plugins/vinePackage vine contains a discovery plugin that is using Vine protocol.
testpackage test contains tests that rely on a fake runtime.
testutilPackage testutil defines helpers for discovery tests.

Package discovery imports 34 packages (graph) and is imported by 19 packages. Updated 2020-10-24. Refresh now. Tools for package owners.