flares-client 0.1.0__py3-none-any.whl

flares_client/__init__.py

@@ -0,0 +1,47 @@
+"""Flares client library. HTTP success and notification delivery are separate outcomes."""
+
+from .client import AsyncClient, Client
+from .errors import DecodeError, FlaresError, HTTPError, TransportError, ValidationError
+from .models import (
+    Alert,
+    AlertResult,
+    Delivery,
+    DestinationOutcome,
+    Health,
+    Heartbeat,
+    HeartbeatInput,
+    Issue,
+    IssueList,
+    IssueStatus,
+    MutationResult,
+    Notification,
+    NotificationStatus,
+    OpenIssue,
+    Severity,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "Client",
+    "AsyncClient",
+    "FlaresError",
+    "ValidationError",
+    "TransportError",
+    "HTTPError",
+    "DecodeError",
+    "Alert",
+    "AlertResult",
+    "Delivery",
+    "DestinationOutcome",
+    "Health",
+    "Heartbeat",
+    "HeartbeatInput",
+    "Issue",
+    "IssueList",
+    "IssueStatus",
+    "MutationResult",
+    "Notification",
+    "NotificationStatus",
+    "OpenIssue",
+    "Severity",
+]

flares_client/_common.py

@@ -0,0 +1,94 @@
+import math
+from typing import Any
+
+import httpx
+from pydantic import BaseModel, TypeAdapter
+from pydantic import ValidationError as ModelError
+
+from .errors import DecodeError, HTTPError, ValidationError
+
+
+def settings(base_url: str, token: str, timeout: float) -> tuple[str, dict[str, str]]:
+    try:
+        url = httpx.URL(base_url)
+    except (httpx.InvalidURL, TypeError):
+        raise ValidationError("Invalid API base URL") from None
+    if (
+        url.scheme not in ("http", "https")
+        or not url.host
+        or url.username
+        or url.password
+        # HTTPX retains empty delimiters even when query/fragment values are empty.
+        or "?" in str(url)
+        or "#" in str(url)
+    ):
+        raise ValidationError(
+            "API base URL must be HTTP(S) without credentials, query, or fragment"
+        )
+    if not isinstance(token, str) or not token or not all(33 <= ord(c) <= 126 for c in token):
+        raise ValidationError("API token must be nonempty printable ASCII without spaces")
+    if (
+        not isinstance(timeout, (float, int))
+        or isinstance(timeout, bool)
+        or not math.isfinite(timeout)
+        or not 0 < timeout <= 86400
+    ):
+        raise ValidationError("Timeout must be greater than zero and at most 86400 seconds")
+    return str(url).rstrip("/"), {"Authorization": f"Bearer {token}"}
+
+
+def body(model: type[BaseModel], **values: Any) -> dict[str, Any]:
+    try:
+        return model.model_validate(values).model_dump(mode="json")
+    except ModelError as error:
+        fields = sorted({str(e["loc"][0]) for e in error.errors() if e["loc"]})
+        raise ValidationError(f"Invalid request fields: {', '.join(fields)}") from None
+
+
+def key_header(key: str | None) -> dict[str, str]:
+    if key is None:
+        return {}
+    if (
+        not isinstance(key, str)
+        or not 1 <= len(key) <= 200
+        or not all(33 <= ord(c) <= 126 for c in key)
+    ):
+        raise ValidationError("Invalid idempotency key")
+    return {"Idempotency-Key": key}
+
+
+def listing(status: str | None, limit: int, offset: int) -> dict[str, Any]:
+    if (
+        status not in (None, "open", "closed")
+        or type(limit) is not int
+        or not 1 <= limit <= 1000
+        or type(offset) is not int
+        or not 0 <= offset <= 4_294_967_295
+    ):
+        raise ValidationError("Invalid status, limit, or offset")
+    params = {"limit": limit, "offset": offset}
+    if status is not None:
+        params["status"] = status
+    return params
+
+
+def delivery_path(id: int) -> str:
+    if type(id) is not int or not 1 <= id <= 9_223_372_036_854_775_807:
+        raise ValidationError("delivery id must be a positive 64-bit integer")
+    return f"/v1/deliveries/{id}"
+
+
+def decode(response: httpx.Response, model: Any) -> Any:
+    if not response.is_success:
+        raise HTTPError(response.status_code)
+    if model is str:
+        return response.text
+    try:
+        value = response.json()
+        if model is None:
+            if not isinstance(value, dict) or value.get("deleted") is not True:
+                raise ValueError
+            return None
+        return TypeAdapter(model).validate_python(value)
+    except (ValueError, TypeError):
+        raise DecodeError() from None

