Add HTTPActionClient Python SDK for the HTTP action server

Author: JE-Chen

automation_file/__init__.py

@@ -9,6 +9,7 @@
 
 from typing import TYPE_CHECKING, Any
 
+from automation_file.client import HTTPActionClient, HTTPActionClientException
 from automation_file.core.action_executor import (
     ActionExecutor,
     add_command_to_executor,
@@ -299,6 +300,8 @@ def __getattr__(name: str) -> Any:
     "start_autocontrol_socket_server",
     "HTTPActionServer",
     "start_http_action_server",
+    "HTTPActionClient",
+    "HTTPActionClientException",
     "ActionACL",
     "ActionNotPermittedException",
     "ProjectBuilder",

automation_file/client/__init__.py

@@ -0,0 +1,7 @@
+"""Client SDK for talking to a running ``HTTPActionServer``."""
+
+from __future__ import annotations
+
+from automation_file.client.http_client import HTTPActionClient, HTTPActionClientException
+
+__all__ = ["HTTPActionClient", "HTTPActionClientException"]

automation_file/client/http_client.py

@@ -0,0 +1,132 @@
+"""Python SDK for :class:`~automation_file.server.http_server.HTTPActionServer`.
+
+``HTTPActionClient(base_url, *, shared_secret=None)`` wraps a single
+``requests.Session`` and exposes ``execute(actions)`` which POSTs the JSON
+action list to ``<base_url>/actions``. The client is intentionally thin:
+it handles auth header assembly, response-code checking, and error
+translation, but makes no attempt to mirror ``ActionExecutor``'s API
+surface — callers pass the same action-list shape they would pass to
+``execute_action``.
+"""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Any
+
+import requests
+
+from automation_file.exceptions import FileAutomationException
+from automation_file.logging_config import file_automation_logger
+from automation_file.remote.url_validator import validate_http_url
+
+_DEFAULT_TIMEOUT = 30.0
+_ACTIONS_PATH = "/actions"
+
+
+class HTTPActionClientException(FileAutomationException):
+    """Raised when the server rejects a request or the response is malformed."""
+
+
+class HTTPActionClient:
+    """Synchronous SDK for a running :class:`HTTPActionServer`."""
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        shared_secret: str | None = None,
+        timeout: float = _DEFAULT_TIMEOUT,
+        verify_loopback: bool = False,
+    ) -> None:
+        stripped = base_url.rstrip("/")
+        if not stripped:
+            raise HTTPActionClientException("base_url must be non-empty")
+        if verify_loopback:
+            validate_http_url(stripped)
+        self._base_url = stripped
+        self._shared_secret = shared_secret
+        self._timeout = float(timeout)
+        self._session = requests.Session()
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    def execute(self, actions: list | dict) -> Any:
+        """POST ``actions`` to ``/actions`` and return the decoded JSON body."""
+        if not isinstance(actions, (list, dict)):
+            raise HTTPActionClientException(
+                f"actions must be list or dict, got {type(actions).__name__}"
+            )
+        url = f"{self._base_url}{_ACTIONS_PATH}"
+        headers = {"Content-Type": "application/json"}
+        if self._shared_secret:
+            headers["Authorization"] = f"Bearer {self._shared_secret}"
+        try:
+            response = self._session.post(
+                url,
+                json=actions,
+                headers=headers,
+                timeout=self._timeout,
+                allow_redirects=False,
+            )
+        except requests.RequestException as err:
+            raise HTTPActionClientException(f"request to {url} failed: {err}") from err
+        return _decode_response(response)
+
+    def ping(self) -> bool:
+        """Best-effort reachability probe — returns True if the server responds."""
+        url = f"{self._base_url}{_ACTIONS_PATH}"
+        try:
+            response = self._session.request(
+                "OPTIONS", url, timeout=min(self._timeout, 5.0), allow_redirects=False
+            )
+        except requests.RequestException:
+            return False
+        # The server only handles POST /actions; OPTIONS yields 501 which
+        # still proves it's reachable. 401/403 also prove reachability.
+        return response.status_code < 500 or response.status_code == 501
+
+    def close(self) -> None:
+        self._session.close()
+
+    def __enter__(self) -> HTTPActionClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+def _decode_response(response: requests.Response) -> Any:
+    status = response.status_code
+    if status == 401:
+        raise HTTPActionClientException("unauthorized: missing or invalid shared secret")
+    if status == 403:
+        body = _safe_body(response)
+        raise HTTPActionClientException(f"forbidden: {body}")
+    if status == 404:
+        raise HTTPActionClientException("server does not expose /actions")
+    if status >= 400:
+        body = _safe_body(response)
+        raise HTTPActionClientException(f"server returned HTTP {status}: {body}")
+    try:
+        return response.json()
+    except ValueError as err:
+        file_automation_logger.error("http_client: bad JSON response: %r", err)
+        raise HTTPActionClientException(f"server returned invalid JSON: {err}") from err
+
+
+def _safe_body(response: requests.Response) -> str:
+    try:
+        data = response.json()
+    except ValueError:
+        return response.text[:200]
+    if isinstance(data, dict) and "error" in data:
+        return str(data["error"])
+    return str(data)[:200]

