discovery

package
Version: v0.1.20 Latest Latest
Warning

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

Go to latest
Published: Sep 25, 2021 License: BSD-3-Clause Imports: 33 Imported by: 34

Documentation

Index

Constants

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

Variables

View Source
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)
)
View Source
var DirectoryDesc rpc.InterfaceDesc = descDirectory

DirectoryDesc describes the Directory interface.

Functions

func AdvertiseServer

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

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

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

func DecodeWireCiphertext

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

DecodeCiphertext decodes the cipher text from a byte slice.

func EncodeTimestamp

func EncodeTimestamp(ts int64) []byte

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

func EncodeWireCiphertext

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

EncodeCiphertext encodes the cipher text into a byte slice.

func ErrorfAdvertisementNotFound added in v0.1.10

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

ErrorfAdvertisementNotFound calls ErrAdvertisementNotFound.Errorf with the supplied arguments.

func ErrorfAlreadyBeingAdvertised added in v0.1.10

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

ErrorfAlreadyBeingAdvertised calls ErrAlreadyBeingAdvertised.Errorf with the supplied arguments.

func ErrorfBadAdvertisement added in v0.1.10

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

ErrorfBadAdvertisement calls ErrBadAdvertisement.Errorf with the supplied arguments.

func ErrorfBadQuery added in v0.1.10

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

ErrorfBadQuery calls ErrBadQuery.Errorf with the supplied arguments.

func ErrorfDiscoveryClosed added in v0.1.10

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

ErrorfDiscoveryClosed calls ErrDiscoveryClosed.Errorf with the supplied arguments.

func ErrorfNoDiscoveryPlugin added in v0.1.10

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

ErrorfNoDiscoveryPlugin calls ErrNoDiscoveryPlugin.Errorf with the supplied arguments.

func ErrorfTooManyPlugins added in v0.1.10

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

ErrorfTooManyPlugins calls ErrTooManyPlugins.Errorf with the supplied arguments.

func MessageAdvertisementNotFound added in v0.1.10

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

MessageAdvertisementNotFound calls ErrAdvertisementNotFound.Message with the supplied arguments.

func MessageAlreadyBeingAdvertised added in v0.1.10

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

MessageAlreadyBeingAdvertised calls ErrAlreadyBeingAdvertised.Message with the supplied arguments.

func MessageBadAdvertisement added in v0.1.10

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

MessageBadAdvertisement calls ErrBadAdvertisement.Message with the supplied arguments.

func MessageBadQuery added in v0.1.10

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

MessageBadQuery calls ErrBadQuery.Message with the supplied arguments.

func MessageDiscoveryClosed added in v0.1.10

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

MessageDiscoveryClosed calls ErrDiscoveryClosed.Message with the supplied arguments.

func MessageNoDiscoveryPlugin added in v0.1.10

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

MessageNoDiscoveryPlugin calls ErrNoDiscoveryPlugin.Message with the supplied arguments.

func MessageTooManyPlugins added in v0.1.10

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

MessageTooManyPlugins calls ErrTooManyPlugins.Message with the supplied arguments.

func NewUpdate

func NewUpdate(adinfo *AdInfo) discovery.Update

NewUpdate returns a new update with the given advertisement information.

func PackAddresses

func PackAddresses(addrs []string) []byte

PackAddresses packs addresses into a byte slice.

func PackEncryptionKeys

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

PackEncryptionKeys packs encryption algorithm and keys into a byte slice.

func ParamsErrAdvertisementNotFound added in v0.1.10

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 added in v0.1.10

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 added in v0.1.10

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

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

func ParamsErrBadQuery added in v0.1.10

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

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

func ParamsErrDiscoveryClosed added in v0.1.10

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

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

func ParamsErrNoDiscoveryPlugin added in v0.1.10

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

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

func ParamsErrTooManyPlugins added in v0.1.10

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

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

UnpackAddresses unpacks addresses from a byte slice.

func UnpackEncryptionKeys

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

UnpackEncryptionKeys unpacks encryption algorithm and keys from a byte slice.

Types

type AdHash

type AdHash [8]byte

An AdHash is a hash of an advertisement.

func (AdHash) VDLIsZero

func (x AdHash) VDLIsZero() bool

func (*AdHash) VDLRead

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

