lce_service.remote_toolbox.core module

exception lce_service.remote_toolbox.core.InvalidToolboxRequestError(message: str)

Bases: ValueError

Exception raised when a request cannot be turned into a safe Remote Toolbox command.

Each API built on the Remote Toolbox subclasses this for its own validation errors, so an endpoint can report any of them, including the ones raised by this shared layer, as bad input with a single handler.

Parameters:

message – A descriptive error message explaining which value was rejected and what shape was expected, suitable for returning to the caller.

exception lce_service.remote_toolbox.core.ToolboxJobNotAccessible(proc_id: int, message: str | None = None)

Bases: LookupError

Exception raised when a Remote Toolbox job cannot be read by the requesting user.

This error is deliberately raised with the same message for every reason a job is not readable: the job id was never issued, the job belongs to a different Remote Toolbox tool, the job was started by another user, or the job has no recorded owner at all. Distinguishing those cases would turn a read endpoint into an oracle for which job ids exist, and the rows it guards are shared with every other toolbox tool.

Parameters:

  • proc_id – The process id the caller asked for.

  • message – The message to report. Subclasses supply one naming what the caller asked for; it must not vary with the reason the job was refused.

lce_service.remote_toolbox.core.get_collecting_appliance(dbc: silo_cursor, appliance_identifier: Any) → Dict[str, Any]

Looks up a collecting appliance by numeric id or by name.

Only appliances that actually collect are returned. A Database Server is rejected even when the identifier matches, because a Remote Toolbox command queued against an appliance that does not collect is a command nothing runs.

Parameters:

  • dbc – A silo_cursor instance used to query the appliance table.

  • appliance_identifier – The numeric appliance id, or the appliance name.

Returns:

A dictionary holding the appliance id, name, ip and function.

Raises:
lce_service.remote_toolbox.core.get_collecting_appliances(dbc: silo_cursor) → List[Dict[str, Any]]

Lists every appliance that collects, and therefore runs Remote Toolbox commands.

A Database Server is excluded even though it is an appliance, because it does not collect and a command queued against one would never run.

Parameters:

dbc – A silo_cursor instance used to query the appliance table.

Returns:

One dictionary per collecting appliance, holding its id, name, ip and function, ordered by name.

Raises:

DatabaseExecutionError – Raised when the appliance lookup fails to execute.

lce_service.remote_toolbox.core.is_aio_appliance() → bool

Determines whether this host is an All-In-One, as the platform’s isAioAppliance does.

The model type is read from silo.conf, at SILO_CONFFILE when it is set. It is read once and kept, since an appliance’s model type does not change while the service runs, so a request neither reads the file nor, when it cannot be read, logs the warning again.

Returns:

True when the model type is SILO_MODEL_AIO, and False otherwise, including when the file or its model type cannot be read.

lce_service.remote_toolbox.core.parse_digit_string(value: str) → int | None

Converts a string holding nothing but digits into the number it spells.

Only a string of ASCII digits is converted, so none of the extra syntax int() accepts can arrive as a number: surrounding whitespace is ignored, but a sign, a decimal point, the digit separators PEP 515 allows, and the digits of other scripts that int() also reads all mean the value is not a number at all.

Parameters:

value – The string to convert.

Returns:

The number the string spells, or None when the string does not spell one.

lce_service.remote_toolbox.core.validate_collector_identifier(appliance_identifier: Any, error: Type[InvalidToolboxRequestError] = <class 'lce_service.remote_toolbox.core.InvalidToolboxRequestError'>) → None

Checks that a collector identifier is an id or a name, without looking the collector up.

A local run ignores the collector it is given, but a malformed one is still refused, so a request is refused for the same value whichever way it runs.

Parameters:

  • appliance_identifier – The collector identifier supplied by the caller, or None when none was given.

  • error – The InvalidToolboxRequestError subclass to raise.

Raises:

InvalidToolboxRequestError – Raised, as error, when the identifier is neither a whole number nor a non-blank string.

lce_service.remote_toolbox.core.validate_flag(value: Any, field_name: str, default: bool | None, error: Type[InvalidToolboxRequestError] = <class 'lce_service.remote_toolbox.core.InvalidToolboxRequestError'>) → bool | None

Validates a boolean field of a Remote Toolbox request.

A JSON boolean is accepted, and so are the numbers 0 and 1, which is how the platform’s own editors send these flags. Anything else is refused rather than read by truthiness, so a string such as “false” can never turn a flag on.

Parameters:

  • value – The value as supplied, or None when the field was not given.

  • field_name – The name of the field, used in the error message.

  • default – The value to use when the field was not given.

  • error – The InvalidToolboxRequestError subclass to raise.

Returns:

The flag.

Raises:

InvalidToolboxRequestError – Raised, as error, when the value is not a boolean, 0 or 1.

lce_service.remote_toolbox.core.validate_run_local(value: Any, error: Type[InvalidToolboxRequestError] = <class 'lce_service.remote_toolbox.core.InvalidToolboxRequestError'>) → bool

Validates the field that runs a Remote Toolbox tool on this host rather than queueing it.

Left out, a tool runs locally on an All-In-One, which is its own collector, and is queued everywhere else. A collector named for a local run is ignored, since the run reads this host.

Parameters:

  • value – The value as supplied, or None when the field was not given.

  • error – The InvalidToolboxRequestError subclass to raise.

Returns:

Whether to run the tool locally.

Raises:

InvalidToolboxRequestError – Raised, as error, when the value is not a boolean, 0 or 1.