cyst.api.host.service

class cyst.api.host.service.Service

Bases: ABC

Service represents an abstraction of any notable process that is running on a node. Services exist in two flavors: passive and active. Active services can initiate request-response exchange and manage their own response processing. Passive services exist only as a descriptions of their properties and their responses are evaluated by the environment.

abstract property name: str

The name of the service. This name is unique within a node and serves as a destination name for messages.

Return type:: str

abstract property owner: str

The identity of the owner of the service.

Return type:: str

abstract property service_access_level: AccessLevel

The access level with which the service can access resources of the node.

Return type:: AccessLevel

abstract property passive_service: PassiveService | None

If the service is a passive one, this function gives access to its PassiveService interface.

Return type:: Optional[PassiveService]

Changed in version 0.6.0: Changed to return Optional

abstract property active_service: ActiveService | None

If the service is an active one, this function gives access to its ActiveService interface.

Return type:: Optional[ActiveService]

Changed in version 0.6.0: Changed to return Optional

class cyst.api.host.service.ActiveService

Bases: ABC

Active service is used to model any active actor within the simulation. Every agent that is being run in the simulation must implement this interface.

abstractmethod async run() → None: Starts the service. This function si automatically called by the environment at the initialization.

abstractmethod async process_message(message: Message) → Tuple[bool, int]

This function is called by the environment whenever a message arrives at the service.

Parameters:: message (Message) – The message to process.
Returns:: A tuple indicating, whether the processing was successful and eventually, how long the processing took. Depending on the role of the service, this return value results in different outcomes. For traffic, processors, i.e., services that process messages before they arrive into their final destination, returning (False, _) results in dropping of the message at that point. After returning (True, _) the messages is passed further. For destination services the resulting value currently does not play a role. Both types of services are expected to create and send an appropriate response. TODO: This should have the same result as the behavioral models and return a Response. That way, there can be a failsafe built-in.
Return type:: Tuple[bool, int]

class cyst.api.host.service.ActiveServiceDescription(name: str, description: str, creation_fn: Callable[[cyst.api.environment.messaging.EnvironmentMessaging, cyst.api.environment.resources.EnvironmentResources, str, Dict[str, Any] | None], ActiveService])

Bases: object

This is a description of an active service. It is used to register a new active service into the system.

Parameters:

name (str) – A name of the active service. It has to be unique among other registered services.
description (str) – A short description of the service purpose and function.
creation_fn (Callable[[EnvironmentMessaging, EnvironmentResources, str, Optional[Dict[str, Any]]], ActiveService]) – A function that is able to create instances of the service. In addition to environment interfaces, the id and configuration dictionary is passed to service as well.

class cyst.api.host.service.ServiceState(*values)

Bases: IntEnum

Service state represents the state of a service.

Possible values:

INIT:: A state that used when service is created and before environment was started.
RUNNING:: A default state that is set when the environment has started.
PAUSED:: A state in which service can’t be accessed, but can be reactivated.
ZOMBIE:: A state in which service can’t be accessed and can’t be reactivated.

class cyst.api.host.service.PassiveService

Bases: Service, ABC

Passive service is used to model an arbitrary service running on a node, which only passively reacts to the actions by other actors within a simulation.

abstract property version: Version

The version of the service.

Return type:: VersionInfo

abstract property state: ServiceState

The state of the service.

Return type:: ServiceState

abstract property tags: Set[Tag]

Set of tags describing the service. It should provide high-level specification of service purpose. In the future, we expect to have a complete domain of services, from which the tags could be chosen. This will also be beneficial for automated generation of simulation scenarios.

Return type:: Set[Tag]

abstract property enable_session: bool

Returns, whether the service enables creation of sessions.

Return type:: bool

abstract property session_access_level: AccessLevel

Returns an access level of eventual sessions. This can be different from the access level of the service itself. For example ssh has elevated access level, but its sessions only have user level access.

Return type:: AccessLevel

abstract property local: bool

Returns whether the service is accessible from the network, or if the only way to address it is from the same node.

Return type:: bool