func (AdHash) VDLReflect

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

func (AdHash) VDLWrite

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

type AdInfo

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

func (x AdInfo) VDLIsZero() bool

func (*AdInfo) VDLRead

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

func (AdInfo) VDLReflect

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

func (AdInfo) VDLWrite

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

type AdStatus

type AdStatus byte

func (AdStatus) VDLIsZero

func (x AdStatus) VDLIsZero() bool

func (*AdStatus) VDLRead

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

func (AdStatus) VDLReflect

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

func (AdStatus) VDLWrite

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

type Barrier

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

func NewBarrier(done func()) *Barrier

func (*Barrier) Add

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

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

type DirectoryClientStub interface {
	DirectoryClientMethods
}

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

func DirectoryClient

func DirectoryClient(name string) DirectoryClientStub

DirectoryClient returns a client stub for Directory.

type DirectoryServerMethods

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

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

DirectoryServerStub adds universal methods to DirectoryServerStubMethods.

func DirectoryServer

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

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

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

EncodingBuffer is used to encode and decode advertisements.

func NewEncodingBuffer

func NewEncodingBuffer(data []byte) *EncodingBuffer

NewEncodingBuffer returns a new encoding buffer.

func (*EncodingBuffer) Bytes

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

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

func (*EncodingBuffer) Len

func (e *EncodingBuffer) Len() int

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

func (*EncodingBuffer) Next

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

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

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

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

func (*EncodingBuffer) ReadInt

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

ReadInt reads an integer from the buffer.

func (*EncodingBuffer) ReadString

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

ReadString reads a string from the buffer.

func (*EncodingBuffer) Write

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

Write appends a byte slice to the buffer.

func (*EncodingBuffer) WriteBytes

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

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

func (*EncodingBuffer) WriteInt

func (e *EncodingBuffer) WriteInt(x int)

WriteInt appends an integer to the buffer.

func (*EncodingBuffer) WriteString

func (e *EncodingBuffer) WriteString(s string)

WriteString appends a string to the buffer.

type EncryptionAlgorithm

type EncryptionAlgorithm int32

func (EncryptionAlgorithm) VDLIsZero

func (x EncryptionAlgorithm) VDLIsZero() bool

func (*EncryptionAlgorithm) VDLRead

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

func (EncryptionAlgorithm) VDLReflect

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

func (EncryptionAlgorithm) VDLWrite

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

type EncryptionKey

type EncryptionKey []byte

func (EncryptionKey) VDLIsZero

func (x EncryptionKey) VDLIsZero() bool

func (*EncryptionKey) VDLRead

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

func (EncryptionKey) VDLReflect

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

func (EncryptionKey) VDLWrite

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

type Factory

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

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

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

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

type Plugin

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

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

func NewTrigger() *Trigger

func (*Trigger) Add

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

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

func (*Trigger) Stop

func (tr *Trigger) Stop()

Stop stops the trigger.

type Uuid

type Uuid []byte

func NewAttributeUUID

func NewAttributeUUID(name string) Uuid

NewAttributeUUID returns a version 5 UUID for the given name.

TODO(jhahn): rename to NewAttributeUuid.

func NewServiceUUID

func NewServiceUUID(interfaceName string) Uuid

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

func (Uuid) String

func (u Uuid) String() string

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

func (Uuid) VDLIsZero

func (x Uuid) VDLIsZero() bool

func (*Uuid) VDLRead

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

func (Uuid) VDLReflect

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

func (Uuid) VDLWrite

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

Directories

Path Synopsis
TODO(jhahn): This is an experimental work to see its feasibility and set the long-term goal, and can be changed without notice.
TODO(jhahn): This is an experimental work to see its feasibility and set the long-term goal, and can be changed without notice.
plugins
ble
loopback
Package loopback implements loopback plugin for discovery service.
Package loopback implements loopback plugin for discovery service.
mdns
Package mdns implements mDNS plugin for discovery service.
Package mdns implements mDNS plugin for discovery service.
vine
Package vine contains a discovery plugin that is using Vine protocol.
Package vine contains a discovery plugin that is using Vine protocol.
package test contains tests that rely on a fake runtime.
package test contains tests that rely on a fake runtime.
Package testutil defines helpers for discovery tests.
Package testutil defines helpers for discovery tests.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL