event-bridge-client 1.0.0__tar.gz

event_bridge_client-1.0.0/.gitignore

@@ -0,0 +1,16 @@
+node_modules/
+dist/
+build/
+.next/
+.turbo/
+*.log
+.DS_Store
+.env
+.env.local
+.env.*.local
+.vercel/
+coverage/
+.nyc_output/
+*.tsbuildinfo
+.pnpm-store/
+prisma/migrations/dev.db*

event_bridge_client-1.0.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: event-bridge-client
+Version: 1.0.0
+Summary: Lightweight client for registering apps, batching lifecycle events, and handling HMAC-signed remote commands.
+License: UNLICENSED
+Keywords: commands,events,hmac,webhooks
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.4
+Provides-Extra: dev
+Requires-Dist: anyio>=4; extra == 'dev'
+Requires-Dist: fastapi>=0.110; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# event-bridge-client (Python)
+
+A lightweight client for connecting a Python application to a control backend:
+register the app, batch and push lifecycle events, and handle HMAC-signed remote
+commands. Wire-compatible with the Node `event-bridge-client` — same signing
+scheme, same endpoints, same payloads.
+
+## Install
+
+```bash
+pip install event-bridge-client          # core (send events, verify commands)
+pip install "event-bridge-client[fastapi]"  # + FastAPI inbound adapter
+```
+
+Requires Python 3.9+.
+
+## Quickstart (FastAPI)
+
+```python
+from fastapi import FastAPI, Request
+from event_bridge_client import create_client
+
+client = create_client(
+    base_url="https://bridge.example.com",
+    api_key="...",
+    callback_url="https://api.example.com/bridge/commands",
+    callback_secret="...",
+    capabilities=["user.ban", "user.unban"],
+    env="PROD",
+)
+
+@client.on_command("user.ban")
+async def _(data, ctx):
+    await ban_account(data["externalUserId"], data["reason"])
+    return {"ok": True}
+
+app = FastAPI()
+
+@app.post("/bridge/commands")
+async def commands(request: Request):
+    return await client.middleware.fastapi(request)
+
+@app.on_event("startup")
+async def _startup():
+    await client.register()
+
+@app.on_event("shutdown")
+async def _shutdown():
+    await client.aclose()
+
+# Anywhere in your app:
+client.events.emit("user.created", {"externalUserId": "usr_123", "email": "a@b.c"})
+```
+
+Command handlers may be sync or async. Each receives `(data, ctx)` where `data`
+is the raw command payload (a dict) and `ctx` carries `command_id`, `issued_at`,
+and `issued_by`. Return `{"ok": True, "result": ...}` or `{"ok": False, "error": "..."}`.
+
+## Managed resources
+
+Declare an entity the backend can list / search / view / action — entirely from
+the descriptor, with no backend-side code change. Records are never shipped to
+the backend; it proxies `list` / `get` / `action` queries back over the same
+signed channel.
+
+```python
+client.define_resource(
+    {
+        "key": "widgetUser",
+        "label": "Widget User",
+        "labelPlural": "Widget Users",
+        "titleField": "email",
+        "fields": [
+            {"key": "id", "label": "ID", "type": "string", "listVisible": False},
+            {"key": "email", "label": "Email", "type": "email", "filterable": True},
+            {"key": "plan", "label": "Plan", "type": "enum", "enumValues": ["free", "pro"]},
+        ],
+        "actions": [
+            {
+                "capability": "widgetUser.ban",
+                "label": "Ban",
+                "confirm": True,
+                "destructive": True,
+                "fields": [{"name": "reason", "label": "Reason", "kind": "textarea", "required": True}],
+            }
+        ],
+    },
+    # `query` is a ResourceListQuery: query.page, query.page_size, query.q, ...
+    list=lambda query: {"records": db.search(query.q, query.page, query.page_size), "total": db.count()},
+    get=lambda record_id: db.find(record_id),  # optional
+    action=lambda inp: ban(inp["recordId"], inp["params"]["reason"]),  # optional
+)
+```
+
+Descriptor keys accept either `snake_case` or `camelCase`; they're sent to the
+backend as `camelCase`. Field `type` is one of `string`, `number`, `boolean`,
+`date`, `datetime`, `enum`, `currency`, `badge`, `email`, `url`, `json`.
+
+## Options
+
+`create_client(...)` keyword arguments:
+
+| Option              | Default   | Notes                                                  |
+|---------------------|-----------|--------------------------------------------------------|
+| `base_url`          | required  | Control backend base URL                               |
+| `api_key`           | required  | API key minted by the backend admin                    |
+| `callback_url`      | required  | HTTPS URL the backend POSTs commands to                |
+| `callback_secret`   | required  | HMAC shared secret minted alongside the API key        |
+| `capabilities`      | `()`      | Strings matching command types, e.g. `user.ban`        |
+| `env`               | `"PROD"`  | `PROD` / `STAGING` / `DEV`                              |
+| `enabled`           | `True`    | If `False`, all methods are no-ops (staged rollout)    |
+| `batch_interval_ms` | `1500`    | Event batcher flush interval                           |
+| `batch_max_size`    | `100`     | Force-flush when this many events are queued           |
+| `max_buffer_size`   | `10000`   | Hard cap on buffered events; oldest dropped past it    |
+| `max_retries`       | `6`       | Exponential-backoff retries for event batch POSTs      |
+| `nonce_store`       | in-memory | Replay store; supply a shared one for multi-instance   |
+
+## Replay protection across instances
+
+The default replay cache is **in-process** — it only protects a single instance.
+If you run more than one instance behind a load balancer, supply a shared
+`nonce_store` (e.g. Redis) so a captured command can't be replayed against
+another instance inside the 300-second signature window:
+
+```python
+class RedisNonceStore:
+    def __init__(self, redis): self.r = redis
+    async def has(self, nonce: str) -> bool:
+        return await self.r.exists(f"bridge:nonce:{nonce}") > 0
+    async def add(self, nonce: str, ttl_ms: int) -> None:
+        await self.r.set(f"bridge:nonce:{nonce}", "1", px=ttl_ms, nx=True)
+
+client = create_client(..., nonce_store=RedisNonceStore(redis))
+```
+
+## Send-only usage (no FastAPI)
+
+If the app only emits events and never receives commands, you don't need
+FastAPI — `pip install event-bridge-client` and use `register()` /
+`events.emit()` / `aclose()`. The middleware is only needed to receive commands.

