Skip to content

Public API Contract

Assertions

API-001 - The root module owns the supported import surface

Contract: ssh_wrapper MUST expose only the documented names in ssh_wrapper.__all__, include __version__, and import successfully without a consumer repository or optional runtime package.

Evidence:

API-002 - Connection authorities are validated structured values

Contract: ConnectionSpec MUST represent either one validated trusted OpenSSH alias or validated direct host, user, and port fields. Authority data MUST remain separate from option and remote-program arguments. IPv6 scope identifiers MUST NOT admit whitespace, NUL, or shell metacharacters.

Evidence:

API-003 - One master object has a one-way lifecycle

Contract: OpenSSHMaster.start() MUST be single-use, readiness MUST require the owned mux, and loss or closure MUST never transition the same object back to a state that can authenticate again. Closing during startup MUST prevent a later authentication. Concurrent closure MUST join the same cleanup; cancellation MUST be propagated only after owned startup or close resources are reclaimed. An in-flight readiness check MUST NOT restore READY or LOST after closing.

Evidence:

API-004 - Secondary command construction is mux-only

Contract: mux_transport_argv(), command_argv(), mux_ssh_command(), create_mux_wrapper(), and rsync_ssh_command() MUST bind to the existing private control socket and MUST prevent authentication or proxy fallback. Transport forms MUST not embed a destination.

Evidence:

API-005 - Expected failures use one stable error shape

Contract: Expected library failures MUST use SSHError with a stable code, human-readable message, and optional structured details. An empty details map MUST be omitted from to_dict().

Evidence:

API-006 - Remote process ownership is explicit and observable

Contract: OwnedRemoteProcess MUST require explicit heartbeat, lease, and grace timeouts that are positive and finite; the standalone supervisor builder MUST also reject non-positive or non-finite timeouts. Under the documented positive tail_bytes precondition, it MUST expose bounded stdout and stderr evidence plus the local mux status; and make repeated local closure safe. Invalid retention limits MUST fail rather than disable the bound. Concurrent start attempts MUST NOT spawn multiple supervisors; closing a pending start MUST prevent later spawning. Cancellation of close() MUST finish owned cleanup before propagating. Cancellation of wait() MUST remain observer cancellation, without implicitly ending a running child's ownership.

Evidence:

API-007 - Public documentation mirrors the compatibility surface

Contract: Public API documentation MUST enumerate every root export, constructor requirement, compatibility-relevant default, enum value, and asynchronous lifecycle operation, including bounded-container preconditions. Documentation MUST NOT advertise an implementation-submodule import as supported API.

Evidence: