presence_client.py
Client and command gate for the local presenced Unix socket.
Overview
Client and command gate for the local presenced Unix socket.
depends on presence_service.py · used by presence-run
API
Cclass PresenceClientError(RuntimeError)
Base exception for client-side presence proof errors (socket, validation, daemon rejection).
_validate_response, _validate_socket, execute_command, request_presenceCclass PresenceDenied(PresenceClientError)
Exception raised when the presence daemon denies the proof request (proof failed, stale, or out of range).
client_main, execute_commandF_validate_response(response) -> dict
Validate a presenced response JSON object. Raises PresenceClientError if the response structure is invalid or contradictory (e.g., ok:true with missing/invalid distance, or ok:false with missing code/reason). Returns the validated response dict.
execute_command, request_presence · calls PresenceClientErrorF_validate_socket(path: str)
Validate the presenced socket path: must exist, be a Unix socket, be owned by the current user, and have no group or other access. Raises PresenceClientError if any check fails.
request_presence · calls PresenceClientErrorFrequest_presence(path: str, max_cm: int, timeout: float=15.0) -> dict
Request one fresh proof. The daemon, never the client, mints the nonce.
client_main · calls PresenceClientError, _validate_response, _validate_socketFexecute_command(response: dict, command: list[str], runner=subprocess.run) -> int
Run exact argv only after success, preserving exit and signal status.
client_main · calls PresenceClientError, PresenceDenied, _validate_responseFpositive_cm(value: str) -> int
Parse and validate a positive integer argument in cm for the distance threshold.
Fpositive_timeout(value: str) -> float
Parse and validate a positive float argument in seconds for the socket and proof deadline.
Fbuild_client_parser()
Build an argparse parser for the presence-run CLI: socket path, distance threshold in cm, timeout in seconds, and the command to run.
client_mainFclient_main(argv=None) -> int
Main entry point for presence-run CLI. Request a fresh proof from presenced, confirm it succeeded, print the distance, then execute the given command only if presence succeeded. Returns 0 on success, 1 on proof denial, 2 on unavailable socket/daemon, 126 on execution error, 127 on command not found.
PresenceDenied, build_client_parser, execute_command, request_presence