lce_service.remote_toolbox.local module

class lce_service.remote_toolbox.local.LocalRun(rows: List[Dict[str, Any]], state: int, returncode: int | None, seconds_elapsed: int, seconds_since_last_output: int | None, timed_out: bool = False, output_limited: bool = False)

Bases: NamedTuple

The output and outcome of a Remote Toolbox command run on this host rather than queued.

The rows are the ones the Remote Toolbox would have written to the output table for the same command, numbered from one, so the readers that page, stitch and reassemble queued output read a local run by exactly the same rules.

Variables:

  • rows – The output rows in the order they were produced, each holding an id, a message type and a raw message.

  • state – The spool state the toolbox would have recorded: finished, or failed when the command could not be decoded or launched.

  • returncode – The command’s exit status, or None when it never ran or was killed.

  • seconds_elapsed – How long the run took.

  • seconds_since_last_output – How long before the run ended its last row was produced.

  • timed_out – Whether the command was killed for running past its timeout, in which case the rows end without the completed row.

  • output_limited – Whether the command wrote more than MAX_LOCAL_OUTPUT_BYTES, in which case every line past the limit was discarded.

framed_payload(marker: str, chunk_size: int, max_chars: int) → FramedPayload

Reassembles the payload the command wrote behind a marker, as read_framed_payload does.

Parameters:

  • marker – The marker that starts every chunk.

  • chunk_size – The length the writer cuts every chunk but the last to.

  • max_chars – The most characters of payload to reassemble.

Returns:

A FramedPayload.

output_limited: bool

Alias for field number 6

page(exclude_prefix: str | None = None) → OutputPage

Returns the whole run’s output as one page.

Every row is returned, since a local run has no request to page through later, but each record is still bounded as a queued run’s is, so the text is what a caller that read a queued run page by page would have joined together.

Parameters:

exclude_prefix – Leave out standard output rows starting with this marker, as a read of queued output does.

Returns:

An OutputPage holding every row, terminated unless the run timed out, and truncated when output past MAX_LOCAL_OUTPUT_BYTES was discarded.

progress(exclude_prefix: str | None = None) → JobProgress

Returns the run’s progress, as get_job_progress reports a queued run’s.

Parameters:

exclude_prefix – Leave out the same rows the page leaves out.

Returns:

A JobProgress for a run that has finished.

returncode: int | None

Alias for field number 2

rows: List[Dict[str, Any]]

Alias for field number 0

seconds_elapsed: int

Alias for field number 3

seconds_since_last_output: int | None

Alias for field number 4

state: int

Alias for field number 1

timed_out: bool

Alias for field number 5

exception lce_service.remote_toolbox.local.LocalRunLimitError(limit: int = 5)

Bases: RuntimeError

Exception raised when a local run is asked for while MAX_CONCURRENT_LOCAL_RUNS are running.

Parameters:

limit – The number of local runs that may execute at once.

lce_service.remote_toolbox.local.decode_queued_command(command: str) → List[str]

Splits a command into the argv the Remote Toolbox would run for it.

This is admin_toolbox._decode_siloproc applied to the command as queue_toolbox_command queues it, behind the marker. The toolbox escapes every quote before splitting, so a quote reaches the command as a literal character rather than grouping words, and the commands this service builds rely on that. Splitting the command any other way would run a different argv here than on a collector.

Parameters:

command – The command, without the Remote Toolbox marker.

Returns:

The argv, without the line buffering prefix.

Raises:

ValueError – Raised, as the toolbox raises it, when the command cannot be split.

lce_service.remote_toolbox.local.run_toolbox_command_locally(command: str, timeout: float = 90.0, description: str = 'Remote Toolbox command', max_output_bytes: int = 33554432) → LocalRun

Runs a Remote Toolbox command on this host and records its output as the toolbox would.

The command is the one queue_toolbox_command would queue, so it is refused for the same reason: one that already carries the toolbox marker would be decoded differently from the command given. It is then decoded, launched and read the way the toolbox does it, without a shell.

Parameters:

  • command – The command to run, without the Remote Toolbox marker.

  • timeout – How long the command may run before it is killed.

  • description – What the command is, in the caller’s terms, for the error message.

  • max_output_bytes – The most bytes of the command’s output to keep.

Returns:

A LocalRun holding the rows the toolbox would have written and the outcome.

Raises: