svc-infra 0.1.600__py3-none-any.whl → 0.1.640__py3-none-any.whl

svc_infra/docs/webhooks.md

@@ -0,0 +1,112 @@
+# Webhooks Framework
+
+This module provides primitives to publish events to external consumers via webhooks, verify inbound signatures, and handle robust retries using the shared JobQueue and Outbox patterns.
+
+> ℹ️ Webhook helper environment expectations live in [Environment Reference](environment.md).
+
+## Quickstart
+
+- Subscriptions and publishing:
+
+```python
+from svc_infra.webhooks.service import InMemoryWebhookSubscriptions, WebhookService
+from svc_infra.db.outbox import InMemoryOutboxStore
+
+subs = InMemoryWebhookSubscriptions()
+subs.add("invoice.created", "https://example.com/webhook", "sekrit")
+svc = WebhookService(outbox=InMemoryOutboxStore(), subs=subs)
+svc.publish("invoice.created", {"id": "inv_1", "version": 1})
+```
+
+- Delivery worker and headers:
+
+```python
+from svc_infra.jobs.builtins.webhook_delivery import make_webhook_handler
+from svc_infra.jobs.worker import process_one
+
+handler = make_webhook_handler(
+    outbox=..., inbox=..., get_webhook_url_for_topic=lambda t: url, get_secret_for_topic=lambda t: secret,
+)
+# process_one(queue, handler) will POST JSON with headers:
+# X-Event-Id, X-Topic, X-Attempt, X-Signature (HMAC-SHA256), X-Signature-Alg, X-Signature-Version, X-Payload-Version
+```
+
+- Verification (FastAPI):
+
+```python
+from fastapi import Depends, FastAPI
+from svc_infra.webhooks.fastapi import require_signature
+from svc_infra.webhooks.signing import sign
+
+app = FastAPI()
+app.post("/webhook")(lambda body=Depends(require_signature(lambda: ["old","new"])): {"ok": True})
+```
+
+## FastAPI wiring
+
+- Attach the router with shared in-memory stores (great for tests / local runs):
+
+```python
+from fastapi import FastAPI
+
+from svc_infra.webhooks import add_webhooks
+
+app = FastAPI()
+add_webhooks(app)
+```
+
+- Respect environment overrides for Redis-backed stores by exporting `REDIS_URL`
+  and selecting the backend via `WEBHOOKS_OUTBOX=redis` (optional
+  `WEBHOOKS_INBOX=redis` for the dedupe store).  The helper records the chosen
+  instances on `app.state` for further customisation:
+
+```python
+import os
+
+os.environ["WEBHOOKS_OUTBOX"] = "redis"
+os.environ["WEBHOOKS_INBOX"] = "redis"
+
+app = FastAPI()
+add_webhooks(app)  # creates RedisOutboxStore / RedisInboxStore when redis-py is available
+
+# Later you can inspect or extend behaviour:
+app.state.webhooks_subscriptions.add("invoice.created", "https://example.com/webhook", "sekrit")
+```
+
+- Provide explicit overrides (e.g. dependency-injected SQL stores) or reuse your
+  existing job queue / scheduler.  Passing a queue automatically registers the
+  outbox tick and delivery handler so your worker loop can process jobs:
+
+```python
+from svc_infra.jobs.easy import easy_jobs
+
+queue, scheduler = easy_jobs()
+
+add_webhooks(
+    app,
+    outbox=my_outbox_store,
+    inbox=lambda: my_inbox_store,  # factories are supported
+    queue=queue,
+    scheduler=scheduler,
+)
+
+# scheduler.add_task(...) is handled internally when both queue and scheduler are supplied
+```
+
+## Runner wiring
+
+If you prefer explicit wiring, you can still register the tick manually:
+
+```python
+from svc_infra.jobs.easy import easy_jobs
+from svc_infra.jobs.builtins.outbox_processor import make_outbox_tick
+
+queue, scheduler = easy_jobs()  # uses JOBS_DRIVER and REDIS_URL
+scheduler.add_task("outbox", 1, make_outbox_tick(outbox_store, queue))
+# Start runner: `svc-infra jobs run`
+```
+
+## Notes
+- Retries/backoff are handled by the JobQueue; delivery marks Inbox after success to prevent duplicates.
+- For production subscriptions and inbox/outbox, provide persistent implementations and override DI in your app.
+- Signature rotation supported via `verify_any` and FastAPI dependency accepting multiple secrets.

