core.ops_exec module

Shared OS-level operation primitives for admin / cluster control commands.

This module is the canonical home for the hardened subprocess, git-environment, cooldown and systemd-restart helpers used by both:

  • message_processor.admin_ops_commands (the legacy single-service !bot_restart / !proxy_restart / !bot_pull worker path), and

  • core.control_ops (the fleet-wide control-ops daemon + publisher).

It is stdlib-only on purpose: message_processor.admin_ops_commands is loaded in isolation by tests/test_admin_ops_commands.py (by file path, with the heavy app stack stubbed), and it imports the primitives below — so this module must never pull in redis / discord / config at import time. The Redis client used for the git-pull dedupe lock is always passed in as an argument.

Security hardening carried over from admin_ops_commands (2026-04-28):

  • asyncio.create_subprocess_exec (no shell=True) — no injection.

  • Per-command cooldown to prevent rapid-repeat DoS.

  • Subprocess output capped at read time.

  • git pull kills the subprocess on timeout (no orphaned index.lock).

  • git pull uses an environment allowlist (no secret leakage to git hooks).

async core.ops_exec.systemctl_restart(service, timeout=20.0)[source]

Synchronously systemctl restart <service> (for restarting OTHER units).

Returns (ok, summary). Use this for the proxy / non-self units; use _deferred_systemctl_restart() for restarting the current process.

Return type:

tuple[bool, str]

Parameters:
class core.ops_exec.PullResult(ran, ok, summary)[source]

Bases: NamedTuple

Outcome of run_git_pull().

Parameters:
ran: bool

Alias for field number 0

ok: bool

Alias for field number 1

summary: str

Alias for field number 2

async core.ops_exec.run_git_pull(repo_dir, *, redis=None, dedupe=True, lock_ttl=90, instance_id='', timeout=60.0)[source]

Run git pull in repo_dir with optional per-host/repo dedupe.

When dedupe is True and redis is provided, contend on a Redis SETNX lock keyed by sg:control:pull:{hostname}:{abs_repo_path} so that multiple co-located services sharing one checkout only pull once. The lock self- partitions by host, so on a multi-host fleet each host pulls exactly once.

Returns a PullResult. ran=False, ok=True means another local service is handling the pull (clean dedup skip).

Return type:

PullResult

Parameters: