svc-infra 0.1.629__py3-none-any.whl → 0.1.631__py3-none-any.whl

svc_infra/docs/billing.md

@@ -0,0 +1,190 @@
+# Billing Primitives
+
+This module provides internal-first billing building blocks for services that need usage-based and subscription billing without coupling to a specific provider. It complements APF Payments (provider-facing) with portable primitives you can use regardless of Stripe/Aiydan/etc.
+
+## What you get
+
+- Usage ingestion with idempotency (UsageEvent)
+- Windowed usage aggregation (UsageAggregate) — daily baseline
+- Plan and entitlements registry (Plan, PlanEntitlement)
+- Tenant subscriptions (Subscription)
+- Price catalog for fixed/usage items (Price)
+- Invoice and line items (Invoice, InvoiceLine)
+- A small `BillingService` to record usage, aggregate, and generate monthly invoices
+- Optional provider sync hook to mirror internal invoices/lines to your payment provider
+
+## Data model (SQL)
+
+Tables (v1):
+- usage_events(id, tenant_id, metric, amount, at_ts, idempotency_key, metadata_json, created_at)
+  - Unique (tenant_id, metric, idempotency_key)
+- usage_aggregates(id, tenant_id, metric, period_start, granularity, total, updated_at)
+  - Unique (tenant_id, metric, period_start, granularity)
+- plans(id, key, name, description, created_at)
+- plan_entitlements(id, plan_id, key, limit_per_window, window, created_at)
+- subscriptions(id, tenant_id, plan_id, effective_at, ended_at, created_at)
+- prices(id, key, currency, unit_amount, metric, recurring_interval, created_at)
+- invoices(id, tenant_id, period_start, period_end, status, total_amount, currency, provider_invoice_id, created_at)
+- invoice_lines(id, invoice_id, price_id, metric, quantity, amount, created_at)
+
+See `src/svc_infra/billing/models.py` for full definitions.
+
+## Quick start (Python)
+
+```python
+from datetime import datetime, timezone
+from sqlalchemy.orm import Session
+from svc_infra.billing import BillingService
+
+# session: SQLAlchemy Session (sync) targeting your DB
+bs = BillingService(session=session, tenant_id="t_123")
+
+# 1) Record usage (idempotent by (tenant, metric, idempotency_key))
+evt_id = bs.record_usage(
+    metric="tokens", amount=42,
+    at=datetime.now(tz=timezone.utc),
+    idempotency_key="req-42",
+    metadata={"model": "gpt"},
+)
+
+# 2) Aggregate for a day (baseline v1 granularity)
+bs.aggregate_daily(metric="tokens", day_start=datetime(2025,1,1,tzinfo=timezone.utc))
+
+# 3) Generate a monthly invoice (fixed+usage lines TBD)
+inv_id = bs.generate_monthly_invoice(
+    period_start=datetime(2025,1,1,tzinfo=timezone.utc),
+    period_end=datetime(2025,2,1,tzinfo=timezone.utc),
+    currency="usd",
+)
+```
+
+Optional: pass a provider sync hook if you want to mirror invoices/lines to Stripe/Aiydan:
+
+```python
+from typing import Callable
+from svc_infra.billing.models import Invoice, InvoiceLine
+
+async def sync_to_provider(inv: Invoice, lines: list[InvoiceLine]):
+    # Map internal invoice/lines to provider calls here
+    ...
+
+bs = BillingService(session=session, tenant_id="t_123", provider_sync=sync_to_provider)
+```
+
+### FastAPI router (usage ingestion & aggregates)
+
+Mount the router and start recording usage with idempotency:
+
+```python
+from fastapi import FastAPI
+from svc_infra.api.fastapi.billing.setup import add_billing
+from svc_infra.api.fastapi.middleware.idempotency import IdempotencyMiddleware
+from svc_infra.api.fastapi.middleware.errors.handlers import register_error_handlers
+
+app = FastAPI()
+app.add_middleware(IdempotencyMiddleware, store={})
+register_error_handlers(app)
+add_billing(app)  # mounts under /_billing
+
+# POST /_billing/usage  {metric, amount, at?, idempotency_key, metadata?} -> 202 {id}
+# GET  /_billing/usage?metric=tokens -> {items: [{period_start, granularity, metric, total}], next_cursor}
+```
+
+### Quotas (soft/hard limits)
+
+Protect your feature endpoints with a quota dependency based on internal plan entitlements and daily aggregates:
+
+```python
+from fastapi import Depends
+from svc_infra.billing.quotas import require_quota
+
+@app.get("/generate-report", dependencies=[Depends(require_quota("reports", window="day", soft=False))])
+async def generate_report():
+  return {"ok": True}
+```
+
+## Relationship to APF Payments
+
+- APF Payments is provider-facing: customers, intents, methods, products/prices, subscriptions, invoices, usage records via Stripe/Aiydan adapters and HTTP routers.
+- Billing Primitives is provider-agnostic: an internal ledger of usage, plans/entitlements, and invoices that you can keep even if you change providers.
+- You can use both: continue to use APF Payments for card/payments flows, and use Billing to meter custom features and create internal invoices; selectively sync them out later.
+
+## Jobs and webhooks
+
+Billing includes helpers to enqueue and process jobs and emit webhooks:
+
+- Job names:
+  - `billing.aggregate_daily` payload: `{tenant_id, metric, day_start: ISO8601}`
+  - `billing.generate_monthly_invoice` payload: `{tenant_id, period_start: ISO8601, period_end: ISO8601, currency}`
+- Emitted webhook topics:
+  - `billing.usage_aggregated` payload: `{tenant_id, metric, day_start, total}`
+  - `billing.invoice.created` payload: `{tenant_id, invoice_id, period_start, period_end, currency}`
+
+Usage with the built-in queue/scheduler and webhooks outbox:
+
+```python
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from svc_infra.jobs.easy import easy_jobs
+from svc_infra.webhooks.add import add_webhooks
+from svc_infra.webhooks.service import WebhookService
+from svc_infra.db.outbox import InMemoryOutboxStore
+from svc_infra.webhooks.service import InMemoryWebhookSubscriptions
+from svc_infra.billing.jobs import (
+    enqueue_aggregate_daily,
+    enqueue_generate_monthly_invoice,
+    make_billing_job_handler,
+)
+
+# Create queue + scheduler
+queue, scheduler = easy_jobs()
+
+# Setup DB async session factory
+engine = create_async_engine("sqlite+aiosqlite:///:memory:")
+SessionLocal = async_sessionmaker(engine, expire_on_commit=False)
+
+# Setup webhooks (in-memory stores shown here)
+outbox = InMemoryOutboxStore()
+subs = InMemoryWebhookSubscriptions()
+subs.add("billing.usage_aggregated", url="https://example.test/hook", secret="sekrit")
+webhooks = WebhookService(outbox=outbox, subs=subs)
+
+# Worker handler
+handler = make_billing_job_handler(session_factory=SessionLocal, webhooks=webhooks)
+
+# Enqueue example jobs
+from datetime import datetime, timezone
+enqueue_aggregate_daily(queue, tenant_id="t1", metric="tokens", day_start=datetime.now(timezone.utc))
+enqueue_generate_monthly_invoice(
+    queue, tenant_id="t1", period_start=datetime(2025,1,1,tzinfo=timezone.utc), period_end=datetime(2025,2,1,tzinfo=timezone.utc), currency="usd"
+)
+
+# In your worker loop call process_one(queue, handler)
+```
+
+## Roadmap (v1 scope)
+
+- Router: `/_billing` endpoints for usage ingestion (idempotent), aggregate listing, plans/subscriptions read.
+- Quotas: decorator/dependency to enforce per-plan limits (soft/hard, day/month windows).
+- Jobs: integrate aggregation and invoice-generation with the scheduler; emit `billing.*` webhooks. (helpers available in `svc_infra.billing.jobs`) — Implemented.
+- Provider sync: optional mapper to Stripe invoices/payment intents; reuse idempotency.
+- Migrations: author initial Alembic migration for billing tables.
+- Docs: examples for quotas and jobs; admin flows for plans and prices.
+
+## Testing
+
+- See `tests/unit/billing/test_billing_service.py` for usage, aggregation, invoice basics, and idempotency uniqueness.
+- Additions planned: router tests (ingest/list), quotas, job executions, webhook events.
+
+## Security & Tenancy
+
+- All records are tenant-scoped; ensure tenant_id is enforced in your service layer / router dependencies.
+- Protect HTTP endpoints with RBAC permissions (e.g., billing.read, billing.write) if you expose them.
+
+## Observability
+
+Planned metrics (names may evolve):
+- billing_usage_ingest_total
+- billing_aggregate_duration_ms
+- billing_invoice_generated_total
+
+See ADR 0008 for design details.