svc_infra/dx/add.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def write_ci_workflow(
+    *,
+    target_dir: str | Path,
+    name: str = "ci.yml",
+    python_version: str = "3.12",
+) -> Path:
+    """Write a minimal CI workflow file (GitHub Actions) with tests/lint/type steps."""
+    p = Path(target_dir) / ".github" / "workflows" / name
+    p.parent.mkdir(parents=True, exist_ok=True)
+    content = f"""
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '{python_version}'
+      - name: Install Poetry
+        run: pipx install poetry
+      - name: Install deps
+        run: poetry install
+      - name: Lint
+        run: poetry run flake8 --select=E,F
+      - name: Typecheck
+        run: poetry run mypy src
+      - name: Tests
+        run: poetry run pytest -q -W error
+"""
+    p.write_text(content.strip() + "\n")
+    return p
+
+
+def write_openapi_lint_config(*, target_dir: str | Path, name: str = ".redocly.yaml") -> Path:
+    """Write a minimal OpenAPI lint config placeholder (Redocly)."""
+    p = Path(target_dir) / name
+    content = """
+apis:
+  main:
+    root: openapi.json
+
+rules:
+  operation-operationId: warn
+  no-unused-components: warn
+  security-defined: off
+"""
+    p.write_text(content.strip() + "\n")
+    return p
+
+
+__all__ = ["write_ci_workflow", "write_openapi_lint_config"]

svc_infra/dx/changelog.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date as _date
+from typing import Sequence
+
+
+@dataclass(frozen=True)
+class Commit:
+    sha: str
+    subject: str
+
+
+_SECTION_ORDER = [
+    ("feat", "Features"),
+    ("fix", "Bug Fixes"),
+    ("perf", "Performance"),
+    ("refactor", "Refactors"),
+]
+
+
+def _classify(subject: str) -> tuple[str, str]:
+    """Return (type, title) where title is display name of the section."""
+    lower = subject.strip().lower()
+    for t, title in _SECTION_ORDER:
+        if lower.startswith(t + ":") or lower.startswith(t + "("):
+            return (t, title)
+    return ("other", "Other")
+
+
+def _format_item(commit: Commit) -> str:
+    subj = commit.subject.strip()
+    # Strip leading type(scope): if present
+    i = subj.find(": ")
+    if i != -1 and i < 20:  # conventional commit prefix
+        pretty = subj[i + 2 :].strip()
+    else:
+        pretty = subj
+    return f"- {pretty} ({commit.sha})"
+
+
+def generate_release_section(
+    *,
+    version: str,
+    commits: Sequence[Commit],
+    release_date: str | None = None,
+) -> str:
+    """Generate a markdown release section from commits.
+
+    Group by type: feat, fix, perf, refactor; everything else under Other.
+    """
+    if release_date is None:
+        release_date = _date.today().isoformat()
+
+    buckets: dict[str, list[str]] = {k: [] for k, _ in _SECTION_ORDER}
+    buckets["other"] = []
+
+    for c in commits:
+        typ, _ = _classify(c.subject)
+        buckets.setdefault(typ, []).append(_format_item(c))
+
+    lines: list[str] = [f"## v{version} - {release_date}", ""]
+    for key, title in _SECTION_ORDER + [("other", "Other")]:
+        items = buckets.get(key) or []
+        if not items:
+            continue
+        lines.append(f"### {title}")
+        lines.extend(items)
+        lines.append("")
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+__all__ = ["Commit", "generate_release_section"]

svc_infra/dx/checks.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def _load_json(path: str | Path) -> dict:
+    import json
+
+    p = Path(path)
+    return json.loads(p.read_text())
+
+
+def check_openapi_problem_schema(
+    schema: dict | None = None, *, path: str | Path | None = None
+) -> None:
+    """Validate OpenAPI has a Problem schema with required fields and formats.
+
+    Raises ValueError with a descriptive message on failure.
+    """
+
+    if schema is None:
+        if path is None:
+            raise ValueError("either schema or path must be provided")
+        schema = _load_json(path)
+
+    comps = (schema or {}).get("components") or {}
+    prob = (comps.get("schemas") or {}).get("Problem")
+    if not isinstance(prob, dict):
+        raise ValueError("Problem schema missing under components.schemas.Problem")
+
+    props = prob.get("properties") or {}
+    # Required keys presence
+    for key in ("type", "title", "status", "detail", "instance", "code"):
+        if key not in props:
+            raise ValueError(f"Problem.{key} missing in properties")
+
+    # instance must be uri-reference per our convention
+    inst = props.get("instance") or {}
+    if inst.get("format") != "uri-reference":
+        raise ValueError("Problem.instance must have format 'uri-reference'")
+
+
+def check_migrations_up_to_date(*, project_root: str | Path = ".") -> None:
+    """Best-effort migrations check: passes if alembic env present and head is reachable.
+
+    This is a lightweight stub that can be extended per-project. For now, it checks
+    that an Alembic env exists when 'alembic.ini' is present; it does not execute DB calls.
+    """
+
+    root = Path(project_root)
+    # If alembic.ini is absent, there's nothing to check here
+    if not (root / "alembic.ini").exists():
+        return
+    # Ensure versions/ dir exists under migrations path if configured, default to 'migrations'
+    mig_dir = root / "migrations"
+    if not mig_dir.exists():
+        # tolerate alternative layout via env; keep stub permissive
+        return
+    versions = mig_dir / "versions"
+    if not versions.exists():
+        raise ValueError("Alembic migrations directory missing versions/ subfolder")
+
+
+__all__ = [
+    "check_openapi_problem_schema",
+    "check_migrations_up_to_date",
+]

