saturnin.component.micro

Saturnin base module for implementation of Firebird Butler Microservices.

This module provides the MicroService base class, which handles common microservice lifecycle management, communication with a controller via ICCP, and a basic event loop for handling ZMQ messages and scheduled tasks.

Constants and variables

saturnin.component.micro.SVC_CTRL: Final[str] = 'iccp'

Service control channel name

Classes

class saturnin.component.micro.MicroService(*args, **kwargs)

Bases: Component, TracedMixin

Saturnin Component for Firebird Butler Microservices.

Parameters:

• zmq_context – ZeroMQ Context.

• descriptor – Service descriptor.

• peer_uid – Peer ID, None means that newly generated UUID type 1 should be used.

aquire_resources() → None

Acquire resources required by component (e.g., open files, connect to other services).

This method is called during the warm-up phase after basic initialization. Implementations should raise an exception if resource acquisition fails.

Return type:

None

bind_endpoints() → None

Binds all ZMQ endpoints defined in endpoints using the respective channels from mngr.

Return type:

None

get_timeout() → int

Returns the timeout in milliseconds until the next scheduled action. If no actions are scheduled, it returns 1000ms (1 second) as a default polling interval.

Return type:

int

handle_config_request(config: ConfigProto) → None

ICCP event handler. Called when controller requested reconfiguration.

Must raise an exception if configuration fails for any reason.

By default, the component does not support run-time configuration, so it raises NotImplementedError.

Parameters:

config (ConfigProto) – New configuration provided by controller.

Return type:

None

handle_stop_component(exc: Exception | None = None) → None

ICCP event handler. Called when commponent should stop its operation. It stops the component by setting the stop event.

Parameters:

exc (Exception | None) – Exception that describes the reason why component should stop. If not provided, the component should stop on controller’s request.

Return type:

None

initialize(config: ComponentConfig) → None

Verify configuration and assemble component structural parts.

Parameters:

config (ComponentConfig) – Service configuration.

Return type:

None

release_resources() → None

Release resources acquired by the component (e.g., close files, disconnect from other services).

This method is called during the graceful shutdown phase.

Return type:

None

run() → None

The main execution loop for the microservice.

This loop continuously waits for I/O events on managed channels and processes them in a prioritized order:

1. Messages on the ICCP control channel (if connected).

2. Output-ready events on other channels.

3. Input-ready events on other channels.

After processing I/O, it executes any due scheduled actions via run_scheduled().

The loop terminates when stop event is set. Upon termination, it performs a graceful shutdown sequence: stop_activities(), release_resources(), sends a FINISHED (or ERROR) message to the controller, and shuts down the ChannelManager.

Return type:

None

run_scheduled() → None

Executes any scheduled actions whose execution time (priority) is at or before the current monotonic time.

Return type:

None

schedule(action: Callable, after: int) → None

Schedule action to be executed after specified time.

Action is executed in run() main I/O loop not sooner than after specified number of milliseconds from time when schedule() is called. However, the actual delay could be longer than specified (depends on time spent in message handlers and other factors).

Parameters:

• action (Callable) – Callable (without arguments) to be executed. Use functools.partial if callable requires arguments.

• after (int) – Delay in milliseconds.

Return type:

None

start_activities() → None

Start normal component activities.

Must raise an exception when start fails.

Return type:

None

stop_activities() → None

Stop component activities.

Return type:

None

warm_up(ctrl_addr: ZMQAddress | None) → None

Performs the warm-up sequence for the microservice.

This includes:

• Setting up the ICCP control channel if ctrl_addr is provided.

• Warming up the ChannelManager to create ZMQ sockets.

• Connecting to the controller via ICCP.

• Binding all service-defined endpoints via bind_endpoints().

• Acquiring necessary resources via aquire_resources().

• Starting normal component activities via start_activities().

• Sending a READY message to the controller upon success, or an ERROR message if any warm-up step fails.

Parameters:

ctrl_addr (ZMQAddress | None) – The ZMQ address of the controller’s control channel. If None, the component runs without ICCP communication (e.g., standalone).

Return type:

None

descriptor: ServiceDescriptor

Service desriptor.

details: Exception | list[str]

Service execution outcome details

endpoints: dict[str, list[ZMQAddress]]

Dictionary with endpoints to which the component binds. Key is channel name, value is list of ZMQAddress instances. Initially empty.

mngr: ChannelManager

ChannelManager instance.

outcome: Outcome

Service execution outcome

peer: PeerDescriptor

Peer descriptor for this component.

state: State

Service internal state

stop: Event

Event to stop the component