archivebox.machine.models

Module Contents

Classes

MachineManager
Machine
NetworkInterfaceManager
NetworkInterface
BinaryManager
Binary	Tracks a binary on a specific machine.
ProcessManager	Manager for Process model.
Process	Tracks a single OS process execution.
BinaryMachine	State machine for managing Binary installation lifecycle.
ProcessMachine	State machine for managing Process (OS subprocess) lifecycle.

Functions

_find_existing_binary_for_reference
_canonical_binary_name
_get_process_binary_env_keys
_sanitize_machine_config	Validate Machine.config in place.

Data

_psutil
_CURRENT_MACHINE
_CURRENT_INTERFACE
_CURRENT_BINARIES
_CURRENT_PROCESS
MACHINE_RECHECK_INTERVAL
NETWORK_INTERFACE_RECHECK_INTERVAL
BINARY_RECHECK_INTERVAL
PROCESS_RECHECK_INTERVAL
PID_REUSE_WINDOW
PROCESS_TIMEOUT_GRACE
START_TIME_TOLERANCE

API

archivebox.machine.models._psutil: Any | None

None

archivebox.machine.models._CURRENT_MACHINE: archivebox.machine.models.Machine | None

None

archivebox.machine.models._CURRENT_INTERFACE: archivebox.machine.models.NetworkInterface | None

None

archivebox.machine.models._CURRENT_BINARIES: dict[str, archivebox.machine.models.Binary]

None

archivebox.machine.models._CURRENT_PROCESS: archivebox.machine.models.Process | None

None

archivebox.machine.models.MACHINE_RECHECK_INTERVAL

None

archivebox.machine.models.NETWORK_INTERFACE_RECHECK_INTERVAL

None

archivebox.machine.models.BINARY_RECHECK_INTERVAL

None

archivebox.machine.models.PROCESS_RECHECK_INTERVAL

60

archivebox.machine.models.PID_REUSE_WINDOW

‘timedelta(…)’

archivebox.machine.models.PROCESS_TIMEOUT_GRACE

‘timedelta(…)’

archivebox.machine.models.START_TIME_TOLERANCE

5.0

archivebox.machine.models._find_existing_binary_for_reference(machine: Machine, reference: str) → Binary | None

archivebox.machine.models._canonical_binary_name(name: Any) → str

archivebox.machine.models._get_process_binary_env_keys(plugin_name: str, hook_path: str, env: dict[str, Any] | None) → list[str]

archivebox.machine.models._sanitize_machine_config(config: dict[str, Any] | None, *, lib_dir: str | pathlib.Path | None = None) → dict[str, Any]

Validate Machine.config in place.

Drops stale *_BINARY overrides whose path no longer exists or whose path falls outside of LIB_DIR (so a binary uninstall or a lib_dir move clears the override automatically). Non-_BINARY keys (BASE_URL, SERVER_SECURITY_MODE, plugin tunables, etc.) are pass-through — they’re arbitrary config overrides and not ours to filter.

class archivebox.machine.models.MachineManager

Bases: django.db.models.Manager

current() → archivebox.machine.models.Machine

class archivebox.machine.models.Machine

Bases: archivebox.base_models.models.ModelWithHealthStats

id

‘CompactUUIDField(…)’

created_at

‘DateTimeField(…)’

modified_at

‘DateTimeField(…)’

guid

‘CharField(…)’

hostname

‘CharField(…)’

hw_in_docker

‘BooleanField(…)’

hw_in_vm

‘BooleanField(…)’

hw_manufacturer

‘CharField(…)’

hw_product

‘CharField(…)’

hw_uuid

‘CharField(…)’

os_arch

‘CharField(…)’

os_family

‘CharField(…)’

os_platform

‘CharField(…)’

os_release

‘CharField(…)’

os_kernel

‘CharField(…)’

stats

‘JSONField(…)’

config

‘JSONField(…)’

num_uses_failed

‘PositiveIntegerField(…)’

num_uses_succeeded

