forebot 0.2.0__py3-none-any.whl

forebot/__init__.py

@@ -0,0 +1,33 @@
+"""Forebot SDK: report status to Forebot and cooperate with its controls.
+
+Typical use::
+
+    import forebot
+
+    forebot.setup_logging()
+    bot = forebot.connect()
+    api_key = bot.require("api_key")
+
+    for _ in bot.loop(interval=60, idle_detail="waiting for work"):
+        for job in fetch_jobs():
+            with bot.working(f"processing {job.id}"):
+                handle(job)
+            if not bot.checkpoint():  # honours pause and shutdown
+                break
+"""
+
+from .bot import IDLE, PAUSED, WORKING, Bot, ForebotError, connect
+from .logs import JSONFormatter, setup_logging
+
+__all__ = [
+    "Bot",
+    "ForebotError",
+    "IDLE",
+    "JSONFormatter",
+    "PAUSED",
+    "WORKING",
+    "connect",
+    "setup_logging",
+]
+
+__version__ = "0.2.0"

forebot/bot.py

@@ -0,0 +1,341 @@
+"""The Forebot bot client."""
+
+from __future__ import annotations
+
+import http.client
+import json
+import logging
+import os
+import signal
+import socket
+import threading
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Dict, Iterator, Optional
+
+IDLE = "idle"
+WORKING = "working"
+PAUSED = "paused"
+
+_log = logging.getLogger("forebot")
+
+
+class _UnixHTTPConnection(http.client.HTTPConnection):
+    """An HTTP connection over a Unix socket.
+
+    A runner gives each bot in a container its own socket, with a
+    ``unix://`` agent URL.
+    """
+
+    def __init__(self, path: str, timeout: float) -> None:
+        super().__init__("localhost", timeout=timeout)
+        self._path = path
+
+    def connect(self) -> None:
+        sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        sock.settimeout(self.timeout)
+        try:
+            sock.connect(self._path)
+        except OSError:
+            sock.close()
+            raise
+        self.sock = sock
+
+
+class Bot:
+    """Connection between a bot process and its Forebot runner.
+
+    When the process is not started by a Forebot runner (for example during
+    local development), the bot runs in *standalone* mode: configuration is
+    read from ``FOREBOT_CONFIG`` (a JSON string) or ``FOREBOT_CONFIG_FILE``
+    (a path to a JSON file), and status reports are no-ops.
+    """
+
+    def __init__(
+        self,
+        agent_url: Optional[str] = None,
+        token: Optional[str] = None,
+        heartbeat_interval: float = 5.0,
+        handle_signals: bool = True,
+    ) -> None:
+        self.agent_url = (agent_url or os.environ.get("FOREBOT_AGENT_URL", "")).rstrip("/")
+        self._token = token or os.environ.get("FOREBOT_AGENT_TOKEN", "")
+        self.managed = bool(self.agent_url and self._token)
+        self.id: Optional[int] = _int_or_none(os.environ.get("FOREBOT_BOT_ID"))
+        self.name: str = os.environ.get("FOREBOT_BOT_NAME", "")
+        self.revision: Optional[int] = None
+        self.heartbeat_interval = heartbeat_interval
+
+        self._lock = threading.Lock()
+        self._activity = IDLE
+        self._detail = ""
+        self._pause_requested = False
+        self._stop = threading.Event()
+        self._wake = threading.Event()  # wakes the heartbeat thread early
+        self._unpaused = threading.Event()
+        self._unpaused.set()
+        self._cooperative = False
+        self._closed = False
+
+        self.config: Dict[str, Any] = self._load_config()
+
+        if handle_signals and threading.current_thread() is threading.main_thread():
+            self._install_signal_handlers()
+
+        self._thread: Optional[threading.Thread] = None
+        if self.managed:
+            self._send_heartbeat()  # report immediately
+            self._thread = threading.Thread(target=self._heartbeat_loop, name="forebot-heartbeat", daemon=True)
+            self._thread.start()
+
+    # ------------------------------------------------------------------ config
+
+    def _load_config(self) -> Dict[str, Any]:
+        if self.managed:
+            try:
+                data = self._request("GET", "/v1/config")
+            except Exception as exc:  # noqa: BLE001
+                raise ForebotError(f"could not load configuration from the runner: {exc}") from exc
+            self.id = data.get("bot_id", self.id)
+            self.name = data.get("bot_name", self.name)
+            self.revision = data.get("revision")
+            return dict(data.get("config") or {})
+        raw = os.environ.get("FOREBOT_CONFIG")
+        if raw:
+            return dict(json.loads(raw))
+        path = os.environ.get("FOREBOT_CONFIG_FILE")
+        if path:
+            with open(path, encoding="utf-8") as fh:
+                return dict(json.load(fh))
+        return {}
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Return a configuration value, or ``default`` if it is not set."""
+        return self.config.get(key, default)
+
+    def require(self, key: str) -> Any:
+        """Return a configuration value, raising ``KeyError`` with a clear message if it is missing."""
+        if key not in self.config:
+            raise KeyError(f"required configuration key {key!r} is not set in Forebot")
+        return self.config[key]
+
+    # ---------------------------------------------------------------- activity
+
+    def set_activity(self, state: str, detail: str = "") -> None:
+        """Report the bot's activity: ``idle``, ``working`` or ``paused``."""
+        if state not in (IDLE, WORKING, PAUSED):
+            raise ValueError(f"unknown activity {state!r}")
+        with self._lock:
+            changed = (state, detail) != (self._activity, self._detail)
+            self._activity, self._detail = state, detail
+        if changed:
+            self._wake.set()
+
+    def idle(self, detail: str = "") -> None:
+        """Report that the bot is waiting for work."""
+        self.set_activity(IDLE, detail)
+
+    def working(self, detail: str = "") -> "_Activity":
+        """Report that the bot is working.
+
+        Use it as a plain call, or as a context manager that reports idle
+        again when the block ends::
+
+            with bot.working("Triaging SENTRY-1234"):
+                ...
+        """
+        with self._lock:
+            prev = (self._activity, self._detail)
+        self.set_activity(WORKING, detail)
+        return _Activity(self, prev)
+
+    @property
+    def activity(self) -> str:
+        with self._lock:
+            return self._activity
+
+    # ------------------------------------------------------- pause / shutdown
+
+    @property
+    def pause_requested(self) -> bool:
+        """True when an operator asked the bot to pause."""
+        with self._lock:
+            return self._pause_requested
+
+    def should_stop(self) -> bool:
+        """True when the bot was asked to shut down (SIGTERM or SIGINT)."""
+        self._cooperative = True
+        return self._stop.is_set()
+
+    @property
+    def stopping(self) -> bool:
+        return self.should_stop()
+
+    def request_stop(self) -> None:
+        """Ask the bot's own loops to finish (same as receiving SIGTERM)."""
+        self._stop.set()
+        self._unpaused.set()
+        self._wake.set()
+
+    def checkpoint(self) -> bool:
+        """Call between units of work.
+
+        Blocks while the bot is paused, reporting ``paused`` to Forebot.
+        Returns ``False`` when the bot should stop, ``True`` otherwise.
+        """
+        self._cooperative = True
+        if self._stop.is_set():
+            return False
+        if not self.pause_requested:
+            return True
+        with self._lock:
+            before = (self._activity, self._detail)
+        self.set_activity(PAUSED, "paused by operator")
+        _log.info("paused by operator")
+        while self.pause_requested and not self._stop.is_set():
+            self._unpaused.wait(1.0)
+        if not self._stop.is_set():
+            _log.info("resumed")
+            self.set_activity(*before)
+        return not self._stop.is_set()
+
+    def sleep(self, seconds: float) -> bool:
+        """Sleep, waking early if the bot is asked to stop.
+
+        Returns ``False`` when the bot should stop.
+        """
+        self._cooperative = True
+        return not self._stop.wait(max(0.0, seconds))
+
+    def loop(self, interval: float, idle_detail: str = "") -> Iterator[int]:
+        """Run a polling loop until the bot is asked to stop.
+
+        Each iteration first honours pause requests. Between iterations the
+        bot reports idle and sleeps ``interval`` seconds::
+
+            for _ in bot.loop(interval=60, idle_detail="waiting for new alerts"):
+                check_for_alerts()
+        """
+        n = 0
+        while self.checkpoint():
+            yield n
+            n += 1
+            self.idle(idle_detail)
+            if not self.sleep(interval):
+                break
+
+    # --------------------------------------------------------------- internals
+
+    def _install_signal_handlers(self) -> None:
+        def handler(signum: int, frame: Any) -> None:
+            if self._stop.is_set() or not self._cooperative:
+                # Second signal, or the bot never checks should_stop():
+                # exit now so the bot does not wait for SIGKILL.
+                raise SystemExit(128 + signum)
+            _log.info("shutdown requested (signal %d)", signum)
+            self.request_stop()
+
+        for sig in (signal.SIGTERM, signal.SIGINT):
+            try:
+                signal.signal(sig, handler)
+            except (ValueError, OSError):  # not supported on this platform/thread
+                pass
+
+    def _request(self, method: str, path: str, body: Optional[dict] = None) -> dict:
+        data = json.dumps(body).encode() if body is not None else None
+        if self.agent_url.startswith("unix://"):
+            return self._unix_request(method, path, data)
+        req = urllib.request.Request(self.agent_url + path, data=data, method=method)
+        req.add_header("Authorization", "Bearer " + self._token)
+        if data is not None:
+            req.add_header("Content-Type", "application/json")
+        with urllib.request.urlopen(req, timeout=5) as resp:  # noqa: S310 - local runner URL
+            return json.loads(resp.read().decode() or "{}")
+
+    def _unix_request(self, method: str, path: str, data: Optional[bytes]) -> dict:
+        headers = {"Authorization": "Bearer " + self._token}
+        if data is not None:
+            headers["Content-Type"] = "application/json"
+        conn = _UnixHTTPConnection(self.agent_url[len("unix://") :], timeout=5)
+        try:
+            conn.request(method, path, body=data, headers=headers)
+            resp = conn.getresponse()
+            raw = resp.read()
+            if resp.status >= 400:
+                raise urllib.error.HTTPError(self.agent_url + path, resp.status, resp.reason, resp.headers, None)
+            return json.loads(raw.decode() or "{}")
+        finally:
+            conn.close()
+
+    def _send_heartbeat(self) -> None:
+        with self._lock:
+            body = {"activity": self._activity, "detail": self._detail}
+        try:
+            reply = self._request("POST", "/v1/heartbeat", body)
+        except (urllib.error.URLError, OSError, ValueError) as exc:
+            _log.debug("heartbeat failed: %s", exc)
+            return
+        paused = bool(reply.get("paused"))
+        with self._lock:
+            changed = paused != self._pause_requested
+            self._pause_requested = paused
+        if changed:
+            if paused:
+                self._unpaused.clear()
+                _log.info("pause requested")
+            else:
+                self._unpaused.set()
+
+    def _heartbeat_loop(self) -> None:
+        while not self._closed:
+            self._wake.wait(self.heartbeat_interval)
+            self._wake.clear()
+            if self._closed:
+                break
+            self._send_heartbeat()
+
+    def close(self) -> None:
+        """Stop the heartbeat thread."""
+        self._closed = True
+        self._wake.set()
+
+
+class _Activity:
+    def __init__(self, bot: Bot, prev: tuple) -> None:
+        self._bot = bot
+        self._prev = prev
+
+    def __enter__(self) -> "_Activity":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        state, detail = self._prev
+        if state == WORKING:  # nested: go back to the outer task
+            self._bot.set_activity(WORKING, detail)
+        else:
+            self._bot.idle()
+
+
+class ForebotError(RuntimeError):
+    """Raised when the bot cannot talk to its runner."""
+
+
+def _int_or_none(v: Optional[str]) -> Optional[int]:
+    try:
+        return int(v) if v else None
+    except ValueError:
+        return None
+
+
+_default: Optional[Bot] = None
+_default_lock = threading.Lock()
+
+
+def connect(**kwargs: Any) -> Bot:
+    """Return the process-wide :class:`Bot`, creating it on first call."""
+    global _default
+    with _default_lock:
+        if _default is None:
+            _default = Bot(**kwargs)
+        return _default

