node

Documentation

Index

• Variables
• func Client[C any](n *Node) (C, error)
• func FindClient[C any](n *Node, c *C)
• func NilUndo()
• func WithLogStateChange(logger *zap.Logger) grpc.DialOption
• type Announcer
  • func AnnounceContext(ctx context.Context, a Announcer) Announcer
  • func AnnounceFeatures(a Announcer, moreFeatures ...Feature) Announcer
  • func AnnounceWithNamePrefix(prefix string, a Announcer) Announcer
• type AnnouncerFunc
  • func (a AnnouncerFunc) Announce(name string, features ...Feature) Undo
• type ClientFunc
  • func (c ClientFunc) Client(p any) error
• type Clienter
• type DialOption
• type EmptyDialOption
• type EmptyFeature
• type EmptyFunction
• type Feature
  • func HasClient(clients ...interface{}) Feature
  • func HasMetadata(md *traits.Metadata) Feature
  • func HasNoAutoMetadata() Feature
  • func HasTrait(name trait.Name, opt ...TraitOption) Feature
• type Function
  • func Api(apis ...server.GrpcApi) Function
  • func Clients(c ...any) Function
  • func Routing(rs ...router.Router) Function
• type MetadataChange
• type Node
  • func New(name string) *Node
  • func (n *Node) Announce(name string, features ...Feature) Undo
  • func (n *Node) Client(p any) error
  • func (n *Node) ListAllMetadata(opts ...resource.ReadOption) []*traits.Metadata
  • func (n *Node) Name() string
  • func (n *Node) PullAllMetadata(ctx context.Context, opts ...resource.ReadOption) <-chan MetadataChange
  • func (n *Node) Register(s *grpc.Server)
  • func (n *Node) Support(functions ...Function)
• type Remote
  • func Dial(ctx context.Context, target string, opts ...grpc.DialOption) Remote
  • func DialChan(ctx context.Context, targets <-chan string, opts ...grpc.DialOption) Remote
• type SelfAnnouncer
• type SelfAnnouncerFunc
  • func (sa SelfAnnouncerFunc) AnnounceSelf(a Announcer) Undo
• type SelfSupporter
• type Supporter
• type TraitOption
  • func NoAddChildTrait() TraitOption
  • func WithClients(client ...interface{}) TraitOption
• type Undo
  • func UndoAll(undo ...Undo) Undo
  • func UndoOnce(undo Undo) Undo

Variables

var MetadataTraitNotSupported = errors.New("metadata is not supported")

Functions

func Client

func Client[C any](n *Node) (C, error)

Client returns a new api client of type C which can be used to interact with the named devices in n.

func FindClient

func FindClient[C any](n *Node, c *C)

FindClient places into c a client backed by the named devices in n.

func NilUndo

func NilUndo()

NilUndo does nothing.

func WithLogStateChange

func WithLogStateChange(logger *zap.Logger) grpc.DialOption

Types

type Announcer

type Announcer interface {
	// Announce signals that the name exists and has the given features.
	Announce(name string, features ...Feature) Undo
}

Announcer defines the Announce method. Calling Announce signals that a given name exists and has the collection of features provided. Typically announcing the same name more than once will combine the features of the existing name with the new features.

func AnnounceContext

func AnnounceContext(ctx context.Context, a Announcer) Announcer

AnnounceContext returns a new Announcer that undoes any announcements when ctx is Done. This leaks a go routine if ctx is never done.

func AnnounceFeatures

func AnnounceFeatures(a Announcer, moreFeatures ...Feature) Announcer

AnnounceFeatures returns an Announcer that acts like `Announce(name, [moreFeatures..., features...])`

func AnnounceWithNamePrefix

func AnnounceWithNamePrefix(prefix string, a Announcer) Announcer

AnnounceWithNamePrefix returns an Announcer whose Announce method acts like `Announce(prefix+name, features...)`

type AnnouncerFunc

type AnnouncerFunc func(name string, features ...Feature) Undo

AnnouncerFunc allows adapting a func of the correct signature to implement Announcer

func (AnnouncerFunc) Announce

func (a AnnouncerFunc) Announce(name string, features ...Feature) Undo

type ClientFunc

type ClientFunc func(p any) error

ClientFunc adapts a func of the correct signature to implement Clienter.

func (ClientFunc) Client

func (c ClientFunc) Client(p any) error

type Clienter

type Clienter interface {
	// Client sets into the pointer p a client, if one is available, or returns an error.
	// Argument p should be a pointer to a variable of the required client type.
	//
	// Example
	//
	//	var client traits.OnOffApiClient
	//	err := n.Client(&client)
	Client(p any) error
}

Clienter represents a type that can respond with an API client.

type DialOption

type DialOption interface {
	grpc.DialOption
	// contains filtered or unexported methods
}

type EmptyDialOption

type EmptyDialOption struct {
	grpc.EmptyDialOption
}

EmptyDialOption does not change how a dial will be performed. Useful for embedding into custom DialOption types to extend the dial api.

type EmptyFeature

type EmptyFeature struct{}

EmptyFeature is a Feature that means nothing. It can be embedded in custom Feature types to allow them to extend the capabilities of the Feature system.

type EmptyFunction

type EmptyFunction struct{}

EmptyFunction does not change the functions a Node supports. Can be embedded in custom Function types to allow extending Node support.

type Feature

type Feature interface {
	// contains filtered or unexported methods
}

Feature describes some aspect of a named device.

func HasClient

func HasClient(clients ...interface{}) Feature

HasClient indicates that the name implements non-trait apis as defined by these clients. The clients are still added to routers and all requests on the clients should accept a Name.

