saturnin.protocol.iccp¶

Saturnin Internal Component Control Protocol

Enums¶

class saturnin.protocol.iccp.MsgType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Bases: IntEnum

Control message type.

ERROR = 4¶

FINISHED = 6¶

OK = 3¶

READY = 1¶

REQUEST = 2¶

STOP = 5¶

class saturnin.protocol.iccp.Request(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Bases: Enum

Service Controller Request Codes.

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.

Return type:: TZMQMessage

clear() → None[source]¶

Clears message data.

Return type:: None

copy() → Message[source]¶

Returns copy of the message.

Return type:: Message

from_zmsg(zmsg: TZMQMessage) → None[source]¶

Populate message data from sequence of ZMQ data frames.

Parameters:: zmsg (TZMQMessage) – Sequence of frames that should be deserialized.
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: TZMQMessage = None) → Message¶

Internal message factory

Parameters:: zmsg (TZMQMessage) –
Return type:: Message

__init__(*, session_type: ~typing.Type[~saturnin.base.transport.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.
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.

property logging_id: str¶: Returns _logging_id_ or <class_name>

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: ~typing.Type[~saturnin.base.transport.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.

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.

Parameters:

channel (Channel) – Channel that received the message.
session (Session) – Session instance.
msg (ICCPMessage) – Received message.

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:

peer (PeerDescriptor) – Component descriptor.
endpoints (Dict[str, List[ZMQAddress]]) – Component endpoints.

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 controller requested reconfiguration.

Any exception raised by event handler is returned back to controller via ERROR message.

Parameters:: config – New configuration provided by 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.

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: ~typing.Type[~saturnin.base.transport.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:

channel (Channel) – Channel associated with component.
session (Session) – Session associated with component.
exc (InvalidMessageError) – Exception raised.

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]¶

Process READY message received from component.

Parameters:

channel (Channel) – Channel associated with component.
session (Session) – Session associated with component.
msg (ICCPMessage) – Message sent by component.

Returns:

Received READY message if it’s the first one from component.

Raises:

StopError – If it’s NOT first READY received from component.

Return type:

ICCPMessage

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

Returns REQUEST.CONFIG control message.

Parameters:: config (Config) – Configuration for component.
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.