Hosts

Execution hosts: this machine, or a remote server behind an SSH session.

exception remote_compression.host.BootstrapError

A prerequisite is missing (ffmpeg, workspace…); the batch cannot start.

remote_compression.host.GRACE = 30.0

Seconds granted to a remote output to appear after a reconnection.

class remote_compression.host.HostResult(ok: bool, exit_status: int | None = None, stderr_tail: str = '', reason: str = '')

Outcome of one compression attempt on a host.

ok

True iff the target file was produced and retrieved.

Type:

bool

exit_status

ffmpeg exit status when known.

Type:

int, optional

stderr_tail

Bounded tail of ffmpeg stderr (diagnosis).

Type:

str

reason

Failure category: ffmpeg-failed, upload-failed, download-failed or exec-timeout. Empty on success.

Type:

str

class remote_compression.host.LocalHost(encoder=None)

Compression on this very machine.

Parameters:

encoder (str, optional) – Encoder whose availability is verified at bootstrap.

bootstrap()

Raises:

BootstrapError – If ffmpeg is not in the local PATH, or lacks the requested encoder.

compress_file(source, target, plan, on_progress=None)

Run ffmpeg locally.

Parameters:

• source (Path) – Input video.

• target (Path) – Output video (the temporary comp_* file).

• plan (FfmpegPlan) – Command to run.

• on_progress (callable, optional) – Receives decoded chunks of the ffmpeg -progress stream.

Return type:

HostResult

remote_compression.host.POLL = 10.0

Orphan polling interval.

class remote_compression.host.PurgeReport(removed: list, failed: list, dry_run: bool)

Outcome of a workspace purge.

property freed_bytes

cumulated size of the removed files.

Type:

int

remote_compression.host.RECONNECT_WINDOW = 300.0

Seconds granted to get the connection back mid-batch.

class remote_compression.host.RemoteHost(hostname, config_path=None, auto_purge_days=7.0, encoder=None, remote_ffmpeg=None, workdir=None, workdir_sftp=None, session=None)

Compression on a remote server, over a single SSH session.

All file operations go through SFTP (platform-agnostic: Linux and Windows servers behave the same); only ffmpeg -version and the ffmpeg command itself are executed remotely, with a syntax common to sh and cmd.exe.

Parameters:

• hostname (str) – SSH alias of the server.

• config_path (str, optional) – Alternative openSSH config file.

• auto_purge_days (float, optional) – Age threshold of the opportunistic purge run at connection time (None disables it).

• encoder (str, optional) – Encoder whose availability is verified at bootstrap.

• remote_ffmpeg (str, optional) – Explicit path of the ffmpeg binary on the server (space-free ASCII; for hosts whose non-interactive PATH misses ffmpeg).

• workdir (str, optional) – Workspace directory as seen by the shell running ffmpeg (default: .rcomp, relative to the login home).

• workdir_sftp (str, optional) – The same directory as seen by the SFTP channel, when the two views differ (Synology chroots SFTP: its /home is the login home, so /home/.rcomp pairs with the default workdir). Defaults to workdir.

• session (SSHSession, optional) – Injected session (tests).

bootstrap()

Fail-fast checks: workspace, ffmpeg, then best-effort auto-purge.

check_ffmpeg()

Raises:

BootstrapError – If ffmpeg fails on the server, or lacks the requested encoder.

compress_file(source, target, plan, on_progress=None)

Upload, encode remotely, download.

On a connection loss, reconnects patiently then tries to re-attach to the orphan encode (ffmpeg may well survive the disconnection on the server) instead of blindly relaunching. At most one relaunch, always with fresh temporary names — a zombie may still be writing to the old target.

Parameters:

• source (Path) – Local input video.

• target (Path) – Local output (the temporary comp_* file).

• plan (FfmpegPlan) – Command to run.

• on_progress (callable, optional) – Receives decoded chunks of the ffmpeg -progress stream.

Return type:

HostResult

Raises:

SSHConnectionError – When the connection cannot be recovered, or is lost twice on the same file: the batch cannot reasonably continue.

ensure_workspace()

Create the remote workspace when missing (pure SFTP).

Raises:

BootstrapError – If it can neither be accessed nor created.

purge_workspace(older_than=datetime.timedelta(0), dry_run=False)

Remove workspace files older than a threshold.

Parameters:

• older_than (datetime.timedelta) – Minimal age (local clock vs remote mtimes; skew is negligible at the thresholds in use). Zero purges everything.

• dry_run (bool) – List without removing.

Returns:

Individual removal failures are collected, never raised.

Return type:

PurgeReport

workspace_status()

Returns:

Regular files of the workspace (sub-directories and symlinks are ignored), sorted by mtime; None when the workspace does not exist.

Return type:

WorkspaceStatus or None

remote_compression.host.SETTLE_TIME = 60.0

A remote output whose size stalls this long is finished (or dead).

remote_compression.host.WORKDIR = '.rcomp'

Remote working directory, relative to the SFTP home (never absolutized: OpenSSH on Windows reports homes as /C:/..., invalid in a cmd argv).

class remote_compression.host.WorkspaceEntry(name: str, size: int, mtime: float)

A regular file in the remote workspace.

age(now=None)

datetime.timedelta: age of the file (relative to local now).

class remote_compression.host.WorkspaceStatus(entries: list)

Content of the remote workspace.

property count

number of files.

Type:

int

property total_bytes

cumulated size.

Type:

int

remote_compression.host.open_host(settings, config_path=None)

Build the right host for the given settings.

Parameters:

• settings (Settings) – Resolved settings (hostname, auto_local, auto_purge_days).

• config_path (str, optional) – Alternative openSSH config file (mostly for tests).

Returns:

Not yet connected: use it as a context manager, whose __enter__ performs connection and fail-fast bootstrap checks.

Return type:

LocalHost or RemoteHost