saturnin.protocol.iccp

Saturnin Internal Component Control Protocol (ICCP).

This protocol defines the messages and rules for communication between Saturnin components (like services or microservices) and their controllers. It handles lifecycle events (ready, stop, finished), configuration requests, and error reporting.

Enums

class saturnin.protocol.iccp.MsgType(value)[source]

Bases: IntEnum

Control message type.

ERROR = 4
FINISHED = 6
OK = 3
READY = 1
REQUEST = 2
STOP = 5
class saturnin.protocol.iccp.Request(value)[source]

Bases: Enum

Controller Request Codes for ICCP.

CONFIGURE = b'CONF'

Classes

class saturnin.protocol.iccp.ICCPMessage[source]

Bases: Message

Service Control Message.

as_zmsg() → TZMQMessage[source]

Returns message as sequence of ZMQ data frames.

Returns:

A list of ZMQ frames representing the message. The first frame is the packed MsgType. Subsequent frames are added based on the message type and its attributes.

Return type:

TZMQMessage

clear() → None[source]

Clears message data.

Return type:

None

copy() → Message[source]

Returns copy of the message.

Returns:

A new ICCPMessage instance with a deep copy of relevant attributes (like peer, endpoints, config) based on the original message’s msg_type.

Return type:

Message

from_zmsg(zmsg: TZMQMessage) → None[source]

Populate message data from sequence of ZMQ data frames.

Parameters:

  • zmsg (TZMQMessage) – Sequence of ZMQ frames to be deserialized. The first frame is

  • the (always the packed MsgType. Subsequent frames depend on)

  • type (message)

Raises:

InvalidMessageError – If message is not a valid protocol message.

Return type:

None

get_keys() → Iterable[source]

Returns iterable of dictionary keys to be used with Protocol.handlers. Keys must be provided in order of precedence (from more specific to general).

Return type:

Iterable

msg_type: MsgType

Type of message

class saturnin.protocol.iccp._ICCP(*args, **kwargs)[source]

Bases: Protocol

Internal Component Control Protocol (ICCP).

Used by Saturnin internally for component/controller transmissions.

_ICCP__message_factory(zmsg: TypeAliasForwardRef('~saturnin.base.transport.TZMQMessage') | None = None) → Message

Internal message factory

Parameters:

zmsg (TypeAliasForwardRef('~saturnin.base.transport.TZMQMessage') | None)

Return type:

Message

__init__(*, session_type: type[Session] = <class 'saturnin.base.transport.Session'>)[source]
Parameters:

session_type (type[Session]) – Class for session objects.

validate(zmsg: TZMQMessage) → None[source]

Verifies that sequence of ZMQ data frames is a valid protocol message.

If this validation passes without exception, then parse() of the same message must be successful as well.

Parameters:

zmsg (TZMQMessage) – ZeroMQ multipart message. Expects the first frame to be the packed MsgType, followed by type-specific frames.

Raises:

InvalidMessageError – If ZMQ message is not a valid protocol message.

Return type:

None

OID: Final[str] = '1.3.6.1.4.1.53446.1.1.0.1.1'

string with protocol OID (dot notation).

UID: Final[uuid.UUID] = UUID('9b7ac9a3-d684-5955-b0ae-2f69e8666868')

UUID instance that identifies the protocol.

class saturnin.protocol.iccp.ICCPComponent(*args, **kwargs)[source]

Bases: _ICCP

Internal Component Control Protocol (ICCP) - Component (client) side.

Used by Saturnin internally for component/controller transmissions.

__init__(*, session_type: type[Session] = <class 'saturnin.base.transport.Session'>, with_traceback: bool = False)[source]
Parameters:

  • session_type (type[Session]) – Class for session objects.

  • with_traceback (bool) – When True, stores traceback along with exception in ERROR/FINISHED.

accept_new_session(channel: Channel, routing_id: RoutingID, msg: ICCPMessage) → bool[source]

Validates incoming message that initiated new session/transmission.

Parameters:

  • channel (Channel) – Channel that received the message.

  • routing_id (RoutingID) – Routing ID of the sender.

  • msg (ICCPMessage) – Received message.

Returns:

Always False (transmission must be initiated by Component).

Return type:

bool

connect_with_session(channel: Channel) → bool[source]

Called by Channel.connect() to determine whether new session should be associated with connected peer.

As ICCP require that connecting peers must send a message to initiate transmission, it always returns True.

Parameters:

channel (Channel) – Channel associated with controller.

Return type:

bool

error_msg(exc: Exception) → ICCPMessage[source]

Returns ERROR control message.

Parameters:

exc (Exception) – Exception to send.

Return type:

ICCPMessage

finished_msg(outcome: Outcome, details: None | Exception | list[str]) → ICCPMessage[source]

Returns FINISHED control message.

Parameters:

  • outcome (Outcome) – Outcome of componentn run.

  • details (None | Exception | list[str]) – Additional information about the outcome. If an Exception, its traceback (if with_traceback is True) or string, string representation is used. If a list[str], it’s used directly. If None, no details are included.

Return type:

ICCPMessage

handle_exception(channel: Channel, session: Session, msg: ICCPMessage, exc: Exception) → None[source]

Event handler for on_exception. Calls on_stop_component with exception.

