floodwall 0.1.0__tar.gz

floodwall-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 protosphinx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

floodwall-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: floodwall
+Version: 0.1.0
+Summary: Ask a Floodwall Cloud plane before your agent changes production.
+License-Expression: MIT
+Project-URL: Repository, https://github.com/erphq/floodwall
+Keywords: floodwall,agents,devops,policy,change-management
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: signing
+Requires-Dist: cryptography>=41; extra == "signing"
+Dynamic: license-file
+
+# floodwall (Python)
+
+Ask a Floodwall Cloud plane before your agent changes production, and tell it
+how the change went. Standard library only; Python 3.9+.
+
+```sh
+pip install floodwall
+```
+
+```python
+from floodwall import Floodwall
+
+fw = Floodwall(api_key=os.environ["FLOODWALL_KEY"], plane="pl_...", agent="deployer")
+
+# Runs the callable only if the plane admits the change, then reports
+# "succeeded", or "failed" with the exception if it raises.
+fw.guard(
+    {"action": {"kind": "scale", "resource": "web", "replicas": 5}, "priority": "normal"},
+    lambda: subprocess.run(["kubectl", "scale", "deploy/web", "--replicas=5"], check=True),
+)
+```
+
+`guard` waits while the change is queued or held for a person (up to
+`timeout_seconds`, 300 by default), and raises `NotAdmitted` if it is
+rejected, expires or lapses. Rate limits (HTTP 429) are waited out.
+
+- `submit`, `wait` and `report` are the steps `guard` takes.
+- `when_unreachable="open"` applies a change unchecked when the plane cannot
+  be reached (`URLError`, timeouts, connection errors and 5xx only) and calls
+  `on_fail_open(intent, error)`. Invalid changes, signing errors and a missing
+  `cryptography` package always raise. The default, `"closed"`, refuses it.
+  The default `on_fail_open` warns with the agent, kind, resource and error,
+  never the manifest.
+- A timeout leaves the intent **held** on the plane: `NotAdmitted` with
+  status `"held"` means it may still be released later. Do not apply the change
+  afterwards without submitting it again.
+- `wait` never polls more than once a second, whatever the server does.
+- If `apply` raises and reporting the failure fails too, your exception is
+  still the one raised (the report error is on its `report_error`). If `apply`
+  succeeds but the report fails, `guard` returns the result and calls
+  `on_report_error(error, key)` (default: `warnings.warn`). Failure reasons are
+  sent with whitespace collapsed, at most 1024 characters.
+- `base_url` must be `https://`, except for `localhost`, `127.0.0.1` and
+  `[::1]`. Redirects are never followed, and the key is not in `repr()`.
+- `Retry-After` may be seconds or an HTTP date.
+- `signing_key` signs each intent, for planes whose keyring requires it:
+  `pip install floodwall[signing]`.
+
+Tests: `python3 -m unittest discover -s tests -t .`
+
+Releases: bump `version` in `pyproject.toml`, then push a tag `sdk-python-v<version>`;
+the `publish-python` workflow publishes it to PyPI (Trusted Publishing, no token).

floodwall-0.1.0/README.md

@@ -0,0 +1,52 @@
+# floodwall (Python)
+
+Ask a Floodwall Cloud plane before your agent changes production, and tell it
+how the change went. Standard library only; Python 3.9+.
+
+```sh
+pip install floodwall
+```
+
+```python
+from floodwall import Floodwall
+
+fw = Floodwall(api_key=os.environ["FLOODWALL_KEY"], plane="pl_...", agent="deployer")
+
+# Runs the callable only if the plane admits the change, then reports
+# "succeeded", or "failed" with the exception if it raises.
+fw.guard(
+    {"action": {"kind": "scale", "resource": "web", "replicas": 5}, "priority": "normal"},
+    lambda: subprocess.run(["kubectl", "scale", "deploy/web", "--replicas=5"], check=True),
+)
+```
+
+`guard` waits while the change is queued or held for a person (up to
+`timeout_seconds`, 300 by default), and raises `NotAdmitted` if it is
+rejected, expires or lapses. Rate limits (HTTP 429) are waited out.
+
+- `submit`, `wait` and `report` are the steps `guard` takes.
+- `when_unreachable="open"` applies a change unchecked when the plane cannot
+  be reached (`URLError`, timeouts, connection errors and 5xx only) and calls
+  `on_fail_open(intent, error)`. Invalid changes, signing errors and a missing
+  `cryptography` package always raise. The default, `"closed"`, refuses it.
+  The default `on_fail_open` warns with the agent, kind, resource and error,
+  never the manifest.
+- A timeout leaves the intent **held** on the plane: `NotAdmitted` with
+  status `"held"` means it may still be released later. Do not apply the change
+  afterwards without submitting it again.
+- `wait` never polls more than once a second, whatever the server does.
+- If `apply` raises and reporting the failure fails too, your exception is
+  still the one raised (the report error is on its `report_error`). If `apply`
+  succeeds but the report fails, `guard` returns the result and calls
+  `on_report_error(error, key)` (default: `warnings.warn`). Failure reasons are
+  sent with whitespace collapsed, at most 1024 characters.
+- `base_url` must be `https://`, except for `localhost`, `127.0.0.1` and
+  `[::1]`. Redirects are never followed, and the key is not in `repr()`.
+- `Retry-After` may be seconds or an HTTP date.
+- `signing_key` signs each intent, for planes whose keyring requires it:
+  `pip install floodwall[signing]`.
+
+Tests: `python3 -m unittest discover -s tests -t .`
+
+Releases: bump `version` in `pyproject.toml`, then push a tag `sdk-python-v<version>`;
+the `publish-python` workflow publishes it to PyPI (Trusted Publishing, no token).

