keble-scraper-api 0.2.0__py3-none-any.whl

keble_scraper_api/infrastructure/callbacks.py

@@ -0,0 +1,285 @@
+"""HMAC-signed registered callback delivery and durable outbox processing."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+from datetime import timedelta
+from enum import StrEnum
+from uuid import UUID
+
+import httpx
+from keble_data_infra_contract import parse_retry_after
+from pydantic import SecretStr
+
+from keble_scraper_contract import (
+    ScrapeCallbackIdentity,
+    ScrapeCompletionEvent,
+    ScrapeWebhookHeaders,
+    utc_now,
+)
+
+from keble_scraper_api.errors import ScraperDomainError, ScraperErrorCode
+from keble_scraper_api.application.scheduling import ceil_persistence_millisecond
+from keble_scraper_api.models import (
+    CallbackTransportDisposition,
+    CallbackTransportResult,
+)
+from keble_scraper_api.protocols import (
+    CompletionCallbackProtocol,
+    OutboxRepositoryProtocol,
+)
+from keble_scraper_api.settings import ScraperSettings
+
+
+class CallbackDeliveryOutcome(StrEnum):
+    """One outbox lease result without conflating retry with queue exhaustion.
+
+    Side effects if changes:
+    - callback batch continuation and Sentry delivery counters.
+    """
+
+    EMPTY = "EMPTY"
+    DELIVERED = "DELIVERED"
+    RESCHEDULED = "RESCHEDULED"
+
+
+class WebhookSigner:
+    """Sign timestamp, event identity, and exact body digest with HMAC-SHA256.
+
+    Steps:
+    1. hash the exact serialized callback body;
+    2. bind timestamp, event identity, and digest into one message;
+    3. authenticate that message with the independent callback key.
+
+    Side effects if changes:
+    - Shopify callback verification and current/next key rotation.
+    """
+
+    def __init__(self, *, key: SecretStr) -> None:
+        """Bind one current signing key independent from service API keys.
+
+        Side effects if changes:
+        - all newly delivered callback signatures.
+        """
+
+        self._key = key
+
+    def sign(
+        self, *, event_id: UUID, body: bytes, timestamp: int
+    ) -> ScrapeWebhookHeaders:
+        """Build stable signature headers over the exact serialized body.
+
+        Steps:
+        1. compute the exact body SHA-256 digest;
+        2. assemble the replay-bound canonical message;
+        3. return versioned HMAC headers without exposing key material.
+
+        Side effects if changes:
+        - webhook acceptance and replay identity.
+        """
+
+        digest = hashlib.sha256(body).hexdigest()
+        message = f"{timestamp}.{event_id}.{digest}".encode()
+        signature = hmac.new(
+            self._key.get_secret_value().encode(),
+            message,
+            hashlib.sha256,
+        ).hexdigest()
+        return ScrapeWebhookHeaders(
+            event_id=event_id,
+            timestamp=timestamp,
+            signature=f"v1={signature}",
+        )
+
+
+class RegisteredHttpCompletionCallback:
+    """Deliver callbacks only to deployment-registered audience URLs.
+
+    Steps:
+    1. map finite audiences to deployment-owned destinations;
+    2. sign exact event bytes and reuse one pooled HTTP client;
+    3. return typed HTTP dispositions without exception laundering.
+
+    Side effects if changes:
+    - outbound Shopify webhook calls; caller URLs remain impossible.
+    """
+
+    def __init__(self, *, settings: ScraperSettings, signer: WebhookSigner) -> None:
+        """Bind callback registry and independent HMAC signer.
+
+        Steps:
+        1. retain immutable destination and timeout settings;
+        2. retain the independent webhook signer;
+        3. create one process-owned pooled HTTP client.
+
+        Side effects if changes:
+        - callback destinations and credentials.
+        """
+
+        self._settings = settings
+        self._signer = signer
+        self._client = httpx.AsyncClient(
+            timeout=self._settings.read_timeout_seconds,
+            trust_env=False,
+        )
+
+    async def close(self) -> None:
+        """Close the process-owned registered-callback connection pool.
+
+        Steps:
+        1. drain and close pooled keep-alive connections;
+        2. leave signing keys and destination settings untouched;
+        3. remain safe after a process made no callback request.
+
+        Side effects if changes:
+        - API/worker shutdown and callback socket cleanup.
+        """
+
+        await self._client.aclose()
+
+    async def deliver(self, *, event: ScrapeCompletionEvent) -> CallbackTransportResult:
+        """POST one exact signed event and classify its HTTP response.
+
+        Steps:
+        1. select only the deployment-registered audience destination;
+        2. sign and send the exact event through the pooled client;
+        3. return finite success/retry/permanent HTTP evidence while allowing
+           client and implementation exceptions to reach supervision.
+
+        Side effects if changes:
+        - external webhook call and downstream refresh-run transition.
+        """
+
+        destinations = {
+            ScrapeCallbackIdentity.SHOPIFY_INDEX: self._settings.shopify_callback_url,
+        }
+        destination = destinations[event.audience]
+        if destination is None:
+            raise ScraperDomainError(
+                code=ScraperErrorCode.CONFIGURATION_INVALID,
+                message="callback audience is not configured",
+            )
+        body = event.model_dump_json(by_alias=True).encode()
+        timestamp = int(utc_now().timestamp())
+        signed = self._signer.sign(
+            event_id=event.event_id,
+            body=body,
+            timestamp=timestamp,
+        )
+        response = await self._client.post(
+            str(destination),
+            content=body,
+            headers={
+                "Content-Type": "application/json",
+                "X-Keble-Event-ID": str(signed.event_id),
+                "X-Keble-Timestamp": str(signed.timestamp),
+                "X-Keble-Signature": signed.signature,
+            },
+        )
+        observed_at = utc_now()
+        retry_at = parse_retry_after(
+            value=response.headers.get("Retry-After"),
+            observed_at=observed_at,
+        )
+        if response.is_success:
+            disposition = CallbackTransportDisposition.DELIVERED
+        elif (
+            response.status_code in {408, 409, 425, 429} or response.status_code >= 500
+        ):
+            disposition = CallbackTransportDisposition.RETRYABLE
+        else:
+            disposition = CallbackTransportDisposition.PERMANENT
+        return CallbackTransportResult(
+            disposition=disposition,
+            status_code=response.status_code,
+            retry_at=(
+                retry_at
+                if disposition is CallbackTransportDisposition.RETRYABLE
+                else None
+            ),
+        )
+
+
+class CallbackOutboxService:
+    """Lease/deliver/reschedule signed callbacks from the durable outbox.
+
+    Steps:
+    1. lease one due event under worker ownership;
+    2. deliver through the typed registered transport;
+    3. acknowledge, reschedule, or dead-letter under immutable row limits.
+
+    Side effects if changes:
+    - webhook retries, dead letters, and at-least-once delivery timing.
+    """
+
+    def __init__(
+        self,
+        *,
+        repository: OutboxRepositoryProtocol,
+        callback: CompletionCallbackProtocol,
+        lease_seconds: int,
+        retry_base_seconds: int,
+    ) -> None:
+        """Bind outbox persistence, transport, lease, and retry cadence.
+
+        Steps:
+        1. retain the callback repository and registered transport;
+        2. retain the lease duration for physical delivery ownership;
+        3. retain only retry cadence because each row owns its immutable limit.
+
+        Side effects if changes:
+        - callback worker concurrency and terminal delivery behavior.
+        """
+
+        self._repository = repository
+        self._callback = callback
+        self._lease_seconds = lease_seconds
+        self._retry_base_seconds = retry_base_seconds
+
+    async def deliver_one(self, *, worker_id: str) -> CallbackDeliveryOutcome:
+        """Deliver at most one due event and persist its next state.
+
+        Steps:
+        1. lease one due row with an immutable attempt budget;
+        2. acknowledge typed HTTP success or compute bounded receiver backoff;
+        3. dead-letter permanent HTTP rejection or an exhausted retry budget;
+        4. allow transport/runtime exceptions to leave the lease recoverable.
+
+        Side effects if changes:
+        - one external callback call and one outbox transition.
+        """
+
+        row = await self._repository.lease_callback_due(
+            worker_id=worker_id,
+            now=utc_now(),
+            lease_seconds=self._lease_seconds,
+        )
+        if row is None:
+            return CallbackDeliveryOutcome.EMPTY
+        delivered = await self._callback.deliver(event=row.event)
+        if delivered.disposition is CallbackTransportDisposition.DELIVERED:
+            await self._repository.mark_delivered(
+                event_id=row.event.event_id,
+                worker_id=worker_id,
+                delivered_at=utc_now(),
+            )
+            return CallbackDeliveryOutcome.DELIVERED
+        dead_letter = (
+            delivered.disposition is CallbackTransportDisposition.PERMANENT
+            or row.attempt_count >= row.attempt_limit
+        )
+        delay = self._retry_base_seconds * (2 ** max(0, row.attempt_count - 1))
+        local_next_attempt_at = utc_now() + timedelta(seconds=delay)
+        await self._repository.reschedule(
+            event_id=row.event.event_id,
+            worker_id=worker_id,
+            next_attempt_at=ceil_persistence_millisecond(
+                value=max(
+                    local_next_attempt_at,
+                    delivered.retry_at or local_next_attempt_at,
+                )
+            ),
+            dead_letter=dead_letter,
+        )
+        return CallbackDeliveryOutcome.RESCHEDULED

keble_scraper_api/infrastructure/celery_factory.py

@@ -0,0 +1,63 @@
+"""Settings-owned Celery queue and beat composition."""
+
+from celery import Celery
+
+from keble_scraper_api.settings import ScraperSettings
+
+
+def build_celery(*, settings: ScraperSettings) -> Celery:
+    """Build one RabbitMQ-only Celery app with isolated queues and schedules.
+
+    Side effects if changes:
+    - task acknowledgement, queue routing, retry recovery, and beat cadence.
+    """
+
+    app = Celery(
+        "keble-scraper",
+        broker=settings.rabbitmq_uri.get_secret_value(),
+        include=["keble_scraper_api.workers.tasks"],
+    )
+    app.conf.update(
+        task_serializer="json",
+        accept_content=["json"],
+        result_backend=None,
+        task_ignore_result=True,
+        task_acks_late=True,
+        task_reject_on_worker_lost=True,
+        worker_prefetch_multiplier=1,
+        broker_connection_retry_on_startup=True,
+        timezone="UTC",
+        enable_utc=True,
+        task_routes={
+            "keble_scraper.execute_job": {
+                "queue": settings.fetch_queue,
+            },
+            "keble_scraper.run_maintenance": {
+                "queue": settings.maintenance_queue,
+            },
+            "keble_scraper.deliver_callbacks": {
+                "queue": settings.maintenance_queue,
+            },
+            "keble_scraper.check_proxies": {
+                "queue": settings.proxy_health_queue,
+            },
+        },
+        beat_schedule={
+            "scraper-maintenance-every-minute": {
+                "task": "keble_scraper.run_maintenance",
+                "schedule": 60.0,
+                "options": {"queue": settings.maintenance_queue},
+            },
+            "scraper-callbacks-every-fifteen-seconds": {
+                "task": "keble_scraper.deliver_callbacks",
+                "schedule": 15.0,
+                "options": {"queue": settings.maintenance_queue},
+            },
+            "scraper-proxy-health-every-five-minutes": {
+                "task": "keble_scraper.check_proxies",
+                "schedule": 300.0,
+                "options": {"queue": settings.proxy_health_queue},
+            },
+        },
+    )
+    return app

keble_scraper_api/infrastructure/cloudflare.py

@@ -0,0 +1,259 @@
+"""Cloudflare Browser Rendering exception transport."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from decimal import Decimal
+from time import monotonic
+from typing import Literal
+
+import httpx
+from keble_data_infra_contract import parse_retry_after
+from keble_helpers.typings import PydanticModelConfig
+from pydantic import BaseModel, Field
+
+from keble_scraper_contract import (
+    ScrapeArtifactTrust,
+    ScrapeAttemptOutcome,
+    ScrapeTransportRoute,
+)
+
+from keble_scraper_api.application.fetching import FetchResult, PreparedFetch
+from keble_scraper_api.settings import ResponsePolicy, ScraperSettings
+
+from .url_policy import PublicUrlPolicy
+
+
+class CloudflareApiError(BaseModel):
+    """One documented Cloudflare API error item without response-body leakage.
+
+    Steps:
+    1. retain the provider-native numeric code;
+    2. validate but never propagate the provider message;
+    3. expose only the code to typed failure evidence.
+
+    Side effects if changes:
+    - Browser Run rate-limit classification and operator diagnostics.
+    """
+
+    model_config = PydanticModelConfig.default(frozen=True, extra="ignore")
+
+    code: int
+    message: str = Field(min_length=1, max_length=1_024)
+
+
+class CloudflareApiErrorEnvelope(BaseModel):
+    """Documented non-success envelope returned by Cloudflare Browser Run.
+
+    Steps:
+    1. require Cloudflare's explicit unsuccessful marker;
+    2. require at least one typed native error;
+    3. keep the raw payload outside logs and public contracts.
+
+    Side effects if changes:
+    - malformed vendor responses escape to Sentry instead of becoming rate/payment facts.
+    """
+
+    model_config = PydanticModelConfig.default(frozen=True, extra="ignore")
+
+    success: Literal[False]
+    errors: tuple[CloudflareApiError, ...] = Field(min_length=1)
+
+
+class CloudflareBrowserFetcher:
+    """Render reviewed exception pages through Cloudflare's content endpoint.
+
+    Steps:
+    1. enforce local URL/domain/credential policy before vendor work;
+    2. reuse one pooled Browser Rendering client;
+    3. return bounded content or typed native capacity evidence.
+
+    Side effects if changes:
+    - browser vendor spend, rendered artifacts, and rate-limit accounting.
+    """
+
+    def __init__(
+        self, *, settings: ScraperSettings, url_policy: PublicUrlPolicy
+    ) -> None:
+        """Bind credentials and the same pre-dispatch public URL policy.
+
+        Steps:
+        1. retain immutable renderer settings and URL policy;
+        2. construct one process-owned client without ambient proxy trust;
+        3. defer vendor calls until an allowlisted request arrives.
+
+        Side effects if changes:
+        - Cloudflare availability and SSRF validation before remote rendering.
+        """
+
+        self._settings = settings
+        self._url_policy = url_policy
+        self._client = httpx.AsyncClient(
+            timeout=self._settings.read_timeout_seconds,
+            trust_env=False,
+        )
+
+    async def close(self) -> None:
+        """Close the pooled Cloudflare HTTP transport.
+
+        Steps:
+        1. close keep-alive connections owned by this fetcher;
+        2. remain safe when called after no vendor request;
+        3. leave credential/settings ownership unchanged.
+
+        Side effects if changes:
+        - API/worker shutdown and Cloudflare socket cleanup.
+        """
+
+        await self._client.aclose()
+
+    async def fetch(
+        self, *, request: PreparedFetch, response_policy: ResponsePolicy
+    ) -> FetchResult:
+        """Validate, render, parse capacity evidence, and bound returned HTML.
+
+        Steps:
+        1. validate public target plus explicit domain/credential gates;
+        2. issue one pooled Browser Run request and parse shared Retry-After evidence;
+        3. retain documented native error codes without inferring payment;
+        4. enforce the response byte ceiling before returning typed evidence.
+
+        Side effects if changes:
+        - actual Browser Rendering calls and billed browser duration.
+        """
+
+        target = await self._url_policy.validate_and_resolve(url=request.url)
+        if not self._domain_allowed(hostname=target.hostname):
+            return FetchResult(
+                outcome=ScrapeAttemptOutcome.DENIED,
+                route=ScrapeTransportRoute.CLOUDFLARE_BROWSER_RUN,
+                trust=ScrapeArtifactTrust.VERIFIED,
+                final_url=request.url,
+                elapsed_ms=0,
+                error_code="URL_DENIED",
+                observed_at=datetime.now(UTC),
+            )
+        if (
+            self._settings.cloudflare_account_id is None
+            or self._settings.cloudflare_api_token is None
+        ):
+            return self._failed(
+                url=request.url, error_code="ROUTE_UNAVAILABLE", elapsed_ms=0
+            )
+        endpoint = (
+            "https://api.cloudflare.com/client/v4/accounts/"
+            f"{self._settings.cloudflare_account_id}/browser-rendering/content"
+        )
+        started = monotonic()
+        raw = await self._client.post(
+            endpoint,
+            headers={
+                "Authorization": (
+                    "Bearer " + self._settings.cloudflare_api_token.get_secret_value()
+                )
+            },
+            json={
+                "url": request.url,
+                "gotoOptions": {"waitUntil": "networkidle0"},
+                "rejectResourceTypes": ["stylesheet", "font"],
+            },
+        )
+        elapsed = max(0.0, monotonic() - started)
+        elapsed_ms = int(elapsed * 1000)
+        observed_at = datetime.now(UTC)
+        retry_at = parse_retry_after(
+            value=raw.headers.get("Retry-After"),
+            observed_at=observed_at,
+        )
+        if raw.status_code == 429 and retry_at is None:
+            retry_at = observed_at + timedelta(
+                seconds=self._settings.upstream_rate_limit_default_seconds
+            )
+        upstream_code = self._upstream_code(response=raw)
+        body = raw.content
+        if len(body) > response_policy.max_bytes:
+            return FetchResult(
+                outcome=ScrapeAttemptOutcome.SIZE_LIMIT,
+                route=ScrapeTransportRoute.CLOUDFLARE_BROWSER_RUN,
+                trust=ScrapeArtifactTrust.VERIFIED,
+                final_url=request.url,
+                status_code=raw.status_code,
+                content_type="text/html",
+                elapsed_ms=elapsed_ms,
+                browser_seconds=Decimal(str(round(elapsed, 3))),
+                error_code="RESPONSE_TOO_LARGE",
+                upstream_code=upstream_code,
+                retry_at=retry_at,
+                observed_at=observed_at,
+            )
+        outcome = (
+            ScrapeAttemptOutcome.SUCCEEDED
+            if raw.is_success
+            else ScrapeAttemptOutcome.HTTP_ERROR
+        )
+        return FetchResult(
+            outcome=outcome,
+            route=ScrapeTransportRoute.CLOUDFLARE_BROWSER_RUN,
+            trust=ScrapeArtifactTrust.VERIFIED,
+            final_url=request.url,
+            status_code=raw.status_code,
+            content_type="text/html",
+            body=body,
+            elapsed_ms=elapsed_ms,
+            browser_seconds=Decimal(str(round(elapsed, 3))),
+            error_code=None
+            if outcome is ScrapeAttemptOutcome.SUCCEEDED
+            else "HTTP_ERROR",
+            upstream_code=upstream_code,
+            retry_at=retry_at,
+            observed_at=observed_at,
+        )
+
+    @staticmethod
+    def _upstream_code(*, response: httpx.Response) -> str | None:
+        """Extract a documented native code from a rate-limit envelope.
+
+        Steps:
+        1. leave success and non-429 HTTP classification to status evidence;
+        2. validate the documented 429 JSON envelope with Pydantic;
+        3. retain only the first bounded numeric code as ``CF_<code>``.
+
+        Side effects if changes:
+        - Cloudflare code 2001 remains rate evidence, never payment evidence;
+        - malformed 429 envelopes escape for Sentry/supervision.
+        """
+
+        if response.status_code != 429:
+            return None
+        envelope = CloudflareApiErrorEnvelope.model_validate_json(response.content)
+        return f"CF_{envelope.errors[0].code}"
+
+    def _domain_allowed(self, *, hostname: str) -> bool:
+        """Require an exact or subdomain match against reviewed browser targets.
+
+        Side effects if changes:
+        - remote browser SSRF exposure and eligible exception-store domains.
+        """
+
+        return any(
+            hostname == domain or hostname.endswith(f".{domain}")
+            for domain in self._settings.cloudflare_browser_domain_allowlist
+        )
+
+    @staticmethod
+    def _failed(*, url: str, error_code: str, elapsed_ms: int) -> FetchResult:
+        """Build one sanitized renderer failure.
+
+        Side effects if changes:
+        - renderer retry and terminal gap reasons.
+        """
+
+        return FetchResult(
+            outcome=ScrapeAttemptOutcome.NETWORK_ERROR,
+            route=ScrapeTransportRoute.CLOUDFLARE_BROWSER_RUN,
+            trust=ScrapeArtifactTrust.VERIFIED,
+            final_url=url,
+            elapsed_ms=elapsed_ms,
+            error_code=error_code,
+            observed_at=datetime.now(UTC),
+        )