event_bridge_client-1.0.0/README.md

@@ -0,0 +1,140 @@
+# event-bridge-client (Python)
+
+A lightweight client for connecting a Python application to a control backend:
+register the app, batch and push lifecycle events, and handle HMAC-signed remote
+commands. Wire-compatible with the Node `event-bridge-client` — same signing
+scheme, same endpoints, same payloads.
+
+## Install
+
+```bash
+pip install event-bridge-client          # core (send events, verify commands)
+pip install "event-bridge-client[fastapi]"  # + FastAPI inbound adapter
+```
+
+Requires Python 3.9+.
+
+## Quickstart (FastAPI)
+
+```python
+from fastapi import FastAPI, Request
+from event_bridge_client import create_client
+
+client = create_client(
+    base_url="https://bridge.example.com",
+    api_key="...",
+    callback_url="https://api.example.com/bridge/commands",
+    callback_secret="...",
+    capabilities=["user.ban", "user.unban"],
+    env="PROD",
+)
+
+@client.on_command("user.ban")
+async def _(data, ctx):
+    await ban_account(data["externalUserId"], data["reason"])
+    return {"ok": True}
+
+app = FastAPI()
+
+@app.post("/bridge/commands")
+async def commands(request: Request):
+    return await client.middleware.fastapi(request)
+
+@app.on_event("startup")
+async def _startup():
+    await client.register()
+
+@app.on_event("shutdown")
+async def _shutdown():
+    await client.aclose()
+
+# Anywhere in your app:
+client.events.emit("user.created", {"externalUserId": "usr_123", "email": "a@b.c"})
+```
+
+Command handlers may be sync or async. Each receives `(data, ctx)` where `data`
+is the raw command payload (a dict) and `ctx` carries `command_id`, `issued_at`,
+and `issued_by`. Return `{"ok": True, "result": ...}` or `{"ok": False, "error": "..."}`.
+
+## Managed resources
+
+Declare an entity the backend can list / search / view / action — entirely from
+the descriptor, with no backend-side code change. Records are never shipped to
+the backend; it proxies `list` / `get` / `action` queries back over the same
+signed channel.
+
+```python
+client.define_resource(
+    {
+        "key": "widgetUser",
+        "label": "Widget User",
+        "labelPlural": "Widget Users",
+        "titleField": "email",
+        "fields": [
+            {"key": "id", "label": "ID", "type": "string", "listVisible": False},
+            {"key": "email", "label": "Email", "type": "email", "filterable": True},
+            {"key": "plan", "label": "Plan", "type": "enum", "enumValues": ["free", "pro"]},
+        ],
+        "actions": [
+            {
+                "capability": "widgetUser.ban",
+                "label": "Ban",
+                "confirm": True,
+                "destructive": True,
+                "fields": [{"name": "reason", "label": "Reason", "kind": "textarea", "required": True}],
+            }
+        ],
+    },
+    # `query` is a ResourceListQuery: query.page, query.page_size, query.q, ...
+    list=lambda query: {"records": db.search(query.q, query.page, query.page_size), "total": db.count()},
+    get=lambda record_id: db.find(record_id),  # optional
+    action=lambda inp: ban(inp["recordId"], inp["params"]["reason"]),  # optional
+)
+```
+
+Descriptor keys accept either `snake_case` or `camelCase`; they're sent to the
+backend as `camelCase`. Field `type` is one of `string`, `number`, `boolean`,
+`date`, `datetime`, `enum`, `currency`, `badge`, `email`, `url`, `json`.
+
+## Options
+
+`create_client(...)` keyword arguments:
+
+| Option              | Default   | Notes                                                  |
+|---------------------|-----------|--------------------------------------------------------|
+| `base_url`          | required  | Control backend base URL                               |
+| `api_key`           | required  | API key minted by the backend admin                    |
+| `callback_url`      | required  | HTTPS URL the backend POSTs commands to                |
+| `callback_secret`   | required  | HMAC shared secret minted alongside the API key        |
+| `capabilities`      | `()`      | Strings matching command types, e.g. `user.ban`        |
+| `env`               | `"PROD"`  | `PROD` / `STAGING` / `DEV`                              |
+| `enabled`           | `True`    | If `False`, all methods are no-ops (staged rollout)    |
+| `batch_interval_ms` | `1500`    | Event batcher flush interval                           |
+| `batch_max_size`    | `100`     | Force-flush when this many events are queued           |
+| `max_buffer_size`   | `10000`   | Hard cap on buffered events; oldest dropped past it    |
+| `max_retries`       | `6`       | Exponential-backoff retries for event batch POSTs      |
+| `nonce_store`       | in-memory | Replay store; supply a shared one for multi-instance   |
+
+## Replay protection across instances
+
+The default replay cache is **in-process** — it only protects a single instance.
+If you run more than one instance behind a load balancer, supply a shared
+`nonce_store` (e.g. Redis) so a captured command can't be replayed against
+another instance inside the 300-second signature window:
+
+```python
+class RedisNonceStore:
+    def __init__(self, redis): self.r = redis
+    async def has(self, nonce: str) -> bool:
+        return await self.r.exists(f"bridge:nonce:{nonce}") > 0
+    async def add(self, nonce: str, ttl_ms: int) -> None:
+        await self.r.set(f"bridge:nonce:{nonce}", "1", px=ttl_ms, nx=True)
+
+client = create_client(..., nonce_store=RedisNonceStore(redis))
+```
+
+## Send-only usage (no FastAPI)
+
+If the app only emits events and never receives commands, you don't need
+FastAPI — `pip install event-bridge-client` and use `register()` /
+`events.emit()` / `aclose()`. The middleware is only needed to receive commands.