‘PositiveIntegerField(…)’

objects

‘MachineManager(…)’

networkinterface_set: django.db.models.Manager[NetworkInterface]

None

class Meta

Bases: archivebox.base_models.models.ModelWithHealthStats.Meta

app_label

‘machine’

classmethod current(refresh: bool = False) → archivebox.machine.models.Machine

classmethod _sanitize_config(machine: archivebox.machine.models.Machine) → archivebox.machine.models.Machine

to_json() → dict

Convert Machine model instance to a JSON-serializable dict.

static from_json(record: dict[str, Any], overrides: dict[str, Any] | None = None)

Update Machine config from JSON dict.

Args: record: JSON dict with ‘config’: {key: value} patch overrides: Not used

Returns: Machine instance or None

save(*args, **kwargs)

class archivebox.machine.models.NetworkInterfaceManager

Bases: django.db.models.Manager

current() → archivebox.machine.models.NetworkInterface

class archivebox.machine.models.NetworkInterface

Bases: archivebox.base_models.models.ModelWithHealthStats

id

‘CompactUUIDField(…)’

created_at

‘DateTimeField(…)’

modified_at

‘DateTimeField(…)’

machine

‘ForeignKey(…)’

mac_address

‘CharField(…)’

ip_public

‘GenericIPAddressField(…)’

ip_local

‘GenericIPAddressField(…)’

dns_server

‘GenericIPAddressField(…)’

hostname

‘CharField(…)’

iface

‘CharField(…)’

isp

‘CharField(…)’

city

‘CharField(…)’

region

‘CharField(…)’

country

‘CharField(…)’

objects

‘NetworkInterfaceManager(…)’

machine_id: uuid.UUID

None

class Meta

Bases: archivebox.base_models.models.ModelWithHealthStats.Meta

app_label

‘machine’

unique_together

((‘machine’, ‘ip_public’, ‘ip_local’, ‘mac_address’, ‘dns_server’),)

constraints

None

classmethod current(refresh: bool = False) → archivebox.machine.models.NetworkInterface

class archivebox.machine.models.BinaryManager

Bases: django.db.models.Manager

get_from_db_or_cache(name: str, abspath: str = '', version: str = '', sha256: str = '', binprovider: str = 'env') → archivebox.machine.models.Binary

Get or create an Binary record from the database or cache.

get_valid_binary(name: str, machine: archivebox.machine.models.Machine | None = None) → archivebox.machine.models.Binary | None

Get a valid Binary for the given name on the current machine, or None if not found.

class archivebox.machine.models.Binary

Bases: archivebox.base_models.models.ModelWithHealthStats, archivebox.workers.models.ModelWithStateMachine

Tracks a binary on a specific machine.

Simple state machine with 2 states:

• queued: Binary needs to be installed

• installed: Binary installed successfully (abspath, version, sha256 populated)

Installation is synchronous during queued→installed transition. If installation fails, Binary stays in queued with retry_at set for later retry.

State machine calls run(), which emits an abxpkg BinaryRequestEvent through the ArchiveBox runner and installs the binary using the specified providers.

class StatusChoices

Bases: django.db.models.TextChoices

QUEUED

(‘queued’, ‘Queued’)

INSTALLED

(‘installed’, ‘Installed’)

id

‘CompactUUIDField(…)’

created_at

‘DateTimeField(…)’

modified_at

‘DateTimeField(…)’

machine

‘ForeignKey(…)’

name

‘CharField(…)’

binproviders

‘CharField(…)’

overrides

‘JSONField(…)’

binprovider

‘CharField(…)’

abspath

‘CharField(…)’

version

‘CharField(…)’

sha256

‘CharField(…)’

status

‘StatusField(…)’

retry_at

‘RetryAtField(…)’

num_uses_failed

‘PositiveIntegerField(…)’

num_uses_succeeded

‘PositiveIntegerField(…)’

machine_id: uuid.UUID

None

state_machine_name: str | None

‘archivebox.machine.models.BinaryMachine’

active_state: str