func HasMetadata

func HasMetadata(md *traits.Metadata) Feature

HasMetadata merges the given metadata into any existing metadata held against the device name. Merging metadata is not commutative, two calls to Announce causes the second call to overwrite the first for all common fields. Announce accepts multiple HasMetadata features acting as if Announce were called in sequence with each HasMetadata feature.

See metadata.Model.MergeMetadata for more details. If md is nil, does not adjust the announcement.

func HasNoAutoMetadata

func HasNoAutoMetadata() Feature

HasNoAutoMetadata indicates that announcing the device should not announce automatic metadata for the device. Announcing will normally inspect all traits and announce basic metadata for them, this feature turns that off. HasMetadata will still be applied.

func HasTrait

func HasTrait(name trait.Name, opt ...TraitOption) Feature

HasTrait indicates that the device implements the named trait.

type Function

type Function interface {
	// contains filtered or unexported methods
}

Function represents something that is supported by a type. For example an API might be represented as a Function and added to a server.

func Api

func Api(apis ...server.GrpcApi) Function

Api instructs the node to register the given apis with the grpc.Server when Node.Register is called.

func Clients

func Clients(c ...any) Function

Clients adds the given clients, which should be proto service clients, to a node. Code can access a nodes clients via Client. Typically these are associated with the nodes routers via server->client conversion.

func Routing

func Routing(rs ...router.Router) Function

Routing adds the given routers to the supported API of the node.

type MetadataChange

type MetadataChange struct {
	Name          string
	ChangeTime    time.Time
	Type          types.ChangeType
	OldValue      *traits.Metadata
	NewValue      *traits.Metadata
	LastSeedValue bool
}

type Node

type Node struct {
	Logger *zap.Logger
	// contains filtered or unexported fields
}

Node represents a smart core node. The node has collection of supported apis, represented by router.Router instances and configured via Support. When new names are created they should call Announce and with the features relevant to the name.

All supported APIs in a Node are routed based on a name. Call Support to add new features to the Node. Calling Support after Register will not have any effect on the served apis.

func New

func New(name string) *Node

New creates a new Node node with the given name.

func (*Node) Announce

func (n *Node) Announce(name string, features ...Feature) Undo

Announce adds a new name with the given features to this node. You may call Announce multiple times with the same name to add additional features, for example new traits. Executing the returned Undo will undo any direct changes made.

A note on undoing

The undo process is not perfect but best effort. Hooks and callbacks may have been executed that have side effects that are not undone.

func (*Node) Client

func (n *Node) Client(p any) error

Client implements Clienter backed by clients configured using Support(Clients).

func (*Node) ListAllMetadata

func (n *Node) ListAllMetadata(opts ...resource.ReadOption) []*traits.Metadata

ListAllMetadata returns a slice containing all metadata set via Announce.

func (*Node) Name

func (n *Node) Name() string

Name returns the device name for this node, how this node refers to itself.

func (*Node) PullAllMetadata

func (n *Node) PullAllMetadata(ctx context.Context, opts ...resource.ReadOption) <-chan MetadataChange

PullAllMetadata returns a chan that emits MetadataChange whenever Announce or that announcement is undone.

func (*Node) Register

func (n *Node) Register(s *grpc.Server)

Register implements server.GrpcApi and registers all supported routers with s.

func (*Node) Support

func (n *Node) Support(functions ...Function)

Support adds new supported functions to this node.

type Remote

type Remote interface {
	io.Closer
	Target() string
	Connect(ctx context.Context) (*grpc.ClientConn, error)
}

Remote represents a remote smart core node

func Dial

func Dial(ctx context.Context, target string, opts ...grpc.DialOption) Remote

Dial calls grpc.DialContext and returns it as a Remote.

func DialChan

func DialChan(ctx context.Context, targets <-chan string, opts ...grpc.DialOption) Remote

DialChan returns a Remote that connects to the last received target from targets. Remote.Connect will return the same grpc.ClientConn, the underlying connection will be replaced each time targets emits a value.

Do not use grpc.WithBlock option with DialChan.

type SelfAnnouncer

type SelfAnnouncer interface {
	AnnounceSelf(a Announcer) Undo
}

SelfAnnouncer is a complement to node.Announcer allowing a type to announce itself.

type SelfAnnouncerFunc

type SelfAnnouncerFunc func(a Announcer) Undo

SelfAnnouncerFunc allows adapting a func of the correct signature to implement SelfAnnouncer

func (SelfAnnouncerFunc) AnnounceSelf

func (sa SelfAnnouncerFunc) AnnounceSelf(a Announcer) Undo

type SelfSupporter

type SelfSupporter interface {
	AddSupport(supporter Supporter)
}

SelfSupporter inverts the receiver for Supporter.

type Supporter

type Supporter interface {
	Support(functions ...Function)
}

Supporter is a type that can have its supported functions changed at runtime.

type TraitOption

type TraitOption func(t *traitFeature)

TraitOption controls how a Node behaves when presented with a new device trait.

func NoAddChildTrait

func NoAddChildTrait() TraitOption

NoAddChildTrait instructs the Node not to add the trait to the nodes parent.Model.

func WithClients

func WithClients(client ...interface{}) TraitOption

WithClients indicates that the trait is implemented by these client instances. The clients will be added to the relevant routers when the trait is announced.

type Undo

type Undo func()

Undo allows a statement to be undone.

func UndoAll

func UndoAll(undo ...Undo) Undo

UndoAll creates an Undo that undoes all the given Undo in order.

func UndoOnce

func UndoOnce(undo Undo) Undo

UndoOnce returns an Undo that only calls undo once.