forebot/logs.py

@@ -0,0 +1,57 @@
+"""Structured logging that the Forebot runner understands."""
+
+from __future__ import annotations
+
+import datetime as _dt
+import json
+import logging
+import os
+import sys
+from typing import Optional, TextIO, Union
+
+
+class JSONFormatter(logging.Formatter):
+    """Formats records as one JSON object per line.
+
+    The runner reads ``level``, ``logger``, ``msg``, ``ts`` and ``exc_info``
+    so the web interface can filter by level and show tracebacks as one entry.
+    """
+
+    def format(self, record: logging.LogRecord) -> str:
+        out = {
+            "ts": _dt.datetime.fromtimestamp(record.created, tz=_dt.timezone.utc).isoformat(),
+            "level": record.levelname.lower(),
+            "logger": record.name,
+            "msg": record.getMessage(),
+        }
+        if record.exc_info:
+            out["exc_info"] = self.formatException(record.exc_info)
+        elif record.stack_info:
+            out["exc_info"] = self.formatStack(record.stack_info)
+        return json.dumps(out, ensure_ascii=False, default=str)
+
+
+def setup_logging(
+    level: Union[int, str] = logging.INFO,
+    stream: Optional[TextIO] = None,
+    json_format: Optional[bool] = None,
+) -> logging.Logger:
+    """Configure the root logger for a bot.
+
+    Under a Forebot runner, logs are written as JSON lines to stdout. In
+    standalone mode they use a readable text format. Pass ``json_format`` to
+    force either one.
+    """
+    if json_format is None:
+        json_format = bool(os.environ.get("FOREBOT_AGENT_URL"))
+    handler = logging.StreamHandler(stream or sys.stdout)
+    if json_format:
+        handler.setFormatter(JSONFormatter())
+    else:
+        handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)-8s %(name)s: %(message)s"))
+    root = logging.getLogger()
+    for h in list(root.handlers):
+        root.removeHandler(h)
+    root.addHandler(handler)
+    root.setLevel(level)
+    return root

