Event Server¶
Event Server is a central component responsible for registering, processing, storing and providing access to events.
Configuration for Event Server is defined with schema
hat-event://server.yaml
.
Running¶
By installing Event Server from hat-event package, executable hat-event-server becomes available and can be used for starting this component.
usage: hat-event-server [-h] [--conf PATH]
options:
-h, --help show this help message and exit
--conf PATH configuration defined by hat-event://server.yaml (default
$XDG_CONFIG_HOME/hat/event.{yaml|yml|toml|json})
Event Server can be run as standalone component or component connecting to Monitor Server.
Redundancy¶
To run multiple redundant Event Servers, monitor parameter has to be defined
in the configuration. Event Server connects to configured Monitor Server and
creates a corresponding Monitor Component. Besides execution of redundancy
algorithm, Monitor Server is also used for service discovery. Each Monitor
Component is described with its info, that is Component Information. One
of the properties of component info is data, through which a component can
share some arbitrary information with any other component. Event Server uses
data (specified by hat-event://monitor_data.yaml
) to share the following
information:
server_id
Event Server unique identifier (defined in configuration as server_id). Needed by Eventer Client to request synchronization with the specific server.
eventer_server/host and eventer_server/host
Eventer Server address is needed to any component that uses Eventer Client to interact with currently active Event Server by events.
syncer_token (optional property)
This token string is used as a key for synchronization between Eventer Server and Eventer Client. Event Server will request synchronization with a remote Event Server only if their server_token are identical. If this token is not defined, synchronization is performed irrespective.
Synchronization between Event Servers is based on :ref:` Eventer communication protocol <eventer>`.
If redundant execution is used, each Event Server can operate in two distinct modes:
standby
operating
Additional transient modes starting and stopping represent transition between starting and operating modes.
Components¶
Event Server functionality can be defined by using the following components:
Engine¶
Engine is responsible for creating Modules and executing processing sessions.
This module is available only during operational mode.
Engine’s method register enables registration of events to backend based on a list of register events. Entity who requests registration is identified by Source identifier which is used only during processing of events and is discarded once event is created. There are four types of sources that may register events on Engine:
EVENTER
Events register by Eventer Server (originating from other components).MODULE
Events registered by Modules.ENGINE
Events registered by engine itself (e.g. starting and stopping of engine).SERVER
Events registered by Event Server internal functions (e.g. synchronization status).
By creating event, Engine enhances register event with:
id - unique event identifier,
timestamp - single point in time when events are registered. All events registered in a single session get the same timestamp.
Process of creating events based on a single list of register events provided through register is called session. Engine starts new session each time Eventer Server or a module requests new registration through register method. After processing session ends, events are registered with backend. Start and end of each session is notified to each module by calling module’s on_session_start and on_session_stop methods respectively. These methods are called sequentially for each module: only when method of one module ended, method of the other module can be called.
During session processing, each module is notified with a newly created event in case it matches its subscription. By subscription, each module defines event type filter condition used for filtering new events that will get notified to the module. Processing of this event by module can result with new register events. Out of register events, Engine creates events and adds them to the current session. All modules, including the one that added that new events, are notified with new additions. This process continues iteratively until all modules return empty lists of new register events. Processing events by single module is always sequential - Engine keeps order of new events added to session so that new events are always added to the end of the queue for module notification.
Warning
Care should be taken by module implementation not to cause self recursive or mutually recursive endless processing loop.
Engine registers an event that signalizes when the Engine was started or
stopped. Event is registered by Engine, with Source.Type set to
ENGINE and with event type event/<server_id>/engine
where <server_id>
represent identification of local server. Source timestamp is
set to None
and payload is specified by
hat-event://events.yaml#/$defs/events/engine
.
Eventer Server¶
Eventer Server module is responsible for providing implementation of server side Eventer communication. This component translates client registration requests to Engine register method calls and client queries to Backend query method calls. At the same time, it observes all new event notifications made by Backend and notifies clients with appropriate messages.
This module is available during standby, starting, operational and stopping modes (event registration is not possible in mode is not operational).
RegisterEvent objects obtained from client’s register requests are forwarded to Engine which converts them to Event and submits to further processing.
A unique identifier is assigned to each chatter connection established with
Eventer Server (unique for the single execution lifetime of Event Server
process). This identifier is associated with all Event`s obtained from the
corresponding connection as through `id of Source (source type is
EVENTER
).
Each Client makes its subscription to Eventer Server during connection initialization. This subscription is used as a filter for selecting subset of event notifications which are sent to associated connection. In addition to subscription, client can request to be notified only with events with specific server_id.
Eventer Server module is responsible for registering events each time new
chatter connection is established and each time existing chatter connection is
closed. These events are defined by event type
event/<server_id>/eventer/<client_name>
where <server_id>
represent
identification of local server and <client_name> is client identifier
obtained during connection initialization. For these events, source timestamp
is set to None
and payload is specified by
hat-event://events.yaml#/$defs/events/eventer
.
Eventer Client¶
If multiple redundant Event Servers are used, each Event Server runs Eventer Client module. This module is used for obtaining and active synchronization of events originating from other Event Server instances.
Eventer Client connets to Eventer server with client name event/<name>
where <name> represents configured component’s name.
This module is available during standby, starting, operational and stopping modes.
By continuously monitoring state reported by Monitor Server, Event Server keeps updated list of other available Event Server instances. For each other available instance, new Eventer Client is created. Immediately after connecting to remote Event Server, Eventer Client will query all server events following last event available in local backend. When initial events are retrieved, Eventer Client keeps active connection to remote Event Server and registers new events as they are received. Eventer Client registers received events directly to backend overriding Engines event processing.
During communication with remote Event Server, additional events representing
synchronization status will be registered. These events are registered on
remote event server via Eventer register message. If local Event Server is in
operational mode, these events will also be registered in local Event Server
with Engine’s register method together with source SERVER
. Event type is
event/<server_id>/synced/<remote_server_id>
where <server_id>
represent identification of local server and
<remote_server_id>
represent identification of remote server. Source
timestamp is set to None
and payload is specified by
hat-event://events.yaml#/$defs/events/synced
.
Immediatly after connection with remote Event Server is established, synced
event with state CONNECTED
is registered. If first query returns at least
one event, synced event with state SYNCING
is registered. Once all remote
events are queried, synced event with state SYNCED
and total number of
synced events is registered.
Each time remote Event Server changes state to OPERATIONAL
, Eventer Client
will register new synced event with last registered synced state. In case
of SYNCED
state and registration triggered by OPERATIONAL
change,
new synced event will have count set to null
.
Extensions¶
Core Event Server functionality is used as basis which is extended with Backends and Modules.
Implementation¶
Documentation is available as part of generated API reference:
Configuration¶
$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "hat-event://server.yaml"
title: Event Server
description: Event Server's configuration
type: object
required:
- name
- server_id
- backend
- modules
- eventer_server
properties:
type:
const: event
description: configuration type identification
version:
type: string
description: component version
log:
$ref: "hat-json://logging.yaml"
name:
type: string
description: component name
server_id:
type: integer
description: server identifier
server_token:
type:
- string
- 'null'
description: server token
backend:
$ref: "hat-event://server.yaml#/$defs/backend"
modules:
type: array
items:
$ref: "hat-event://server.yaml#/$defs/module"
eventer_server:
type: object
required:
- host
- port
properties:
host:
type: string
default: "127.0.0.1"
port:
type: integer
default: 23012
monitor_component:
type: object
required:
- host
- port
- group
properties:
host:
type: string
default: "127.0.0.1"
port:
type: integer
default: 23010
group:
type: string
$defs:
backend:
type: object
description: |
structure of backend configuration depends on backend type
required:
- module
properties:
module:
type: string
description: full python module name that implements backend
module:
type: object
description: |
structure of module configuration depends on module type
required:
- module
properties:
module:
type: string
description: full python module name that implements module