svc_infra/docs/cache.md

@@ -16,3 +16,61 @@ async def get_user(user_id: int):
 
 - `CACHE_PREFIX`, `CACHE_VERSION` – change the namespace alias used by the decorators. 【F:src/svc_infra/cache/README.md†L20-L173】
 - `CACHE_TTL_DEFAULT`, `CACHE_TTL_SHORT`, `CACHE_TTL_LONG` – override canonical TTL buckets. 【F:src/svc_infra/cache/ttl.py†L26-L55】
+
+## Easy integration: add_cache
+
+Use the one-liner helper to wire cache initialization into your ASGI app lifecycle with sensible defaults. This doesn’t replace the decorators; it standardizes init/readiness/shutdown and exposes a handle for convenience.
+
+```python
+from fastapi import FastAPI
+from svc_infra.cache import add_cache, cache_read, cache_write, resource
+
+app = FastAPI()
+
+# Wires startup (init + readiness) and shutdown (graceful close). Idempotent.
+add_cache(app)
+
+user = resource("user", "user_id")
+
+@user.cache_read(suffix="profile", ttl=300)
+async def get_user_profile(user_id: int):
+    ...
+
+@user.cache_write()
+async def update_user_profile(user_id: int, payload):
+    ...
+
+# Optional: direct cache instance for advanced scenarios
+# available after startup when using add_cache(app)
+# app.state.cache -> cashews cache instance
+```
+
+### Env-driven defaults
+
+- URL: `CACHE_URL` → `REDIS_URL` → `mem://`
+- Prefix: `CACHE_PREFIX` (default `svc`)
+- Version: `CACHE_VERSION` (default `v1`)
+
+You can override explicitly:
+
+```python
+add_cache(app, url="redis://localhost:6379/0", prefix="myapp", version="v2")
+```
+
+### Behavior
+
+- Idempotent: multiple calls won’t duplicate handlers.
+- Startup/shutdown hooks: registered when supported by the app; startup performs a readiness probe. Startup is optional for correctness, but recommended for production reliability.
+- app.state exposure: by default, exposes `app.state.cache` to access the underlying cashews instance.
+
+### No-app usage
+
+If you’re not wiring an app (e.g., a script), you can initialize without startup hooks:
+
+```python
+from svc_infra.cache import add_cache
+
+shutdown = add_cache(None)  # immediate init (best-effort)
+# ... do work ...
+# call shutdown() is a no-op placeholder for symmetry
+```

