discovery

package
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: 7 Imported by: 58

Documentation

Overview

Package discovery defines types and interfaces for discovering services.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AdId

type AdId [16]byte

An AdId is a globally unique identifier of an advertisement.

func NewAdId

func NewAdId() (AdId, error)

NewId returns a new random id.

func ParseAdId

func ParseAdId(s string) (AdId, error)

Parse decodes the hexadecimal string into id.

func (AdId) IsValid

func (id AdId) IsValid() bool

IsValid reports whether the id is valid.

func (AdId) String

func (id AdId) String() string

String returns the string corresponding to the id.

func (AdId) VDLIsZero

func (x AdId) VDLIsZero() bool

func (*AdId) VDLRead

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

func (AdId) VDLReflect

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

func (AdId) VDLWrite

func (x AdId) VDLWrite(enc vdl.Encoder) error
type Advertisement struct {
	// Universal unique identifier of the advertisement.
	// If this is not specified, a random unique identifier will be assigned.
	Id AdId
	// Interface name that the advertised service implements.
	// E.g., 'v.io/v23/services/vtrace.Store'.
	InterfaceName string
	// Addresses (vanadium object names) that the advertised service is served on.
	// E.g., '/host:port/a/b/c', '/ns.dev.v.io:8101/blah/blah'.
	Addresses []string
	// Attributes as a key/value pair.
	// E.g., {'resolution': '1024x768'}.
	//
	// The key must be US-ASCII printable characters, excluding the '=' character
	// and should not start with '_' character.
	//
	// We limit the maximum number of attachments to 32.
	Attributes Attributes
	// Attachments as a key/value pair.
	// E.g., {'thumbnail': binary_data }.
	//
	// Unlike attributes, attachments are for binary data and they are not queryable.
	//
	// The key must be US-ASCII printable characters, excluding the '=' character
	// and should not start with '_' character.
	//
	// We limit the maximum number of attachments to 32 and the maximum size of each
	// attachment is 4K bytes.
	Attachments Attachments
}

Advertisement represents a feed into advertiser to broadcast its contents to scanners.

A large advertisement may require additional RPC calls causing delay in discovery. We limit the maximum size of an advertisement to 512 bytes excluding id and attachments.

func (Advertisement) VDLIsZero

func (x Advertisement) VDLIsZero() bool

func (*Advertisement) VDLRead

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

func (Advertisement) VDLReflect

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

func (Advertisement) VDLWrite

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

type Attachments

type Attachments map[string][]byte

Attachments represents service attachments as a key/value pair.

func (Attachments) VDLIsZero

func (x Attachments) VDLIsZero() bool

func (*Attachments) VDLRead

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

func (Attachments) VDLReflect

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

func (Attachments) VDLWrite

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

type Attributes

type Attributes map[string]string

Attributes represents service attributes as a key/value pair.

func (Attributes) VDLIsZero

func (x Attributes) VDLIsZero() bool

func (*Attributes) VDLRead

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

func (Attributes) VDLReflect

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

func (Attributes) VDLWrite

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

type DataOrError

type DataOrError struct {
	Data  []byte
	Error error
}

DataOrError contains either an attachment data or an error encountered fetching the attachment.

type T

type T interface {
	// Advertise broadcasts the advertisement to be discovered by "Scan" operations.
	//
	// visibility is used to limit the principals that can see the advertisement. An
	// empty set means that there are no restrictions on visibility (i.e, equivalent
	// to []security.BlessingPattern{security.AllPrincipals}).
	//
	// If the advertisement id is not specified, a random unique a random unique identifier
	// will be assigned. The advertisement should not be changed while it is being advertised.
	//
	// It is an error to have simultaneously active advertisements for two identical
	// instances (Advertisement.Id).
	//
	// Advertising will continue until the context is canceled or exceeds its deadline
	// and the returned channel will be closed when it stops.
	Advertise(ctx *context.T, ad *Advertisement, visibility []security.BlessingPattern) (<-chan struct{}, error)

	// Scan scans advertisements that match the query and returns the channel of updates.
	//
	// Scan excludes the advertisements that are advertised from the same discovery
	// instance.
	//
	// The query is a WHERE expression of a syncQL query against advertisements, where
	// key is Advertisement.Id and value is Advertisement.
	//
	// Examples
	//
	//    v.InterfaceName = "v.io/i"
	//    v.InterfaceName = "v.io/i" AND v.Attributes["a"] = "v"
	//    v.Attributes["a"] = "v1" OR v.Attributes["a"] = "v2"
	//
	// SyncQL tutorial at:
	//    https://vanadium.github.io/tutorials/syncbase/syncql-tutorial.html
	//
	// Scanning will continue until the context is canceled or exceeds its deadline.
	Scan(ctx *context.T, query string) (<-chan Update, error)
}

T is the interface for discovery operations; it is the client side library for the discovery service.

type Update

type Update interface {
	// IsLost returns true when this update corresponds to an advertisement
	// that led to a previous update vanishing.
	IsLost() bool

	// Id returns the universal unique identifier of the advertisement.
	Id() AdId //nolint:golint // API change required.

	// InterfaceName returns the interface name that the service implements.
	InterfaceName() string

	// Addresses returns the addresses (vanadium object names) that the service
	// is served on.
	Addresses() []string

	// Attribute returns the named attribute. An empty string is returned if
	// not found.
	Attribute(name string) string

	// Attachment returns the channel on which the named attachment can be read.
	// Nil data is returned if not found.
	//
	// This may do RPC calls if the attachment is not fetched yet and fetching
	// will fail if the context is canceled or exceeds its deadline.
	//
	// Attachments may not be available when this update is for lost advertisement.
	Attachment(ctx *context.T, name string) <-chan DataOrError

	// Advertisement returns a copy of the advertisement that this update
	// corresponds to.
	//
	// The returned advertisement may not include all attachments.
	Advertisement() Advertisement

	// Timestamp returns the time when advertising began for the corresponding
	// Advertisement.
	Timestamp() time.Time
}

Update is the interface for a discovery update.

Jump to

Keyboard shortcuts

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