None

warn_on_save_outside_runner

False

objects

‘BinaryManager(…)’

class Meta

Bases: archivebox.base_models.models.ModelWithHealthStats.Meta, archivebox.workers.models.ModelWithStateMachine.Meta

app_label

‘machine’

verbose_name

‘Binary’

verbose_name_plural

‘Binaries’

unique_together

((‘machine’, ‘name’, ‘abspath’, ‘version’, ‘sha256’),)

__str__() → str

property is_valid: bool

A binary is valid if it has a resolved path and is marked installed.

binary_info() → dict

Return info about the binary.

property output_dir: pathlib.Path

Get output directory for this binary’s hook logs. Path: data/machines/{machine_uuid}/binaries/{binary_name}/{binary_uuid}

to_json() → dict

Convert Binary model instance to a JSON-serializable dict.

static from_json(record: dict[str, Any], overrides: dict[str, Any] | None = None)

Create/update Binary from JSON dict.

Handles two cases:

1. From binaries.json: creates queued binary with name, binproviders, overrides

2. From hook output: updates binary with abspath, version, sha256, binprovider

Args: record: JSON dict with ‘name’ and either: - ‘binproviders’, ‘overrides’ (from binaries.json) - ‘abspath’, ‘version’, ‘sha256’, ‘binprovider’ (from hook output) overrides: Not used

Returns: Binary instance or None

_allowed_binproviders() → set[str] | None

Return the allowed binproviders for this binary, or None for wildcard.

run()

Execute binary installation through the ArchiveBox binary runner.

cleanup()

Clean up background binary installation hooks.

Called by state machine if needed (not typically used for binaries since installations are foreground, but included for consistency).

symlink_to_lib_bin(lib_bin_dir: str | pathlib.Path) → pathlib.Path | None

Symlink this binary into LIB_BIN_DIR for human-facing convenience.

After a binary is installed by any binprovider (pip, npm, brew, apt, etc), we can optionally expose a flat convenience directory for shell users. ArchiveBox/abx-dl runtime lookup must use the provider-specific LIB_DIR paths, not this indirection.

Args: lib_bin_dir: Path to LIB_BIN_DIR (e.g., /data/lib/arm64-darwin/bin)

Returns: Path to the created symlink, or None if symlinking failed

Example: >>> binary = Binary.objects.get(name=’yt-dlp’) >>> binary.symlink_to_lib_bin(‘/data/lib/arm64-darwin/bin’) Path(‘/data/lib/arm64-darwin/bin/yt-dlp’)

symlink_to_lib_bin_after_commit(lib_bin_dir: str | pathlib.Path) → None

Symlink after the current DB transaction commits.

Binary rows are projections of provider/hook state and are allowed to be updated directly, but filesystem writes must not run while an outer transaction is still open. Refetch after commit so the symlink points at the committed row, not a possibly-rolled-back in-memory value.

class archivebox.machine.models.ProcessManager

Bases: django.db.models.Manager

Manager for Process model.

current() → archivebox.machine.models.Process

Get the Process record for the current OS process.

get_by_pid(pid: int, machine: archivebox.machine.models.Machine | None = None) → archivebox.machine.models.Process | None

Find a Process by PID with proper validation against PID reuse.

IMPORTANT: PIDs are reused by the OS! This method:

1. Filters by machine (required - PIDs are only unique per machine)

2. Filters by time window (processes older than 24h are stale)

3. Validates via psutil that start times match

Args: pid: OS process ID machine: Machine instance (defaults to current machine)

Returns: Process if found and validated, None otherwise

create_for_archiveresult(archiveresult, **kwargs)

Create a Process record for an ArchiveResult.

Called during migration and when creating new ArchiveResults.

class archivebox.machine.models.Process

Bases: archivebox.base_models.models.ModelWithDeleteAfter, django.db.models.Model

Tracks a single OS process execution.

Process represents the actual subprocess spawned to execute a hook. One Process can optionally be associated with an ArchiveResult (via OneToOne), but Process can also exist standalone for internal operations.