Parameters:

  • channel (Channel) – Channel associated with controller.

  • session (Session) – Session associated with controller.

  • msg (ICCPMessage) – Message sent by controller.

  • exc (Exception) – Exception to handle.

Return type:

None

handle_invalid_msg(channel: Channel, session: Session, exc: InvalidMessageError) → None[source]

Event handler for on_invalid_msg. Calls on_stop_component with exception.

Parameters:

  • channel (Channel) – Channel associated with controller.

  • session (Session) – Session associated with controller.

  • exc (InvalidMessageError) – Exception raised.

Return type:

None

handle_request(channel: Channel, session: Session, msg: ICCPMessage) → None[source]

Process REQUEST message received from controller.

Currently handles Request.CONFIGURE by invoking the on_config_request event with the provided configuration. Sends an OK message back to the controller upon successful processing, or an ERROR message if an exception occurs during the on_config_request handling.

Parameters:

  • channel (Channel) – The channel connected to the controller.

  • session (Session) – The session instance for this communication.

  • msg (ICCPMessage) – The received ICCPMessage containing the request.

Raises:

StopError – If sending the response (OK/ERROR) to the controller fails.

Return type:

None

handle_stop(channel: Channel, session: Session, msg: ICCPMessage) → None[source]

Process STOP message received from controller. Calls on_stop_component.

Parameters:

  • channel (Channel) – Channel associated with controller.

  • session (Session) – Session associated with controller.

  • msg (ICCPMessage) – Received message.

Return type:

None

ok_msg() → ICCPMessage[source]

Returns OK control message.

Return type:

ICCPMessage

ready_msg(peer: PeerDescriptor, endpoints: dict[str, list[ZMQAddress]]) → ICCPMessage[source]

Returns READY control message.

Parameters:
Return type:

ICCPMessage

wrong_message(channel: Channel, session: Session, msg: ICCPMessage) → None[source]

Handle wrong message received from controller.

Parameters:

  • channel (Channel) – Channel associated with controller.

  • session (Session) – Session associated with controller.

  • msg (ICCPMessage) – Message sent by controller.

Return type:

None

Raises StopError, which in turn calls on_exception from handle_msg.

on_config_request

eventsocket called when the controller requests reconfiguration.

The handler should apply the new configuration. Any exception raised by this event handler will be caught and sent back to the controller as an ERROR message.

Parameters:

config – The new configuration (ConfigProto) provided by the controller.

on_stop_component

eventsocket called when commponent should stop its operation.

Parameters:

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

with_traceback: bool
class saturnin.protocol.iccp.ICCPController(*args, **kwargs)[source]

Bases: _ICCP

Internal Component Control Protocol (ICCP) - Controller (server) side.

Used by Saturnin internally for component/controller transmissions.

__init__(*, session_type: type[Session] = <class 'saturnin.base.transport.Session'>)[source]
Parameters:

session_type (type[Session]) – Class for session objects.

handle_exception(channel: Channel, session: Session, msg: ICCPMessage, exc: Exception) → None[source]

Event handler for on_exception. Calls on_stop_controller with exception.

Parameters:

  • channel (Channel) – Channel associated with component.

  • session (Session) – Session associated with component.

  • msg (ICCPMessage) – Message sent by component.

  • exc (Exception) – Exception to handle.

Return type:

None

handle_invalid_msg(channel: Channel, session: Session, exc: InvalidMessageError) → None[source]

Event handler for on_invalid_msg. Calls on_stop_controller with exception.

Parameters:
Return type:

None

handle_oef(channel: Channel, session: Session, msg: ICCPMessage) → ICCPMessage[source]

Process OK/ERROR/FINISHED messages received from component. It simply returns the message.

Parameters:

  • channel (Channel) – Channel associated with component.

  • session (Session) – Session associated with component.

  • msg (ICCPMessage) – Message sent by component.

Return type:

ICCPMessage

handle_ready(channel: Channel, session: Session, msg: ICCPMessage) → ICCPMessage[source]

Processes a READY message received from a component.

If this is the first READY message for the session (indicated by session.ready not being set), it marks the session as ready and returns the received message. This typically signals that the component is initialized and has provided its peer information and endpoints.

Parameters:

  • channel (Channel) – Channel associated with the component.

  • session (Session) – Session associated with the component.

  • msg (ICCPMessage) – The READY message sent by the component.

Returns:

The received ICCPMessage if it’s the first READY for this session.

Raises:

StopError – If a READY message is received for a session already marked as ready, as this indicates an unexpected state.

Return type:

ICCPMessage

request_config_msg(config: Config | None = None) → ICCPMessage[source]

Returns REQUEST.CONFIG control message.

Parameters:

config (Config | None) – Optional firebird.base.config.Config instance containing the configuration for the component. If None, an empty configuration request is created.

Return type:

ICCPMessage

stop_msg() → ICCPMessage[source]

Returns STOP control message.

Return type:

ICCPMessage

wrong_message(channel: Channel, session: Session, msg: ICCPMessage) → None[source]

Handle wrong message received from component.

Parameters:

  • channel (Channel) – Channel associated with component.

  • session (Session) – Session associated with component.

  • msg (ICCPMessage) – Message sent by component.

Return type:

None

Raises StopError, which in turn calls on_exception from handle_msg.

on_stop_controller

eventsocket called when controller should stop its operation due to error condition.

Parameters:

exc – Exception that describes the reason why component should stop.