README
¶
Guest Agent Events Handling Layer
Overview
The Guest Agent events handling layer is a generic and multi-purpose events handling layer, it's designed to offer a unified mechanism and API to manage and communicate "external" events across the guest agent implementation. Such "external" events could be a underlying Operating System event such as file changes or removal, sockets, named pipes etc as well as platform services such as metadata service, snapshot service etc.
The events layer is formed of a Manager, a Watcher and a Subscriber where the Manager is the events controller/manager itself, the Watcher is the implementation of the event listening and the Subscriber is the callback function interested in a given event and registered to handle it or "to be notified when they happen".
Each Event is internally identified by a string ID, when registering the Subscriber must tell what event it's interested on, such as:
eventManager.Subscribe("metadata-watcher,longpoll", &userData, func(evType string, data interface{}, evData interface{}) bool {
// Event handling implementation...
return true
})
The Subscriber implementation must return a boolean, such a boolean determines if the Subscriber must be renewed or if it must be unregistered/unsubscribed.
Sequence Diagram
Below is a high level sequence diagram showing how the Guest Agent, Manager, Watchers and Handlers/Subscribers interact with each other:
┌───────────┐ ┌─────────────┐ ┌─────────┐┌─────────┐┌─────────┐┌─────────┐
│Guest Agent│ │Event Manager│ │Watcher A││Watcher B││Handler A││Handler B│
└─────┬─────┘ └──────┬──────┘ └────┬────┘└────┬────┘└────┬────┘└────┬────┘
│ │ │ │ │ │
│ Initialize │ │ │ │ │
│────────────────>│ │ │ │ │
│ │ │ │ │ │
│ │ Register │ │ │ │
│ │─────────────>│ │ │ │
│ │ │ │ │ │
│ │ Register │ │ │
│ │────────────────────────>│ │ │
│ │ │ │ │ │
│Done initializing│ │ │ │ │
│<────────────────│ │ │ │ │
│ │ │ │ │ │
│ │ Subscribe()│ │ │ │
│─────────────────────────────────────────────────────>│ │
│ │ │ │ │ │
│ │ Subscribe() │ │ │
│────────────────────────────────────────────────────────────────>│
│ │ │ │ │ │
│ Run() │ │ │ │ │
│────────────────>│ │ │ │ │
│ │ │ │ │ │
│ │ Run() │ │ │ │
│ │─────────────>│ │ │ │
│ │ │ │ │ │
│ │ Run() │ │ │
│ │────────────────────────>│ │ │
│ │ │ │ │ │
│ │dispatch event│ │ │ │
│ │<─────────────│ │ │ │
│ │ │ │ │ │
│ │ │Call() │ │ │
│ │───────────────────────────────────>│ │
│ │ │ │ │ │
│ │ dispatch event │ │ │
│ │<────────────────────────│ │ │
│ │ │ │ │ │
│ │ │ Call() │ │
│ │──────────────────────────────────────────────>│
┌─────┴─────┐ ┌──────┴──────┐ ┌────┴────┐┌────┴────┐┌────┴────┐┌────┴────┐
│Guest Agent│ │Event Manager│ │Watcher A││Watcher B││Handler A││Handler B│
└───────────┘ └─────────────┘ └─────────┘└─────────┘└─────────┘└─────────┘
Built-in Watchers
| Watcher | Events | Desc |
|---|---|---|
| metadata | metadata-watcher,longpoll | A new version of the metadata descriptor was detected. |
| ssh-trusted-ca-pipe-watcher | ssh-trusted-ca-pipe-watcher,read | A read in the trusted-ca pipe was detected. |
Documentation
¶
Overview ¶
Package events is a events processing layer.
Index ¶
- type EventCb
- type EventData
- type Manager
- func (mngr *Manager) AddDefaultWatchers(ctx context.Context) error
- func (mngr *Manager) AddWatcher(ctx context.Context, watcher Watcher) error
- func (mngr *Manager) RemoveWatcher(ctx context.Context, watcher Watcher) error
- func (mngr *Manager) Run(ctx context.Context) error
- func (mngr *Manager) Subscribe(evType string, data interface{}, cb EventCb)
- func (mngr *Manager) Unsubscribe(evType string, cb EventCb)
- type Watcher
- type WatcherEventType
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type EventCb ¶
EventCb defines the callback interface between watchers and subscribers. The arguments are:
- ctx the app' context passed in from the manager's Run() call.
- evType a string defining the what event type triggered the call.
- data a user context pointer to be consumed by the callback.
- evData a event specific data pointer.
The callback should return true if it wants to renew, returning false will case the callback to be unregistered/unsubscribed.
type EventData ¶
type EventData struct {
// Data points to the Watcher provided data.
Data interface{}
// Error is used when a Watcher has failed and wants communicate its subscribers about the error.
Error error
}
EventData wraps the data communicated from a Watcher to a Subscriber.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager defines the interface between events management layer and the core guest agent implementation.
func Get ¶
func Get() *Manager
Get allocates a new manager if one doesn't exists or returns the one previously allocated.
func (*Manager) AddWatcher ¶
AddWatcher adds/enables a new watcher. The watcher will be fired up right away if the event manager is already running, otherwise it's scheduled to run when Run() is called.
func (*Manager) RemoveWatcher ¶
RemoveWatcher removes a watcher from the event manager. Each running watcher has its own context (derived from the one provided in the AddWatcher() call) and will have it canceled after calling this method.
func (*Manager) Run ¶
Run runs the event manager, it will block until all watchers have given up/failed. The event manager is meant to be started right after the early initialization code and live until the application ends, the event manager can not be restarted - the Run() method will return an error if one tries to run it twice.
func (*Manager) Subscribe ¶
Subscribe registers an event consumer/subscriber callback to a given event type, data is a context pointer provided by the caller to be passed down when calling cb when a new event happens.
func (*Manager) Unsubscribe ¶
Unsubscribe removes the subscription of a given callback for a given event type.
type Watcher ¶
type Watcher interface {
// ID returns the watcher id.
ID() string
// Events return a slice with all the event types a given Watcher handles.
Events() []string
// Run implements the actuall "listening" strategy and emits a event "signal".
// It must return:
// - [bool] if the watcher should renew(run again).
// - [interface{}] a event context data pointer further describing the event(if needed).
// - [err] error case the Watcher failed and wants to notify subscribers(see EventData).
Run(ctx context.Context, evType string) (bool, interface{}, error)
}
Watcher defines the interface between the events manager and the actual watcher implementation.
type WatcherEventType ¶
type WatcherEventType struct {
// contains filtered or unexported fields
}
WatcherEventType wraps/couples together a Watcher and an event type.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package metadata implement the metadata events watcher.
|
Package metadata implement the metadata events watcher. |
|
Package sshtrustedca implement the sshd trusted ca cert pipe events watcher.
|
Package sshtrustedca implement the sshd trusted ca cert pipe events watcher. |