Follows the unified state machine pattern:

• queued: Process ready to launch

• running: Process actively executing

• exited: Process completed (check exit_code for success/failure)

State machine calls launch() to spawn the process and monitors its lifecycle.

class StatusChoices

Bases: django.db.models.TextChoices

QUEUED

(‘queued’, ‘Queued’)

RUNNING

(‘running’, ‘Running’)

EXITED

(‘exited’, ‘Exited’)

class TypeChoices

Bases: django.db.models.TextChoices

SUPERVISORD

(‘supervisord’, ‘Supervisord’)

ORCHESTRATOR

(‘orchestrator’, ‘Orchestrator’)

SERVER

(‘server’, ‘Server’)

UPDATE

(‘update’, ‘Update’)

ADD

(‘add’, ‘Add’)

SEARCH

(‘search’, ‘Search’)

WORKER

(‘worker’, ‘Worker’)

CLI

(‘cli’, ‘CLI’)

HOOK

(‘hook’, ‘Hook’)

BINARY

(‘binary’, ‘Binary’)

id

‘CompactUUIDField(…)’

created_at

‘DateTimeField(…)’

modified_at

‘DateTimeField(…)’

machine

‘ForeignKey(…)’

parent

‘ForeignKey(…)’

process_type

‘CharField(…)’

worker_type

‘CharField(…)’

pwd

‘CharField(…)’

cmd

‘JSONField(…)’

env

‘JSONField(…)’

timeout

‘IntegerField(…)’

pid

‘IntegerField(…)’

exit_code

‘IntegerField(…)’

stdout

‘TextField(…)’

stderr

‘TextField(…)’

started_at

‘DateTimeField(…)’

ended_at

‘DateTimeField(…)’

binary

‘ForeignKey(…)’

iface

‘ForeignKey(…)’

url

‘URLField(…)’

status

‘CharField(…)’

retry_at

‘DateTimeField(…)’

machine_id: uuid.UUID

None

parent_id: uuid.UUID | None

None

binary_id: uuid.UUID | None

None

children: django.db.models.Manager[archivebox.machine.models.Process]

None

archiveresult: archivebox.core.models.ArchiveResult

None

state_machine_name: str

‘archivebox.machine.models.ProcessMachine’

delete_after_final_statuses

()

objects

‘ProcessManager(…)’

class Meta

Bases: archivebox.base_models.models.ModelWithDeleteAfter.Meta

app_label

‘machine’

verbose_name

‘Process’

verbose_name_plural

‘Processes’

indexes

None

constraints

None

__str__() → str

get_delete_after_config_value()

classmethod missing_delete_at_candidates()

property cmd_version: str

Get version from associated binary.

property bin_abspath: str

Get absolute path from associated binary.

property plugin: str

Get plugin name from associated ArchiveResult (if any).

property hook_name: str

Get hook name from associated ArchiveResult (if any).

to_json() → dict

Convert Process model instance to a JSON-serializable dict.

hydrate_binary_from_context(*, plugin_name: str = '', hook_path: str = '') → archivebox.machine.models.Binary | None

classmethod parse_records_from_text(text: str) → list[dict]

Parse JSONL records from raw text using the shared JSONL parser.

get_records() → list[dict]

Parse JSONL records from this process’s stdout.

static from_json(record: dict[str, Any], overrides: dict[str, Any] | None = None)

Create/update Process from JSON dict.

Args: record: JSON dict with ‘id’ or process details overrides: Optional dict of field overrides

Returns: Process instance or None

safe_update(update_fields: dict[str, Any], *, refresh: bool = True, extra_filter: dict[str, Any] | None = None) → bool

Compare-and-swap update for short Process scheduler writes.

Process is not a ModelWithStateMachine subclass yet, but its state-machine methods still need the same modified_at CAS behavior as Crawl/Snapshot/Binary without falling back to save().

update_and_requeue(**kwargs) → bool

Scheduler-facing wrapper around safe_update().