floodwall-0.1.0/floodwall/__init__.py

@@ -0,0 +1,379 @@
+"""Ask a Floodwall Cloud plane before an agent changes production.
+
+Standard library only. Signing intents (for planes with a keyring) needs the
+optional ``cryptography`` package: ``pip install floodwall[signing]``.
+
+    fw = Floodwall(api_key="fw_live_...", plane="pl_...", agent="deployer")
+    fw.guard({"action": {"kind": "scale", "resource": "web", "replicas": 5}},
+             lambda: scale_web(5))
+"""
+
+from __future__ import annotations
+
+import hashlib
+import datetime
+import email.utils
+import json
+import math
+import socket
+import struct
+import threading
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import warnings
+from typing import Any, Callable, Dict, Optional, TypeVar
+
+__all__ = ["Floodwall", "FloodwallError", "NotAdmitted", "intent_bytes", "intent_digest"]
+
+DEFAULT_BASE_URL = "https://api.floodwall.ai"
+PRIORITIES = ("bulk", "normal", "urgent", "pager")
+BLAST_RADII = ("cell", "service", "region", "global")
+WAITING = {"queued", "held"}
+#: Polls of a waiting intent are never closer together than this, whatever the server does.
+MIN_POLL_SECONDS = 1.0
+MAX_REASON = 1024
+LOCAL_HOSTS = ("localhost", "127.0.0.1", "::1")
+
+T = TypeVar("T")
+
+
+class FloodwallError(Exception):
+    """The plane answered with an error the caller should not retry blindly."""
+
+    def __init__(self, status: int, message: str, body: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+class NotAdmitted(Exception):
+    """The change was rejected, expired or lapsed, or still waited when time ran out.
+
+    When ``decision["status"]`` is ``"held"`` (or ``"queued"``) after a timeout,
+    the intent is still held on the plane and may be released later. The agent
+    must not apply the change afterwards without submitting it again.
+    """
+
+    def __init__(self, decision: Dict[str, Any]):
+        key = decision["key"]
+        why = f": {decision['reason']}" if decision.get("reason") else ""
+        super().__init__(f"floodwall did not admit {key['agent']}/{key['id']}: {decision['status']}{why}")
+        self.decision = decision
+
+
+# A 429's Retry-After is waited out up to this, however long it asks for.
+_MAX_RETRY_AFTER_SECONDS = 60.0
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """A redirect is an error: the API key must not follow a response to another place."""
+
+    def redirect_request(self, *args, **kwargs):
+        return None
+
+
+class Floodwall:
+    """A connection to one plane, as one agent.
+
+    ``when_unreachable`` is ``"closed"`` (the default: a change the plane
+    cannot be asked about is refused) or ``"open"`` (it is applied unchecked
+    and ``on_fail_open`` is called). ``signing_key`` is the agent's Ed25519
+    private key: 32 seed bytes, or a ``cryptography`` Ed25519PrivateKey.
+
+    ``base_url`` must be ``https://`` unless the host is localhost, 127.0.0.1
+    or ``[::1]``. ``on_report_error(error, key)`` is told when reporting a
+    successful change failed (the result is still returned); the default warns
+    without the manifest. Redirects are never followed.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        plane: str,
+        agent: str,
+        base_url: str = DEFAULT_BASE_URL,
+        when_unreachable: str = "closed",
+        on_fail_open: Optional[Callable[[Any, BaseException], None]] = None,
+        signing_key: Any = None,
+        on_report_error: Optional[Callable[[BaseException, Dict[str, str]], None]] = None,
+        opener: Optional[Callable[[urllib.request.Request, float], Any]] = None,
+        timeout: float = 30.0,
+    ):
+        for name, value in (("api_key", api_key), ("plane", plane), ("agent", agent)):
+            if not isinstance(value, str) or not value:
+                raise TypeError(f"{name} is required")
+        if when_unreachable not in ("closed", "open"):
+            raise ValueError('when_unreachable must be "closed" or "open"')
+        _check_base_url(base_url)
+        self.api_key = api_key
+        self.plane = plane
+        self.agent = agent
+        self.base_url = base_url.rstrip("/")
+        self.when_unreachable = when_unreachable
+        self.on_fail_open = on_fail_open or _warn_fail_open
+        self.on_report_error = on_report_error or _warn_report_error
+        self.signing_key = signing_key
+        self.timeout = timeout
+        if opener is None:
+            built = urllib.request.build_opener(_NoRedirect)
+            opener = lambda request, timeout: built.open(request, timeout=timeout)  # noqa: E731
+        self._open = opener
+        self._sleep = time.sleep
+        self._last_id = 0
+        self._lock = threading.Lock()
+
+    def __repr__(self) -> str:
+        return f"Floodwall(plane={self.plane!r}, agent={self.agent!r}, base_url={self.base_url!r})"
+
+    def next_id(self) -> int:
+        """An id above every id this client has used: the time in microseconds, or one more."""
+        with self._lock:
+            self._last_id = max(self._last_id + 1, int(time.time() * 1_000_000))
+            return self._last_id
+
+    def intent(self, change: Dict[str, Any]) -> Dict[str, Any]:
+        """The change in the plane's form (keys in the order the plane reads them)."""
+        action = change.get("action") or {}
+        priority = change.get("priority", "normal")
+        blast = change.get("blast_radius", change.get("blastRadius", "service"))
+        if priority not in PRIORITIES:
+            raise ValueError(f"priority must be one of {', '.join(PRIORITIES)}")
+        if blast not in BLAST_RADII:
+            raise ValueError(f"blast_radius must be one of {', '.join(BLAST_RADII)}")
+        kind = action.get("kind")
+        if kind == "apply":
+            normalized = {"kind": "apply", "resource": str(action["resource"]), "manifest": str(action.get("manifest", ""))}
+        elif kind == "scale":
+            replicas = action.get("replicas")
+            if not isinstance(replicas, int) or isinstance(replicas, bool) or not 0 <= replicas <= 0xFFFFFFFF:
+                raise ValueError("scale replicas must be a whole number from 0 to 4294967295")
+            normalized = {"kind": "scale", "resource": str(action["resource"]), "replicas": replicas}
+        elif kind == "destroy":
+            normalized = {"kind": "destroy", "resource": str(action["resource"])}
+        else:
+            raise ValueError('action.kind must be "apply", "scale" or "destroy"')
+        return {
+            "id": str(change["id"] if "id" in change else self.next_id()),
+            "agent": self.agent,
+            "action": normalized,
+            "priority": priority,
+            "blast_radius": blast,
+            "signature": None,
+        }
+
+    def prepare(self, change: Dict[str, Any]) -> Dict[str, Any]:
+        """Validate (and sign, when there is a key) a change: errors here are the caller's, never "unreachable"."""
+        intent = change if "agent" in change and "blast_radius" in change else self.intent(change)
+        if self.signing_key is not None:
+            intent["signature"] = sign(intent, self.signing_key)
+        return intent
+
+    def submit(self, change: Dict[str, Any]) -> Dict[str, Any]:
+        """Offer a change; returns the plane's first answer (admit, held, rejected or queued)."""
+        return self._post(self.prepare(change))
+
+    def _post(self, intent: Dict[str, Any]) -> Dict[str, Any]:
+        answer = self._request("POST", f"/v1/planes/{_q(self.plane)}/intents", intent)
+        return _decision(answer, intent["agent"], intent["id"])
+
+    def wait(self, key: Dict[str, str], timeout_seconds: float = 300) -> Dict[str, Any]:
+        """Wait until the intent leaves the queue and the hold queue, or time runs out.
+
+        A timeout leaves the intent held. Polls are at least a second apart even
+        if the server answers at once.
+        """
+        until = time.monotonic() + timeout_seconds
+        while True:
+            started = time.monotonic()
+            left = until - started
+            wait = max(0, min(20, int(left + 0.999)))
+            answer = self._request(
+                "GET", f"/v1/planes/{_q(self.plane)}/intents/{_q(key['agent'])}/{_q(key['id'])}?wait={wait}"
+            )
+            status = _decision(answer, key["agent"], key["id"])
+            if status["status"] not in WAITING or left <= 0:
+                return status
+            pause = min(MIN_POLL_SECONDS - (time.monotonic() - started), until - time.monotonic())
+            if pause > 0:
+                self._sleep(pause)
+
+    def report(self, key: Dict[str, str], outcome: str, reason: Optional[str] = None) -> None:
+        """Report how an admitted change went, which frees its resource."""
+        if outcome not in ("succeeded", "failed"):
+            raise ValueError('outcome must be "succeeded" or "failed"')
+        self._request(
+            "POST",
+            f"/v1/planes/{_q(self.plane)}/intents/{_q(key['agent'])}/{_q(key['id'])}/outcome",
+            {"outcome": outcome, "reason": None if reason is None else " ".join(str(reason).split())[:MAX_REASON]},
+        )
+
+    def guard(self, change: Dict[str, Any], apply: Callable[[], T], timeout_seconds: float = 300) -> T:
+        """Run ``apply`` only if the plane admits the change, and report how it went.
+
+        Raises ``NotAdmitted`` when it is not admitted (a ``"held"`` intent after a
+        timeout may still be released later: do not apply the change then without
+        submitting it again). If ``apply`` raises and the failure report fails too,
+        the apply error is still the one raised, with the report error on its
+        ``report_error`` attribute. If ``apply`` succeeds but the report fails, the
+        result is returned and ``on_report_error`` is told. Only transport failures
+        and 5xx count as unreachable; invalid changes and signing errors always raise.
+        """
+        intent = self.prepare(change)
+        try:
+            first = self._post(intent)
+        except Exception as error:  # noqa: BLE001 - classified below
+            if self.when_unreachable == "open" and _unreachable(error):
+                self.on_fail_open(intent, error)
+                return apply()
+            raise
+        settled = self.wait(first["key"], timeout_seconds) if first["status"] in WAITING else first
+        if settled["status"] not in ("admit", "in_flight"):
+            raise NotAdmitted(settled)
+        try:
+            result = apply()
+        except BaseException as error:
+            try:
+                self.report(first["key"], "failed", str(error))
+            except Exception as report_error:  # noqa: BLE001 - the change's error wins
+                try:
+                    error.report_error = report_error
+                except Exception:  # noqa: BLE001
+                    pass
+            raise
+        try:
+            self.report(first["key"], "succeeded")
+        except Exception as report_error:  # noqa: BLE001
+            self.on_report_error(report_error, first["key"])
+        return result
+
+    def _request(self, method: str, path: str, body: Any = None) -> Dict[str, Any]:
+        data = None if body is None else json.dumps(body, separators=(",", ":")).encode()
+        headers = {"User-Agent": "floodwall-python/0.1"}
+        if data is not None:
+            headers["Content-Type"] = "application/json"
+        for attempt in range(6):
+            request = urllib.request.Request(self.base_url + path, data=data, method=method, headers=headers)
+            request.add_unredirected_header("Authorization", f"Bearer {self.api_key}")
+            try:
+                with self._open(request, self.timeout) as response:
+                    text = response.read().decode()
+                    return json.loads(text) if text else {}
+            except urllib.error.HTTPError as error:
+                text = error.read().decode(errors="replace")
+                try:
+                    parsed = json.loads(text) if text else {}
+                except ValueError:
+                    parsed = {"error": text}
+                if error.code == 429 and attempt < 5:
+                    self._sleep(_retry_after(error.headers.get("Retry-After")))
+                    continue
+                raise FloodwallError(error.code, parsed.get("error") or f"floodwall answered {error.code}", parsed) from None
+        raise AssertionError("unreachable")
+
+
+def _q(value: Any) -> str:
+    return urllib.parse.quote(str(value), safe="")
+
+
+def _unreachable(error: BaseException) -> bool:
+    """Only a transport failure (no connection, a timeout) or a 5xx means the plane is unreachable."""
+    if isinstance(error, FloodwallError):
+        return error.status >= 500
+    if isinstance(error, urllib.error.HTTPError):
+        return False
+    return isinstance(error, (urllib.error.URLError, socket.timeout, ConnectionError, TimeoutError))
+
+
+def _retry_after(value: Any) -> float:
+    """Seconds to wait from a Retry-After header, given as seconds or an HTTP date; 1 s if unusable, 60 s at most."""
+    try:
+        text = str(value).strip()
+        try:
+            seconds = float(text)
+        except ValueError:
+            when = email.utils.parsedate_to_datetime(text)
+            if when.tzinfo is None:
+                when = when.replace(tzinfo=datetime.timezone.utc)
+            seconds = (when - datetime.datetime.now(datetime.timezone.utc)).total_seconds()
+        return min(max(0.0, seconds), _MAX_RETRY_AFTER_SECONDS) if math.isfinite(seconds) else 1.0
+    except Exception:  # noqa: BLE001 - a bad header must not crash the client
+        return 1.0
+
+
+def _check_base_url(base_url: str) -> None:
+    parts = urllib.parse.urlsplit(base_url)
+    if parts.scheme == "https" and parts.hostname:
+        return
+    if parts.scheme == "http" and parts.hostname in LOCAL_HOSTS:
+        return
+    raise ValueError("base_url must be https:// unless the host is localhost, 127.0.0.1 or [::1]")
+
+
+def _warn_fail_open(intent: Any, error: BaseException) -> None:
+    action = intent.get("action") or {}
+    warnings.warn(
+        f"floodwall unreachable; applied unchecked: agent={intent.get('agent')} kind={action.get('kind')} "
+        f"resource={action.get('resource')}: {error}",
+        stacklevel=2,
+    )
+
+
+def _warn_report_error(error: BaseException, key: Dict[str, str]) -> None:
+    warnings.warn(f"floodwall could not report the outcome of {key['agent']}/{key['id']}: {error}", stacklevel=2)
+
+
+def _decision(answer: Dict[str, Any], agent: str, intent_id: str) -> Dict[str, Any]:
+    key = answer.get("key") or {"agent": agent, "id": intent_id}
+    status = answer.get("status") or answer.get("verdict") or "queued"
+    status = {"defer": "held", "reject": "rejected"}.get(status, status)
+    return {
+        "key": {"agent": key["agent"], "id": str(key["id"])},
+        "status": status,
+        "verdict": answer.get("verdict"),
+        "reason": answer.get("reason"),
+        "policies": answer.get("policies", []),
+    }
+
+
+def _field(parts: list, data: bytes) -> None:
+    parts.append(struct.pack("<Q", len(data)))
+    parts.append(data)
+
+
+def intent_bytes(intent: Dict[str, Any]) -> bytes:
+    """The bytes whose SHA-256 an agent signs (the crate's Intent::digest)."""
+    parts: list = []
+    _field(parts, b"floodwall/intent/v1")
+    _field(parts, intent["agent"].encode())
+    parts.append(struct.pack("<Q", int(intent["id"])))
+    action = intent["action"]
+    if action["kind"] == "apply":
+        parts.append(b"\x00")
+        _field(parts, action["resource"].encode())
+        _field(parts, action["manifest"].encode())
+    elif action["kind"] == "scale":
+        parts.append(b"\x01")
+        _field(parts, action["resource"].encode())
+        parts.append(struct.pack("<I", action["replicas"]))
+    else:
+        parts.append(b"\x02")
+        _field(parts, action["resource"].encode())
+    parts.append(bytes([PRIORITIES.index(intent["priority"]), BLAST_RADII.index(intent["blast_radius"])]))
+    return b"".join(parts)
+
+
+def intent_digest(intent: Dict[str, Any]) -> bytes:
+    return hashlib.sha256(intent_bytes(intent)).digest()
+
+
+def sign(intent: Dict[str, Any], key: Any) -> str:
+    """The intent's Ed25519 signature as hex. Needs the ``cryptography`` package."""
+    try:
+        from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+    except ImportError as error:  # pragma: no cover - depends on the environment
+        raise RuntimeError("signing intents needs `pip install floodwall[signing]`") from error
+    if isinstance(key, (bytes, bytearray)):
+        key = Ed25519PrivateKey.from_private_bytes(bytes(key))
+    return key.sign(intent_digest(intent)).hex()

floodwall-0.1.0/floodwall.egg-info/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: floodwall
+Version: 0.1.0
+Summary: Ask a Floodwall Cloud plane before your agent changes production.
+License-Expression: MIT
+Project-URL: Repository, https://github.com/erphq/floodwall
+Keywords: floodwall,agents,devops,policy,change-management
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: signing
+Requires-Dist: cryptography>=41; extra == "signing"
+Dynamic: license-file
+
+# floodwall (Python)
+
+Ask a Floodwall Cloud plane before your agent changes production, and tell it
+how the change went. Standard library only; Python 3.9+.
+
+```sh
+pip install floodwall
+```
+
+```python
+from floodwall import Floodwall
+
+fw = Floodwall(api_key=os.environ["FLOODWALL_KEY"], plane="pl_...", agent="deployer")
+
+# Runs the callable only if the plane admits the change, then reports
+# "succeeded", or "failed" with the exception if it raises.
+fw.guard(
+    {"action": {"kind": "scale", "resource": "web", "replicas": 5}, "priority": "normal"},
+    lambda: subprocess.run(["kubectl", "scale", "deploy/web", "--replicas=5"], check=True),
+)
+```
+
+`guard` waits while the change is queued or held for a person (up to
+`timeout_seconds`, 300 by default), and raises `NotAdmitted` if it is
+rejected, expires or lapses. Rate limits (HTTP 429) are waited out.
+
+- `submit`, `wait` and `report` are the steps `guard` takes.
+- `when_unreachable="open"` applies a change unchecked when the plane cannot
+  be reached (`URLError`, timeouts, connection errors and 5xx only) and calls
+  `on_fail_open(intent, error)`. Invalid changes, signing errors and a missing
+  `cryptography` package always raise. The default, `"closed"`, refuses it.
+  The default `on_fail_open` warns with the agent, kind, resource and error,
+  never the manifest.
+- A timeout leaves the intent **held** on the plane: `NotAdmitted` with
+  status `"held"` means it may still be released later. Do not apply the change
+  afterwards without submitting it again.
+- `wait` never polls more than once a second, whatever the server does.
+- If `apply` raises and reporting the failure fails too, your exception is
+  still the one raised (the report error is on its `report_error`). If `apply`
+  succeeds but the report fails, `guard` returns the result and calls
+  `on_report_error(error, key)` (default: `warnings.warn`). Failure reasons are
+  sent with whitespace collapsed, at most 1024 characters.
+- `base_url` must be `https://`, except for `localhost`, `127.0.0.1` and
+  `[::1]`. Redirects are never followed, and the key is not in `repr()`.
+- `Retry-After` may be seconds or an HTTP date.
+- `signing_key` signs each intent, for planes whose keyring requires it:
+  `pip install floodwall[signing]`.
+
+Tests: `python3 -m unittest discover -s tests -t .`
+
+Releases: bump `version` in `pyproject.toml`, then push a tag `sdk-python-v<version>`;
+the `publish-python` workflow publishes it to PyPI (Trusted Publishing, no token).

floodwall-0.1.0/floodwall.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+floodwall/__init__.py
+floodwall.egg-info/PKG-INFO
+floodwall.egg-info/SOURCES.txt
+floodwall.egg-info/dependency_links.txt
+floodwall.egg-info/requires.txt
+floodwall.egg-info/top_level.txt
+tests/test_client.py

floodwall-0.1.0/floodwall.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

floodwall-0.1.0/floodwall.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[signing]
+cryptography>=41

floodwall-0.1.0/floodwall.egg-info/top_level.txt

@@ -0,0 +1 @@
+floodwall

floodwall-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "floodwall"
+version = "0.1.0"
+description = "Ask a Floodwall Cloud plane before your agent changes production."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["floodwall", "agents", "devops", "policy", "change-management"]
+requires-python = ">=3.9"
+dependencies = []
+
+[project.optional-dependencies]
+# Only for planes that require signed intents.
+signing = ["cryptography>=41"]
+
+[tool.setuptools]
+# Only the client; tests/ is not part of the package.
+packages = ["floodwall"]
+
+[project.urls]
+Repository = "https://github.com/erphq/floodwall"

floodwall-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

floodwall-0.1.0/tests/test_client.py

@@ -0,0 +1,300 @@
+import http.server
+import io
+import json
+import socket
+import sys
+import threading
+import unittest
+import urllib.error
+import warnings
+from unittest import mock
+
+from floodwall import Floodwall, FloodwallError, NotAdmitted, intent_bytes
+
+
+class Answer(io.BytesIO):
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        return False
+
+
+def stub(handler):
+    calls = []
+
+    def opener(request, timeout):
+        body = json.loads(request.data) if request.data else None
+        call = {"method": request.get_method(), "url": request.full_url, "headers": dict(request.header_items()), "body": body}
+        calls.append(call)
+        status, answer = handler(call)
+        data = json.dumps(answer).encode()
+        if status >= 400:
+            raise urllib.error.HTTPError(request.full_url, status, "error", {"Retry-After": "0"}, io.BytesIO(data))
+        return Answer(data)
+
+    return calls, opener
+
+
+def client(opener, **extra):
+    return Floodwall(api_key="fw_test_x", plane="p1", agent="deployer", opener=opener, **extra)
+
+
+SCALE = {"action": {"kind": "scale", "resource": "web", "replicas": 3}}
+
+
+class ClientTest(unittest.TestCase):
+    def test_guard_applies_an_admitted_change_and_reports_it(self):
+        calls, opener = stub(lambda c: (200, {"verdict": "admit"}))
+        self.assertEqual(client(opener).guard(SCALE, lambda: "applied"), "applied")
+        self.assertEqual(calls[0]["headers"]["Authorization"], "Bearer fw_test_x")
+        self.assertEqual(list(calls[0]["body"]), ["id", "agent", "action", "priority", "blast_radius", "signature"])
+        self.assertTrue(calls[1]["url"].endswith("/outcome"))
+        self.assertEqual(calls[1]["body"], {"outcome": "succeeded", "reason": None})
+
+    def test_a_held_change_is_applied_once_released(self):
+        polls = []
+
+        def handler(c):
+            if c["method"] == "POST" and c["url"].endswith("/intents"):
+                return 200, {"verdict": "defer", "reason": "off the allowlist"}
+            if c["method"] == "GET":
+                polls.append(1)
+                return 200, {"status": "held" if len(polls) < 2 else "in_flight"}
+            return 200, {}
+
+        calls, opener = stub(handler)
+        client(opener).guard(SCALE, lambda: None)
+        self.assertEqual(len(polls), 2)
+
+    def test_a_rejected_change_is_never_applied(self):
+        calls, opener = stub(lambda c: (200, {"verdict": "reject", "reason": "no"}))
+        with self.assertRaises(NotAdmitted):
+            client(opener).guard(SCALE, lambda: self.fail("applied"))
+        self.assertEqual(len(calls), 1)
+
+    def test_a_failing_change_is_reported_failed(self):
+        calls, opener = stub(lambda c: (200, {"verdict": "admit"}))
+
+        def boom():
+            raise RuntimeError("kubectl exploded")
+
+        with self.assertRaises(RuntimeError):
+            client(opener).guard(SCALE, boom)
+        self.assertEqual(calls[-1]["body"], {"outcome": "failed", "reason": "kubectl exploded"})
+
+    def test_rate_limits_are_waited_out(self):
+        tries = []
+
+        def handler(c):
+            tries.append(1)
+            return (429, {"error": "slow"}) if len(tries) < 2 else (200, {"verdict": "admit"})
+
+        calls, opener = stub(handler)
+        self.assertEqual(client(opener).submit(SCALE)["status"], "admit")
+
+    def test_unreachable_closed_refuses_and_open_applies(self):
+        def down(request, timeout):
+            raise urllib.error.URLError("no route")
+
+        with self.assertRaises(urllib.error.URLError):
+            client(down).guard(SCALE, lambda: self.fail())
+        unchecked = []
+        out = client(down, when_unreachable="open", on_fail_open=lambda c, e: unchecked.append(c)).guard(SCALE, lambda: "ran")
+        self.assertEqual(out, "ran")
+        self.assertEqual(len(unchecked), 1)
+        calls, opener = stub(lambda c: (401, {"error": "bad key"}))
+        with self.assertRaises(FloodwallError):
+            client(opener, when_unreachable="open").guard(SCALE, lambda: self.fail())
+
+    def test_signed_bytes_match_the_crate(self):
+        import struct
+
+        def field(s):
+            return struct.pack("<Q", len(s)) + s
+
+        got = intent_bytes({"id": "7", "agent": "a", "action": {"kind": "scale", "resource": "w", "replicas": 2},
+                            "priority": "urgent", "blast_radius": "region", "signature": None})
+        want = field(b"floodwall/intent/v1") + field(b"a") + struct.pack("<Q", 7) + b"\x01" + field(b"w") + struct.pack("<I", 2) + b"\x02\x02"
+        self.assertEqual(got, want)
+
+    def test_fail_open_only_for_transport_failures(self):
+        seen = []
+        asked = []
+
+        def down(request, timeout):
+            asked.append(1)
+            raise urllib.error.URLError("no route")
+
+        def open_(opener, **extra):
+            return client(opener, when_unreachable="open", on_fail_open=lambda i, e: seen.append(i), **extra)
+
+        # Validation errors raise, with no request and nothing applied.
+        with self.assertRaises(ValueError):
+            open_(down).guard({**SCALE, "priority": "nope"}, lambda: self.fail("applied"))
+        with self.assertRaises(ValueError):
+            open_(down).guard({"action": {"kind": "scale", "resource": "w", "replicas": -1}}, lambda: self.fail("applied"))
+        # A missing `cryptography` package raises, never fails open.
+        with mock.patch.dict(sys.modules, {"cryptography": None, "cryptography.hazmat.primitives.asymmetric.ed25519": None}):
+            with self.assertRaises(RuntimeError):
+                open_(down, signing_key=b"k" * 32).guard(SCALE, lambda: self.fail("applied"))
+        self.assertEqual((asked, seen), ([], []))
+
+        def raising(exc):
+            def opener(request, timeout):
+                raise exc
+
+            return opener
+
+        with self.assertRaises(KeyError):
+            open_(raising(KeyError("odd"))).guard(SCALE, lambda: self.fail("applied"))
+        for exc in (urllib.error.URLError("x"), socket.timeout("t"), ConnectionResetError("r"), TimeoutError("t")):
+            self.assertEqual(open_(raising(exc)).guard(SCALE, lambda: "ran"), "ran")
+        _, opener = stub(lambda c: (503, {"error": "down"}))
+        self.assertEqual(open_(opener).guard(SCALE, lambda: "ran"), "ran")
+        _, opener = stub(lambda c: (400, {"error": "bad"}))
+        with self.assertRaises(FloodwallError):
+            open_(opener).guard(SCALE, lambda: self.fail("applied"))
+        self.assertEqual(len(seen), 5)
+
+    def test_default_fail_open_warning_leaves_the_manifest_out(self):
+        def down(request, timeout):
+            raise urllib.error.URLError("no route")
+
+        change = {"action": {"kind": "apply", "resource": "web", "manifest": "SECRET: hunter2"}}
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always", UserWarning)
+            warnings.simplefilter("ignore", ResourceWarning)
+            client(down, when_unreachable="open").guard(change, lambda: 1)
+        self.assertEqual(len(caught), 1)
+        text = str(caught[0].message)
+        self.assertIn("deployer", text)
+        self.assertIn("web", text)
+        self.assertNotIn("hunter2", text)
+
+    def test_wait_never_polls_faster_than_once_a_second(self):
+        polls = []
+        calls, opener = stub(lambda c: (200, {"status": "held" if len(polls.append(1) or polls) < 4 else "in_flight"}))
+        fw = client(opener)
+        sleeps = []
+        fw._sleep = sleeps.append
+        self.assertEqual(fw.wait({"agent": "deployer", "id": "1"})["status"], "in_flight")
+        self.assertEqual(len(sleeps), 3)
+        for pause in sleeps:
+            self.assertTrue(0.9 < pause <= 1.0, pause)
+
+    def test_a_failed_report_never_masks_the_changes_error(self):
+        calls, opener = stub(lambda c: (200, {"verdict": "admit"}) if c["url"].endswith("/intents") else (500, {"error": "down"}))
+        error = RuntimeError("kubectl exploded")
+
+        def boom():
+            raise error
+
+        with self.assertRaises(RuntimeError) as raised:
+            client(opener).guard(SCALE, boom)
+        self.assertIs(raised.exception, error)
+        self.assertEqual(error.report_error.status, 500)
+
+    def test_a_failed_report_after_success_returns_the_result(self):
+        calls, opener = stub(lambda c: (200, {"verdict": "admit"}) if c["url"].endswith("/intents") else (500, {"error": "down"}))
+        told = []
+        out = client(opener, on_report_error=lambda e, k: told.append((e, k))).guard(SCALE, lambda: "applied")
+        self.assertEqual(out, "applied")
+        self.assertEqual(told[0][0].status, 500)
+        self.assertEqual(told[0][1]["agent"], "deployer")
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always", UserWarning)
+            warnings.simplefilter("ignore", ResourceWarning)
+            self.assertEqual(client(opener).guard(SCALE, lambda: "ok"), "ok")
+        self.assertEqual(len(caught), 1)
+
+    def test_failure_reasons_are_collapsed_and_capped(self):
+        calls, opener = stub(lambda c: (200, {"verdict": "admit"}))
+        with self.assertRaises(RuntimeError):
+            client(opener).guard(SCALE, lambda: (_ for _ in ()).throw(RuntimeError("a\n\n  b\tc " + "x" * 3000)))
+        reason = calls[-1]["body"]["reason"]
+        self.assertTrue(reason.startswith("a b c xxx"))
+        self.assertEqual(len(reason), 1024)
+
+    def test_ids_are_not_burned_when_given(self):
+        fw = client(lambda r, t: None)
+        self.assertEqual(fw.intent({**SCALE, "id": 5})["id"], "5")
+        self.assertEqual(fw._last_id, 0)
+
+    def test_retry_after_is_waited_out_for_a_minute_at_most(self):
+        for header, expected in (("3600", 60.0), ("Wed, 21 Oct 2099 07:28:00 GMT", 60.0), ("2", 2.0)):
+            tries = []
+            slept = []
+
+            def opener(request, timeout, header=header):
+                tries.append(1)
+                if len(tries) < 2:
+                    raise urllib.error.HTTPError(request.full_url, 429, "slow", {"Retry-After": header}, io.BytesIO(b"{}"))
+                return Answer(b'{"verdict":"admit"}')
+
+            fw = client(opener)
+            fw._sleep = slept.append
+            fw.submit(SCALE)
+            self.assertEqual(slept, [expected], header)
+
+    def test_retry_after_may_be_a_date_or_garbage(self):
+        for header in ("Wed, 21 Oct 2099 07:28:00 GMT", "soon", "", "nan", "-5"):
+            tries = []
+
+            def opener(request, timeout, header=header):
+                tries.append(1)
+                if len(tries) < 2:
+                    raise urllib.error.HTTPError(request.full_url, 429, "slow", {"Retry-After": header}, io.BytesIO(b"{}"))
+                return Answer(b'{"verdict":"admit"}')
+
+            fw = client(opener)
+            fw._sleep = lambda s: None
+            self.assertEqual(fw.submit(SCALE)["status"], "admit", header)
+
+    def test_base_url_must_be_https_unless_local_and_the_key_stays_out_of_repr(self):
+        for url in ("http://api.example.com", "ftp://x", "api.example.com"):
+            with self.assertRaises(ValueError):
+                client(None, base_url=url)
+        for url in ("https://api.example.com/", "http://localhost:8787", "http://127.0.0.1:1", "http://[::1]:3"):
+            client(None, base_url=url)
+        self.assertNotIn("fw_test_x", repr(client(None)))
+
+    def test_redirects_are_refused_and_the_key_is_not_forwarded(self):
+        hits = []
+
+        class Target(http.server.BaseHTTPRequestHandler):
+            def do_POST(self):
+                hits.append(dict(self.headers))
+                self.send_response(200)
+                self.end_headers()
+                self.wfile.write(b"{}")
+
+            log_message = lambda *a: None  # noqa: E731
+
+        target = http.server.HTTPServer(("127.0.0.1", 0), Target)
+
+        class Redirect(http.server.BaseHTTPRequestHandler):
+            def do_POST(self):
+                self.send_response(307)
+                self.send_header("Location", f"http://127.0.0.1:{target.server_port}/x")
+                self.end_headers()
+
+            log_message = lambda *a: None  # noqa: E731
+
+        front = http.server.HTTPServer(("127.0.0.1", 0), Redirect)
+        for server in (target, front):
+            threading.Thread(target=server.serve_forever, daemon=True).start()
+        try:
+            fw = Floodwall(api_key="fw_test_x", plane="p1", agent="deployer", base_url=f"http://127.0.0.1:{front.server_port}")
+            with self.assertRaises(FloodwallError) as raised:
+                fw.submit(SCALE)
+            self.assertEqual(raised.exception.status, 307)
+            self.assertEqual(hits, [])
+        finally:
+            for server in (target, front):
+                server.shutdown()
+                server.server_close()
+
+
+if __name__ == "__main__":
+    unittest.main()