flares_client/client.py

@@ -0,0 +1,269 @@
+"""HTTP clients with identical synchronous and asynchronous operations."""
+
+from typing import Any, Self
+
+import httpx
+
+from ._common import body, decode, delivery_path, key_header, listing, settings
+from .errors import TransportError
+from .models import (
+    Alert,
+    AlertResult,
+    CloseIssue,
+    Delivery,
+    Health,
+    Heartbeat,
+    HeartbeatInput,
+    Issue,
+    IssueList,
+    IssueStatus,
+    MutationResult,
+    OpenIssue,
+    Severity,
+)
+
+
+class Client:
+    def __init__(self, base_url: str, token: str, *, timeout: float = 15.0):
+        self._base_url, headers = settings(base_url, token, timeout)
+        self._client = httpx.Client(headers=headers, timeout=timeout, follow_redirects=False)
+
+    def __enter__(self) -> Self:
+        self._client.__enter__()
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self._client.__exit__(*args)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def _request(self, method: str, path: str, model: Any, **kwargs: Any) -> Any:
+        try:
+            response = self._client.request(method, self._base_url + path, **kwargs)
+        except httpx.HTTPError as error:
+            raise TransportError(timed_out=isinstance(error, httpx.TimeoutException)) from None
+        return decode(response, model)
+
+    def open_issue(
+        self,
+        id: str,
+        *,
+        title: str | None = None,
+        message: str | None = None,
+        severity: Severity | str = Severity.WARNING,
+        remind_every_seconds: int | None = None,
+        notify_on_resolution: bool = False,
+    ) -> MutationResult:
+        data = body(
+            OpenIssue,
+            id=id,
+            title=title,
+            message=message,
+            severity=severity,
+            remind_every_seconds=remind_every_seconds,
+            notify_on_resolution=notify_on_resolution,
+        )
+        return self._request("POST", "/v1/issues/open", MutationResult, json=data)
+
+    def close_issue(self, id: str) -> MutationResult:
+        return self._request(
+            "POST", "/v1/issues/close", MutationResult, json=body(CloseIssue, id=id)
+        )
+
+    def get_issue(self, id: str) -> Issue:
+        return self._request("GET", "/v1/issue", Issue, params=body(CloseIssue, id=id))
+
+    def list_issues(
+        self, *, status: IssueStatus | str | None = None, limit: int = 100, offset: int = 0
+    ) -> IssueList:
+        return self._request("GET", "/v1/issues", IssueList, params=listing(status, limit, offset))
+
+    def alert(
+        self,
+        title: str,
+        message: str,
+        *,
+        severity: Severity | str = Severity.WARNING,
+        group_key: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> AlertResult:
+        return self._request(
+            "POST",
+            "/v1/alerts",
+            AlertResult,
+            json=body(Alert, title=title, message=message, severity=severity, group_key=group_key),
+            headers=key_header(idempotency_key),
+        )
+
+    def get_delivery(self, id: int) -> Delivery:
+        return self._request("GET", delivery_path(id), Delivery)
+
+    def register_heartbeat(
+        self,
+        id: str,
+        *,
+        title: str,
+        interval_seconds: int,
+        grace_seconds: int = 0,
+        severity: Severity | str = Severity.WARNING,
+        notify_on_recovery: bool = False,
+    ) -> Heartbeat:
+        return self._request(
+            "POST",
+            "/v1/heartbeats",
+            Heartbeat,
+            json=body(
+                HeartbeatInput,
+                id=id,
+                title=title,
+                interval_seconds=interval_seconds,
+                grace_seconds=grace_seconds,
+                severity=severity,
+                notify_on_recovery=notify_on_recovery,
+            ),
+        )
+
+    def check_in(self, id: str) -> Heartbeat:
+        return self._request(
+            "POST", "/v1/heartbeats/check-in", Heartbeat, json=body(CloseIssue, id=id)
+        )
+
+    def list_heartbeats(self) -> list[Heartbeat]:
+        return self._request("GET", "/v1/heartbeats", list[Heartbeat])
+
+    def delete_heartbeat(self, id: str) -> None:
+        return self._request("DELETE", "/v1/heartbeat", None, params=body(CloseIssue, id=id))
+
+    def health(self) -> Health:
+        return self._request("GET", "/healthz", Health)
+
+    def readiness(self) -> Health:
+        return self._request("GET", "/readyz", Health)
+
+    def metrics(self) -> str:
+        return self._request("GET", "/metrics", str)
+
+
+class AsyncClient:
+    def __init__(self, base_url: str, token: str, *, timeout: float = 15.0):
+        self._base_url, headers = settings(base_url, token, timeout)
+        self._client = httpx.AsyncClient(headers=headers, timeout=timeout, follow_redirects=False)
+
+    async def __aenter__(self) -> Self:
+        await self._client.__aenter__()
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self._client.__aexit__(*args)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def _request(self, method: str, path: str, model: Any, **kwargs: Any) -> Any:
+        try:
+            response = await self._client.request(method, self._base_url + path, **kwargs)
+        except httpx.HTTPError as error:
+            raise TransportError(timed_out=isinstance(error, httpx.TimeoutException)) from None
+        return decode(response, model)
+
+    async def open_issue(
+        self,
+        id: str,
+        *,
+        title: str | None = None,
+        message: str | None = None,
+        severity: Severity | str = Severity.WARNING,
+        remind_every_seconds: int | None = None,
+        notify_on_resolution: bool = False,
+    ) -> MutationResult:
+        data = body(
+            OpenIssue,
+            id=id,
+            title=title,
+            message=message,
+            severity=severity,
+            remind_every_seconds=remind_every_seconds,
+            notify_on_resolution=notify_on_resolution,
+        )
+        return await self._request("POST", "/v1/issues/open", MutationResult, json=data)
+
+    async def close_issue(self, id: str) -> MutationResult:
+        return await self._request(
+            "POST", "/v1/issues/close", MutationResult, json=body(CloseIssue, id=id)
+        )
+
+    async def get_issue(self, id: str) -> Issue:
+        return await self._request("GET", "/v1/issue", Issue, params=body(CloseIssue, id=id))
+
+    async def list_issues(
+        self, *, status: IssueStatus | str | None = None, limit: int = 100, offset: int = 0
+    ) -> IssueList:
+        return await self._request(
+            "GET", "/v1/issues", IssueList, params=listing(status, limit, offset)
+        )
+
+    async def alert(
+        self,
+        title: str,
+        message: str,
+        *,
+        severity: Severity | str = Severity.WARNING,
+        group_key: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> AlertResult:
+        return await self._request(
+            "POST",
+            "/v1/alerts",
+            AlertResult,
+            json=body(Alert, title=title, message=message, severity=severity, group_key=group_key),
+            headers=key_header(idempotency_key),
+        )
+
+    async def get_delivery(self, id: int) -> Delivery:
+        return await self._request("GET", delivery_path(id), Delivery)
+
+    async def register_heartbeat(
+        self,
+        id: str,
+        *,
+        title: str,
+        interval_seconds: int,
+        grace_seconds: int = 0,
+        severity: Severity | str = Severity.WARNING,
+        notify_on_recovery: bool = False,
+    ) -> Heartbeat:
+        return await self._request(
+            "POST",
+            "/v1/heartbeats",
+            Heartbeat,
+            json=body(
+                HeartbeatInput,
+                id=id,
+                title=title,
+                interval_seconds=interval_seconds,
+                grace_seconds=grace_seconds,
+                severity=severity,
+                notify_on_recovery=notify_on_recovery,
+            ),
+        )
+
+    async def check_in(self, id: str) -> Heartbeat:
+        return await self._request(
+            "POST", "/v1/heartbeats/check-in", Heartbeat, json=body(CloseIssue, id=id)
+        )
+
+    async def list_heartbeats(self) -> list[Heartbeat]:
+        return await self._request("GET", "/v1/heartbeats", list[Heartbeat])
+
+    async def delete_heartbeat(self, id: str) -> None:
+        return await self._request("DELETE", "/v1/heartbeat", None, params=body(CloseIssue, id=id))
+
+    async def health(self) -> Health:
+        return await self._request("GET", "/healthz", Health)
+
+    async def readiness(self) -> Health:
+        return await self._request("GET", "/readyz", Health)
+
+    async def metrics(self) -> str:
+        return await self._request("GET", "/metrics", str)

flares_client/errors.py

@@ -0,0 +1,29 @@
+"""Sanitized, distinguishable client errors."""
+
+
+class FlaresError(Exception):
+    """Base class for Flares client errors."""
+
+
+class ValidationError(FlaresError, ValueError):
+    """Invalid client configuration or request arguments."""
+
+
+class TransportError(FlaresError):
+    def __init__(self, *, timed_out: bool = False):
+        self.timed_out = timed_out
+        super().__init__(
+            "API request failed or timed out; delivery may have occurred. "
+            "Reuse the alert idempotency key or check issue state before retrying"
+        )
+
+
+class HTTPError(FlaresError):
+    def __init__(self, status_code: int):
+        self.status_code = status_code
+        super().__init__(f"API returned HTTP {status_code}")
+
+
+class DecodeError(FlaresError):
+    def __init__(self):
+        super().__init__("API returned an invalid response")

flares_client/models.py

@@ -0,0 +1,140 @@
+"""Typed API models. Response objects accept additive server fields."""
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Annotated
+
+from pydantic import BaseModel, ConfigDict, Field
+
+IssueId = Annotated[str, Field(strict=True, min_length=1, max_length=200)]
+Title = Annotated[str, Field(strict=True, min_length=1, max_length=250)]
+Message = Annotated[str, Field(strict=True, min_length=1, max_length=1024)]
+Interval = Annotated[int, Field(strict=True, ge=1, le=31_536_000)]
+
+
+class Severity(StrEnum):
+    INFO = "info"
+    WARNING = "warning"
+    CRITICAL = "critical"
+
+
+class IssueStatus(StrEnum):
+    OPEN = "open"
+    CLOSED = "closed"
+
+
+class NotificationStatus(StrEnum):
+    PENDING = "pending"
+    SENT = "sent"
+    FAILED = "failed"
+    UNKNOWN = "unknown"
+    NOT_ATTEMPTED = "not_attempted"
+
+
+class Request(BaseModel):
+    model_config = ConfigDict(extra="forbid", hide_input_in_errors=True)
+
+
+class OpenIssue(Request):
+    id: IssueId
+    title: Title | None = None
+    message: Message | None = None
+    severity: Severity = Severity.WARNING
+    remind_every_seconds: Interval | None = None
+    notify_on_resolution: bool = False
+
+
+class CloseIssue(Request):
+    id: IssueId
+
+
+class Alert(Request):
+    title: Title
+    message: Message
+    severity: Severity = Severity.WARNING
+    group_key: IssueId | None = None
+
+
+class HeartbeatInput(Request):
+    id: IssueId
+    title: Title
+    interval_seconds: Interval
+    grace_seconds: Annotated[int, Field(strict=True, ge=0, le=31_536_000)] = 0
+    severity: Severity = Severity.WARNING
+    notify_on_recovery: bool = False
+
+
+class Notification(BaseModel):
+    status: NotificationStatus
+    error: str | None
+
+
+class Issue(BaseModel):
+    id: str
+    status: IssueStatus
+    title: str
+    message: str
+    severity: Severity
+    remind_every_seconds: int | None
+    notify_on_resolution: bool
+    delivery_id: int | None
+    created_at: datetime
+    updated_at: datetime
+    opened_at: datetime
+    closed_at: datetime | None
+    opening_count: int
+    notification: Notification
+
+
+class MutationResult(BaseModel):
+    delivery_id: int | None
+    issue: Issue
+    changed: bool
+    notification: Notification
+
+
+class AlertResult(BaseModel):
+    delivery_id: int
+    notification: Notification
+
+
+class IssueList(BaseModel):
+    items: list[Issue]
+    total: int
+    limit: int
+    offset: int
+
+
+class Heartbeat(BaseModel):
+    id: str
+    title: str
+    interval_seconds: int
+    grace_seconds: int
+    severity: Severity
+    notify_on_recovery: bool
+    last_seen: int
+    due_at: int
+    overdue: bool
+
+
+class DestinationOutcome(BaseModel):
+    destination: str
+    attempts: int
+    notification: Notification
+
+
+class Delivery(BaseModel):
+    id: int
+    title: str
+    message: str
+    severity: Severity
+    kind: str
+    count: int
+    created_at: int
+    next_attempt_at: int
+    notification: Notification
+    destinations: list[DestinationOutcome]
+
+
+class Health(BaseModel):
+    status: str

flares_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,42 @@
+Metadata-Version: 2.5
+Name: flares-client
+Version: 0.1.0
+Summary: Synchronous and asynchronous HTTP clients for Flares
+Project-URL: Repository, https://github.com/torpedro/flares
+Project-URL: Issues, https://github.com/torpedro/flares/issues
+Project-URL: Documentation, https://github.com/torpedro/flares/blob/main/clients/python/README.md
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: pydantic<3,>=2.10
+Description-Content-Type: text/markdown
+
+# Flares Python client
+
+Requires Python 3.11+. Install the built wheel with `pip install flares_client-*.whl`, or install from this directory with `uv pip install .`.
+
+```python
+from flares_client import Client
+
+with Client("http://localhost:8000", "your-api-token") as client:
+    result = client.open_issue("backup", title="Backup failed", severity="critical")
+    print(result.issue.status, result.notification.status)
+    client.close_issue("backup")
+```
+
+```python
+from flares_client import AsyncClient
+
+
+async def notify():
+    async with AsyncClient("http://localhost:8000", "your-api-token") as client:
+        return await client.alert("Backup", "Finished", idempotency_key="backup-run-123")
+```
+
+Both clients have the same operations: `open_issue`, `close_issue`, `get_issue`, `list_issues`, `alert`, `get_delivery`, `register_heartbeat`, `check_in`, `list_heartbeats`, `delete_heartbeat`, `health`, `readiness`, and `metrics`. Responses are typed Pydantic models, except `metrics` (text) and `delete_heartbeat` (`None`). Models and enums are exported from `flares_client`. Request options match the HTTP API; list options are `status`, `limit=100`, and `offset=0`.
+
+Use `timeout=15.0` to customize HTTPX's network-operation timeouts. Keep a client open to reuse connections; context managers close it, or call `close()` / `await aclose()` explicitly. Library configuration is passed directly; the server and CLI retain their YAML configuration.
+
+Catch `ValidationError`, `TransportError` (with `timed_out`), `HTTPError` (with `status_code`), or `DecodeError`; all inherit `FlaresError`. Error messages do not include secrets or provider response bodies. A successful HTTP response with notification status `failed` is a normal result, not an exception. `pending` means accepted, not delivered. Requests never retry or follow redirects automatically. Reuse an explicit alert idempotency key after an uncertain outcome.
+
+Development (from this directory): `uv sync --locked`, `uv run pytest tests`, `uv build`. Run the repository contract suite after building the server and Rust contract driver; see the root README.

flares_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+flares_client/__init__.py,sha256=2Zlc4VISg-yTCrRvMjz2bG4UDUv_jld5M2ghYMxuips,939
+flares_client/_common.py,sha256=dHWx2-dab6LTRA68hUpc1tnSzNOl-HiPVTG0dAJbICI,3252
+flares_client/client.py,sha256=wErC4stKHp3oWMj_lvuCBdNrkw329eULXOsuuPXWXE4,8800
+flares_client/errors.py,sha256=niF00bkP_bQDuffQFzjqXs5jCK6bTC8ydbJdD2DyMC8,850
+flares_client/models.py,sha256=Ggj7X-bzIYdq8kfyjtUW7BEysVrcfsQqEp6H9GeI0SU,2985
+flares_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flares_client-0.1.0.dist-info/METADATA,sha256=I6781Bt_6-sYKVPjxSSXmQf0XncynmQeSpRf65hYT8g,2619
+flares_client-0.1.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+flares_client-0.1.0.dist-info/RECORD,,

flares_client-0.1.0.dist-info/WHEEL

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