svc-infra 0.1.596__py3-none-any.whl → 0.1.598__py3-none-any.whl

svc_infra/cli/__init__.py

@@ -4,6 +4,7 @@ import typer
 
 from svc_infra.cli.cmds import (
     _HELP,
+    jobs_app,
     register_alembic,
     register_mongo,
     register_mongo_scaffold,
@@ -26,6 +27,9 @@ register_mongo_scaffold(app)
 # -- observability commands ---
 register_obs(app)
 
+# -- jobs commands ---
+app.add_typer(jobs_app, name="jobs")
+
 
 def main():
     app()

svc_infra/cli/__main__.py

@@ -0,0 +1,4 @@
+from . import main
+
+if __name__ == "__main__":
+    main()

svc_infra/cli/cmds/__init__.py

@@ -4,6 +4,7 @@ from svc_infra.cli.cmds.db.nosql.mongo.mongo_scaffold_cmds import (
 )
 from svc_infra.cli.cmds.db.sql.alembic_cmds import register as register_alembic
 from svc_infra.cli.cmds.db.sql.sql_scaffold_cmds import register as register_sql_scaffold
+from svc_infra.cli.cmds.jobs.jobs_cmds import app as jobs_app
 from svc_infra.cli.cmds.obs.obs_cmds import register as register_obs
 
 from .help import _HELP
@@ -14,5 +15,6 @@ __all__ = [
     "register_mongo",
     "register_mongo_scaffold",
     "register_obs",
+    "jobs_app",
     "_HELP",
 ]

svc_infra/cli/cmds/jobs/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

svc_infra/cli/cmds/jobs/jobs_cmds.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Optional
+
+import typer
+
+from svc_infra.jobs.easy import easy_jobs
+from svc_infra.jobs.loader import schedule_from_env
+from svc_infra.jobs.worker import process_one
+
+app = typer.Typer(help="Background jobs and scheduler commands")
+
+
+@app.command("run")
+def run(
+    poll_interval: float = typer.Option(0.5, help="Sleep seconds between loops when idle"),
+    max_loops: Optional[int] = typer.Option(None, help="Max loops before exit (for tests)"),
+):
+    """Run scheduler ticks and process jobs in a simple loop."""
+
+    queue, scheduler = easy_jobs()
+    # load schedule from env JSON if provided
+    schedule_from_env(scheduler)
+
+    async def _loop():
+        loops = 0
+        while True:
+            await scheduler.tick()
+            processed = await process_one(queue, _noop_handler)
+            if not processed:
+                # idle
+                await asyncio.sleep(poll_interval)
+            if max_loops is not None:
+                loops += 1
+                if loops >= max_loops:
+                    break
+
+    async def _noop_handler(job):
+        # Default handler does nothing; users should write their own runners
+        return None
+
+    asyncio.run(_loop())

svc_infra/db/inbox.py

@@ -13,6 +13,10 @@ class InboxStore(Protocol):
         """Optional: remove expired keys, return number purged."""
         ...
 
+    def is_marked(self, key: str) -> bool:
+        """Return True if key is already marked (not expired), without modifying it."""
+        ...
+
 
 class InMemoryInboxStore:
     def __init__(self) -> None:
@@ -33,6 +37,11 @@ class InMemoryInboxStore:
             self._keys.pop(k, None)
         return len(to_del)
 
+    def is_marked(self, key: str) -> bool:
+        now = time.time()
+        exp = self._keys.get(key)
+        return bool(exp and exp > now)
+
 
 class SqlInboxStore:
     """Skeleton for a SQL-backed inbox store (dedupe table).
@@ -53,3 +62,6 @@ class SqlInboxStore:
 
     def purge_expired(self) -> int:  # pragma: no cover - skeleton
         raise NotImplementedError
+
+    def is_marked(self, key: str) -> bool:  # pragma: no cover - skeleton
+        raise NotImplementedError

svc_infra/db/outbox.py

@@ -20,7 +20,12 @@ class OutboxStore(Protocol):
         pass
 
     def fetch_next(self, *, topics: Optional[Iterable[str]] = None) -> Optional[OutboxMessage]:
-        """Return the next unprocessed message (FIFO per-topic), or None if none available."""
+        """Return the next undispatched, unprocessed message (FIFO per-topic), or None.
+
+        Notes:
+        - Messages with attempts > 0 are considered "dispatched" to the job queue and won't be re-enqueued.
+        - Delivery retries are handled by the job queue worker, not by re-reading the outbox.
+        """
         pass
 
     def mark_processed(self, msg_id: int) -> None:
@@ -48,6 +53,9 @@ class InMemoryOutboxStore:
         for msg in self._messages:
             if msg.processed_at is not None:
                 continue
+            # skip already dispatched messages (attempts>0)
+            if msg.attempts > 0:
+                continue
             if allowed is not None and msg.topic not in allowed:
                 continue
             return msg

svc_infra/jobs/builtins/outbox_processor.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Iterable, Optional
+
+from svc_infra.db.outbox import OutboxStore
+from svc_infra.jobs.queue import JobQueue
+
+
+def make_outbox_tick(
+    outbox: OutboxStore,
+    queue: JobQueue,
+    *,
+    topics: Optional[Iterable[str]] = None,
+    job_name_prefix: str = "outbox",
+):
+    """Return an async task function to move one outbox message into the job queue.
+
+    - It fetches at most one unprocessed message per tick to avoid starving others.
+    - The enqueued job name is f"{job_name_prefix}.{topic}" to allow routing.
+    - The job payload contains `outbox_id`, `topic`, and original `payload`.
+    """
+
+    dispatched: set[int] = set()
+
+    async def _tick():
+        # Outbox is sync; this wrapper is async for scheduler compatibility
+        msg = outbox.fetch_next(topics=topics)
+        if not msg:
+            return
+        if msg.id in dispatched:
+            return
+        job_name = f"{job_name_prefix}.{msg.topic}"
+        queue.enqueue(job_name, {"outbox_id": msg.id, "topic": msg.topic, "payload": msg.payload})
+        # mark as dispatched (bump attempts) so it won't be re-enqueued by fetch_next
+        outbox.mark_failed(msg.id)
+        dispatched.add(msg.id)
+
+    return _tick

svc_infra/jobs/builtins/webhook_delivery.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import httpx
+
+from svc_infra.db.inbox import InboxStore
+from svc_infra.db.outbox import OutboxStore
+from svc_infra.jobs.queue import Job
+from svc_infra.webhooks.signing import sign
+
+
+def make_webhook_handler(
+    *,
+    outbox: OutboxStore,
+    inbox: InboxStore,
+    get_webhook_url_for_topic,
+    get_secret_for_topic,
+    header_name: str = "X-Signature",
+):
+    """Return an async job handler to deliver webhooks.
+
+    Expected job payload shape:
+    {"outbox_id": int, "topic": str, "payload": {...}}
+    """
+
+    async def _handler(job: Job) -> None:
+        data = job.payload or {}
+        outbox_id = data.get("outbox_id")
+        topic = data.get("topic")
+        payload = data.get("payload") or {}
+        if not outbox_id or not topic:
+            # Nothing we can do; ack to avoid poison loop
+            return
+        # dedupe marker key (marked after successful delivery)
+        key = f"webhook:{outbox_id}"
+        if inbox.is_marked(key):
+            # already delivered
+            outbox.mark_processed(int(outbox_id))
+            return
+        event = payload.get("event") if isinstance(payload, dict) else None
+        subscription = payload.get("subscription") if isinstance(payload, dict) else None
+        if event is not None and subscription is not None:
+            delivery_payload = event
+            url = subscription.get("url") or get_webhook_url_for_topic(topic)
+            secret = subscription.get("secret") or get_secret_for_topic(topic)
+            subscription_id = subscription.get("id")
+        else:
+            delivery_payload = payload
+            url = get_webhook_url_for_topic(topic)
+            secret = get_secret_for_topic(topic)
+            subscription_id = None
+        sig = sign(secret, delivery_payload)
+        headers = {
+            header_name: sig,
+            "X-Event-Id": str(outbox_id),
+            "X-Topic": str(topic),
+            "X-Attempt": str(job.attempts or 1),
+            "X-Signature-Alg": "hmac-sha256",
+            "X-Signature-Version": "v1",
+        }
+        if subscription_id:
+            headers["X-Webhook-Subscription"] = str(subscription_id)
+        # include event payload version if present
+        version = None
+        if isinstance(delivery_payload, dict):
+            version = delivery_payload.get("version")
+        if version is not None:
+            headers["X-Payload-Version"] = str(version)
+        async with httpx.AsyncClient(timeout=10) as client:
+            resp = await client.post(url, json=delivery_payload, headers=headers)
+            if 200 <= resp.status_code < 300:
+                # record delivery and mark processed
+                inbox.mark_if_new(key, ttl_seconds=24 * 3600)
+                outbox.mark_processed(int(outbox_id))
+                return
+            # allow retry on non-2xx: raise to trigger fail/backoff
+            raise RuntimeError(f"webhook delivery failed: {resp.status_code}")
+
+    return _handler

svc_infra/jobs/easy.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import os
+
+from redis import Redis
+
+from .queue import InMemoryJobQueue, JobQueue
+from .redis_queue import RedisJobQueue
+from .scheduler import InMemoryScheduler
+
+
+class JobsConfig:
+    def __init__(self, driver: str | None = None):
+        # Future: support redis/sql drivers via extras
+        self.driver = driver or os.getenv("JOBS_DRIVER", "memory").lower()
+
+
+def easy_jobs(*, driver: str | None = None) -> tuple[JobQueue, InMemoryScheduler]:
+    """One-call wiring for jobs: returns (queue, scheduler).
+
+    Defaults to in-memory implementations for local/dev. ENV override via JOBS_DRIVER.
+    """
+    cfg = JobsConfig(driver=driver)
+    # Choose backend
+    if cfg.driver == "redis":
+        url = os.getenv("REDIS_URL", "redis://localhost:6379/0")
+        client = Redis.from_url(url)
+        queue = RedisJobQueue(client)
+    else:
+        queue = InMemoryJobQueue()
+    scheduler = InMemoryScheduler()
+    return queue, scheduler

svc_infra/jobs/loader.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import asyncio
+import importlib
+import json
+import os
+from typing import Awaitable, Callable
+
+from .scheduler import InMemoryScheduler
+
+
+def _resolve_target(path: str) -> Callable[[], Awaitable[None]]:
+    mod_name, func_name = path.split(":", 1)
+    mod = importlib.import_module(mod_name)
+    fn = getattr(mod, func_name)
+    if asyncio.iscoroutinefunction(fn):
+        return fn  # type: ignore[return-value]
+
+    # wrap sync into async
+    async def _wrapped():
+        fn()
+
+    return _wrapped
+
+
+def schedule_from_env(scheduler: InMemoryScheduler, env_var: str = "JOBS_SCHEDULE_JSON") -> None:
+    data = os.getenv(env_var)
+    if not data:
+        return
+    try:
+        tasks = json.loads(data)
+    except json.JSONDecodeError:
+        return
+    if not isinstance(tasks, list):
+        return
+    for t in tasks:
+        try:
+            name = t["name"]
+            interval = int(t.get("interval_seconds", 60))
+            target = t["target"]
+            fn = _resolve_target(target)
+            scheduler.add_task(name, interval, fn)
+        except Exception:
+            # ignore bad entries
+            continue

svc_infra/jobs/queue.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from typing import Any, Dict, Optional, Protocol
+
+
+@dataclass
+class Job:
+    id: str
+    name: str
+    payload: Dict[str, Any]
+    available_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    attempts: int = 0
+    max_attempts: int = 5
+    backoff_seconds: int = 60  # base backoff for retry
+    last_error: Optional[str] = None
+
+
+class JobQueue(Protocol):
+    def enqueue(self, name: str, payload: Dict[str, Any], *, delay_seconds: int = 0) -> Job:
+        pass
+
+    def reserve_next(self) -> Optional[Job]:
+        pass
+
+    def ack(self, job_id: str) -> None:
+        pass
+
+    def fail(self, job_id: str, *, error: str | None = None) -> None:
+        pass
+
+
+class InMemoryJobQueue:
+    """Simple in-memory queue for tests and local runs.
+
+    Single-threaded reserve/ack/fail semantics. Not suitable for production.
+    """
+
+    def __init__(self):
+        self._seq = 0
+        self._jobs: list[Job] = []
+
+    def _next_id(self) -> str:
+        self._seq += 1
+        return str(self._seq)
+
+    def enqueue(self, name: str, payload: Dict[str, Any], *, delay_seconds: int = 0) -> Job:
+        when = datetime.now(timezone.utc) + timedelta(seconds=delay_seconds)
+        job = Job(id=self._next_id(), name=name, payload=dict(payload), available_at=when)
+        self._jobs.append(job)
+        return job
+
+    def reserve_next(self) -> Optional[Job]:
+        now = datetime.now(timezone.utc)
+        for job in self._jobs:
+            if job.available_at <= now and job.attempts >= 0 and job.attempts < job.max_attempts:
+                job.attempts += 1
+                return job
+        return None
+
+    def ack(self, job_id: str) -> None:
+        self._jobs = [j for j in self._jobs if j.id != job_id]
+
+    def fail(self, job_id: str, *, error: str | None = None) -> None:
+        now = datetime.now(timezone.utc)
+        for job in self._jobs:
+            if job.id == job_id:
+                job.last_error = error
+                # Exponential backoff: base * attempts
+                delay = job.backoff_seconds * max(1, job.attempts)
+                job.available_at = now + timedelta(seconds=delay)
+                return

svc_infra/jobs/redis_queue.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+from datetime import datetime, timezone
+from typing import Dict, Optional
+
+from redis import Redis
+
+from .queue import Job, JobQueue
+
+
+class RedisJobQueue(JobQueue):
+    """Redis-backed job queue with visibility timeout and delayed retries.
+
+    Keys (with optional prefix):
+      - {p}:ready (LIST)        ready job ids
+      - {p}:processing (LIST)   in-flight job ids
+      - {p}:processing_vt (ZSET) id -> visible_at (epoch seconds)
+      - {p}:delayed (ZSET)      id -> available_at (epoch seconds)
+      - {p}:seq (STRING)        INCR for job ids
+      - {p}:job:{id} (HASH)     job fields (json payload)
+      - {p}:dlq (LIST)          dead-letter job ids
+    """
+
+    def __init__(self, client: Redis, *, prefix: str = "jobs", visibility_timeout: int = 60):
+        self._r = client
+        self._p = prefix
+        self._vt = visibility_timeout
+
+    # Key helpers
+    def _k(self, name: str) -> str:
+        return f"{self._p}:{name}"
+
+    def _job_key(self, job_id: str) -> str:
+        return f"{self._p}:job:{job_id}"
+
+    # Core ops
+    def enqueue(self, name: str, payload: Dict, *, delay_seconds: int = 0) -> Job:
+        now = datetime.now(timezone.utc)
+        job_id = str(self._r.incr(self._k("seq")))
+        job = Job(id=job_id, name=name, payload=dict(payload))
+        # Persist job
+        data = asdict(job)
+        data["payload"] = json.dumps(data["payload"])  # store payload as JSON string
+        # available_at stored as ISO format
+        data["available_at"] = job.available_at.isoformat()
+        self._r.hset(
+            self._job_key(job_id), mapping={k: str(v) for k, v in data.items() if v is not None}
+        )
+        if delay_seconds and delay_seconds > 0:
+            at = int(now.timestamp()) + int(delay_seconds)
+            self._r.zadd(self._k("delayed"), {job_id: at})
+        else:
+            # push to ready
+            self._r.lpush(self._k("ready"), job_id)
+        return job
+
+    def _move_due_delayed_to_ready(self) -> None:
+        now_ts = int(datetime.now(timezone.utc).timestamp())
+        ids = self._r.zrangebyscore(self._k("delayed"), "-inf", now_ts)
+        if not ids:
+            return
+        pipe = self._r.pipeline()
+        for jid in ids:
+            jid_s = jid.decode() if isinstance(jid, (bytes, bytearray)) else str(jid)
+            pipe.lpush(self._k("ready"), jid_s)
+            pipe.zrem(self._k("delayed"), jid_s)
+        pipe.execute()
+
+    def _requeue_timed_out_processing(self) -> None:
+        now_ts = int(datetime.now(timezone.utc).timestamp())
+        ids = self._r.zrangebyscore(self._k("processing_vt"), "-inf", now_ts)
+        if not ids:
+            return
+        pipe = self._r.pipeline()
+        for jid in ids:
+            jid_s = jid.decode() if isinstance(jid, (bytes, bytearray)) else str(jid)
+            pipe.lrem(self._k("processing"), 1, jid_s)
+            pipe.lpush(self._k("ready"), jid_s)
+            pipe.zrem(self._k("processing_vt"), jid_s)
+            # clear stale visibility timestamp so next reservation can set a fresh one
+            pipe.hdel(self._job_key(jid_s), "visible_at")
+        pipe.execute()
+
+    def reserve_next(self) -> Optional[Job]:
+        # opportunistically move due delayed jobs
+        self._move_due_delayed_to_ready()
+        # move timed-out processing jobs back to ready before reserving
+        self._requeue_timed_out_processing()
+        jid = self._r.rpoplpush(self._k("ready"), self._k("processing"))
+        if not jid:
+            return None
+        job_id = jid.decode() if isinstance(jid, (bytes, bytearray)) else str(jid)
+        key = self._job_key(job_id)
+        data = self._r.hgetall(key)
+        if not data:
+            # corrupted entry; ack and skip
+            self._r.lrem(self._k("processing"), 1, job_id)
+            return None
+
+        # Decode fields
+        def _get(field: str, default: Optional[str] = None) -> Optional[str]:
+            val = (
+                data.get(field.encode())
+                if isinstance(next(iter(data.keys())), bytes)
+                else data.get(field)
+            )
+            if val is None:
+                return default
+            return val.decode() if isinstance(val, (bytes, bytearray)) else str(val)
+
+        attempts = int(_get("attempts", "0")) + 1
+        max_attempts = int(_get("max_attempts", "5"))
+        backoff_seconds = int(_get("backoff_seconds", "60"))
+        name = _get("name", "") or ""
+        payload_json = _get("payload", "{}") or "{}"
+        try:
+            payload = json.loads(payload_json)
+        except Exception:  # pragma: no cover
+            payload = {}
+        available_at_str = _get("available_at")
+        available_at = (
+            datetime.fromisoformat(available_at_str)
+            if available_at_str
+            else datetime.now(timezone.utc)
+        )
+        # If exceeded max_attempts → DLQ and skip
+        if attempts > max_attempts:
+            self._r.lrem(self._k("processing"), 1, job_id)
+            self._r.lpush(self._k("dlq"), job_id)
+            return None
+        # Update attempts and visibility timeout
+        visible_at = int(datetime.now(timezone.utc).timestamp()) + int(self._vt)
+        pipe = self._r.pipeline()
+        pipe.hset(key, mapping={"attempts": attempts, "visible_at": visible_at})
+        pipe.zadd(self._k("processing_vt"), {job_id: visible_at})
+        pipe.execute()
+        return Job(
+            id=job_id,
+            name=name,
+            payload=payload,
+            available_at=available_at,
+            attempts=attempts,
+            max_attempts=max_attempts,
+            backoff_seconds=backoff_seconds,
+        )
+
+    def ack(self, job_id: str) -> None:
+        self._r.lrem(self._k("processing"), 1, job_id)
+        self._r.zrem(self._k("processing_vt"), job_id)
+        self._r.delete(self._job_key(job_id))
+
+    def fail(self, job_id: str, *, error: str | None = None) -> None:
+        key = self._job_key(job_id)
+        data = self._r.hgetall(key)
+        if not data:
+            # nothing to do
+            self._r.lrem(self._k("processing"), 1, job_id)
+            return
+
+        def _get(field: str, default: Optional[str] = None) -> Optional[str]:
+            val = (
+                data.get(field.encode())
+                if isinstance(next(iter(data.keys())), bytes)
+                else data.get(field)
+            )
+            if val is None:
+                return default
+            return val.decode() if isinstance(val, (bytes, bytearray)) else str(val)
+
+        attempts = int(_get("attempts", "0"))
+        max_attempts = int(_get("max_attempts", "5"))
+        backoff_seconds = int(_get("backoff_seconds", "60"))
+        now_ts = int(datetime.now(timezone.utc).timestamp())
+        # DLQ if at or beyond max_attempts
+        if attempts >= max_attempts:
+            self._r.lrem(self._k("processing"), 1, job_id)
+            self._r.zrem(self._k("processing_vt"), job_id)
+            self._r.lpush(self._k("dlq"), job_id)
+            return
+        delay = backoff_seconds * max(1, attempts)
+        available_at_ts = now_ts + delay
+        mapping = {
+            "last_error": error or "",
+            "available_at": datetime.fromtimestamp(available_at_ts, tz=timezone.utc).isoformat(),
+        }
+        self._r.hset(key, mapping=mapping)
+        self._r.lrem(self._k("processing"), 1, job_id)
+        self._r.zrem(self._k("processing_vt"), job_id)
+        self._r.zadd(self._k("delayed"), {job_id: available_at_ts})

svc_infra/jobs/scheduler.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Awaitable, Callable, Dict
+
+CronFunc = Callable[[], Awaitable[None]]
+
+
+@dataclass
+class ScheduledTask:
+    name: str
+    interval_seconds: int
+    func: CronFunc
+    next_run_at: datetime
+
+
+class InMemoryScheduler:
+    """Interval-based scheduler for simple periodic tasks (tests/local).
+
+    Not a full cron parser. Tracks next_run_at per task.
+    """
+
+    def __init__(self):
+        self._tasks: Dict[str, ScheduledTask] = {}
+
+    def add_task(self, name: str, interval_seconds: int, func: CronFunc) -> None:
+        now = datetime.now(timezone.utc)
+        self._tasks[name] = ScheduledTask(
+            name=name,
+            interval_seconds=interval_seconds,
+            func=func,
+            next_run_at=now + timedelta(seconds=interval_seconds),
+        )
+
+    async def tick(self) -> None:
+        now = datetime.now(timezone.utc)
+        for task in self._tasks.values():
+            if task.next_run_at <= now:
+                await task.func()
+                task.next_run_at = now + timedelta(seconds=task.interval_seconds)

svc_infra/jobs/worker.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import Awaitable, Callable
+
+from .queue import Job, JobQueue
+
+ProcessFunc = Callable[[Job], Awaitable[None]]
+
+
+async def process_one(queue: JobQueue, handler: ProcessFunc) -> bool:
+    """Reserve a job, process with handler, ack on success or fail with backoff.
+
+    Returns True if a job was processed (success or fail), False if no job was available.
+    """
+    job = queue.reserve_next()
+    if not job:
+        return False
+    try:
+        await handler(job)
+    except Exception as exc:  # pragma: no cover - exercise in tests by raising
+        queue.fail(job.id, error=str(exc))
+        return True
+    queue.ack(job.id)
+    return True

svc_infra/webhooks/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

svc_infra/webhooks/fastapi.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import Callable, Sequence
+
+from fastapi import HTTPException, Request, status
+
+from .signing import verify, verify_any
+
+
+def require_signature(
+    secrets_provider: Callable[[], str | Sequence[str]],
+    *,
+    header_name: str = "X-Signature",
+):
+    async def _dep(request: Request):
+        sig = request.headers.get(header_name)
+        if not sig:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED, detail="missing signature"
+            )
+        try:
+            body = await request.json()
+        except Exception:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="invalid JSON body")
+        secrets = secrets_provider()
+        ok = False
+        if isinstance(secrets, str):
+            ok = verify(secrets, body, sig)
+        else:
+            ok = verify_any(secrets, body, sig)
+        if not ok:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED, detail="invalid signature"
+            )
+        return body
+
+    return _dep

svc_infra/webhooks/router.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from svc_infra.db.outbox import InMemoryOutboxStore, OutboxStore
+
+from .service import InMemoryWebhookSubscriptions, WebhookService
+
+router = APIRouter(prefix="/_webhooks", tags=["webhooks"])
+
+
+def get_outbox() -> OutboxStore:
+    # For now expose an in-memory default. Apps can override via DI.
+    # In production, provide a proper store through dependency override.
+    return InMemoryOutboxStore()
+
+
+def get_subs() -> InMemoryWebhookSubscriptions:
+    return InMemoryWebhookSubscriptions()
+
+
+def get_service(
+    outbox: OutboxStore = Depends(get_outbox),
+    subs: InMemoryWebhookSubscriptions = Depends(get_subs),
+) -> WebhookService:
+    return WebhookService(outbox=outbox, subs=subs)
+
+
+@router.post("/subscriptions")
+def add_subscription(
+    body: Dict[str, Any],
+    subs: InMemoryWebhookSubscriptions = Depends(get_subs),
+):
+    topic = body.get("topic")
+    url = body.get("url")
+    secret = body.get("secret")
+    if not topic or not url or not secret:
+        raise HTTPException(status_code=400, detail="Missing topic/url/secret")
+    subs.add(topic, url, secret)
+    return {"ok": True}
+
+
+@router.post("/test-fire")
+def test_fire(
+    body: Dict[str, Any],
+    svc: WebhookService = Depends(get_service),
+):
+    topic = body.get("topic")
+    payload = body.get("payload") or {}
+    if not topic:
+        raise HTTPException(status_code=400, detail="Missing topic")
+    outbox_id = svc.publish(topic, payload)
+    return {"ok": True, "outbox_id": outbox_id}

svc_infra/webhooks/service.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Dict, List
+
+from uuid import uuid4
+
+from svc_infra.db.outbox import OutboxStore
+
+
+@dataclass
+class WebhookSubscription:
+    topic: str
+    url: str
+    secret: str
+    id: str = field(default_factory=lambda: uuid4().hex)
+
+
+class InMemoryWebhookSubscriptions:
+    def __init__(self):
+        self._subs: Dict[str, List[WebhookSubscription]] = {}
+
+    def add(self, topic: str, url: str, secret: str) -> None:
+        self._subs.setdefault(topic, []).append(WebhookSubscription(topic, url, secret))
+
+    def get_for_topic(self, topic: str) -> List[WebhookSubscription]:
+        return list(self._subs.get(topic, []))
+
+
+class WebhookService:
+    def __init__(self, outbox: OutboxStore, subs: InMemoryWebhookSubscriptions):
+        self._outbox = outbox
+        self._subs = subs
+
+    def publish(self, topic: str, payload: Dict, *, version: int = 1) -> int:
+        created_at = datetime.now(timezone.utc).isoformat()
+        base_event = {
+            "topic": topic,
+            "payload": payload,
+            "version": version,
+            "created_at": created_at,
+        }
+        # For each subscription, enqueue an outbox message with subscriber identity
+        last_id = 0
+        for sub in self._subs.get_for_topic(topic):
+            event = dict(base_event)
+            msg_payload = {
+                "event": event,
+                "subscription": {
+                    "id": sub.id,
+                    "topic": sub.topic,
+                    "url": sub.url,
+                    "secret": sub.secret,
+                },
+            }
+            msg = self._outbox.enqueue(topic, msg_payload)
+            last_id = msg.id
+        return last_id

svc_infra/webhooks/signing.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from typing import Dict, Iterable
+
+
+def canonical_body(payload: Dict) -> bytes:
+    return json.dumps(payload, separators=(",", ":"), sort_keys=True).encode()
+
+
+def sign(secret: str, payload: Dict) -> str:
+    body = canonical_body(payload)
+    return hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
+
+
+def verify(secret: str, payload: Dict, signature: str) -> bool:
+    expected = sign(secret, payload)
+    try:
+        return hmac.compare_digest(expected, signature)
+    except Exception:
+        return False
+
+
+def verify_any(secrets: Iterable[str], payload: Dict, signature: str) -> bool:
+    for s in secrets:
+        if verify(s, payload, signature):
+            return True
+    return False

{svc_infra-0.1.596.dist-info → svc_infra-0.1.598.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: svc-infra
-Version: 0.1.596
+Version: 0.1.598
 Summary: Infrastructure for building and deploying prod-ready services
 License: MIT
 Keywords: fastapi,sqlalchemy,alembic,auth,infra,async,pydantic

{svc_infra-0.1.596.dist-info → svc_infra-0.1.598.dist-info}/RECORD

@@ -119,8 +119,9 @@ svc_infra/cache/resources.py,sha256=BhvPAZvCQ-fitUdniGEOOE4g1ZvljdCA_R5pR8WfJz4,
 svc_infra/cache/tags.py,sha256=9URw4BRlnb4QFAYpDI36fMms6642xq4TeV9jqsEjzE8,2625
 svc_infra/cache/ttl.py,sha256=_lWvNx1CTE4RcFEOUYkADd7_k4I13SLmtK0AMRUq2OM,1945
 svc_infra/cache/utils.py,sha256=-LWr5IiJCNm3pwaoeCVlxNknnO2ChNKFcAGlFU98kjg,4856
-svc_infra/cli/__init__.py,sha256=0pamzH-j-ePUgnqxfI6NiAiVn9NzptQbNbtNtK4O4oc,624
-svc_infra/cli/cmds/__init__.py,sha256=u-plcPPdmz1J4724M0sEdlt3wW7834QgzBLmKBy47hA,613
+svc_infra/cli/__init__.py,sha256=wsmFGr8wiKeoIW7pImcHt6piEV5KZQR2IDfgh3yHpyY,699
+svc_infra/cli/__main__.py,sha256=5BjNuyet8AY-POwoF5rGt722rHQ7tJ0Vf0UFUfzzi-I,58
+svc_infra/cli/cmds/__init__.py,sha256=HyUBE2pvhlTF5Uk03x_fqj4cbdX1Ri2CyHLUFBNK2UE,691
 svc_infra/cli/cmds/db/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 svc_infra/cli/cmds/db/nosql/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 svc_infra/cli/cmds/db/nosql/mongo/README.md,sha256=0u3XLeoBd0XQzXwwfEiFISMIij11TJ9iOGzrysBvsFk,1788
@@ -131,6 +132,8 @@ svc_infra/cli/cmds/db/sql/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJW
 svc_infra/cli/cmds/db/sql/alembic_cmds.py,sha256=KjumtKSOZR1UxbpZUuqllpknerDLNcY-0kqqqxiOnL4,7664
 svc_infra/cli/cmds/db/sql/sql_scaffold_cmds.py,sha256=eNTCqHXOxgl9H3WTbGVn9BHXYwCpjIEJsDqhEFdrYMM,4613
 svc_infra/cli/cmds/help.py,sha256=wGfZFMYaR2ZPwW2JwKDU7M3m4AtdCd8GRQ412AmEBUM,758
+svc_infra/cli/cmds/jobs/__init__.py,sha256=U4S_2y3zgLZVfMenHRaJFBW8yqh2mUBuI291LGQVOJ8,35
+svc_infra/cli/cmds/jobs/jobs_cmds.py,sha256=l-w5GuR82GWR_F1CA7WPYAM895XBD8TQj_hZ6retBv0,1252
 svc_infra/cli/cmds/obs/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 svc_infra/cli/cmds/obs/obs_cmds.py,sha256=fltUZu5fcnZdl0_JPJBIxIaA1Xqpw1BXE-SWBP-PRuY,6485
 svc_infra/cli/foundation/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -138,7 +141,7 @@ svc_infra/cli/foundation/runner.py,sha256=RbfjKwb3aHk1Y0MYU8xMpKRpIqRVMVr8GuL2ED
 svc_infra/cli/foundation/typer_bootstrap.py,sha256=KapgH1R-qON9FuYH1KYlVx_5sJvjmAGl25pB61XCpm4,985
 svc_infra/db/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 svc_infra/db/crud_schema.py,sha256=-fv-Om1lHVt6lcNbie6A2kRcPex4SDByUPfks6SpmUc,2521
-svc_infra/db/inbox.py,sha256=07GHRGN3jCjGVgcjjVGeKKgXkmwvgtwSu_O1Cb1_9hA,1600
+svc_infra/db/inbox.py,sha256=drxLRLHaMRrCDgo_8wj12do80wDh5ssHV6LGkaM98no,1996
 svc_infra/db/nosql/__init__.py,sha256=5ETPHk-KYUtc-efuGzDFQmWkT0xFtYy8YWOHobMZhvM,154
 svc_infra/db/nosql/base.py,sha256=p47VVpwWvGNkyWe5RDSmGaUFyZovcyNqirMqoHFQ4QU,230
 svc_infra/db/nosql/constants.py,sha256=Z9bJImxwb8D7vovASFegv8XMwaWcM28tsKJV2SjywXE,416
@@ -160,7 +163,7 @@ svc_infra/db/nosql/service.py,sha256=CtltFp1Bwm4wCQnFLDtH5-P5NmUEzkWSAf3htoiTBCQ
 svc_infra/db/nosql/service_with_hooks.py,sha256=rNH6renb-ppc8Y07jX5eSQnkkhJct2IZCq7mM9aBb48,747
 svc_infra/db/nosql/types.py,sha256=lcyuoZvBHRlGD24WL2HCEG5YmCpwo7qB4VYAckcY-WE,814
 svc_infra/db/nosql/utils.py,sha256=3u7X8WEPO1Cwy1SmZHmFMMbDfu1HhapJUAFbSMe3J9g,3524
-svc_infra/db/outbox.py,sha256=9oUcob8FjPP_sx56uwca-pb3_fSMBL1hAd68hIc8TFc,3022
+svc_infra/db/outbox.py,sha256=1ZIXaYMgQ2wLZX40iR8MKrRL5QNgoMP_jjSr-gSLAjY,3363
 svc_infra/db/sql/README.md,sha256=OI1T7SiY4_f0eTWQGtIeUsgkFqzvloh1vctOm6nvIvU,8581
 svc_infra/db/sql/__init__.py,sha256=PkDutfhzofY0jbE83ZuxbrvXhogvP1tmk5MniyfwQws,159
 svc_infra/db/sql/apikey.py,sha256=27-4GAieD8NxoVKHw_WF2cj8A4UXbcnvtUUTztbo_yw,5019
@@ -191,6 +194,14 @@ svc_infra/db/sql/uniq_hooks.py,sha256=6gCnO0_Y-rhB0p-VuY0mZ9m1u3haiLWI3Ns_iUTqF_
 svc_infra/db/sql/utils.py,sha256=nzuDcDhnVNehx5Y9BZLgxw8fvpfYbxTfXQsgnznVf4w,32862
 svc_infra/db/sql/versioning.py,sha256=okZu2ad5RAFXNLXJgGpcQvZ5bc6gPjRWzwiBT0rEJJw,400
 svc_infra/db/utils.py,sha256=aTD49VJSEu319kIWJ1uijUoP51co4lNJ3S0_tvuyGio,802
+svc_infra/jobs/builtins/outbox_processor.py,sha256=VZoehNyjdaV_MmV74WMcbZR6z9E3VFMtZC-pxEwK0x0,1247
+svc_infra/jobs/builtins/webhook_delivery.py,sha256=z_cl6YKwnduGjGaB8ZoUpKhFcEAhUZqqBma8v2FO1so,2982
+svc_infra/jobs/easy.py,sha256=eix-OxWeE3vdkY3GGNoYM0GAyOxc928SpiSzMkr9k0A,977
+svc_infra/jobs/loader.py,sha256=LFO6gOacj6rT698vkDg0YfcHDRTue4zus3Nl9QrS5R0,1164
+svc_infra/jobs/queue.py,sha256=PS5f4CJm5_K7icojTxZOwC6uKw3O2M-jE111u85ySbA,2288
+svc_infra/jobs/redis_queue.py,sha256=wgmWKslF1dkYscJe49UgUX7gwEuGyOUWEb0-pn82I3g,7543
+svc_infra/jobs/scheduler.py,sha256=dTUEEyEuTVHNmJT8wPdMu4YjnTN7R_YW67gtCKpqC7M,1180
+svc_infra/jobs/worker.py,sha256=T2A575_mnieJHPOYU_FseubLA_HQf9pB4CkRgzRJBHU,694
 svc_infra/mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 svc_infra/mcp/svc_infra_mcp.py,sha256=NmBY7AM3_pnHAumE-eM5Njr8kpb7Gh1-fjcZAEammiI,1927
 svc_infra/obs/README.md,sha256=wOABJUOhuj0ftGt24ZfuChlFNJTYvYq4KM_rcRIdWRU,7884
@@ -252,7 +263,12 @@ svc_infra/security/permissions.py,sha256=fQm7-OcJJkWsScDcjS2gwmqaW93zQqltaHRl6bv
 svc_infra/security/session.py,sha256=JkClqoZ-Moo9yqHzCREXMVSpzyjbn2Zh6zCjtWO93Ik,2848
 svc_infra/security/signed_cookies.py,sha256=2t61BgjsBaTzU46bt7IUJo7lwDRE9_eS4vmAQXJ8mlY,2219
 svc_infra/utils.py,sha256=VX1yjTx61-YvAymyRhGy18DhybiVdPddiYD_FlKTbJU,952
-svc_infra-0.1.596.dist-info/METADATA,sha256=CTG82284mj-bs4cIoYxw9fXMRAL8fX9_Wr2txqfC7tY,3527
-svc_infra-0.1.596.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
-svc_infra-0.1.596.dist-info/entry_points.txt,sha256=6x_nZOsjvn6hRZsMgZLgTasaCSKCgAjsGhACe_CiP0U,48
-svc_infra-0.1.596.dist-info/RECORD,,
+svc_infra/webhooks/__init__.py,sha256=U4S_2y3zgLZVfMenHRaJFBW8yqh2mUBuI291LGQVOJ8,35
+svc_infra/webhooks/fastapi.py,sha256=BCNvGNxukf6dC2a4i-6en-PrjBGV19YvCWOot5lXWsA,1101
+svc_infra/webhooks/router.py,sha256=6JvAVPMEth_xxHX-IsIOcyMgHX7g1H0OVxVXKLuMp9w,1596
+svc_infra/webhooks/service.py,sha256=hWgiJRXKBwKunJOx91C7EcLUkotDtD3Xp0RT6vj2IC0,1797
+svc_infra/webhooks/signing.py,sha256=NCwdZzmravUe7HVIK_uXK0qqf12FG-_MVsgPvOw6lsM,784
+svc_infra-0.1.598.dist-info/METADATA,sha256=OwFbEqh9yMLpWr5rcN3Bp0M_ywJypISbUxabiMuQZY8,3527
+svc_infra-0.1.598.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
+svc_infra-0.1.598.dist-info/entry_points.txt,sha256=6x_nZOsjvn6hRZsMgZLgTasaCSKCgAjsGhACe_CiP0U,48
+svc_infra-0.1.598.dist-info/RECORD,,