Monitor

The monitor is an optional object provided by this library that can be used on top of an existing Controller to get notified when the global status of the Tor daemon changes.

At first we introduce a ControllerStatus which is a dataclasses.dataclass() used to record the global status of a controller, then we describe the Monitor itself.

class aiostem.monitor.ControllerStatus

Keep track of the Controller’s status.

It is used to keep track of various status parameters from Tor’s daemon.

bootstrap: Annotated[int]

Tor’s bootstrap progress status (in percent).

has_circuits: bool

Whether Tor has established circuits.

has_dir_info: bool

Whether Tor has enough directory information.

net_liveness: bool

Whether Tor has a working network.

property is_healthy: bool

Tell whether we are healthy enough to run workers.

Returns:

A boolean value that tells whether we are healthy or not.

class aiostem.monitor.Monitor

Monitor controller’s status.

__init__(controller: Controller, *, keepalive: bool = True) → None

Create a new instance of a monitor to check for Tor’s daemon status.

Parameters:

controller (Controller) – a controller connected to Tor’s daemon

Keyword Arguments:

keepalive – whether we should run a task to keep Tor in ACTIVE mode.

async __aenter__() → Self

Start the controller’s monitoring.

This subscribes to relevant events from the controller and optionally starts the keep-alive task used to ensure that Tor always stay ACTIVE. This later part is important if you don’t plan on using the socks port but will only use the control port.

Raises:

RuntimeError – when the controller has already been entered

Returns:

Self – The exact same Monitor object.

async __aexit__(exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: TracebackType | None) → bool

Exit the monitor’s context and unregister from the underlying events.

Returns:

bool – False to let any exception flow through the call stack.

property condition: Condition

Get the underlying asyncio condition.

This condition is triggered when any update has been received, which does not guarantee that the global health status has changed.

USE EXAMPLE:

async with monitor.condition:
    await monitor.condition.wait_for(lambda: monitor.is_healthy)
    print('Monitor is now healthy.')

property is_entered: bool

Tell whether the monitor context is currently entered.

property is_healthy: bool

Tell whether the underlying controller is healthy.

This is a shorthand for monitor.status.is_healthy.

property status: ControllerStatus

Get the current controller status.

Note that this status is no a copy but a reference to the internal status. Any change on its field values have consequences on the Monitor’s view.

async wait_for_error() → ControllerStatus

Wait until the controller stops being healthy.

This method can be implemented using condition, is_healthy and status.

Returns:

ControllerStatus – The current controller’s status.

async wait_until_healthy() → ControllerStatus

Wait until the controller is ready and healthy.

This method can be implemented using condition, is_healthy and status.

Returns:

ControllerStatus – The current controller’s status.