svc_infra/docs/ops.md

@@ -31,3 +31,7 @@ This guide explains how to use svc-infra’s probes, circuit breaker, and metric
 
 - Prometheus middleware is enabled unless `SVC_INFRA_DISABLE_PROMETHEUS=1`.
 - Observability settings: `METRICS_ENABLED`, `METRICS_PATH`, and optional histogram buckets.
+
+## See also
+
+- Timeouts & Resource Limits: `./timeouts-and-resource-limits.md` — request/body/handler timeouts, outbound client timeouts, DB statement timeouts, jobs/webhooks, and graceful shutdown.

svc_infra/docs/rate-limiting.md

@@ -115,6 +115,10 @@ metrics.on_suspect_payload = lambda path, size: logger.warning(
 - Consider separate limits for read vs write routes.
 - Combine with request size limits and auth lockout for layered defense.
 
+## Related
+
+- Timeouts & Resource Limits: `./timeouts-and-resource-limits.md` — complements rate limits by bounding slow uploads, long handlers, and downstream timeouts.
+
 ## Testing
 
 - Use `-m ratelimit` to select rate-limiting tests.

svc_infra/docs/timeouts-and-resource-limits.md

@@ -0,0 +1,147 @@
+# Timeouts & Resource Limits
+
+This guide covers request/handler timeouts, outbound HTTP client timeouts, database statement timeouts, job/webhook delivery timeouts, and graceful shutdown. It explains defaults, configuration, wiring, and recommended tuning by environment.
+
+## Why timeouts?
+
+- Protects your service from slowloris uploads and hanging requests
+- Limits blast radius of slow downstreams (HTTP, DB, webhooks)
+- Enables predictable backpressure and faster recovery during incidents
+
+## Configuration overview
+
+The library exposes simple environment variables with sensible defaults. Use floats for second values unless noted.
+
+- REQUEST_BODY_TIMEOUT_SECONDS (int)
+  - Default: prod=15, nonprod=30
+  - Purpose: Abort slow request body reads (slowloris defense)
+- REQUEST_TIMEOUT_SECONDS (int)
+  - Default: prod=30, nonprod=15
+  - Purpose: Cap overall handler execution time
+- HTTP_CLIENT_TIMEOUT_SECONDS (float)
+  - Default: 10.0
+  - Purpose: Default timeout for outbound httpx clients created via helpers
+- DB_STATEMENT_TIMEOUT_MS (int)
+  - Default: unset (disabled)
+  - Purpose: Per-transaction statement timeout (Postgres via SET LOCAL)
+- JOB_DEFAULT_TIMEOUT_SECONDS (float)
+  - Default: unset (disabled)
+  - Purpose: Caps per-job handler runtime in the in-process jobs runner
+- WEBHOOK_DELIVERY_TIMEOUT_SECONDS (float)
+  - Default: falls back to HTTP client default (10.0)
+  - Purpose: Timeout for webhook delivery HTTP calls
+- SHUTDOWN_GRACE_PERIOD_SECONDS (float)
+  - Default: prod=20.0, nonprod=5.0
+  - Purpose: Wait time for in-flight requests to drain on shutdown
+
+See ADR-0010 for design rationale: `src/svc_infra/docs/adr/0010-timeouts-and-resource-limits.md`.
+
+## Request/handler timeouts (FastAPI)
+
+Two middlewares enforce timeouts inside your ASGI app:
+
+- BodyReadTimeoutMiddleware
+  - Enforces a per-chunk timeout while reading the incoming request body.
+  - If reads stall beyond the timeout, responds with 408 application/problem+json.
+  - Module: `svc_infra.api.fastapi.middleware.timeout.BodyReadTimeoutMiddleware`
+- HandlerTimeoutMiddleware
+  - Caps overall request handler execution time using asyncio.wait_for.
+  - If exceeded, responds with 504 application/problem+json.
+  - Module: `svc_infra.api.fastapi.middleware.timeout.HandlerTimeoutMiddleware`
+
+Example wiring:
+
+```python
+from fastapi import FastAPI
+from svc_infra.api.fastapi.middleware.timeout import (
+    BodyReadTimeoutMiddleware,
+    HandlerTimeoutMiddleware,
+)
+
+app = FastAPI()
+
+# Abort slow uploads (slowloris) after 15s in prod / 30s nonprod by default
+app.add_middleware(BodyReadTimeoutMiddleware)  # or timeout_seconds=20
+
+# Cap total handler time (e.g., 30s in prod by default)
+app.add_middleware(HandlerTimeoutMiddleware)  # or timeout_seconds=25
+```
+
+HTTP semantics:
+
+- Body timeout → 408 Request Timeout (Problem+JSON) with fields: type, title, status, detail, instance, trace_id
+- Handler timeout → 504 Gateway Timeout (Problem+JSON) with fields: type, title, status, detail, instance, trace_id
+
+## Outbound HTTP client timeouts (httpx)
+
+Use the provided helpers to create httpx clients with the default timeout (driven by HTTP_CLIENT_TIMEOUT_SECONDS).
+
+- Module: `svc_infra.http.client`
+  - `get_default_timeout_seconds()` → float
+  - `make_timeout(seconds=None) -> httpx.Timeout`
+  - `new_httpx_client(timeout_seconds=None, ...) -> httpx.Client`
+  - `new_async_httpx_client(timeout_seconds=None, ...) -> httpx.AsyncClient`
+
+Error mapping:
+
+- `httpx.TimeoutException` is mapped to 504 Gateway Timeout with Problem+JSON by default when `register_error_handlers(app)` is used.
+  - Module: `svc_infra.api.fastapi.middleware.errors.handlers.register_error_handlers`
+
+## Database statement timeouts (SQLAlchemy / Postgres)
+
+If `DB_STATEMENT_TIMEOUT_MS` is set and Postgres is used, a per-transaction `SET LOCAL statement_timeout = :ms` is executed for sessions yielded by the built-in dependency.
+
+- Module: `svc_infra.api.fastapi.db.sql.session.get_session`
+- Non-Postgres dialects (e.g., SQLite) ignore this gracefully.
+
+## Jobs and webhooks
+
+- Jobs runner
+  - Env: `JOB_DEFAULT_TIMEOUT_SECONDS`
+  - Module: `svc_infra.jobs.worker.process_one` — wraps job handler with `asyncio.wait_for()` when configured.
+- Webhook delivery
+  - Env: `WEBHOOK_DELIVERY_TIMEOUT_SECONDS` (falls back to HTTP client default when unset)
+  - Module: `svc_infra.jobs.builtins.webhook_delivery.make_webhook_handler` — uses `new_async_httpx_client` with derived timeout.
+
+## Graceful shutdown
+
+Install graceful shutdown to wait for in-flight requests (up to a grace period) during application shutdown.
+
+- Module: `svc_infra.api.fastapi.middleware.graceful_shutdown.install_graceful_shutdown`
+- Env: `SHUTDOWN_GRACE_PERIOD_SECONDS` (prod=20.0, nonprod=5.0 by default)
+
+```python
+from svc_infra.api.fastapi.middleware.graceful_shutdown import install_graceful_shutdown
+
+install_graceful_shutdown(app)  # or grace_seconds=30.0
+```
+
+## Tuning recommendations
+
+- Production
+  - REQUEST_BODY_TIMEOUT_SECONDS: 10–20s (shorter for public APIs)
+  - REQUEST_TIMEOUT_SECONDS: 20–30s (align with upstream proxy/gateway timeouts)
+  - HTTP_CLIENT_TIMEOUT_SECONDS: 3–10s (favor quick failover with retries)
+  - DB_STATEMENT_TIMEOUT_MS: set per-route/transaction if queries are constrained
+  - SHUTDOWN_GRACE_PERIOD_SECONDS: 20–60s depending on peak latencies
+- Staging/Dev
+  - Relax timeouts slightly to reduce test flakiness (defaults already reflect this)
+- Gateways/Proxies
+  - Ensure upstream (e.g., NGINX, ALB) timeouts exceed app’s body timeout and are aligned with handler timeout to avoid double timeouts.
+
+## Testing and acceptance
+
+- Unit tests cover body read timeout, handler timeout, outbound timeout mapping, and a smoke check for DB statement timeout.
+- Acceptance tests:
+  - A2-04: slow handler → 504 Problem
+  - A2-05: slow body → 408 Problem or 413 (size) as applicable
+  - A2-06: outbound httpx timeout → 504 Problem
+
+## Troubleshooting
+
+- Seeing 200 instead of 408 for slow uploads under some servers?
+  - Some servers buffer the entire body before invoking the app. The BodyReadTimeoutMiddleware greedily drains with per-chunk timeouts and replays to reliably detect slowloris. Ensure HTTP/1.1 parsing with a streaming-capable server implementation (e.g., uvicorn+httptools) in acceptance tests.
+- Outbound timeouts not mapped to Problem?
+  - Ensure `register_error_handlers(app)` is installed so `httpx.TimeoutException` returns a 504 Problem.
+- Statement timeout ignored on SQLite?
+  - Expected. Non-Postgres dialects skip `SET LOCAL` safely.

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,64 @@
+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)
+    return httpx.Client(timeout=timeout, headers=headers, base_url=base_url, **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)
+    return httpx.AsyncClient(timeout=timeout, headers=headers, base_url=base_url, **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/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

svc_infra/security/hibp.py

@@ -5,7 +5,7 @@ import time
 from dataclasses import dataclass
 from typing import Dict, Optional
 
-import httpx
+from svc_infra.http import new_httpx_client
 
 
 def sha1_hex(data: str) -> str:
@@ -39,7 +39,11 @@ class HIBPClient:
         self.timeout = timeout
         self.user_agent = user_agent
         self._cache: Dict[str, CacheEntry] = {}
-        self._http = httpx.Client(timeout=self.timeout, headers={"User-Agent": self.user_agent})
+        # Use central factory for consistent defaults; retain explicit timeout override
+        self._http = new_httpx_client(
+            timeout_seconds=self.timeout,
+            headers={"User-Agent": self.user_agent},
+        )
 
     def _get_cached(self, prefix: str) -> Optional[str]:
         now = time.time()

{svc_infra-0.1.629.dist-info → svc_infra-0.1.631.dist-info}/METADATA

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