forebot-0.2.0.dist-info/METADATA

@@ -0,0 +1,54 @@
+Metadata-Version: 2.5
+Name: forebot
+Version: 0.2.0
+Summary: Python SDK for bots managed by Forebot
+Project-URL: Homepage, https://github.com/gridcell/forebot
+Project-URL: Documentation, https://github.com/gridcell/forebot/blob/main/docs/sdk.md
+Project-URL: Source, https://github.com/gridcell/forebot-sdk
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# forebot (Python SDK)
+
+The Forebot SDK lets a Python bot report its activity to Forebot, read its configuration, and cooperate with pause and stop requests. It has no dependencies.
+
+```bash
+pip install forebot
+```
+
+```python
+import forebot
+
+forebot.setup_logging()
+bot = forebot.connect()
+
+for _ in bot.loop(interval=60, idle_detail="waiting for work"):
+    with bot.working("checking the queue"):
+        ...
+```
+
+See the [SDK guide](https://github.com/gridcell/forebot/blob/main/docs/sdk.md) in the Forebot repository for the full guide.
+
+## Development
+
+```bash
+uv run --with pytest --with-editable . pytest -q
+```
+
+## Release
+
+1. Set `version` in `pyproject.toml` and commit.
+2. Tag the commit with the same version and push the tag:
+
+   ```bash
+   git tag v0.2.0
+   git push origin v0.2.0
+   ```
+
+The `publish` workflow runs the tests, checks that the tag matches the version, builds the package, and uploads it to PyPI.

forebot-0.2.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+forebot/__init__.py,sha256=WHuHClwo9wymGl-qlfowGV0dSFERkq3m7UX_1A9NCpA,762
+forebot/bot.py,sha256=-zI-HpmfTmabwTyVq7lBQD9dJJ5z7hcGLDZuH5Fk6kU,11989
+forebot/logs.py,sha256=hXEXsvcE7_UCpeIwDD1wr1zZUCF2EbOjZ5x8YD4ZZDY,1909
+forebot/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+forebot-0.2.0.dist-info/METADATA,sha256=ZwwjFDggwVubYSI9glE6r1sTUPIy4UHMwEHZW8Ib5oc,1538
+forebot-0.2.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+forebot-0.2.0.dist-info/RECORD,,

forebot-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any