mark_running(*, process_type: str | None = None, pwd: str | pathlib.Path | None = None, url: str | None = None, worker_type: str = '', timeout: int | None = None) → None

Record the current process role without changing ownership state elsewhere.

heartbeat() → None

Touch modified_at so standby/leader selection can see this parent is alive.

mark_exited(*, exit_code: int = 0) → None

Mark a foreground/internal process row exited after command cleanup.

classmethod current() → archivebox.machine.models.Process

Get or create the Process record for the current OS process.

Similar to Machine.current(), this:

1. Checks cache for existing Process with matching PID

2. Validates the cached Process is still valid (PID not reused)

3. Creates new Process if needed

IMPORTANT: Uses psutil to validate PID hasn’t been reused. PIDs are recycled by OS, so we compare start times.

classmethod _find_parent_process(machine: archivebox.machine.models.Machine | None = None) → archivebox.machine.models.Process | None

Find the parent Process record by looking up PPID.

IMPORTANT: Validates against PID reuse by checking:

1. Same machine (PIDs are only unique per machine)

2. Start time matches OS process start time

3. Process is still RUNNING and recent

Returns None if parent is not an ArchiveBox process.

classmethod _detect_process_type() → str

Detect the type of the current process from sys.argv.

archivebox add --bg is a fire-and-forget queue write — it does not run the runner or own the runtime stack — so it’s classified as CLI instead of ADD. The ADD process_type is reserved for the foreground archivebox add flow that actually takes over the runtime stack via current_command(TypeChoices.ADD, ...). Misclassifying --bg as ADD makes runtime_stack_owner treat it as a newer stack owner for the few seconds it’s alive, knocks the running archivebox server out of leadership, and triggers a supervisord tear-down + respawn cycle (~5s of dead time per add). Detecting bg here at insert time avoids any race window where the row briefly exists as ADD before a higher-level demotion.

classmethod cleanup_stale_running(machine: archivebox.machine.models.Machine | None = None) → int

Mark stale RUNNING processes as EXITED in the DB.

Processes are stale if:

• Status is RUNNING but OS process no longer exists

• Status is RUNNING but exceeded its timeout plus a small grace margin

• Status is RUNNING but started_at is older than PID_REUSE_WINDOW

Returns count of processes cleaned up.

property root: archivebox.machine.models.Process

Get the root process (CLI command) of this hierarchy.

property ancestors: list[archivebox.machine.models.Process]

Get all ancestor processes from parent to root.

property depth: int

Get depth in the process tree (0 = root).

get_descendants(include_self: bool = False)

Get all descendant processes recursively.

property proc: psutil.Process | None

Get validated psutil.Process for this record.

Returns psutil.Process ONLY if:

1. Process with this PID exists in OS

2. OS process start time matches our started_at (within tolerance)

3. Process is on current machine

Returns None if:

• PID doesn’t exist (process exited)

• PID was reused by a different process (start times don’t match)

• We’re on a different machine than where process ran

• psutil is not available

This prevents accidentally matching a stale/recycled PID.

property is_running: bool

Check if process is currently running via psutil.

More reliable than checking status field since it validates the actual OS process exists and matches our record.

is_alive() → bool

Alias for is_running, for compatibility with subprocess.Popen API.

get_memory_info() → dict | None

Get memory usage if process is running.

get_cpu_percent() → float | None

Get CPU usage percentage if process is running.

get_children_pids() → list[int]

Get PIDs of child processes from OS (not DB).

property stdout_file: pathlib.Path | None

Path to stdout log.

property stderr_file: pathlib.Path | None

Path to stderr log.

property hook_script_name: str | None

Best-effort hook filename extracted from the process command.

property runtime_dir: pathlib.Path | None

Directory where this process stores runtime stdout/stderr logs.

tail_stdout(lines: int = 50, follow: bool = False)

Tail stdout log file (like tail or tail -f).

Args: lines: Number of lines to show (default 50) follow: If True, follow the file and yield new lines as they appear