svc_infra/http/__init__.py

@@ -0,0 +1,13 @@
+from .client import (
+    get_default_timeout_seconds,
+    make_timeout,
+    new_async_httpx_client,
+    new_httpx_client,
+)
+
+__all__ = [
+    "get_default_timeout_seconds",
+    "new_httpx_client",
+    "new_async_httpx_client",
+    "make_timeout",
+]

svc_infra/http/client.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Optional
+
+import httpx
+
+from svc_infra.app.env import pick
+
+
+def _parse_float_env(name: str, default: float) -> float:
+    raw = os.getenv(name)
+    if raw is None or raw == "":
+        return default
+    try:
+        return float(raw)
+    except ValueError:
+        return default
+
+
+def get_default_timeout_seconds() -> float:
+    """Return default outbound HTTP client timeout in seconds.
+
+    Env var: HTTP_CLIENT_TIMEOUT_SECONDS (float)
+    Defaults: 10.0 seconds for all envs unless overridden; tweakable via pick() if needed.
+    """
+    default = pick(prod=10.0, nonprod=10.0)
+    return _parse_float_env("HTTP_CLIENT_TIMEOUT_SECONDS", default)
+
+
+def make_timeout(seconds: float | None = None) -> httpx.Timeout:
+    s = seconds if seconds is not None else get_default_timeout_seconds()
+    # Apply same timeout for connect/read/write/pool for simplicity
+    return httpx.Timeout(timeout=s)
+
+
+def new_httpx_client(
+    *,
+    timeout_seconds: Optional[float] = None,
+    headers: Optional[Dict[str, str]] = None,
+    base_url: Optional[str] = None,
+    **kwargs: Any,
+) -> httpx.Client:
+    """Create a sync httpx Client with default timeout and optional headers/base_url.
+
+    Callers can override timeout_seconds; remaining kwargs are forwarded to httpx.Client.
+    """
+    timeout = make_timeout(timeout_seconds)
+    # httpx doesn't accept base_url=None; only pass if non-None
+    client_kwargs = {"timeout": timeout, "headers": headers, **kwargs}
+    if base_url is not None:
+        client_kwargs["base_url"] = base_url
+    return httpx.Client(**client_kwargs)
+
+
+def new_async_httpx_client(
+    *,
+    timeout_seconds: Optional[float] = None,
+    headers: Optional[Dict[str, str]] = None,
+    base_url: Optional[str] = None,
+    **kwargs: Any,
+) -> httpx.AsyncClient:
+    """Create an async httpx AsyncClient with default timeout and optional headers/base_url.
+
+    Callers can override timeout_seconds; remaining kwargs are forwarded to httpx.AsyncClient.
+    """
+    timeout = make_timeout(timeout_seconds)
+    # httpx doesn't accept base_url=None; only pass if non-None
+    client_kwargs = {"timeout": timeout, "headers": headers, **kwargs}
+    if base_url is not None:
+        client_kwargs["base_url"] = base_url
+    return httpx.AsyncClient(**client_kwargs)

svc_infra/jobs/builtins/webhook_delivery.py

@@ -1,9 +1,10 @@
 from __future__ import annotations
 
-import httpx
+import os
 
 from svc_infra.db.inbox import InboxStore
 from svc_infra.db.outbox import OutboxStore
+from svc_infra.http import get_default_timeout_seconds, new_async_httpx_client
 from svc_infra.jobs.queue import Job
 from svc_infra.webhooks.signing import sign
 
