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

keble_scraper_api/settings.py

@@ -0,0 +1,484 @@
+"""Environment-only typed runtime configuration."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from enum import StrEnum
+from pathlib import Path
+
+from keble_helpers.typings import PydanticModelConfig
+from pydantic import (
+    AnyHttpUrl,
+    BaseModel,
+    Field,
+    SecretStr,
+    TypeAdapter,
+    field_validator,
+    model_validator,
+)
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from keble_scraper_contract import OperatorRole
+
+
+class RuntimeEnvironment(StrEnum):
+    """Finite deployment environments with explicit auth behavior.
+
+    Side effects if changes:
+    - production startup validation and development auth bypass.
+    """
+
+    DEVELOPMENT = "development"
+    TEST = "test"
+    STAGING = "staging"
+    PRODUCTION = "production"
+
+
+class ResponsePolicy(BaseModel):
+    """Server-owned content-type and streaming byte limits.
+
+    Side effects if changes:
+    - secure fetcher acceptance and artifact storage bounds.
+    """
+
+    model_config = PydanticModelConfig.default(frozen=True, extra="forbid")
+
+    max_bytes: int = Field(ge=1, le=1_000_000_000)
+    content_type_prefixes: tuple[str, ...]
+
+
+class ScraperSettings(BaseSettings):
+    """Single validated settings source for API, workers, beat, and routing.
+
+    Steps:
+    1. parse environment/Infisical-compatible values into strong types;
+    2. normalize optional blanks and reject partial credential tuples;
+    3. expose immutable runtime, capacity, cost, and ownership policy.
+
+    Side effects if changes:
+    - Mongo/Redis/Rabbit/OSS ownership and queue names;
+    - vendor credentials, spend gates, auth, callbacks, and Sentry startup.
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="SCRAPER_",
+        env_file=".env",
+        extra="ignore",
+        frozen=True,
+    )
+
+    environment: RuntimeEnvironment = RuntimeEnvironment.DEVELOPMENT
+    host: str = "0.0.0.0"
+    port: int = Field(default=8080, ge=1, le=65_535)
+    frontend_dist: str = "/app/frontend/dist"
+    public_base_url: AnyHttpUrl = AnyHttpUrl("http://localhost:8080")
+    mongo_uri: SecretStr = SecretStr("mongodb://localhost:27017/?replicaSet=rs0")
+    mongo_database: str = "keble_scraper"
+    redis_uri: SecretStr = SecretStr("redis://localhost:9736/0")
+    redis_namespace: str = "keble-scraper"
+    rabbitmq_uri: SecretStr = SecretStr(
+        "amqp://guest:guest@localhost:5672/keble-scraper"
+    )
+    fetch_queue: str = "keble-scraper.fetch"
+    render_queue: str = "keble-scraper.render"
+    proxy_health_queue: str = "keble-scraper.proxy-health"
+    maintenance_queue: str = "keble-scraper.maintenance"
+    fetch_worker_concurrency: int = Field(default=8, ge=1, le=128)
+    render_worker_concurrency: int = Field(default=1, ge=1, le=16)
+    proxy_health_worker_concurrency: int = Field(default=4, ge=1, le=64)
+    maintenance_worker_concurrency: int = Field(default=2, ge=1, le=32)
+    worker_lease_seconds: int = Field(default=300, ge=30, le=3_600)
+    max_attempts: int = Field(default=4, ge=1, le=10)
+    job_deadline_seconds: int = Field(default=259_200, ge=300, le=604_800)
+    retry_base_seconds: int = Field(default=30, ge=1, le=3_600)
+    upstream_rate_limit_default_seconds: int = Field(
+        default=60,
+        ge=1,
+        le=86_400,
+    )
+    maintenance_dispatch_concurrency: int = Field(default=32, ge=1, le=128)
+    terminal_history_retention_days: int = Field(default=90, ge=30, le=3_650)
+    delivered_outbox_retention_days: int = Field(default=30, ge=7, le=3_650)
+    audit_history_retention_days: int = Field(default=400, ge=90, le=3_650)
+    history_retention_batch_size: int = Field(default=1_000, ge=1, le=10_000)
+    history_retention_lease_seconds: int = Field(default=300, ge=30, le=3_600)
+    connect_timeout_seconds: float = Field(default=10, gt=0, le=120)
+    read_timeout_seconds: float = Field(default=30, gt=0, le=600)
+    max_redirects: int = Field(default=5, ge=0, le=10)
+    identified_user_agent: str = "KebleDataBot/0.1 (+https://keble.ai/data-crawler)"
+    document_max_bytes: int = Field(default=10_000_000, ge=1)
+    json_max_bytes: int = Field(default=20_000_000, ge=1)
+    sitemap_max_bytes: int = Field(default=50_000_000, ge=1)
+    media_max_bytes: int = Field(default=100_000_000, ge=1)
+    service_key_current: SecretStr = SecretStr("development-service-key-change-me")
+    service_key_next: SecretStr | None = None
+    service_caller_identity: str = "keble-shopify"
+    callback_hmac_current: SecretStr = SecretStr("development-hmac-key-change-me")
+    callback_hmac_next: SecretStr | None = None
+    callback_replay_seconds: int = Field(default=300, ge=30, le=3_600)
+    shopify_callback_url: AnyHttpUrl | None = None
+    session_fernet_key: SecretStr | None = None
+    session_cookie_name: str = "keble_scraper_session"
+    session_hours: int = Field(default=8, ge=1, le=24)
+    google_client_id: str | None = None
+    truth_base_url: AnyHttpUrl | None = None
+    truth_auth_path: str = "/auth/google/workspace/exchange"
+    truth_timeout_seconds: float = Field(default=10, gt=0, le=60)
+    dev_auth_enabled: bool = False
+    dev_auth_email: str = "local-scraper@keble.dev"
+    dev_auth_role: OperatorRole = OperatorRole.SUPADMIN
+    bright_proxy_host: str | None = None
+    bright_proxy_port: int = Field(default=33335, ge=1, le=65_535)
+    bright_customer: str | None = None
+    bright_zone: str | None = None
+    bright_password: SecretStr | None = None
+    bright_cost_per_gb_usd: Decimal = Field(default=Decimal("8"), gt=0)
+    bright_daily_budget_usd: Decimal = Field(default=Decimal("25"), ge=0)
+    bright_requests_per_second: Decimal = Field(default=Decimal("5"), gt=0)
+    direct_requests_per_second: Decimal = Field(default=Decimal("2"), gt=0)
+    development_http_proxy_url: SecretStr | None = None
+    development_dns_over_https_url: AnyHttpUrl | None = None
+    cloudflare_account_id: str | None = None
+    cloudflare_api_token: SecretStr | None = None
+    cloudflare_browser_domain_allowlist: tuple[str, ...] = ()
+    cloudflare_browser_cost_per_hour_usd: Decimal = Field(
+        default=Decimal("0.09"),
+        gt=0,
+    )
+    cloudflare_daily_budget_usd: Decimal = Field(default=Decimal("5"), ge=0)
+    cloudflare_requests_per_second: Decimal = Field(default=Decimal("10"), gt=0)
+    public_proxy_experiment_enabled: bool = False
+    public_proxy_production_commit_allowed: bool = False
+    public_proxy_feed_allowlist: tuple[str, ...] = ()
+    proxy_secret_fernet_key: SecretStr | None = None
+    oss_endpoint: AnyHttpUrl | None = None
+    oss_bucket: str | None = Field(default=None, min_length=3, max_length=255)
+    oss_access_key_id: str | None = Field(default=None, min_length=1, max_length=256)
+    oss_access_key_secret: SecretStr | None = Field(default=None, min_length=1)
+    oss_prefix: str = "keble-scraper"
+    artifact_namespace_owner: str | None = Field(
+        default=None,
+        min_length=3,
+        max_length=256,
+        pattern=r"^[A-Za-z0-9._:/-]+$",
+    )
+    local_artifact_directory: str | None = None
+    local_artifact_base_url: AnyHttpUrl | None = None
+    artifact_download_seconds: int = Field(default=300, ge=30, le=3_600)
+    sentry_dsn: SecretStr | None = None
+    sentry_traces_sample_rate: float = Field(default=0.1, ge=0, le=1)
+    sentry_release: str = "keble-scraper-api@0.2.0"
+
+    @field_validator(
+        "local_artifact_directory",
+        "local_artifact_base_url",
+        mode="before",
+    )
+    @classmethod
+    def blank_local_artifact_value_is_absent(cls, value: object) -> object | None:
+        """Normalize explicit blank local-store overrides to absence.
+
+        1. Allow Compose to disable legacy env-file local storage explicitly.
+        2. Preserve every non-blank typed value for normal Pydantic validation.
+
+        Side effects if changes:
+        - private OSS may replace local development artifacts without a dual-store conflict;
+        - non-blank local directory/base-URL pairing remains strictly validated.
+        """
+
+        if isinstance(value, str) and not value.strip():
+            return None
+        return value
+
+    @field_validator(
+        "oss_endpoint",
+        "oss_bucket",
+        "oss_access_key_id",
+        "oss_access_key_secret",
+        mode="before",
+    )
+    @classmethod
+    def blank_oss_value_is_absent(cls, value: object) -> object | None:
+        """Normalize blank OSS environment overrides to true absence.
+
+        Steps:
+        1. treat blank strings as an operator-disabled OSS value;
+        2. treat an empty ``SecretStr`` as equally absent;
+        3. preserve every non-blank value for normal URL/length validation.
+
+        Side effects if changes:
+        - local storage may coexist only with a genuinely absent OSS tuple;
+        - production and worker startup reject partial OSS credentials before paid work.
+        """
+
+        if isinstance(value, str) and not value.strip():
+            return None
+        if isinstance(value, SecretStr) and not value.get_secret_value().strip():
+            return None
+        return value
+
+    @model_validator(mode="after")
+    def validate_environment_guards(self) -> "ScraperSettings":
+        """Reject development access and unsafe proxy commits in production.
+
+        Steps:
+        1. reject development-only auth/proxy behavior outside its allowed scope;
+        2. require a stable artifact namespace owner for staging/production;
+        3. validate complete secure production credentials, URLs, and key rotation.
+
+        Side effects if changes:
+        - production startup, public-proxy quarantine, and console access.
+        """
+
+        if (
+            self.environment is not RuntimeEnvironment.DEVELOPMENT
+            and self.dev_auth_enabled
+        ):
+            raise ValueError("SCRAPER_DEV_AUTH_ENABLED is allowed only in development")
+        if (
+            self.environment is RuntimeEnvironment.PRODUCTION
+            and self.public_proxy_production_commit_allowed
+        ):
+            raise ValueError(
+                "public proxy artifacts are forbidden for v0.1 production commits"
+            )
+        if (
+            self.environment
+            in {RuntimeEnvironment.STAGING, RuntimeEnvironment.PRODUCTION}
+            and self.artifact_namespace_owner is None
+        ):
+            raise ValueError(
+                "SCRAPER_ARTIFACT_NAMESPACE_OWNER is required outside local/test runtimes"
+            )
+        if self.environment is RuntimeEnvironment.PRODUCTION:
+            required = {
+                "SCRAPER_GOOGLE_CLIENT_ID": self.google_client_id,
+                "SCRAPER_TRUTH_BASE_URL": self.truth_base_url,
+                "SCRAPER_SHOPIFY_CALLBACK_URL": self.shopify_callback_url,
+                "SCRAPER_SESSION_FERNET_KEY": self.session_fernet_key,
+                "SCRAPER_PROXY_SECRET_FERNET_KEY": self.proxy_secret_fernet_key,
+                "SCRAPER_BRIGHT_PROXY_HOST": self.bright_proxy_host,
+                "SCRAPER_BRIGHT_CUSTOMER": self.bright_customer,
+                "SCRAPER_BRIGHT_ZONE": self.bright_zone,
+                "SCRAPER_BRIGHT_PASSWORD": self.bright_password,
+                "SCRAPER_OSS_ENDPOINT": self.oss_endpoint,
+                "SCRAPER_OSS_BUCKET": self.oss_bucket,
+                "SCRAPER_OSS_ACCESS_KEY_ID": self.oss_access_key_id,
+                "SCRAPER_OSS_ACCESS_KEY_SECRET": self.oss_access_key_secret,
+                "SCRAPER_SENTRY_DSN": self.sentry_dsn,
+            }
+            missing = [name for name, value in required.items() if value is None]
+            if missing:
+                raise ValueError(
+                    "production scraper settings are missing: " + ", ".join(missing)
+                )
+            secure_urls = {
+                "SCRAPER_PUBLIC_BASE_URL": self.public_base_url,
+                "SCRAPER_TRUTH_BASE_URL": self.truth_base_url,
+                "SCRAPER_SHOPIFY_CALLBACK_URL": self.shopify_callback_url,
+                "SCRAPER_OSS_ENDPOINT": self.oss_endpoint,
+            }
+            insecure = [
+                name
+                for name, value in secure_urls.items()
+                if value is not None and value.scheme != "https"
+            ]
+            if insecure:
+                raise ValueError(
+                    "production scraper URLs must use HTTPS: " + ", ".join(insecure)
+                )
+            secrets = {
+                "SCRAPER_SERVICE_KEY_CURRENT": self.service_key_current,
+                "SCRAPER_SERVICE_KEY_NEXT": self.service_key_next,
+                "SCRAPER_CALLBACK_HMAC_CURRENT": self.callback_hmac_current,
+                "SCRAPER_CALLBACK_HMAC_NEXT": self.callback_hmac_next,
+                "SCRAPER_BRIGHT_PASSWORD": self.bright_password,
+                "SCRAPER_OSS_ACCESS_KEY_SECRET": self.oss_access_key_secret,
+            }
+            weak = [
+                name
+                for name, value in secrets.items()
+                if value is not None and len(value.get_secret_value()) < 32
+            ]
+            if weak:
+                raise ValueError(
+                    "production scraper secrets must contain at least 32 characters: "
+                    + ", ".join(weak)
+                )
+            fernet_keys = {
+                "SCRAPER_SESSION_FERNET_KEY": self.session_fernet_key,
+                "SCRAPER_PROXY_SECRET_FERNET_KEY": self.proxy_secret_fernet_key,
+            }
+            invalid_fernet = [
+                name
+                for name, value in fernet_keys.items()
+                if value is not None and len(value.get_secret_value()) != 44
+            ]
+            if invalid_fernet:
+                raise ValueError(
+                    "production Fernet keys must be URL-safe 32-byte keys: "
+                    + ", ".join(invalid_fernet)
+                )
+            if (
+                self.service_key_next is not None
+                and self.service_key_next.get_secret_value()
+                == self.service_key_current.get_secret_value()
+            ):
+                raise ValueError("service current and next keys must differ")
+            if (
+                self.callback_hmac_next is not None
+                and self.callback_hmac_next.get_secret_value()
+                == self.callback_hmac_current.get_secret_value()
+            ):
+                raise ValueError("callback current and next keys must differ")
+        cloudflare_pair = (
+            self.cloudflare_account_id is not None,
+            self.cloudflare_api_token is not None,
+        )
+        if any(cloudflare_pair) and not all(cloudflare_pair):
+            raise ValueError(
+                "Cloudflare account and API token must be configured together"
+            )
+        if all(cloudflare_pair) and not self.cloudflare_browser_domain_allowlist:
+            raise ValueError("Cloudflare browser rendering requires a domain allowlist")
+        invalid_browser_domains = [
+            domain
+            for domain in self.cloudflare_browser_domain_allowlist
+            if not domain
+            or domain != domain.strip().lower().rstrip(".")
+            or "." not in domain
+            or any(token in domain for token in ("://", "/", "@", "?", "#"))
+        ]
+        if invalid_browser_domains:
+            raise ValueError(
+                "Cloudflare browser allowlist must contain bare lowercase domains"
+            )
+        local_artifact_pair = (
+            self.local_artifact_directory is not None,
+            self.local_artifact_base_url is not None,
+        )
+        if any(local_artifact_pair) and not all(local_artifact_pair):
+            raise ValueError(
+                "local artifact directory and base URL must be configured together"
+            )
+        if all(local_artifact_pair) and self.environment not in {
+            RuntimeEnvironment.DEVELOPMENT,
+            RuntimeEnvironment.TEST,
+        }:
+            raise ValueError(
+                "local artifact storage is allowed only in development/test"
+            )
+        if (
+            self.local_artifact_directory is not None
+            and not Path(self.local_artifact_directory).expanduser().is_absolute()
+        ):
+            raise ValueError("local artifact directory must be an absolute path")
+        if (
+            self.local_artifact_base_url is not None
+            and self.local_artifact_base_url.host
+            not in {"localhost", "127.0.0.1", "::1"}
+        ):
+            raise ValueError("local artifact base URL must use a loopback hostname")
+        oss_configured = any(
+            value is not None
+            for value in (
+                self.oss_endpoint,
+                self.oss_bucket,
+                self.oss_access_key_id,
+                self.oss_access_key_secret,
+            )
+        )
+        oss_complete = all(
+            value is not None
+            for value in (
+                self.oss_endpoint,
+                self.oss_bucket,
+                self.oss_access_key_id,
+                self.oss_access_key_secret,
+            )
+        )
+        if oss_configured and not oss_complete:
+            raise ValueError(
+                "OSS endpoint, bucket, access-key ID, and access-key secret must be configured together"
+            )
+        if all(local_artifact_pair) and oss_configured:
+            raise ValueError(
+                "configure either local artifact storage or private OSS, not both"
+            )
+        development_egress_pair = (
+            self.development_http_proxy_url is not None,
+            self.development_dns_over_https_url is not None,
+        )
+        if any(development_egress_pair) and not all(development_egress_pair):
+            raise ValueError(
+                "development HTTP proxy and DNS-over-HTTPS URL must be configured together"
+            )
+        if all(development_egress_pair) and self.environment not in {
+            RuntimeEnvironment.DEVELOPMENT,
+            RuntimeEnvironment.TEST,
+        }:
+            raise ValueError(
+                "development proxy egress is allowed only in development/test"
+            )
+        if self.development_http_proxy_url is not None:
+            proxy_url = TypeAdapter(AnyHttpUrl).validate_python(
+                self.development_http_proxy_url.get_secret_value()
+            )
+            if proxy_url.scheme != "http":
+                raise ValueError("development HTTP proxy must use the http scheme")
+        return self
+
+    @property
+    def resolved_artifact_namespace_owner(self) -> str:
+        """Return the explicit deployment owner or an isolated local/test fallback.
+
+        Steps:
+        1. use the stable configured owner in staging and production;
+        2. derive a deterministic environment/database owner only for local tests.
+
+        Side effects if changes:
+        - object-store canaries and Mongo namespace markers must receive one value;
+        - changing this value requires an explicit artifact-namespace migration.
+        """
+
+        return self.artifact_namespace_owner or (
+            f"{self.environment.value}/{self.mongo_database}"
+        )
+
+    def response_policy(self, policy_class: str) -> ResponsePolicy:
+        """Resolve a finite response policy without caller-controlled limits.
+
+        Steps:
+        1. map the contract enum value to one server byte ceiling;
+        2. return only reviewed MIME prefixes for that class.
+
+        Side effects if changes:
+        - fetch streaming and typed content/size denial outcomes.
+        """
+
+        policies = {
+            "DOCUMENT": ResponsePolicy(
+                max_bytes=self.document_max_bytes,
+                content_type_prefixes=(
+                    "text/html",
+                    "text/plain",
+                    "application/xhtml+xml",
+                ),
+            ),
+            "JSON": ResponsePolicy(
+                max_bytes=self.json_max_bytes,
+                content_type_prefixes=(
+                    "application/json",
+                    "application/graphql-response+json",
+                ),
+            ),
+            "SITEMAP": ResponsePolicy(
+                max_bytes=self.sitemap_max_bytes,
+                content_type_prefixes=("application/xml", "text/xml", "text/plain"),
+            ),
+            "MEDIA": ResponsePolicy(
+                max_bytes=self.media_max_bytes,
+                content_type_prefixes=("image/", "video/"),
+            ),
+        }
+        return policies[policy_class]

