archivebox.core.takeover_util

Coordinate local foreground processes without pretending to provide a distributed lock.

ArchiveBox wants one orchestrator per collection, but Process rows can only prove liveness for PIDs visible on the current machine/PID namespace. We therefore enforce one active runner per (Machine, DATA_DIR) locally, retire stale rows from sequential containers on that machine, and only warn about rows owned by a different machine. Foreign-machine rows must never block progress or be killed: multi-machine coordination belongs in the Crawl/Snapshot CAS claim layer, not in process takeover.

These helpers only hand local supervisord/runner ownership between CLI parents. They must not hold database transactions or filesystem locks while work runs.

Module Contents

Functions

current_command
runtime_stack_owner	Return the live local parent allowed to own the server runtime stack.
command_owns_runtime_stack
foreground_runner_owner	Return the newest live local parent allowed to borrow runner/sonic.
command_owns_foreground_runner
ensure_daemon_stack
live_runner_processes	Return locally verifiable runners and warn about unsupported overlap.
enter_single_runner_gate	Admit one active runner for this Machine and DATA_DIR using Process rows.
standby_until_runtime_stack_needed
standby_until_foreground_runner_needed

Data

RUNNER_ACTIVE_WORKER_TYPE
RUNNER_WAITING_WORKER_TYPE
RUNNER_GATE_WORKER_TYPES

API

archivebox.core.takeover_util.RUNNER_ACTIVE_WORKER_TYPE

‘worker_runner’

archivebox.core.takeover_util.RUNNER_WAITING_WORKER_TYPE

‘runner_waiting’

archivebox.core.takeover_util.RUNNER_GATE_WORKER_TYPES

()

archivebox.core.takeover_util.current_command(process_type: str, *, data_dir: str | pathlib.Path, url: str | None = None)

archivebox.core.takeover_util.runtime_stack_owner(*, data_dir: str | pathlib.Path, exclude_id=None)

Return the live local parent allowed to own the server runtime stack.

archivebox.core.takeover_util.command_owns_runtime_stack(command, *, data_dir: str | pathlib.Path) → bool

archivebox.core.takeover_util.foreground_runner_owner(*, data_dir: str | pathlib.Path, exclude_id=None)

Return the newest live local parent allowed to borrow runner/sonic.

archivebox.core.takeover_util.command_owns_foreground_runner(command, *, data_dir: str | pathlib.Path) → bool

archivebox.core.takeover_util.ensure_daemon_stack(*, reason: str = '')

archivebox.core.takeover_util.live_runner_processes(*, data_dir: str | pathlib.Path)

Return locally verifiable runners and warn about unsupported overlap.

A Process row from another machine is observability only: its PID cannot be checked or signalled here, so it neither joins the local election nor gets mutated. A row for this same Machine from another PID namespace represents a previous sequential container under the supported model; warn, retire the unreachable row, and let the new container continue.

archivebox.core.takeover_util.enter_single_runner_gate(command, *, data_dir: str | pathlib.Path, graceful_timeout: float = 5.0) → bool

Admit one active runner for this Machine and DATA_DIR using Process rows.

The current process is a real OS process while it waits, so we keep its Process row RUNNING but mark worker_type=runner_waiting. Only the process that wins takeover is promoted to worker_type=worker_runner, which is protected by a partial unique DB constraint scoped to (Machine, DATA_DIR). Older locally verifiable runners are terminated and fully waited out before promotion, so runner work never overlaps on one machine. Foreign machines are intentionally outside this gate and only produce a warning above.

archivebox.core.takeover_util.standby_until_runtime_stack_needed(command, *, data_dir: str | pathlib.Path, interval: float = 2.0) → dict[str, object]

archivebox.core.takeover_util.standby_until_foreground_runner_needed(command, *, data_dir: str | pathlib.Path, interval: float = 2.0, work_is_complete: collections.abc.Callable[[], bool] | None = None) → dict[str, object]