event_bridge_client-1.0.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "event-bridge-client"
+version = "1.0.0"
+description = "Lightweight client for registering apps, batching lifecycle events, and handling HMAC-signed remote commands."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "UNLICENSED" }
+keywords = ["events", "hmac", "webhooks", "commands"]
+dependencies = [
+  "httpx>=0.27",
+  "pydantic>=2.4",
+]
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.110"]
+dev = ["pytest>=8", "fastapi>=0.110", "anyio>=4"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/event_bridge_client"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

event_bridge_client-1.0.0/src/event_bridge_client/__init__.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from .batcher import SDK_VERSION
+from .client import EventBridgeClient, create_client
+from .errors import HandlerNotRegisteredError, ManagementError, SignatureError
+from .hmac import HMAC_HEADERS, HMAC_WINDOW_SECONDS, SignedHeaders, sign, verify
+from .nonce import NonceLRU, NonceStore
+from .options import ClientOptions, CommandCtx
+from .schemas import (
+    COMMAND_TYPES,
+    EVENT_TYPES,
+    ResourceAction,
+    ResourceDescriptor,
+    ResourceField,
+    ResourceListQuery,
+)
+
+__version__ = SDK_VERSION
+
+__all__ = [
+    "create_client",
+    "EventBridgeClient",
+    "ClientOptions",
+    "CommandCtx",
+    "sign",
+    "verify",
+    "SignedHeaders",
+    "HMAC_HEADERS",
+    "HMAC_WINDOW_SECONDS",
+    "NonceStore",
+    "NonceLRU",
+    "ManagementError",
+    "SignatureError",
+    "HandlerNotRegisteredError",
+    "ResourceDescriptor",
+    "ResourceField",
+    "ResourceAction",
+    "ResourceListQuery",
+    "EVENT_TYPES",
+    "COMMAND_TYPES",
+    "SDK_VERSION",
+    "__version__",
+]

event_bridge_client-1.0.0/src/event_bridge_client/_util.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import inspect
+import logging
+from datetime import datetime, timezone
+from typing import Any
+
+_default_logger = logging.getLogger("event_bridge_client")
+
+
+def now_iso() -> str:
+    """ISO-8601 timestamp with millisecond precision and a ``Z`` suffix,
+    byte-identical to JavaScript's ``new Date().toISOString()`` so the backend's
+    datetime validation accepts it regardless of which SDK produced the event."""
+    dt = datetime.now(timezone.utc)
+    return dt.strftime("%Y-%m-%dT%H:%M:%S.") + f"{dt.microsecond // 1000:03d}Z"
+
+
+async def maybe_await(value: Any) -> Any:
+    """Await ``value`` if it is awaitable, otherwise return it as-is. Lets
+    handlers be either sync or async."""
+    if inspect.isawaitable(value):
+        return await value
+    return value
+
+
+def get_logger(logger: logging.Logger | None) -> logging.Logger:
+    return logger or _default_logger

event_bridge_client-1.0.0/src/event_bridge_client/batcher.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any, Dict, List
+
+import httpx
+
+from ._util import get_logger, now_iso
+from .options import ClientOptions
+from .ulid import ulid
+
+# Keep in sync with pyproject.toml "version" and the Node SDK.
+SDK_VERSION = "1.0.0"
+DEFAULT_MAX_BUFFER = 10_000
+
+
+class EventBatcher:
+    """Buffers events and flushes them to ``/sdk/events`` on an interval or when
+    the buffer fills. Mirrors the Node batcher: bounded buffer (drop-oldest),
+    single-flight flush, and exponential backoff on failure."""
+
+    def __init__(self, opts: ClientOptions, http: httpx.AsyncClient) -> None:
+        self._o = opts
+        self._http = http
+        self._buffer: List[Dict[str, Any]] = []
+        self._lock = asyncio.Lock()
+        self._wake = asyncio.Event()
+        self._task: "asyncio.Task[None] | None" = None
+        self._stopped = False
+        self._retry = 0
+        self._next_send_at = 0.0
+
+    def start(self) -> None:
+        if self._task is not None:
+            return
+        self._stopped = False
+        self._task = asyncio.create_task(self._run())
+
+    def emit(self, event_type: str, data: Any) -> None:
+        if not self._o.enabled:
+            return
+        self._buffer.append(
+            {"id": ulid(), "type": event_type, "data": data, "occurredAt": now_iso()}
+        )
+        self._cap_buffer()
+        if len(self._buffer) >= self._o.batch_max_size:
+            self._wake.set()
+
+    def _cap_buffer(self) -> None:
+        max_ = self._o.max_buffer_size or DEFAULT_MAX_BUFFER
+        if len(self._buffer) > max_:
+            dropped = len(self._buffer) - max_
+            del self._buffer[:dropped]
+            get_logger(self._o.logger).warning(
+                "[event-bridge] event buffer exceeded %d; dropped %d oldest event(s)",
+                max_,
+                dropped,
+            )
+
+    async def _run(self) -> None:
+        interval = self._o.batch_interval_ms / 1000.0
+        while not self._stopped:
+            try:
+                await asyncio.wait_for(self._wake.wait(), timeout=interval)
+            except asyncio.TimeoutError:
+                pass
+            self._wake.clear()
+            await self.flush()
+
+    async def flush(self) -> None:
+        if not self._o.enabled:
+            return
+        async with self._lock:
+            if not self._buffer:
+                return
+            # Respect the backoff window set by a previous failure.
+            if time.monotonic() < self._next_send_at:
+                return
+            batch = self._buffer[: self._o.batch_max_size]
+            del self._buffer[: len(batch)]
+            payload = {
+                "events": [
+                    {
+                        "id": e["id"],
+                        "occurredAt": e["occurredAt"],
+                        "sdkVersion": SDK_VERSION,
+                        "type": e["type"],
+                        "data": e["data"],
+                    }
+                    for e in batch
+                ]
+            }
+            await self._send(batch, payload)
+
+    async def _send(self, batch: List[Dict[str, Any]], payload: Dict[str, Any]) -> None:
+        try:
+            resp = await self._http.post(
+                f"{self._o.base_url}/sdk/events",
+                headers={"content-type": "application/json", "x-api-key": self._o.api_key},
+                json=payload,
+            )
+            if resp.status_code >= 400:
+                raise RuntimeError(f"events POST {resp.status_code}")
+            self._retry = 0
+            self._next_send_at = 0.0
+        except Exception as err:  # noqa: BLE001 — network/HTTP failures are expected
+            if self._retry >= self._o.max_retries:
+                get_logger(self._o.logger).error(
+                    "[event-bridge] events batch dropped after retries: %s", err
+                )
+                self._retry = 0
+                self._next_send_at = 0.0
+                return
+            self._retry += 1
+            # Re-queue at the head and back off; the interval loop retries.
+            self._buffer[0:0] = batch
+            self._cap_buffer()
+            delay = min(60.0, 1.0 * (2 ** self._retry))
+            self._next_send_at = time.monotonic() + delay
+            get_logger(self._o.logger).warning(
+                "[event-bridge] events retry in %.0fs (attempt %d)", delay, self._retry
+            )
+
+    async def drain(self) -> None:
+        """Stop the timer and make a bounded best-effort attempt to flush what's
+        left (used on shutdown). Won't spin forever if the backend is down."""
+        self._stopped = True
+        if self._task is not None:
+            self._wake.set()
+            await asyncio.gather(self._task, return_exceptions=True)
+            self._task = None
+        for _ in range(self._o.max_retries + 1):
+            if not self._buffer:
+                break
+            self._next_send_at = 0.0  # ignore backoff on shutdown
+            before = len(self._buffer)
+            await self.flush()
+            if self._buffer and len(self._buffer) >= before:
+                break  # not making progress — give up rather than hang