keble_scraper_api/telemetry.py

@@ -0,0 +1,109 @@
+"""Shared Sentry initialization for API, Celery worker, and beat processes."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+import sentry_sdk
+from keble_helpers.typings import PydanticModelConfig
+from pydantic import BaseModel, SecretStr
+
+from keble_scraper_api.settings import RuntimeEnvironment, ScraperSettings
+
+
+class TelemetryRuntime(StrEnum):
+    """Finite process roles attached to every scraper Sentry event.
+
+    Steps:
+    1. distinguish request, scheduler, worker-parent, and task-child processes;
+    2. provide a stable low-cardinality tag value;
+    3. keep queue/job identities out of global initialization.
+
+    Side effects if changes:
+    - Sentry issue grouping and runtime-specific alert routing.
+    """
+
+    API = "api"
+    CELERY_PARENT = "celery-parent"
+    WORKER = "worker"
+    BEAT = "beat"
+
+
+class SentryRuntimeConfiguration(BaseModel):
+    """Secret-safe immutable Sentry initialization input for one process role.
+
+    Steps:
+    1. retain the write-only DSN and stable release/environment;
+    2. retain the bounded trace sample rate;
+    3. retain a finite runtime tag without payload or user data.
+
+    Side effects if changes:
+    - every API/worker/beat event uses these shared telemetry facts.
+    """
+
+    model_config = PydanticModelConfig.default(frozen=True, extra="forbid")
+
+    dsn: SecretStr
+    environment: RuntimeEnvironment
+    release: str
+    traces_sample_rate: float
+    runtime: TelemetryRuntime
+
+
+def build_sentry_runtime_configuration(
+    *,
+    settings: ScraperSettings,
+    runtime: TelemetryRuntime,
+) -> SentryRuntimeConfiguration | None:
+    """Build one enabled secret-safe configuration or explicit disabled result.
+
+    Steps:
+    1. treat an absent DSN as telemetry intentionally disabled;
+    2. copy only reviewed structural settings into the immutable model;
+    3. bind the exact process role for tests and alert routing.
+
+    Side effects if changes:
+    - determines whether process initialization calls the Sentry SDK.
+    """
+
+    if settings.sentry_dsn is None:
+        return None
+    return SentryRuntimeConfiguration(
+        dsn=settings.sentry_dsn,
+        environment=settings.environment,
+        release=settings.sentry_release,
+        traces_sample_rate=settings.sentry_traces_sample_rate,
+        runtime=runtime,
+    )
+
+
+def configure_sentry(
+    *,
+    settings: ScraperSettings,
+    runtime: TelemetryRuntime,
+) -> None:
+    """Initialize Sentry consistently before one process performs real work.
+
+    Steps:
+    1. build the common configuration and return when explicitly disabled;
+    2. initialize automatic FastAPI/Celery integrations without default PII;
+    3. attach a stable process-role tag for worker/beat crash-loop visibility.
+
+    Side effects if changes:
+    - initializes the process-global Sentry SDK client and runtime tag.
+    """
+
+    configuration = build_sentry_runtime_configuration(
+        settings=settings,
+        runtime=runtime,
+    )
+    if configuration is None:
+        return
+    sentry_sdk.init(
+        dsn=configuration.dsn.get_secret_value(),
+        environment=configuration.environment.value,
+        release=configuration.release,
+        traces_sample_rate=configuration.traces_sample_rate,
+        send_default_pii=False,
+    )
+    sentry_sdk.set_tag("keble.runtime", configuration.runtime.value)

keble_scraper_api/workers/celery_app.py

@@ -0,0 +1,48 @@
+"""Celery application imported by worker and beat processes."""
+
+from celery.signals import worker_process_init, worker_process_shutdown
+
+from keble_scraper_api.infrastructure.celery_factory import build_celery
+from keble_scraper_api.settings import ScraperSettings
+from keble_scraper_api.telemetry import TelemetryRuntime, configure_sentry
+from keble_scraper_api.workers.runtime import (
+    initialize_worker_runtime,
+    shutdown_worker_runtime,
+)
+
+settings = ScraperSettings()
+configure_sentry(settings=settings, runtime=TelemetryRuntime.CELERY_PARENT)
+celery_app = build_celery(settings=settings)
+
+
+@worker_process_init.connect
+def initialize_process(**signal_values: object) -> None:
+    """Create one persistent event loop/container per Celery child process.
+
+    Steps:
+    1. initialize child-local Sentry before dependency startup;
+    2. start the persistent event loop and process container;
+    3. allow startup faults to reach Celery and Sentry unchanged.
+
+    Side effects if changes:
+    - worker Mongo/Redis pools and startup indexes.
+    """
+
+    configure_sentry(settings=settings, runtime=TelemetryRuntime.WORKER)
+    initialize_worker_runtime(settings=settings)
+
+
+@worker_process_shutdown.connect
+def shutdown_process(**signal_values: object) -> None:
+    """Close worker pools and event loop on process shutdown.
+
+    Steps:
+    1. accept the Celery signal payload without dynamic inspection;
+    2. close the child runtime exactly once;
+    3. leave process-global telemetry to normal interpreter shutdown.
+
+    Side effects if changes:
+    - Celery child resource cleanup.
+    """
+
+    shutdown_worker_runtime()