Yields: Lines from stdout

tail_stderr(lines: int = 50, follow: bool = False)

Tail stderr log file (like tail or tail -f).

Args: lines: Number of lines to show (default 50) follow: If True, follow the file and yield new lines as they appear

Yields: Lines from stderr

pipe_stdout(lines: int = 10, follow: bool = True)

Pipe stdout to sys.stdout.

Args: lines: Number of initial lines to show follow: If True, follow the file and print new lines as they appear

pipe_stderr(lines: int = 10, follow: bool = True)

Pipe stderr to sys.stderr.

Args: lines: Number of initial lines to show follow: If True, follow the file and print new lines as they appear

ensure_log_files() → None

Ensure stdout/stderr log files exist for this process.

_build_env() → dict

Build environment dict for subprocess, merging stored env with system.

launch(background: bool = False, cwd: str | None = None) → archivebox.machine.models.Process

Spawn the subprocess and update this Process record.

Args: background: If True, don’t wait for completion (for daemons/bg hooks) cwd: Working directory for the subprocess (defaults to self.pwd)

Returns: self (updated with pid, started_at, etc.)

kill(signal_num: int = 15) → bool

Kill this process and update status.

Uses self.proc for safe killing - only kills if PID matches our recorded process (prevents killing recycled PIDs).

Args: signal_num: Signal to send (default SIGTERM=15)

Returns: True if killed successfully, False otherwise

poll() → int | None

Check if process has exited and update status if so.

Cleanup when process exits:

• Copy stdout/stderr to DB (keep files for debugging)

• Delete PID file

Returns: exit_code if exited, None if still running

wait(timeout: int | None = None) → int

Wait for process to exit, polling periodically.

Args: timeout: Max seconds to wait (None = use self.timeout)

Returns: exit_code

Raises: TimeoutError if process doesn’t exit in time

terminate(graceful_timeout: float = 5.0) → bool

Gracefully terminate process: SIGTERM → wait → SIGKILL.

This consolidates the scattered SIGTERM/SIGKILL logic from:

• crawls/models.py Crawl.cleanup()

• workers/pid_utils.py stop_worker()

• supervisord_util.py stop_existing_supervisord_process()

Args: graceful_timeout: Seconds to wait after SIGTERM before SIGKILL

Returns: True if process was terminated, False if already dead

kill_tree(graceful_timeout: float = 2.0) → int

Kill this process and all its children (OS children, not DB children) in parallel.

Uses parallel polling approach - sends SIGTERM to all processes at once, then polls all simultaneously with individual deadline tracking.

This consolidates the scattered child-killing logic from:

• crawls/models.py Crawl.cleanup() os.killpg()

• supervisord_util.py stop_existing_supervisord_process()

Args: graceful_timeout: Seconds to wait after SIGTERM before SIGKILL

Returns: Number of processes killed (including self)

kill_children_db() → int

Kill all DB-tracked child processes (via parent FK).

Different from kill_tree() which uses OS children. This kills processes created via Process.create(parent=self).

Returns: Number of child Process records killed

classmethod get_running(process_type: str | None = None, machine: archivebox.machine.models.Machine | None = None) → django.db.models.QuerySet[archivebox.machine.models.Process]

Get all running processes, optionally filtered by type.

Replaces:

• workers/pid_utils.py get_all_worker_pids()

• workers/orchestrator.py get_total_worker_count()

Args: process_type: Filter by TypeChoices (e.g., ‘worker’, ‘hook’) machine: Filter by machine (defaults to current)

Returns: QuerySet of running Process records

classmethod get_running_count(process_type: str | None = None, machine: archivebox.machine.models.Machine | None = None) → int

Get count of running processes.

Replaces:

• workers/pid_utils.py get_running_worker_count()

classmethod stop_all(process_type: str | None = None, machine: archivebox.machine.models.Machine | None = None, graceful: bool = True) → int

Stop all running processes of a given type.

Args: process_type: Filter by TypeChoices machine: Filter by machine graceful: If True, use terminate() (SIGTERM→SIGKILL), else kill()

