rate limit patch (#45)

Author: karlg100

docs/RATE_LIMITING_AND_TIMEOUTS.md

@@ -0,0 +1,94 @@
+# Rate Limiting & Default Timeouts (Backwards-Compatible)
+
+This fork adds a **client-side write rate limiter** and **default HTTP timeouts** without breaking existing callers.
+
+- **Backwards compatible:** Existing code that calls `Frigidaire(email, password)` keeps working.
+- **Write call smoothing:** Mutating HTTP verbs (`POST`, `PUT`, `PATCH`, `DELETE`) are spaced out by default to avoid server lockouts.
+- **Retry-After aware:** `429/423` responses back off, honoring `Retry-After` (capped).
+- **Default HTTP timeout:** If a request doesn’t pass `timeout=...`, a library default is applied (`15s` by default).
+
+## Quickstart
+
+```python
+from frigidaire import Frigidaire
+# If your build doesn't auto-enable autowrap at import time, uncomment one of these:
+# import frigidaire.rl_autowrap as _
+# from frigidaire.rl_autowrap import enable_autowrap; enable_autowrap()
+
+api = Frigidaire("email", "password")
+devices = api.get_appliances()
+print(devices)
+```
+
+## Customization (optional)
+
+You can pass kwargs to `Frigidaire(...)` to tune behavior. All are optional:
+
+- `http_timeout`: float or `(connect, read)` tuple; default `15.0` seconds
+- `rate_limit_min_interval`: seconds between write requests; default `1.25`
+- `rate_limit_jitter`: random jitter added to spacing; default `0.25`
+- `rate_limit_methods`: set of verbs to limit; default `{"POST","PUT","PATCH","DELETE"}`
+- `rate_limit_scope_key`: share a limiter across instances by key (default: the account email)
+- `max_retry_after`: cap for honoring server `Retry-After`; default `60.0`
+- `max_retries_on_429`: max retries for `429/423`; default `4`
+
+**Example:**
+
+```python
+api = Frigidaire(
+    "email", "password",
+    http_timeout=20.0,                # or (5, 30)
+    rate_limit_min_interval=1.5,      # seconds between writes
+    rate_limit_jitter=0.3,            # smooth bursts
+    max_retry_after=90.0,
+    max_retries_on_429=5,
+    # rate_limit_methods={"POST","PUT","PATCH","DELETE"},
+    # rate_limit_scope_key="household-42",
+)
+```
+
+## CLI Smoke Tests
+
+We provide a small script in `scripts/smoke_test_frigidaire.py` that exercises the new features without changing device state.
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+
+export FRIGIDAIRE_EMAIL="you@example.com"
+export FRIGIDAIRE_PASSWORD="••••••••"
+
+# Optional tunables for the test run
+export MIN_INTERVAL=1.5
+export JITTER=0.0
+export HTTP_TIMEOUT=15.0
+
+python scripts/smoke_test_frigidaire.py       --min-interval "${MIN_INTERVAL:-1.5}"       --jitter "${JITTER:-0.0}"       --http-timeout "${HTTP_TIMEOUT:-15.0}"
+```
+
+What it checks:
+
+1. **Auth + list devices** (read-only)
+2. **Default timeout** (~15s) using a delayed URL when no per-request timeout is passed
+3. **Rate-limit spacing** using harmless POSTs to prove gaps between writes
+4. **Retry-After** handling — tries a live 429, then falls back to a local simulation if the live check is blocked
+
+## Opt-in vs. auto-enable
+
+If your package enables autowrap at import time (via a small block in `frigidaire/__init__.py`), no changes are needed by callers.  
+Otherwise, add one of these once at startup:
+
+```python
+import frigidaire.rl_autowrap as _
+# or
+from frigidaire.rl_autowrap import enable_autowrap
+enable_autowrap()
+```
+
+## Notes
+
+- The rate limiter is **in-process** and keyed by `rate_limit_scope_key` (defaults to the account email).
+- Reads (`GET`) are not rate-limited by default.
+- Timeouts apply **only** when a given request doesn’t already supply `timeout=`.
+- For Home Assistant users, no changes are required if the library is imported normally and autowrap is enabled.

frigidaire/__init__.py

@@ -592,3 +592,12 @@ def put_request(self, url: str, path: str, headers: Dict[str, str], data: Dict)
             return self.parse_response(response)
         except Exception as e:
             self.handle_request_exception(e, "PUT", f'{url}{path}', headers, encoded_data)
+
+# ---- Auto-enable write rate limiting (safe no-op if already enabled) ----
+try:
+    from .rl_autowrap import enable_autowrap as _frigidaire_enable_autowrap
+    _frigidaire_enable_autowrap()
+except Exception:
+    # Don't fail imports if autowrap can't be enabled
+    pass
+# -------------------------------------------------------------------------

frigidaire/rate_limit.py

@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: MIT
+from __future__ import annotations
+import random
+import threading
+import time
+from typing import Callable, Optional, Set, Union, Tuple
+
+RL_DEFAULT_METHODS: Set[str] = frozenset({"POST", "PUT", "PATCH", "DELETE"})
+TimeoutType = Union[float, Tuple[float, float]]  # requests supports float or (connect, read)
+
+class RateLimiter:
+    """Thread-safe limiter that ensures at least `min_interval` seconds between calls."""
+    def __init__(self, min_interval: float = 1.25, jitter: float = 0.0) -> None:
+        self._min = max(0.0, float(min_interval))
+        self._jitter = max(0.0, float(jitter))
+        self._lock = threading.Lock()
+        self._next_ok_at = 0.0  # monotonic timestamp (seconds)
+
+    def wait(self) -> None:
+        with self._lock:
+            now = time.monotonic()
+            if now < self._next_ok_at:
+                time.sleep(self._next_ok_at - now)
+            delay = self._min + (random.uniform(0.0, self._jitter) if self._jitter else 0.0)
+            self._next_ok_at = time.monotonic() + delay
+
+    def cool_down(self, extra_seconds: float) -> None:
+        if extra_seconds <= 0:
+            return
+        with self._lock:
+            self._next_ok_at = max(self._next_ok_at, time.monotonic() + float(extra_seconds))
+
+def _parse_retry_after_seconds(value: Optional[str]) -> Optional[float]:
+    if not value:
+        return None
+    try:
+        return float(value)  # prefer seconds
+    except Exception:
+        return None
+
+def wrap_session_request(
+    request_func: Callable[..., "requests.Response"],
+    limiter: "RateLimiter",
+    rl_methods: Set[str] = RL_DEFAULT_METHODS,
+    max_retry_after: float = 60.0,
+    max_retries_on_429: int = 4,
+    default_timeout: Optional[TimeoutType] = 15.0,
+) -> Callable[..., "requests.Response"]:
+    """Wrap requests.Session.request with rate limiting, 429 handling, and default timeout."""
+    import time as _time
+
+    def _wrapped(method: str, url: str, **kwargs):
+        m = (method or "").upper()
+        if m in rl_methods:
+            limiter.wait()
+
+        if default_timeout is not None and "timeout" not in kwargs:
+            kwargs["timeout"] = default_timeout
+
+        retries = 0
+        backoff = 1.0
+        while True:
+            resp = request_func(method, url, **kwargs)
+            status = getattr(resp, "status_code", None)
+            if status in (429, 423):
+                retry_after = _parse_retry_after_seconds(getattr(resp, "headers", {}).get("Retry-After"))
+                delay = min(float(max_retry_after), retry_after or backoff)
+                limiter.cool_down(delay)
+                if retries >= max_retries_on_429:
+                    return resp
+                _time.sleep(delay)
+                retries += 1
+                backoff = min(float(max_retry_after), backoff * 2.0)
+                continue
+            return resp
+
+    return _wrapped

frigidaire/rl_autowrap.py

@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: MIT
+from __future__ import annotations
+
+from typing import Any, Optional, Tuple, Union, Set
+from .rate_limit import RateLimiter, RL_DEFAULT_METHODS, wrap_session_request
+
+TimeoutType = Union[float, Tuple[float, float]]
+_ENABLED = False
+
+def _coerce_timeout(val: Any) -> Optional[TimeoutType]:
+    if val is None:
+        return None
+    if isinstance(val, (int, float)):
+        return float(val)
+    if isinstance(val, (tuple, list)) and len(val) == 2:
+        return (float(val[0]), float(val[1]))
+    if isinstance(val, str):
+        s = val.strip()
+        if "," in s:
+            a, b = s.split(",", 1)
+            return (float(a), float(b))
+        try:
+            return float(s)
+        except ValueError:
+            return None
+    return None
+
+def enable_autowrap() -> None:
+    global _ENABLED
+    if _ENABLED:
+        return
+    try:
+        import frigidaire as pkg
+    except Exception:
+        return
+
+    Frigidaire = getattr(pkg, "Frigidaire", None)
+    if Frigidaire is None or getattr(Frigidaire, "_rl_patched", False):
+        _ENABLED = True
+        return
+
+    orig_init = Frigidaire.__init__
+
+    def __init__(self, email: str, password: str, *args: Any, **kwargs: Any):
+        _rl_min = float(kwargs.pop("rate_limit_min_interval", 1.25))
+        _rl_jit = float(kwargs.pop("rate_limit_jitter", 0.25))
+        _rl_methods: Set[str] = kwargs.pop("rate_limit_methods", None) or RL_DEFAULT_METHODS
+        _rl_scope = kwargs.pop("rate_limit_scope_key", None) or email
+        _max_retry_after = float(kwargs.pop("max_retry_after", 60.0))
+        _max_retries_on_429 = int(kwargs.pop("max_retries_on_429", 4))
+
+        _http_timeout_raw = kwargs.pop("http_timeout", 15.0)
+        _http_timeout = _coerce_timeout(_http_timeout_raw)
+        if _http_timeout is None:
+            _http_timeout = 15.0
+
+        orig_init(self, email, password, *args, **kwargs)
+
+        global _SCOPED_LIMITERS
+        try:
+            _SCOPED_LIMITERS  # type: ignore[name-defined]
+        except NameError:
+            _SCOPED_LIMITERS = {}  # type: ignore[assignment]
+        limiter = _SCOPED_LIMITERS.setdefault(_rl_scope, RateLimiter(_rl_min, _rl_jit))
+
+        try:
+            self._session.request = wrap_session_request(  # type: ignore[attr-defined]
+                self._session.request,  # type: ignore[attr-defined]
+                limiter,
+                _rl_methods,
+                _max_retry_after,
+                _max_retries_on_429,
+                default_timeout=_http_timeout,
+            )
+        except Exception:
+            pass
+
+    Frigidaire.__init__ = __init__  # type: ignore[method-assign]
+    Frigidaire._rl_patched = True  # type: ignore[attr-defined]
+    _ENABLED = True

run_smoke_tests.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# run_smoke_tests.sh — sets up a venv, installs the library in editable mode, and runs smoke tests.
+here="$(cd "$(dirname "$0")" && pwd)"
+repo_root="$here"  # assume script is placed at repo root
+
+# venv
+if [[ ! -d "$repo_root/.venv" ]]; then
+  python3 -m venv "$repo_root/.venv"
+fi
+# shellcheck disable=SC1091
+source "$repo_root/.venv/bin/activate"
+pip install -e "$repo_root"
+
+# Prompt for creds if not provided via env (password hidden)
+if [[ -z "${FRIGIDAIRE_EMAIL:-}" ]]; then
+  read -r -p "Frigidaire email: " FRIGIDAIRE_EMAIL
+  export FRIGIDAIRE_EMAIL
+fi
+if [[ -z "${FRIGIDAIRE_PASSWORD:-}" ]]; then
+  read -r -s -p "Frigidaire password: " FRIGIDAIRE_PASSWORD
+  echo
+  export FRIGIDAIRE_PASSWORD
+fi
+
+# Defaults chosen to make spacing visible
+MIN_INTERVAL="${MIN_INTERVAL:-1.5}"
+JITTER="${JITTER:-0.0}"
+HTTP_TIMEOUT="${HTTP_TIMEOUT:-15.0}"
+
+python "$repo_root/smoke_test_frigidaire.py" \
+  --min-interval "$MIN_INTERVAL" \
+  --jitter "$JITTER" \
+  --http-timeout "$HTTP_TIMEOUT"