boomerang-python 1.0.0__py3-none-any.whl

boomerang/__init__.py

@@ -0,0 +1,29 @@
+from .client import BoomerangClient
+from .errors import (
+    BoomerangConflictError,
+    BoomerangError,
+    BoomerangForbiddenError,
+    BoomerangServiceUnavailableError,
+    BoomerangUnauthorizedError,
+)
+from .models import (
+    BoomerangJobStatus,
+    BoomerangPayload,
+    BoomerangTriggerRequest,
+    BoomerangTriggerResponse,
+)
+from .signature import BoomerangSignature
+
+__all__ = [
+    "BoomerangClient",
+    "BoomerangSignature",
+    "BoomerangError",
+    "BoomerangUnauthorizedError",
+    "BoomerangForbiddenError",
+    "BoomerangConflictError",
+    "BoomerangServiceUnavailableError",
+    "BoomerangTriggerRequest",
+    "BoomerangTriggerResponse",
+    "BoomerangJobStatus",
+    "BoomerangPayload",
+]

boomerang/client.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+from urllib.parse import quote
+
+import httpx
+
+from .errors import (
+    BoomerangConflictError,
+    BoomerangError,
+    BoomerangForbiddenError,
+    BoomerangServiceUnavailableError,
+    BoomerangUnauthorizedError,
+)
+from .models import (
+    BoomerangJobStatus,
+    BoomerangTriggerRequest,
+    BoomerangTriggerResponse,
+)
+
+_STATUS_MAP: dict[int, type[BoomerangError]] = {
+    401: BoomerangUnauthorizedError,
+    403: BoomerangForbiddenError,
+    409: BoomerangConflictError,
+    503: BoomerangServiceUnavailableError,
+}
+
+
+class BoomerangClient:
+    """Thin HTTP client for the Boomerang async webhook service."""
+
+    def __init__(self, base_url: str, token: str) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._token = token
+        self._client = httpx.Client()
+        self._async_client = httpx.AsyncClient()
+
+    # --- lifecycle ---
+
+    def close(self) -> None:
+        """Close the underlying connection pools."""
+        self._client.close()
+
+    async def aclose(self) -> None:
+        """Close the underlying async connection pool."""
+        await self._async_client.aclose()
+
+    def __enter__(self) -> BoomerangClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    async def __aenter__(self) -> BoomerangClient:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.aclose()
+
+    # --- headers ---
+
+    def _auth_headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self._token}",
+            "Content-Type": "application/json",
+        }
+
+    # --- error handling ---
+
+    @staticmethod
+    def _raise_for_status(response: httpx.Response) -> None:
+        if response.is_success:
+            return
+        try:
+            body = response.json() if response.content else {}
+        except Exception:
+            body = {}
+        message = body.get("error", response.reason_phrase or "Unknown error")
+        error_cls = _STATUS_MAP.get(response.status_code)
+        if error_cls is BoomerangConflictError:
+            raise BoomerangConflictError(
+                message,
+                retry_after_seconds=body.get("retryAfterSeconds"),
+            )
+        if error_cls is not None:
+            raise error_cls(message)
+        raise BoomerangError(response.status_code, message)
+
+    # --- sync ---
+
+    def trigger(
+        self,
+        worker_url: str,
+        callback_url: str,
+        callback_secret: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> BoomerangTriggerResponse:
+        """Submit a job via ``POST /sync``. Returns the assigned job ID."""
+        req = BoomerangTriggerRequest(
+            worker_url=worker_url,
+            callback_url=callback_url,
+            callback_secret=callback_secret,
+            idempotency_key=idempotency_key,
+        )
+        response = self._client.post(
+            f"{self._base_url}/sync",
+            headers=self._auth_headers(),
+            content=req.model_dump_json(by_alias=True, exclude_none=True),
+        )
+        self._raise_for_status(response)
+        return BoomerangTriggerResponse.model_validate(response.json())
+
+    def poll(self, job_id: str) -> BoomerangJobStatus:
+        """Poll job status via ``GET /sync/{jobId}``."""
+        response = self._client.get(
+            f"{self._base_url}/sync/{quote(job_id, safe='')}",
+            headers=self._auth_headers(),
+        )
+        self._raise_for_status(response)
+        return BoomerangJobStatus.model_validate(response.json())
+
+    # --- async ---
+
+    async def trigger_async(
+        self,
+        worker_url: str,
+        callback_url: str,
+        callback_secret: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> BoomerangTriggerResponse:
+        """Async variant of :meth:`trigger`."""
+        req = BoomerangTriggerRequest(
+            worker_url=worker_url,
+            callback_url=callback_url,
+            callback_secret=callback_secret,
+            idempotency_key=idempotency_key,
+        )
+        response = await self._async_client.post(
+            f"{self._base_url}/sync",
+            headers=self._auth_headers(),
+            content=req.model_dump_json(by_alias=True, exclude_none=True),
+        )
+        self._raise_for_status(response)
+        return BoomerangTriggerResponse.model_validate(response.json())
+
+    async def poll_async(self, job_id: str) -> BoomerangJobStatus:
+        """Async variant of :meth:`poll`."""
+        response = await self._async_client.get(
+            f"{self._base_url}/sync/{quote(job_id, safe='')}",
+            headers=self._auth_headers(),
+        )
+        self._raise_for_status(response)
+        return BoomerangJobStatus.model_validate(response.json())

boomerang/errors.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+
+class BoomerangError(Exception):
+    """Base class for all Boomerang SDK errors."""
+
+    status_code: int = 0
+
+    def __init__(self, status_code: int, message: str) -> None:
+        self.status_code = status_code
+        self.message = message
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        return f"[{self.status_code}] {self.message}"
+
+
+class BoomerangUnauthorizedError(BoomerangError):
+    """401 — missing or invalid JWT."""
+
+    def __init__(self, message: str = "Unauthorized") -> None:
+        super().__init__(401, message)
+
+
+class BoomerangForbiddenError(BoomerangError):
+    """403 — callbackUrl or workerUrl not in the server's allowlist."""
+
+    def __init__(self, message: str = "Forbidden") -> None:
+        super().__init__(403, message)
+
+
+class BoomerangConflictError(BoomerangError):
+    """409 — duplicate job submitted within idempotency cooldown."""
+
+    def __init__(self, message: str = "Conflict", retry_after_seconds: int | None = None) -> None:
+        super().__init__(409, message)
+        self.retry_after_seconds = retry_after_seconds
+
+
+class BoomerangServiceUnavailableError(BoomerangError):
+    """503 — Boomerang worker pool is saturated."""
+
+    def __init__(self, message: str = "Service Unavailable") -> None:
+        super().__init__(503, message)
+
+
+STATUS_CODE_TO_ERROR: dict[int, type[BoomerangError]] = {
+    401: BoomerangUnauthorizedError,
+    403: BoomerangForbiddenError,
+    409: BoomerangConflictError,
+    503: BoomerangServiceUnavailableError,
+}
+
+
+def raise_for_status(status_code: int, message: str) -> None:
+    """Raise the appropriate ``BoomerangError`` subclass for *status_code*."""
+    error_cls = STATUS_CODE_TO_ERROR.get(status_code)
+    if error_cls is not None:
+        raise error_cls(message)
+    raise BoomerangError(status_code, message)

boomerang/middleware/fastapi.py

@@ -0,0 +1,42 @@
+"""FastAPI dependency for verifying Boomerang webhook signatures."""
+
+from typing import Callable
+
+from ..models import BoomerangPayload
+from ..signature import BoomerangSignature
+
+
+def boomerang_webhook(secret: str) -> Callable:
+    """Return a FastAPI dependency callable that verifies the webhook
+    signature and returns a :class:`BoomerangPayload`.
+
+    Usage::
+
+        from fastapi import Depends
+
+        @app.post("/hooks/sync-done")
+        async def on_sync_done(
+            payload: BoomerangPayload = Depends(boomerang_webhook(secret)),
+        ):
+            ...
+    """
+    from fastapi import HTTPException, Request
+
+    async def _verify(request: Request) -> BoomerangPayload:
+        signature = request.headers.get("x-signature-sha256")
+        if not signature:
+            raise HTTPException(status_code=401, detail="Missing X-Signature-SHA256 header")
+
+        body = await request.body()
+
+        try:
+            valid = BoomerangSignature.verify(body, signature, secret)
+        except ValueError:
+            raise HTTPException(status_code=401, detail="Malformed signature header")
+
+        if not valid:
+            raise HTTPException(status_code=401, detail="Invalid signature")
+
+        return BoomerangPayload.model_validate_json(body)
+
+    return _verify

boomerang/middleware/flask.py

@@ -0,0 +1,48 @@
+"""Flask decorator for verifying Boomerang webhook signatures."""
+
+from __future__ import annotations
+
+import functools
+from typing import Any, Callable
+
+from ..models import BoomerangPayload
+from ..signature import BoomerangSignature
+
+
+def boomerang_webhook(secret: str) -> Callable:
+    """Decorator that verifies the webhook signature and injects a
+    :class:`BoomerangPayload` as the first positional argument.
+
+    Usage::
+
+        @app.post("/hooks/sync-done")
+        @boomerang_webhook(secret=os.environ["WEBHOOK_SECRET"])
+        def on_sync_done(payload: BoomerangPayload):
+            ...
+    """
+
+    def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            from flask import abort, request  # noqa: lazy import
+
+            signature = request.headers.get("x-signature-sha256")
+            if not signature:
+                abort(401, description="Missing X-Signature-SHA256 header")
+
+            body = request.get_data()
+
+            try:
+                valid = BoomerangSignature.verify(body, signature, secret)
+            except ValueError:
+                abort(401, description="Malformed signature header")
+
+            if not valid:
+                abort(401, description="Invalid signature")
+
+            payload = BoomerangPayload.model_validate_json(body)
+            return fn(payload, *args, **kwargs)
+
+        return wrapper
+
+    return decorator

boomerang/models.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class _CamelModel(BaseModel):
+    """Base model that serialises snake_case fields to camelCase JSON."""
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        frozen=True,
+    )
+
+
+class BoomerangTriggerRequest(_CamelModel):
+    """Request body for ``POST /sync``."""
+
+    worker_url: str = Field(alias="workerUrl")
+    callback_url: str = Field(alias="callbackUrl")
+    callback_secret: str | None = Field(default=None, alias="callbackSecret")
+    idempotency_key: str | None = Field(default=None, alias="idempotencyKey")
+
+
+class BoomerangTriggerResponse(_CamelModel):
+    """Response body returned by ``POST /sync``."""
+
+    job_id: str = Field(alias="jobId")
+
+
+class BoomerangJobStatus(_CamelModel):
+    """Response body returned by ``GET /sync/{jobId}``."""
+
+    job_id: str = Field(alias="jobId")
+    status: Literal["PENDING", "IN_PROGRESS", "DONE", "FAILED"]
+    created_at: str | None = Field(default=None, alias="createdAt")
+    completed_at: str | None = Field(default=None, alias="completedAt")
+    result: dict[str, Any] | None = None
+    error: str | None = None
+
+
+class BoomerangPayload(_CamelModel):
+    """Webhook callback payload delivered to the consumer's ``callbackUrl``.
+
+    This model is immutable (frozen) so middleware can safely pass it around.
+    """
+
+    boomerang_version: str = Field(alias="boomerangVersion")
+    job_id: str = Field(alias="jobId")
+    status: Literal["DONE", "FAILED"]
+    completed_at: datetime = Field(alias="completedAt")
+    result: dict[str, Any] | None = None
+    error: str | None = None

boomerang/signature.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+
+class BoomerangSignature:
+    """HMAC-SHA256 signature verification for Boomerang webhooks."""
+
+    _PREFIX = "sha256="
+
+    @staticmethod
+    def verify(body: bytes, signature_header: str, secret: str) -> bool:
+        """Return ``True`` if *signature_header* is a valid HMAC for *body*.
+
+        Uses constant-time comparison to prevent timing attacks.
+
+        Raises ``ValueError`` if *signature_header* does not start with
+        ``sha256=``.
+        """
+        if not signature_header.startswith(BoomerangSignature._PREFIX):
+            raise ValueError(
+                f"Malformed signature header: expected 'sha256=...' prefix, "
+                f"got {signature_header!r}"
+            )
+        expected = BoomerangSignature.compute(body, secret)
+        return hmac.compare_digest(expected, signature_header)
+
+    @staticmethod
+    def compute(body: bytes, secret: str) -> str:
+        """Return the signature header value: ``sha256=<lowercase hex>``."""
+        digest = hmac.new(
+            secret.encode("utf-8"),
+            body,
+            hashlib.sha256,
+        ).hexdigest()
+        return f"sha256={digest}"

boomerang_python-1.0.0.dist-info/METADATA

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: boomerang-python
+Version: 1.0.0
+Summary: Python SDK for the Boomerang async webhook platform
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.0
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.100; extra == 'dev'
+Requires-Dist: flask>=2.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=2.0; extra == 'flask'
+Description-Content-Type: text/markdown
+
+# boomerang-client
+
+Python SDK for the [Boomerang](https://github.com/sameerchereddy/boomerang) async webhook platform.

boomerang_python-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+boomerang/__init__.py,sha256=ynfhztblaMXn7PyrCap--bt8QreBGMcUKi6zaO9IqQE,712
+boomerang/client.py,sha256=_QAztZONDMDVaNcJwSHx55rTXjEA4Y6IXQqspkEquGY,4802
+boomerang/errors.py,sha256=ITOj3XgcoRr8cjNVHw7AEKZfvnicXS0pgGpLcAWRKqM,1872
+boomerang/models.py,sha256=7BHm3G0EdKFI5EG-n9D68WAq1VCBIUc_wRHrbEddd90,1710
+boomerang/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+boomerang/signature.py,sha256=W1ngRfZgZQ0h98zIWjS1mykYNQN68VvQh4YGyZ3C4bY,1198
+boomerang/middleware/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+boomerang/middleware/fastapi.py,sha256=AqTgWv2QKD5gF9yUVM8FaGCbH_8EwOTWq7man_7QUsE,1291
+boomerang/middleware/flask.py,sha256=bS--oA9J8YmD85NTthzW5n7pMxppoK2NkSeRAPSia6Q,1477
+boomerang_python-1.0.0.dist-info/METADATA,sha256=8_wWBca8__-8vKktiOOzEX3K38viaMmz_qoEQaiCJLw,792
+boomerang_python-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+boomerang_python-1.0.0.dist-info/RECORD,,

boomerang_python-1.0.0.dist-info/WHEEL

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