keble_scraper_api/infrastructure/credentials.py

@@ -0,0 +1,75 @@
+"""Encrypted-at-rest proxy credential conversion."""
+
+from __future__ import annotations
+
+from urllib.parse import quote, urlsplit
+
+from cryptography.fernet import Fernet
+from pydantic import SecretStr
+
+from keble_scraper_contract import ProxyCandidateCreate
+
+from keble_scraper_api.errors import ScraperDomainError, ScraperErrorCode
+
+
+class ProxyCredentialCipher:
+    """Encrypt complete proxy URLs and expose only redacted operational values.
+
+    Side effects if changes:
+    - Mongo proxy secrets and actual experimental proxy egress.
+    """
+
+    def __init__(self, *, fernet_key: SecretStr) -> None:
+        """Construct one process cipher from secret-system material.
+
+        Side effects if changes:
+        - old proxy candidates must remain decryptable across deployments.
+        """
+
+        self._fernet = Fernet(fernet_key.get_secret_value().encode())
+
+    def encode(self, *, command: ProxyCandidateCreate) -> tuple[str, str]:
+        """Validate an endpoint, attach credentials, and return redacted/ciphertext.
+
+        Side effects if changes:
+        - admin imports can create future outbound network routes.
+        """
+
+        parsed = urlsplit(command.endpoint)
+        if (
+            parsed.scheme not in {"http", "https"}
+            or parsed.hostname is None
+            or parsed.username is not None
+            or parsed.password is not None
+            or parsed.query
+            or parsed.fragment
+            or parsed.path not in {"", "/"}
+        ):
+            raise ScraperDomainError(
+                code=ScraperErrorCode.URL_DENIED,
+                message="proxy endpoint must be a credential-free HTTP(S) origin",
+            )
+        port = parsed.port or (443 if parsed.scheme == "https" else 80)
+        credentials = ""
+        if command.username is not None:
+            password = (
+                command.password.get_secret_value()
+                if command.password is not None
+                else ""
+            )
+            credentials = (
+                f"{quote(command.username, safe='')}:{quote(password, safe='')}@"
+            )
+        complete = f"{parsed.scheme}://{credentials}{parsed.hostname}:{port}"
+        redacted = f"{parsed.scheme}://{parsed.hostname}:{port}"
+        encrypted = self._fernet.encrypt(complete.encode()).decode()
+        return redacted, encrypted
+
+    def decode(self, *, encrypted_proxy_url: str) -> SecretStr:
+        """Decrypt one route only at dispatch time.
+
+        Side effects if changes:
+        - proxy credentials enter the HTTP client's in-memory request config.
+        """
+
+        return SecretStr(self._fernet.decrypt(encrypted_proxy_url.encode()).decode())