Share SSH command construction in remotes

Four builders repeated the same batch-mode SSH option list and the same
POSIX "~/.local/bin/herdr or PATH" fallback script, and the delete/stop
helpers were near-identical copies. Build every remote command through
ssh_command()/posix_herdr_script() and run Session mutations through one
helper. Generated argv is byte-for-byte unchanged.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
2026-10-03 03:06:27 +00:00
co-authored by Claude Fable 5.1
parent 72d594033e
commit d2228ed5fb
+148 -146
View File
@@ -1,5 +1,6 @@
from __future__ import annotations from __future__ import annotations
import base64
import codecs import codecs
from collections import deque from collections import deque
from dataclasses import dataclass from dataclasses import dataclass
@@ -7,26 +8,47 @@ import fcntl
import json import json
import os import os
from pathlib import Path from pathlib import Path
import re
import shlex
import subprocess import subprocess
import tempfile import tempfile
import time import time
from typing import Iterable, Sequence from typing import Callable, Iterable, Sequence
from urllib.parse import SplitResult, unquote, urlsplit from urllib.parse import SplitResult, unquote, urlsplit
from .domain import is_valid_session_name from .domain import is_valid_session_name
REGISTRY_VERSION = 1 REGISTRY_VERSION = 1
REMOTE_DIRECT_COMMAND = "herdr session list --json" # Non-interactive, non-replayed SSH: fail fast instead of prompting.
REMOTE_LIST_SCRIPT = ( SSH_BATCH_OPTIONS = (
'if [ -x "$HOME/.local/bin/herdr" ]; then ' "-T",
'exec "$HOME/.local/bin/herdr" session list --json; ' "-o", "BatchMode=yes",
"elif command -v herdr >/dev/null 2>&1; then " "-o", "StrictHostKeyChecking=yes",
"exec herdr session list --json; " "-o", "ConnectionAttempts=1",
"else echo 'herdr is not installed on the remote host' >&2; exit 127; fi"
) )
def posix_herdr_script(arguments: str, *, prefix: str = "") -> str:
"""POSIX sh snippet running `herdr ARGUMENTS` with the per-user fallback.
A non-interactive SSH PATH often lacks ~/.local/bin; ``arguments`` must
already be shell-quoted. Exit 127 lets callers tell "no herdr" apart from
a failed command.
"""
return (
prefix + 'if [ -x "$HOME/.local/bin/herdr" ]; then '
f'exec "$HOME/.local/bin/herdr" {arguments}; '
"elif command -v herdr >/dev/null 2>&1; then "
f"exec herdr {arguments}; "
"else echo 'herdr is not installed on the remote host' >&2; exit 127; fi"
)
REMOTE_DIRECT_COMMAND = "herdr session list --json"
REMOTE_LIST_SCRIPT = posix_herdr_script("session list --json")
class RegistryError(RuntimeError): class RegistryError(RuntimeError):
"""A remote registry error which is safe to show to the user.""" """A remote registry error which is safe to show to the user."""
@@ -309,6 +331,39 @@ def ssh_destination_arguments(target: str) -> list[str]:
return arguments return arguments
def ssh_command(
ssh_bin: str,
entry: RemoteEntry,
remote_command: str,
*,
connect_timeout: int = 4,
) -> list[str]:
"""One batch-mode SSH invocation running ``remote_command`` on the target."""
return [
ssh_bin,
*SSH_BATCH_OPTIONS,
"-o",
f"ConnectTimeout={connect_timeout}",
*ssh_destination_arguments(entry.target),
remote_command,
]
def remote_herdr_command(
ssh_bin: str,
entry: RemoteEntry,
arguments: str,
*,
connect_timeout: int = 4,
posix_fallback: bool = False,
) -> list[str]:
"""Run `herdr ARGUMENTS` remotely, via PATH or the POSIX ~/.local/bin fallback."""
remote_command = (
posix_herdr_script(arguments) if posix_fallback else f"herdr {arguments}"
)
return ssh_command(ssh_bin, entry, remote_command, connect_timeout=connect_timeout)
def remote_session_command( def remote_session_command(
ssh_bin: str, ssh_bin: str,
entry: RemoteEntry, entry: RemoteEntry,
@@ -316,20 +371,19 @@ def remote_session_command(
connect_timeout: int = 4, connect_timeout: int = 4,
posix_fallback: bool = False, posix_fallback: bool = False,
) -> list[str]: ) -> list[str]:
return [ return remote_herdr_command(
ssh_bin, ssh_bin,
"-T", entry,
"-o", "session list --json",
"BatchMode=yes", connect_timeout=connect_timeout,
"-o", posix_fallback=posix_fallback,
"StrictHostKeyChecking=yes", )
"-o",
"ConnectionAttempts=1",
"-o", def _session_arguments(action: str, session: str) -> str:
f"ConnectTimeout={connect_timeout}", if not is_valid_session_name(session):
*ssh_destination_arguments(entry.target), raise ValueError("invalid remote Session name")
REMOTE_LIST_SCRIPT if posix_fallback else REMOTE_DIRECT_COMMAND, return f"session {action} -- {session}"
]
def remote_delete_session_command( def remote_delete_session_command(
@@ -340,30 +394,13 @@ def remote_delete_session_command(
connect_timeout: int = 4, connect_timeout: int = 4,
posix_fallback: bool = False, posix_fallback: bool = False,
) -> list[str]: ) -> list[str]:
if not is_valid_session_name(session): return remote_herdr_command(
raise ValueError("invalid remote Session name")
direct_command = f"herdr session delete --json -- {session}"
fallback_command = (
'if [ -x "$HOME/.local/bin/herdr" ]; then '
f'exec "$HOME/.local/bin/herdr" session delete --json -- {session}; '
"elif command -v herdr >/dev/null 2>&1; then "
f"exec herdr session delete --json -- {session}; "
"else echo 'herdr is not installed on the remote host' >&2; exit 127; fi"
)
return [
ssh_bin, ssh_bin,
"-T", entry,
"-o", _session_arguments("delete --json", session),
"BatchMode=yes", connect_timeout=connect_timeout,
"-o", posix_fallback=posix_fallback,
"StrictHostKeyChecking=yes", )
"-o",
"ConnectionAttempts=1",
"-o",
f"ConnectTimeout={connect_timeout}",
*ssh_destination_arguments(entry.target),
fallback_command if posix_fallback else direct_command,
]
def remote_stop_session_command( def remote_stop_session_command(
@@ -374,30 +411,54 @@ def remote_stop_session_command(
connect_timeout: int = 4, connect_timeout: int = 4,
posix_fallback: bool = False, posix_fallback: bool = False,
) -> list[str]: ) -> list[str]:
if not is_valid_session_name(session): return remote_herdr_command(
raise ValueError("invalid remote Session name")
direct_command = f"herdr session stop -- {session}"
fallback_command = (
'if [ -x "$HOME/.local/bin/herdr" ]; then '
f'exec "$HOME/.local/bin/herdr" session stop -- {session}; '
"elif command -v herdr >/dev/null 2>&1; then "
f"exec herdr session stop -- {session}; "
"else echo 'herdr is not installed on the remote host' >&2; exit 127; fi"
)
return [
ssh_bin, ssh_bin,
"-T", entry,
"-o", _session_arguments("stop", session),
"BatchMode=yes", connect_timeout=connect_timeout,
"-o", posix_fallback=posix_fallback,
"StrictHostKeyChecking=yes", )
"-o",
"ConnectionAttempts=1",
"-o", def _run_remote_session_command(
f"ConnectTimeout={connect_timeout}", build: Callable[..., list[str]],
*ssh_destination_arguments(entry.target), error_type: type[RuntimeError],
fallback_command if posix_fallback else direct_command, action: str,
] ssh_bin: str,
entry: RemoteEntry,
session: str,
timeout: float,
) -> tuple[str, str]:
"""Run a Session mutation, retrying once through the POSIX PATH fallback.
Returns decoded (stdout, stderr); any non-zero exit becomes ``error_type``.
"""
result: subprocess.CompletedProcess[bytes] | None = None
for posix_fallback in (False, True):
command = build(ssh_bin, entry, session, posix_fallback=posix_fallback)
try:
result = subprocess.run(
command,
capture_output=True,
check=False,
timeout=timeout,
)
except subprocess.TimeoutExpired as error:
raise error_type(
f"remote Session {action} timed out after {timeout:g}s"
) from error
except OSError as error:
raise error_type(f"could not start remote Session {action}: {error}") from error
if result.returncode != 127 or posix_fallback:
break
assert result is not None
stdout = decode_remote_output(result.stdout)
stderr = decode_remote_output(result.stderr)
if result.returncode != 0:
detail = (stderr or stdout or f"ssh exited with status {result.returncode}").strip()
raise error_type(" ".join(detail.splitlines()))
return stdout, stderr
def delete_remote_session( def delete_remote_session(
@@ -408,38 +469,15 @@ def delete_remote_session(
timeout: float = 8.0, timeout: float = 8.0,
) -> None: ) -> None:
"""Delete one stopped Herdr Session through a non-interactive SSH call.""" """Delete one stopped Herdr Session through a non-interactive SSH call."""
result: subprocess.CompletedProcess[bytes] | None = None stdout, _ = _run_remote_session_command(
for posix_fallback in (False, True): remote_delete_session_command,
command = remote_delete_session_command( RemoteSessionDeleteError,
ssh_bin, "delete",
entry, ssh_bin,
session, entry,
posix_fallback=posix_fallback, session,
) timeout,
try: )
result = subprocess.run(
command,
capture_output=True,
check=False,
timeout=timeout,
)
except subprocess.TimeoutExpired as error:
raise RemoteSessionDeleteError(
f"remote Session delete timed out after {timeout:g}s"
) from error
except OSError as error:
raise RemoteSessionDeleteError(
f"could not start remote Session delete: {error}"
) from error
if result.returncode != 127 or posix_fallback:
break
assert result is not None
stdout = decode_remote_output(result.stdout)
stderr = decode_remote_output(result.stderr)
if result.returncode != 0:
detail = (stderr or stdout or f"ssh exited with status {result.returncode}").strip()
raise RemoteSessionDeleteError(" ".join(detail.splitlines()))
try: try:
payload = json.loads(stdout) payload = json.loads(stdout)
except json.JSONDecodeError as error: except json.JSONDecodeError as error:
@@ -458,38 +496,15 @@ def stop_remote_session(
timeout: float = 8.0, timeout: float = 8.0,
) -> None: ) -> None:
"""Stop one running Herdr Session through a non-interactive SSH call.""" """Stop one running Herdr Session through a non-interactive SSH call."""
result: subprocess.CompletedProcess[bytes] | None = None _run_remote_session_command(
for posix_fallback in (False, True): remote_stop_session_command,
command = remote_stop_session_command( RemoteSessionStopError,
ssh_bin, "stop",
entry, ssh_bin,
session, entry,
posix_fallback=posix_fallback, session,
) timeout,
try: )
result = subprocess.run(
command,
capture_output=True,
check=False,
timeout=timeout,
)
except subprocess.TimeoutExpired as error:
raise RemoteSessionStopError(
f"remote Session stop timed out after {timeout:g}s"
) from error
except OSError as error:
raise RemoteSessionStopError(
f"could not start remote Session stop: {error}"
) from error
if result.returncode != 127 or posix_fallback:
break
assert result is not None
stdout = decode_remote_output(result.stdout)
stderr = decode_remote_output(result.stderr)
if result.returncode != 0:
detail = (stderr or stdout or f"ssh exited with status {result.returncode}").strip()
raise RemoteSessionStopError(" ".join(detail.splitlines()))
def clip_utf8_tail(raw: bytes, limit: int) -> bytes: def clip_utf8_tail(raw: bytes, limit: int) -> bytes:
@@ -781,24 +796,13 @@ def remote_control_command(
Windows SSH commonly uses cmd.exe; only a base64 PowerShell script crosses Windows SSH commonly uses cmd.exe; only a base64 PowerShell script crosses
that shell. ProcessStartInfo then receives Windows-quoted native arguments. that shell. ProcessStartInfo then receives Windows-quoted native arguments.
""" """
import base64
import re
import shlex
if any(not re.fullmatch(r"[A-Z_][A-Z_0-9]*", key) for key in unset_environment): if any(not re.fullmatch(r"[A-Z_][A-Z_0-9]*", key) for key in unset_environment):
raise ValueError("invalid environment variable name") raise ValueError("invalid environment variable name")
if any("\0" in argument for argument in arguments): if any("\0" in argument for argument in arguments):
raise ValueError("NUL in remote argument") raise ValueError("NUL in remote argument")
if platform == "posix": if platform == "posix":
unset = "".join(f"unset {key}; " for key in unset_environment) unset = "".join(f"unset {key}; " for key in unset_environment)
argv = shlex.join(arguments) script = posix_herdr_script(shlex.join(arguments), prefix=unset)
script = (
unset + 'if [ -x "$HOME/.local/bin/herdr" ]; then '
f'exec "$HOME/.local/bin/herdr" {argv}; '
'elif command -v herdr >/dev/null 2>&1; then '
f"exec herdr {argv}; "
"else echo 'herdr is not installed on the remote host' >&2; exit 127; fi"
)
elif platform == "windows": elif platform == "windows":
def literal(value: str) -> str: def literal(value: str) -> str:
return "'" + value.replace("'", "''") + "'" return "'" + value.replace("'", "''") + "'"
@@ -831,6 +835,4 @@ def remote_control_command(
script = "powershell.exe -NoLogo -NoProfile -NonInteractive -EncodedCommand " + encoded script = "powershell.exe -NoLogo -NoProfile -NonInteractive -EncodedCommand " + encoded
else: else:
raise ValueError("unknown remote platform") raise ValueError("unknown remote platform")
return [ssh_bin, "-T", "-o", "BatchMode=yes", "-o", "StrictHostKeyChecking=yes", return ssh_command(ssh_bin, entry, script)
"-o", "ConnectionAttempts=1", "-o", "ConnectTimeout=4",
*ssh_destination_arguments(entry.target), script]