Returns: Number of processes stopped

classmethod get_next_worker_id(process_type: str = 'worker', machine: archivebox.machine.models.Machine | None = None) → int

Get the next available worker ID for spawning new workers.

Replaces workers/pid_utils.py get_next_worker_id(). Simply returns count of running workers of this type.

Args: process_type: Worker type to count machine: Machine to scope query

Returns: Next available worker ID (0-indexed)

classmethod cleanup_orphaned_chrome() → int

Kill orphaned Chrome processes using chrome_utils.js killZombieChrome.

Scans DATA_DIR for chrome/*.pid files from stale crawls (>5 min old) and kills any orphaned Chrome processes.

Called by:

• Orchestrator on startup (cleanup from previous crashes)

• Orchestrator periodically (every N minutes)

Returns: Number of zombie Chrome processes killed

classmethod cleanup_orphaned_workers() → int

Mark orphaned worker/hook processes as EXITED in the DB.

Orphaned if:

• Root (orchestrator/cli) is not running, or

• No orchestrator/cli ancestor exists.

Standalone worker runs (archivebox run –snapshot-id) are allowed.

class archivebox.machine.models.BinaryMachine(obj, *args, **kwargs)

Bases: archivebox.workers.models.BaseStateMachine

State machine for managing Binary installation lifecycle.

Simple 2-state machine: ┌─────────────────────────────────────────────────────────────┐ │ QUEUED State │ │ • Binary needs to be installed │ └─────────────────────────────────────────────────────────────┘ ↓ tick() when can_install() ↓ Synchronous installation during transition ┌─────────────────────────────────────────────────────────────┐ │ INSTALLED State │ │ • Binary installed (abspath, version, sha256 set) │ │ • Health stats incremented │ └─────────────────────────────────────────────────────────────┘

If installation fails, Binary stays in QUEUED with retry_at bumped.

Initialization

model_attr_name

‘binary’

binary: archivebox.machine.models.Binary

None

queued

‘State(…)’

installed

‘State(…)’

tick

None

can_install() → bool

Check if binary installation can start.

enter_queued()

Binary is queued for installation.

on_install()

Called during queued→installed transition. Runs installation synchronously.

enter_installed()

Binary installed successfully.

class archivebox.machine.models.ProcessMachine(obj, *args, **kwargs)

Bases: archivebox.workers.models.BaseStateMachine

State machine for managing Process (OS subprocess) lifecycle.

Process Lifecycle: ┌─────────────────────────────────────────────────────────────┐ │ QUEUED State │ │ • Process ready to launch, waiting for resources │ └─────────────────────────────────────────────────────────────┘ ↓ tick() when can_start() ┌─────────────────────────────────────────────────────────────┐ │ RUNNING State → enter_running() │ │ 1. process.launch() │ │ • Spawn subprocess with cmd, pwd, env, timeout │ │ • Set pid, started_at │ │ • Process runs in background or foreground │ │ 2. Monitor process completion │ │ • Check exit code when process completes │ └─────────────────────────────────────────────────────────────┘ ↓ tick() checks is_exited() ┌─────────────────────────────────────────────────────────────┐ │ EXITED State │ │ • Process completed (exit_code set) │ │ • Health stats incremented │ │ • stdout/stderr captured │ └─────────────────────────────────────────────────────────────┘

Note: This is a simpler state machine than ArchiveResult. Process is just about execution lifecycle. ArchiveResult handles the archival-specific logic (status, output parsing, etc.).

Initialization

model_attr_name

‘process’

process: archivebox.machine.models.Process

None

queued

‘State(…)’

running

‘State(…)’

exited

‘State(…)’

tick

None

launch

‘to(…)’

kill

‘to(…)’

can_start() → bool

Check if process can start (has cmd and machine).

is_exited() → bool

Check if process has exited (exit_code is set).

enter_queued()

Process is queued for execution.

enter_running()

Start process execution.

enter_exited()

Process has exited.