hostctl 0.3.0__tar.gz → 0.3.1__tar.gz

{hostctl-0.3.0 → hostctl-0.3.1}/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-09-22
+
+### Fixed
+
+- **A composite path falls back when SFTP cannot connect.** Nothing on the
+  path route connected the provider first: pathlib_next dialled SFTP inside
+  the operation, so an untrusted host key (`HostKeyNotVerifiable`) or a
+  refused port escaped raw and the next path provider was never tried --
+  while `run()` on the same host fell back. A composite path now calls the
+  provider's `connect()` before dispatch, and SFTP maps asyncssh's connect
+  errors the way the SSH leg already did. Most likely to fire since 0.3.0
+  started verifying the SFTP host key: any host not yet in `known_hosts`.
+- **`run()` no longer re-dials a declined provider on every call.** 0.3.0
+  cleared every decline per call, so a dead primary cost a full connect
+  attempt (~9 s against a refused port) on each `run()` while the fallback
+  served. A decline now lasts for the generation again, and is re-admitted
+  only when no other provider can serve -- which keeps a single-provider
+  host from bricking on one transient refusal, for paths as well as `run()`.
+- A path refusal with nothing left to try names why ("no path provider
+  completed read (...: Host key is not trusted ...)") and keeps the cause.
+
 ## [0.3.0] - 2026-09-22
 
 ### Added
@@ -741,7 +762,9 @@ test suite on Python 3.9 through 3.14.
   assigned to it; a config-less host now builds its own family configuration
   instead.
 
-[Unreleased]: https://github.com/jose-pr/hostctl/compare/v0.2.7...HEAD
+[Unreleased]: https://github.com/jose-pr/hostctl/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/jose-pr/hostctl/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/jose-pr/hostctl/compare/v0.2.7...v0.3.0
 [0.2.7]: https://github.com/jose-pr/hostctl/compare/v0.2.6...v0.2.7
 [0.2.6]: https://github.com/jose-pr/hostctl/compare/v0.2.5...v0.2.6
 [0.2.5]: https://github.com/jose-pr/hostctl/compare/v0.2.4...v0.2.5

{hostctl-0.3.0 → hostctl-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hostctl
-Version: 0.3.0
+Version: 0.3.1
 Summary: Run commands and access files on a host, local or remote, protocol-agnostic
 Project-URL: Homepage, https://github.com/jose-pr/hostctl/
 Project-URL: Documentation, https://jose-pr.github.io/hostctl/

{hostctl-0.3.0 → hostctl-0.3.1}/docs/guide/providers.md

@@ -100,7 +100,15 @@ the same conservative default.
 
 A provider that declines is remembered for the current connection generation, so
 later operations skip it instead of re-attempting it every time. Reconnecting or
-replacing a provider starts a new generation and re-probes everything.
+replacing a provider starts a new generation and re-probes everything. The one
+exception is a host with nothing else left: when every other candidate is
+unavailable, an earlier refusal is tried again rather than failing without
+dialling, so one transient refusal cannot brick a single-provider host.
+
+Paths and commands connect the same way: a composite path calls the provider's
+`connect()` before each dispatch, which is where a refused port or an untrusted
+host key becomes `OperationNotStarted`. A path provider's `connect()` must
+therefore be idempotent and cheap once connected.
 
 ## Selection traces
 

{hostctl-0.3.0 → hostctl-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hostctl"
-version = "0.3.0"
+version = "0.3.1"
 authors = [{ name = "Jose A." }]
 description = "Run commands and access files on a host, local or remote, protocol-agnostic"
 readme = "README.md"

{hostctl-0.3.0 → hostctl-0.3.1}/src/hostctl/AGENTS.md

@@ -315,7 +315,12 @@ hostctl applies to whatever you return.
   falls through to the next provider for **that call only**; it does not take
   the provider out of service.
 - `ProviderSelector` holds the ordered providers and the per-generation
-  declines; `ProviderSelection` is one resolved choice.
+  declines; `ProviderSelection` is one resolved choice. `select()` re-admits
+  a decline recorded by an earlier operation only when no other provider can
+  serve.
+- A provider's optional `connect()` is where a pre-dispatch failure belongs.
+  Composite paths call a path provider's `connect()` before **every**
+  dispatch, so it must be idempotent and cheap once connected.
   `ProviderSelector.redact(value)` is the one redaction used in traces --
   rendered commands routinely carry credentials, so log through it.
 - `SessionInitializer` is the hook a provider may accept to prepare a session

{hostctl-0.3.0 → hostctl-0.3.1}/src/hostctl/host/_ssh.py

@@ -706,10 +706,24 @@ class SftpPathProvider(PathProvider):
     # Closing is owned by SshExecutorProvider for the shared transport;
     # connecting is not, because the SFTP client has to be established from
     # the caller's thread before any native recursive operation runs.
+    #
+    # Composite paths call this before EVERY dispatch, so once connected it
+    # must stay cheap: a lock, a liveness check and a cache hit.
     def connect(self):
+        from .. import _async
+
         try:
             self.transport.connect()
-            self.transport.warm_sftp()
+            try:
+                self.transport.warm_sftp()
+            except Exception as exc:
+                # pathlib_next dials its own SFTP connection and hands back
+                # asyncssh's errors raw -- `HostKeyNotVerifiable` is not an
+                # OSError -- so map them as the transport's own connect does.
+                normalized = _async.normalize_asyncssh_error(exc)
+                if normalized is exc:
+                    raise
+                raise normalized from exc
         except (OSError, TimeoutError) as exc:
             log.debug(
                 "SFTP provider declining before dispatch: %s: %s",

{hostctl-0.3.0 → hostctl-0.3.1}/src/hostctl/host/composite_path.py

@@ -498,10 +498,20 @@ class _CompositePathMixin:
         candidates = self._providers_in_order(operation, pin=pin)
         attempted = False
         not_implemented: typing.Optional[NotImplementedError] = None
+        not_started: typing.Optional[OperationNotStarted] = None
         for provider in candidates:
             attempted = True
             old = (self._provider, self._backend_path, self._factory, self._pinned)
             try:
+                # Connect first, where a failure is provably pre-dispatch.
+                # SFTP used to be dialled lazily inside the backend by the
+                # operation itself, so an unreachable server or an untrusted
+                # host key escaped as a raw transport error and the next
+                # provider was never tried -- while `run()`, which connects
+                # before dispatch, fell back on the same host.
+                connect = getattr(provider, "connect", None)
+                if connect is not None:
+                    connect()
                 backend_path = self._provider_path(provider)
                 if pin:
                     # A write/open operation owns the provider choice before
@@ -531,6 +541,7 @@ class _CompositePathMixin:
                 # `excluded` already stops us retrying it for this call.
                 continue
             except OperationNotStarted as exc:
+                not_started = exc
                 if pin:
                     self._provider, self._backend_path, self._factory, self._pinned = (
                         old
@@ -554,7 +565,16 @@ class _CompositePathMixin:
             # visibly with a single provider, where "try the next one" has
             # nothing to try.
             raise not_implemented
-        raise OperationNotStarted(f"no path provider completed {operation}")
+        # Carry the last refusal: "no provider completed" alone hid WHY -- a
+        # rejected host key read the same as a refused port.
+        cause = not_started.cause if not_started is not None else None
+        detail = ""
+        if not_started is not None:
+            reason = f"{not_started}: {cause}" if cause is not None else not_started
+            detail = f" ({ProviderSelector.redact(reason)})"
+        raise OperationNotStarted(
+            f"no path provider completed {operation}{detail}", cause=cause
+        ) from (cause or not_started)
 
     def via(self, name: str):
         provider = next((item for item in self._providers if item.name == name), None)

{hostctl-0.3.0 → hostctl-0.3.1}/src/hostctl/host/system.py

@@ -826,11 +826,11 @@ class SystemHost(Host):
             raise NotImplementedError(
                 f"{type(self).__name__} does not provide the 'run' capability"
             )
-        # A refusal recorded by an earlier call must not decide this one: a
-        # single-provider SSH host that hit one transient ConnectionError
-        # never dialled out again until close(). Within this call, `excluded`
-        # still stops a provider being retried after it declines.
-        self._executor_selector.retry_declined()
+        # No `retry_declined()` here. Clearing every refusal per call re-dialled
+        # a dead primary on EVERY run() -- ~9 s each against a refused port --
+        # although the fallback was serving. The selector re-admits an earlier
+        # refusal only when nothing else is left, which is what keeps a
+        # single-provider host from bricking on one transient failure.
         excluded: list[str] = []
         while True:
             provider = self._executor_selector.select(exclude=excluded).provider

{hostctl-0.3.0 → hostctl-0.3.1}/src/hostctl/provider/_common.py

@@ -337,13 +337,12 @@ class ProviderSelector:
         return self._generation
 
     def retry_declined(self) -> None:
-        """Forget refusals recorded during an earlier call.
+        """Forget every refusal recorded this generation.
 
-        A decline exists to stop one dispatch re-dialling a provider that just
-        refused; it was never meant to outlive the call. Kept for the life of
-        the selector it bricked a single-provider host: one transient refusal
-        (sshd restarting, a network blip) and hostctl never dialled out again
-        until `close()`.
+        Not needed to recover a host: `select()` already re-admits an earlier
+        refusal when nothing else can serve. This is for a caller that knows
+        the declined provider is back (sshd restarted) and wants it preferred
+        over a fallback that is still serving.
         """
         with self._lock:
             self._declined.clear()
@@ -539,6 +538,15 @@ class ProviderSelector:
                 len(self._attempt_trace),
             )
             return result
+        if self._readmit_earlier_declines(excluded, capability):
+            # Nothing else can serve, so a refusal recorded by an EARLIER
+            # operation gets another chance rather than failing this one
+            # without dialling: one transient refusal (sshd restarting) on a
+            # single-provider host otherwise bricked it until close(). A
+            # decline this operation made itself is in `excluded` and stays.
+            return self.select(
+                capability=capability, exclude=excluded, policy=policy, pin=pin
+            )
         log.debug(
             "no provider available (generation %d); candidates: %s",
             self._generation,
@@ -563,6 +571,32 @@ class ProviderSelector:
             cause=cause,
         ) from cause
 
+    def _readmit_earlier_declines(
+        self, excluded: typing.AbstractSet[str], capability: str | None
+    ) -> bool:
+        """Forget declines that the running operation did not make.
+
+        A name the caller excluded is one it tried and saw refuse, so only
+        declines outside `excluded` came from an earlier operation.
+        """
+        with self._lock:
+            stale = [
+                provider.name
+                for provider in self.providers
+                if provider.name in self._declined
+                and provider.name not in excluded
+                and (capability is None or capability in provider.capabilities)
+            ]
+            for name in stale:
+                del self._declined[name]
+                self._decline_causes.pop(name, None)
+        for name in stale:
+            log.debug(
+                "provider %s re-admitted: every other candidate is unavailable",
+                _redacted_name(name),
+            )
+        return bool(stale)
+
     def _record(self, entry: dict[str, object]) -> None:
         """Merge one trace entry, letting a later record supersede an earlier.
 

{hostctl-0.3.0 → hostctl-0.3.1}/tests/test_provider_fault_injection.py

@@ -800,6 +800,137 @@ def test_path_falls_back_over_every_candidate_not_just_one():
     assert path.provider.name == "third"
 
 
+def _served_by_memory(text="served"):
+    backend = MemPathBackend()
+    MemPath("/etc", backend=backend).mkdir(parents=True)
+    MemPath("/etc/hostname", backend=backend).write_text(text)
+    return PathProvider("memory", lambda *parts: MemPath(*parts, backend=backend))
+
+
+def _sftp_that_cannot_connect(*, connect=None, warm=None):
+    from hostctl import SshConfig
+    from hostctl.host._ssh import SftpPathProvider, _SshTransport
+
+    transport = _SshTransport(SshConfig("nas.example", username="root"))
+    transport.connect = connect or (lambda: None)
+    transport.warm_sftp = warm or (lambda: None)
+    return SftpPathProvider(transport)
+
+
+@pytest.mark.parametrize(
+    "error",
+    (
+        # What `_SshTransport.connect()` makes of each: an untrusted host key
+        # (`HostKeyNotVerifiable`) and a refused or firewalled port.
+        ConnectionError("Host key is not trusted for host nas.example"),
+        ConnectionRefusedError(10061, "connection refused"),
+        TimeoutError("connect timed out"),
+    ),
+    ids=("host-key", "refused", "timeout"),
+)
+def test_a_path_falls_back_when_sftp_cannot_connect(error):
+    """`run()` connects before dispatch and fell back; `path()` did not.
+
+    Nothing on the composite-path route called `SftpPathProvider.connect()`:
+    pathlib_next dialled SFTP lazily inside the operation, so the transport
+    error escaped `_dispatch` and the working next provider was never tried.
+    """
+
+    def refuse():
+        raise error
+
+    host = PosixHost(
+        path_providers=(_sftp_that_cannot_connect(connect=refuse), _served_by_memory())
+    )
+
+    path = host.path("/etc/hostname")
+
+    assert path.read_text() == "served"
+
+
+def test_a_raw_asyncssh_host_key_error_from_the_sftp_leg_declines():
+    """pathlib_next dials its own SFTP connection and raises asyncssh's error
+    raw; `HostKeyNotVerifiable` is not an OSError, so it was never taken as
+    "nothing started" even where `connect()` did run."""
+    import asyncssh
+
+    def untrusted():
+        raise asyncssh.HostKeyNotVerifiable("Host key is not trusted")
+
+    host = PosixHost(
+        path_providers=(_sftp_that_cannot_connect(warm=untrusted), _served_by_memory())
+    )
+
+    assert host.path("/etc/hostname").read_text() == "served"
+
+
+def test_a_path_refusal_names_its_cause_when_nothing_is_left():
+    def refuse():
+        raise ConnectionError("Host key is not trusted for host nas.example")
+
+    host = PosixHost(path_providers=(_sftp_that_cannot_connect(connect=refuse),))
+
+    with pytest.raises(OperationNotStarted) as raised:
+        host.path("/etc/hostname").read_text()
+
+    assert "Host key is not trusted" in str(raised.value)
+    assert isinstance(raised.value.cause, ConnectionError)
+
+
+def test_a_path_refusal_does_not_brick_a_single_provider_host():
+    """Now that a failed SFTP connect declines, the decline must not outlive
+    the refusal on a host with nothing to fall back to."""
+    state = {"failing": True}
+
+    def flaky():
+        if state["failing"]:
+            raise ConnectionRefusedError(10061, "sshd restarting")
+
+    backend = MemPathBackend()
+    MemPath("/etc", backend=backend).mkdir(parents=True)
+    MemPath("/etc/hostname", backend=backend).write_text("back")
+    provider = _sftp_that_cannot_connect(connect=flaky)
+    provider.factory = lambda *parts: MemPath(*parts, backend=backend)
+    host = PosixHost(path_providers=(provider,))
+
+    with pytest.raises(OperationNotStarted):
+        host.path("/etc/hostname").read_text()
+
+    state["failing"] = False
+    assert host.path("/etc/hostname").read_text() == "back"
+
+
+def test_a_declined_primary_is_not_redialled_while_the_fallback_serves():
+    """Every `run()` cleared every decline, so a dead primary was dialled
+    again on each call -- ~9 s apiece against a refused port -- although the
+    fallback had been serving all along."""
+    dialled = []
+
+    def refuse(command, *args, **options):
+        dialled.append(command)
+        raise OperationNotStarted(
+            "connection refused", cause=ConnectionRefusedError("refused")
+        )
+
+    host = PosixHost(
+        executor_providers=(
+            ExecutorProvider("ssh", refuse, capabilities=()),
+            ExecutorProvider(
+                "fallback",
+                lambda command, *args, **options: subprocess.CompletedProcess(
+                    (command,), 0, b"ok", b""
+                ),
+                capabilities=(),
+            ),
+        )
+    )
+
+    for _ in range(3):
+        assert host.run("uptime", check=False).stdout == b"ok"
+
+    assert len(dialled) == 1
+
+
 def test_two_threads_selecting_do_not_share_a_trace():
     """The per-operation trace and the probe/decline maps were unsynchronised
     instance state, so concurrent operations on one host mixed trace entries