@@ -65,7 +66,18 @@ def make_webhook_handler(
             version = delivery_payload.get("version")
         if version is not None:
             headers["X-Payload-Version"] = str(version)
-        async with httpx.AsyncClient(timeout=10) as client:
+        # Derive timeout: dedicated WEBHOOK_DELIVERY_TIMEOUT_SECONDS or default HTTP client timeout
+        timeout_seconds = None
+        env_timeout = os.getenv("WEBHOOK_DELIVERY_TIMEOUT_SECONDS")
+        if env_timeout:
+            try:
+                timeout_seconds = float(env_timeout)
+            except ValueError:
+                timeout_seconds = get_default_timeout_seconds()
+        else:
+            timeout_seconds = get_default_timeout_seconds()
+
+        async with new_async_httpx_client(timeout_seconds=timeout_seconds) as client:
             resp = await client.post(url, json=delivery_payload, headers=headers)
             if 200 <= resp.status_code < 300:
                 # record delivery and mark processed

svc_infra/jobs/queue.py

@@ -69,5 +69,13 @@ class InMemoryJobQueue:
                 job.last_error = error
                 # Exponential backoff: base * attempts
                 delay = job.backoff_seconds * max(1, job.attempts)
-                job.available_at = now + timedelta(seconds=delay)
+                if delay > 0:
+                    # Add a tiny fudge so an immediate subsequent poll in ultra-fast
+                    # environments (like our acceptance API) doesn't re-reserve the job.
+                    # This keeps tests deterministic without impacting semantics.
+                    job.available_at = now + timedelta(seconds=delay, milliseconds=250)
+                else:
+                    # When backoff is explicitly zero (e.g., unit tests forcing
+                    # immediate retry), make the job available right away.
+                    job.available_at = now
                 return

svc_infra/jobs/runner.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from typing import Awaitable, Callable, Optional
+
+from .queue import JobQueue
+
+ProcessFunc = Callable[[object], Awaitable[None]]
+
+
+class WorkerRunner:
+    """Cooperative worker loop with graceful stop.
+
+    - start(): begin polling the queue and processing jobs
+    - stop(grace_seconds): signal stop, wait up to grace for current job to finish
+    """
+
+    def __init__(self, queue: JobQueue, handler: ProcessFunc, *, poll_interval: float = 0.25):
+        self._queue = queue
+        self._handler = handler
+        self._poll_interval = poll_interval
+        self._task: Optional[asyncio.Task] = None
+        self._stopping = asyncio.Event()
+        self._inflight: Optional[asyncio.Task] = None
+
+    async def _loop(self) -> None:
+        try:
+            while not self._stopping.is_set():
+                job = self._queue.reserve_next()
+                if not job:
+                    await asyncio.sleep(self._poll_interval)
+                    continue
+
+                # Process one job; track in-flight task for stop()
+                async def _run():
+                    try:
+                        await self._handler(job)
+                    except Exception as exc:  # pragma: no cover
+                        self._queue.fail(job.id, error=str(exc))
+                        return
+                    self._queue.ack(job.id)
+
+                self._inflight = asyncio.create_task(_run())
+                try:
+                    await self._inflight
+                finally:
+                    self._inflight = None
+        finally:
+            # exiting loop
+            pass
+
+    def start(self) -> asyncio.Task:
+        if self._task is None or self._task.done():
+            self._task = asyncio.create_task(self._loop())
+        return self._task
+
+    async def stop(self, *, grace_seconds: float = 10.0) -> None:
+        self._stopping.set()
+        # Wait for in-flight job to complete, up to grace
+        if self._inflight is not None and not self._inflight.done():
+            try:
+                await asyncio.wait_for(self._inflight, timeout=grace_seconds)
+            except asyncio.TimeoutError:
+                # Give up; job will be retried if your queue supports visibility timeouts
+                pass
+        # Finally, wait for loop to exit (should be quick since stopping is set)
+        if self._task is not None:
+            try:
+                await asyncio.wait_for(self._task, timeout=max(0.1, self._poll_interval + 0.1))
+            except asyncio.TimeoutError:
+                # Cancel as a last resort
+                self._task.cancel()
+                with contextlib.suppress(Exception):
+                    await self._task

svc_infra/jobs/worker.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import asyncio
+import os
 from typing import Awaitable, Callable
 
 from .queue import Job, JobQueue
@@ -7,6 +9,16 @@ from .queue import Job, JobQueue
 ProcessFunc = Callable[[Job], Awaitable[None]]
 
 
+def _get_job_timeout_seconds() -> float | None:
+    raw = os.getenv("JOB_DEFAULT_TIMEOUT_SECONDS")
+    if not raw:
+        return None
+    try:
+        return float(raw)
+    except ValueError:
+        return None
+
+
 async def process_one(queue: JobQueue, handler: ProcessFunc) -> bool:
     """Reserve a job, process with handler, ack on success or fail with backoff.
 
@@ -16,7 +28,11 @@ async def process_one(queue: JobQueue, handler: ProcessFunc) -> bool:
     if not job:
         return False
     try:
-        await handler(job)
+        timeout = _get_job_timeout_seconds()
+        if timeout and timeout > 0:
+            await asyncio.wait_for(handler(job), timeout=timeout)
+        else:
+            await handler(job)
     except Exception as exc:  # pragma: no cover - exercise in tests by raising
         queue.fail(job.id, error=str(exc))
         return True