tests/test_http_client.py

@@ -0,0 +1,120 @@
+"""Tests for :class:`HTTPActionClient`."""
+# pylint: disable=cyclic-import
+
+from __future__ import annotations
+
+import pytest
+
+from automation_file.client import HTTPActionClient, HTTPActionClientException
+from automation_file.core.action_executor import executor
+from automation_file.server.action_acl import ActionACL
+from automation_file.server.http_server import start_http_action_server
+
+
+def _ensure_echo_registered() -> None:
+    if "test_client_echo" not in executor.registry:
+        executor.registry.register("test_client_echo", lambda value: value)
+
+
+def _base_url(server) -> str:
+    host, port = server.server_address
+    return f"http://{host}:{port}"
+
+
+def test_client_executes_action_round_trip() -> None:
+    _ensure_echo_registered()
+    server = start_http_action_server(host="127.0.0.1", port=0)
+    try:
+        with HTTPActionClient(_base_url(server)) as client:
+            result = client.execute([["test_client_echo", {"value": "hello"}]])
+        assert isinstance(result, dict)
+        assert any(value == "hello" for value in result.values())
+    finally:
+        server.shutdown()
+
+
+def test_client_sends_bearer_token_when_configured() -> None:
+    _ensure_echo_registered()
+    server = start_http_action_server(host="127.0.0.1", port=0, shared_secret="topsecret")
+    try:
+        with HTTPActionClient(_base_url(server), shared_secret="topsecret") as client:
+            result = client.execute([["test_client_echo", {"value": 42}]])
+        assert any(value == 42 for value in result.values())
+    finally:
+        server.shutdown()
+
+
+def test_client_unauthorized_when_missing_secret() -> None:
+    _ensure_echo_registered()
+    server = start_http_action_server(host="127.0.0.1", port=0, shared_secret="topsecret")
+    try:
+        with (
+            HTTPActionClient(_base_url(server)) as client,
+            pytest.raises(HTTPActionClientException, match="unauthorized"),
+        ):
+            client.execute([["test_client_echo", {"value": 1}]])
+    finally:
+        server.shutdown()
+
+
+def test_client_forbidden_when_denied_by_acl() -> None:
+    _ensure_echo_registered()
+    acl = ActionACL.build(denied=["test_client_echo"])
+    server = start_http_action_server(host="127.0.0.1", port=0, action_acl=acl)
+    try:
+        with (
+            HTTPActionClient(_base_url(server)) as client,
+            pytest.raises(HTTPActionClientException, match="forbidden"),
+        ):
+            client.execute([["test_client_echo", {"value": 1}]])
+    finally:
+        server.shutdown()
+
+
+def test_client_rejects_bad_action_type() -> None:
+    client = HTTPActionClient("http://127.0.0.1:1")
+    try:
+        with pytest.raises(HTTPActionClientException, match="list or dict"):
+            client.execute("not-a-list")  # type: ignore[arg-type]
+    finally:
+        client.close()
+
+
+def test_client_requires_base_url() -> None:
+    with pytest.raises(HTTPActionClientException, match="non-empty"):
+        HTTPActionClient("")
+
+
+def test_client_connection_error_wraps_request_exception() -> None:
+    # Port 1 is unlikely to have a server — connect should fail quickly.
+    client = HTTPActionClient("http://127.0.0.1:1", timeout=1.0)
+    try:
+        with pytest.raises(HTTPActionClientException, match="failed"):
+            client.execute([["noop"]])
+    finally:
+        client.close()
+
+
+def test_client_ping_reaches_running_server() -> None:
+    _ensure_echo_registered()
+    server = start_http_action_server(host="127.0.0.1", port=0)
+    try:
+        with HTTPActionClient(_base_url(server)) as client:
+            assert client.ping() is True
+    finally:
+        server.shutdown()
+
+
+def test_client_ping_returns_false_for_dead_endpoint() -> None:
+    client = HTTPActionClient("http://127.0.0.1:1", timeout=1.0)
+    try:
+        assert client.ping() is False
+    finally:
+        client.close()
+
+
+def test_client_surfaces_via_facade() -> None:
+    import automation_file
+
+    assert automation_file.HTTPActionClient is HTTPActionClient
+    assert automation_file.HTTPActionClientException is HTTPActionClientException