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

keble_scraper_api/maintenance/reset_pre_release_state.py

@@ -0,0 +1,743 @@
+"""Inspect or clear the incompatible first-release Scraper namespace."""
+
+from __future__ import annotations
+
+from argparse import ArgumentParser
+from asyncio import run
+from collections.abc import AsyncIterator, Sequence
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from enum import StrEnum
+from json import dumps
+from pathlib import Path
+from typing import Protocol, cast
+
+from pymongo import ASCENDING, AsyncMongoClient
+from pymongo.asynchronous.collection import AsyncCollection
+from redis.asyncio import Redis
+
+from keble_scraper_api.container import build_artifact_store
+from keble_scraper_api.protocols import ArtifactStoreProtocol
+from keble_scraper_api.settings import RuntimeEnvironment, ScraperSettings
+
+
+RESET_CONFIRMATION = "RESET_SCRAPER_PRE_RELEASE_STATE"
+WRITER_STOP_CONFIRMATION = "I_STOPPED_SCRAPER_WRITERS"
+SAFE_ENVIRONMENTS = frozenset({RuntimeEnvironment.DEVELOPMENT, RuntimeEnvironment.TEST})
+DELETE_BATCH_SIZE = 1_000
+RESET_COLLECTIONS = (
+    "scrape_outbox",
+    "scrape_attempts",
+    "scrape_jobs",
+    "scrape_cache_entries",
+    "scrape_artifact_pins",
+    "scrape_artifacts",
+    "scrape_audit_events",
+    "proxy_candidates",
+    "scrape_metadata",
+)
+ROLLBACK_CONDITION = (
+    "Stop Shopify/Scraper release cutover and restore the recorded Mongo/Redis "
+    "snapshots plus artifact-prefix backup when startup ownership fencing fails, "
+    "a new job cannot complete one callback, or artifact cleanup counts differ."
+)
+
+
+class ScraperResetConfigurationError(ValueError):
+    """Refuse a clean break whose local safety contract is incomplete.
+
+    Steps:
+    1. distinguish operator refusal from provider or persistence faults.
+
+    Side effects if changes:
+    - release automation treats this as a no-authority/no-mutation outcome.
+    """
+
+
+class ResetMode(StrEnum):
+    """Finite write-free and destructive command modes.
+
+    Steps:
+    1. represent inspection separately from application;
+    2. prevent nullable flags or strings from granting mutation authority.
+
+    Side effects if changes:
+    - only APPLY may delete binary, Mongo, or Redis state.
+    """
+
+    DRY_RUN = "DRY_RUN"
+    APPLY = "APPLY"
+
+
+class MongoResetProtocol(Protocol):
+    """Narrow configured-database surface used by the reset.
+
+    Steps:
+    1. prove connectivity before collection reads;
+    2. expose only exact named collections from one database.
+
+    Side effects if changes:
+    - the command must never discover/drop an adjacent database or collection.
+    """
+
+    async def command(self, command: str) -> dict[str, object]:
+        """Execute the bounded connectivity command.
+
+        Steps:
+        1. prove the configured database client is reachable.
+
+        Side effects if changes:
+        - no inspection or mutation may proceed after failure.
+        """
+
+        ...
+
+    def __getitem__(self, name: str) -> AsyncCollection[dict[str, object]]:
+        """Bind one explicitly allowlisted collection.
+
+        Steps:
+        1. return the exact named collection without database discovery.
+
+        Side effects if changes:
+        - reset scope remains controlled by `RESET_COLLECTIONS`.
+        """
+
+        ...
+
+
+class RedisResetProtocol(Protocol):
+    """Narrow exact-namespace Redis surface used by the reset.
+
+    Steps:
+    1. prove connectivity;
+    2. stream exact-prefix keys and delete bounded batches;
+    3. close the command-owned pool.
+
+    Side effects if changes:
+    - unrelated Redis namespaces must survive the clean break.
+    """
+
+    async def ping(self) -> bool:
+        """Prove Redis is reachable before inspection.
+
+        Steps:
+        1. execute the adapter connectivity command.
+
+        Side effects if changes:
+        - no Mongo or binary deletion may begin after failure.
+        """
+
+        ...
+
+    def scan_iter(self, *, match: str) -> AsyncIterator[str]:
+        """Stream keys matching one exact namespace prefix.
+
+        Steps:
+        1. yield identities without reading or logging values.
+
+        Side effects if changes:
+        - count and deletion scopes share this iterator.
+        """
+
+        ...
+
+    async def delete(self, *names: str) -> int:
+        """Delete one bounded opaque key batch.
+
+        Steps:
+        1. remove only the exact supplied identities.
+
+        Side effects if changes:
+        - APPLY totals and idempotency depend on the returned count.
+        """
+
+        ...
+
+    async def aclose(self) -> None:
+        """Close the command-owned Redis pool.
+
+        Steps:
+        1. release all connections after evidence is complete.
+
+        Side effects if changes:
+        - repeated maintenance invocations must not leak connections.
+        """
+
+        ...
+
+
+@dataclass(frozen=True, slots=True)
+class ResetOptions:
+    """Validated secret-free authority for one clean-break campaign.
+
+    Steps:
+    1. retain finite mode and exact safety acknowledgements;
+    2. retain database, Redis, artifact-owner, backup, and audit identities;
+    3. exclude credentials, fetched bodies, and provider payloads.
+
+    Side effects if changes:
+    - APPLY authorization and rollback evidence depend on these exact fields.
+    """
+
+    mode: ResetMode
+    confirmation: str | None
+    writer_confirmation: str | None
+    expected_database: str | None
+    expected_redis_namespace: str | None
+    expected_artifact_owner: str | None
+    rollback_reference: str | None
+    artifact_inventory_reference: str | None
+    audit_output: Path | None
+    campaign_id: str
+    reason: str
+
+
+@dataclass(frozen=True, slots=True)
+class ResetReport:
+    """Count-only inspection or deletion evidence for one campaign.
+
+    Steps:
+    1. retain exact Mongo, Redis, and binary counts;
+    2. disclose legacy retention populations separately;
+    3. retain rollback/inventory evidence without object identities.
+
+    Side effects if changes:
+    - stdout and immutable audit output consume this stable shape.
+    """
+
+    mode: ResetMode
+    mongo_counts: dict[str, int]
+    redis_key_count: int
+    artifact_object_count: int
+    jobs_without_history_clock: int
+    delivered_outbox_without_history_clock: int
+    audits_without_history_clock: int
+    rollback_reference: str | None
+    artifact_inventory_reference: str | None
+    rollback_condition: str = ROLLBACK_CONDITION
+
+    def total_mongo_rows(self) -> int:
+        """Return the exact sum of allowlisted Mongo counts.
+
+        Steps:
+        1. sum the authoritative per-collection integer counts once.
+
+        Side effects if changes:
+        - per-collection counts remain authoritative for reconciliation.
+        """
+
+        return sum(self.mongo_counts.values())
+
+
+def parse_args(*, argv: Sequence[str] | None = None) -> ResetOptions:
+    """Parse a DRY_RUN-first command without credential arguments.
+
+    Steps:
+    1. retain exact target, writer, backup, owner, and audit fields;
+    2. validate bounded campaign and reason strings;
+    3. select APPLY only from the explicit flag.
+
+    Side effects if changes:
+    - runbooks depend on these literal flags and confirmation values.
+    """
+
+    parser = ArgumentParser(description=__doc__)
+    parser.add_argument("--apply", action="store_true")
+    parser.add_argument("--confirm")
+    parser.add_argument("--writers-stopped")
+    parser.add_argument("--expected-database")
+    parser.add_argument("--expected-redis-namespace")
+    parser.add_argument("--expected-artifact-owner")
+    parser.add_argument("--rollback-reference")
+    parser.add_argument("--artifact-inventory-reference")
+    parser.add_argument("--audit-output", type=Path)
+    parser.add_argument("--campaign-id", default="review2-wp8-scraper-reset")
+    parser.add_argument(
+        "--reason",
+        default="REVIEW2 WP8 first-release Scraper clean break",
+    )
+    parsed = parser.parse_args(argv)
+    campaign_id = str(parsed.campaign_id).strip()
+    reason = str(parsed.reason).strip()
+    if len(campaign_id) < 8 or len(campaign_id) > 96:
+        raise ValueError("--campaign-id must contain 8..96 characters")
+    if len(reason) < 8 or len(reason) > 1_000:
+        raise ValueError("--reason must contain 8..1000 characters")
+    return ResetOptions(
+        mode=ResetMode.APPLY if bool(parsed.apply) else ResetMode.DRY_RUN,
+        confirmation=None if parsed.confirm is None else str(parsed.confirm),
+        writer_confirmation=(
+            None if parsed.writers_stopped is None else str(parsed.writers_stopped)
+        ),
+        expected_database=(
+            None if parsed.expected_database is None else str(parsed.expected_database)
+        ),
+        expected_redis_namespace=(
+            None
+            if parsed.expected_redis_namespace is None
+            else str(parsed.expected_redis_namespace)
+        ),
+        expected_artifact_owner=(
+            None
+            if parsed.expected_artifact_owner is None
+            else str(parsed.expected_artifact_owner)
+        ),
+        rollback_reference=(
+            None
+            if parsed.rollback_reference is None
+            else str(parsed.rollback_reference).strip()
+        ),
+        artifact_inventory_reference=(
+            None
+            if parsed.artifact_inventory_reference is None
+            else str(parsed.artifact_inventory_reference).strip()
+        ),
+        audit_output=parsed.audit_output,
+        campaign_id=campaign_id,
+        reason=reason,
+    )
+
+
+def assert_reset_authorized(
+    *,
+    settings: ScraperSettings,
+    options: ResetOptions,
+) -> None:
+    """Refuse ambiguous or production-like deletion before clients open.
+
+    Steps:
+    1. allow write-free DRY_RUN without acknowledgements;
+    2. reject APPLY outside development/test;
+    3. require exact writer, database, Redis, owner, backup, inventory, and audit evidence.
+
+    Side effects if changes:
+    - production-like Scraper data cannot be deleted by this command.
+    """
+
+    if options.mode is ResetMode.DRY_RUN:
+        return
+    if settings.environment not in SAFE_ENVIRONMENTS:
+        raise ScraperResetConfigurationError(
+            "APPLY is permanently disabled for production-like environments"
+        )
+    if options.confirmation != RESET_CONFIRMATION:
+        raise ScraperResetConfigurationError(
+            f"--apply requires --confirm {RESET_CONFIRMATION}"
+        )
+    if options.writer_confirmation != WRITER_STOP_CONFIRMATION:
+        raise ScraperResetConfigurationError(
+            f"--apply requires --writers-stopped {WRITER_STOP_CONFIRMATION}"
+        )
+    if options.expected_database != settings.mongo_database:
+        raise ScraperResetConfigurationError(
+            "--expected-database must exactly match Scraper settings"
+        )
+    if options.expected_redis_namespace != settings.redis_namespace:
+        raise ScraperResetConfigurationError(
+            "--expected-redis-namespace must exactly match Scraper settings"
+        )
+    if options.expected_artifact_owner != settings.resolved_artifact_namespace_owner:
+        raise ScraperResetConfigurationError(
+            "--expected-artifact-owner must exactly match Scraper settings"
+        )
+    if options.rollback_reference is None or len(options.rollback_reference) < 8:
+        raise ScraperResetConfigurationError(
+            "--apply requires a non-empty --rollback-reference"
+        )
+    if (
+        options.artifact_inventory_reference is None
+        or len(options.artifact_inventory_reference) < 8
+    ):
+        raise ScraperResetConfigurationError(
+            "--apply requires an artifact namespace inventory/backup reference"
+        )
+    if options.audit_output is None:
+        raise ScraperResetConfigurationError(
+            "--apply requires an immutable --audit-output path"
+        )
+
+
+async def _redis_key_count(
+    *,
+    redis: RedisResetProtocol,
+    namespace: str,
+) -> int:
+    """Count one exact Redis namespace without reading values.
+
+    Steps:
+    1. scan only `namespace:*`;
+    2. increment a scalar without retaining identities.
+
+    Side effects if changes:
+    - DRY_RUN remains bounded in memory even for a large namespace.
+    """
+
+    count = 0
+    async for _ in redis.scan_iter(match=f"{namespace}:*"):
+        count += 1
+    return count
+
+
+async def inspect_state(
+    *,
+    database: MongoResetProtocol,
+    redis: RedisResetProtocol,
+    settings: ScraperSettings,
+    options: ResetOptions,
+) -> ResetReport:
+    """Inspect exact clean-break populations without fetching stored bodies.
+
+    Steps:
+    1. prove Mongo and Redis connectivity;
+    2. count every allowlisted collection and exact Redis namespace;
+    3. count missing retention clocks and artifact metadata rows separately.
+
+    Side effects if changes:
+    - DRY_RUN and APPLY preflight share these count semantics.
+    """
+
+    await database.command("ping")
+    await redis.ping()
+    counts = {
+        name: await database[name].count_documents({}) for name in RESET_COLLECTIONS
+    }
+    jobs_without_clock = await database["scrape_jobs"].count_documents(
+        {"history_expires_at": {"$exists": False}}
+    )
+    outbox_without_clock = await database["scrape_outbox"].count_documents(
+        {
+            "state": "DELIVERED",
+            "history_expires_at": {"$exists": False},
+        }
+    )
+    audits_without_clock = await database["scrape_audit_events"].count_documents(
+        {"history_expires_at": {"$exists": False}}
+    )
+    return ResetReport(
+        mode=options.mode,
+        mongo_counts=counts,
+        redis_key_count=await _redis_key_count(
+            redis=redis,
+            namespace=settings.redis_namespace,
+        ),
+        artifact_object_count=counts["scrape_artifacts"],
+        jobs_without_history_clock=jobs_without_clock,
+        delivered_outbox_without_history_clock=outbox_without_clock,
+        audits_without_history_clock=audits_without_clock,
+        rollback_reference=options.rollback_reference,
+        artifact_inventory_reference=options.artifact_inventory_reference,
+    )
+
+
+async def iter_artifact_object_keys(
+    *,
+    database: MongoResetProtocol,
+) -> AsyncIterator[str]:
+    """Stream exact persisted object keys without materializing the corpus.
+
+    Steps:
+    1. read only object-key and identity fields from artifact metadata;
+    2. order by stable Mongo identity and request bounded server batches;
+    3. yield validated non-empty string keys one at a time.
+
+    Side effects if changes:
+    - binary deletion must finish before artifact metadata is removed.
+    """
+
+    cursor = (
+        database["scrape_artifacts"]
+        .find({}, {"_id": 1, "object_key": 1})
+        .sort("_id", ASCENDING)
+        .batch_size(DELETE_BATCH_SIZE)
+    )
+    async for row in cursor:
+        key = row.get("object_key")
+        if not isinstance(key, str) or not key:
+            raise ScraperResetConfigurationError(
+                "scrape_artifacts contains an invalid object_key"
+            )
+        yield key
+
+
+async def _delete_artifact_objects(
+    *,
+    store: ArtifactStoreProtocol,
+    object_keys: AsyncIterator[str],
+) -> int:
+    """Delete referenced binary objects in bounded batches before metadata.
+
+    Steps:
+    1. accumulate at most the fixed batch size;
+    2. delete each exact key batch through the canonical artifact store;
+    3. return the number of referenced keys submitted successfully.
+
+    Side effects if changes:
+    - a storage failure leaves Mongo metadata intact for safe replay.
+    """
+
+    deleted = 0
+    batch: list[str] = []
+    async for key in object_keys:
+        batch.append(key)
+        if len(batch) == DELETE_BATCH_SIZE:
+            await store.delete_many(object_keys=batch)
+            deleted += len(batch)
+            batch = []
+    if batch:
+        await store.delete_many(object_keys=batch)
+        deleted += len(batch)
+    return deleted
+
+
+async def _delete_redis_namespace(
+    *,
+    redis: RedisResetProtocol,
+    namespace: str,
+) -> int:
+    """Delete one exact Redis namespace in bounded batches.
+
+    Steps:
+    1. scan only `namespace:*` identities;
+    2. delete each bounded batch and aggregate exact counts;
+    3. leave every adjacent key untouched.
+
+    Side effects if changes:
+    - rate/budget/dispatch state restarts empty only inside the Scraper namespace.
+    """
+
+    deleted = 0
+    batch: list[str] = []
+    async for key in redis.scan_iter(match=f"{namespace}:*"):
+        batch.append(key)
+        if len(batch) == DELETE_BATCH_SIZE:
+            deleted += await redis.delete(*batch)
+            batch = []
+    if batch:
+        deleted += await redis.delete(*batch)
+    return deleted
+
+
+async def apply_reset(
+    *,
+    database: MongoResetProtocol,
+    redis: RedisResetProtocol,
+    store: ArtifactStoreProtocol,
+    object_keys: AsyncIterator[str],
+    settings: ScraperSettings,
+    inspected: ResetReport,
+) -> ResetReport:
+    """Delete binaries, dependent Mongo rows, and exact Redis state in order.
+
+    Steps:
+    1. delete every referenced binary while Mongo recovery metadata still exists;
+    2. delete dependent Mongo rows in the fixed allowlist order;
+    3. delete only the exact Redis namespace and return replay-safe counts.
+
+    Side effects if changes:
+    - interrupted binary deletion is retryable because metadata remains;
+    - startup rebuilds indexes/ownership metadata after all writers remain stopped.
+    """
+
+    artifact_deleted = await _delete_artifact_objects(
+        store=store,
+        object_keys=object_keys,
+    )
+    deleted: dict[str, int] = {}
+    for name in RESET_COLLECTIONS:
+        deleted[name] = (await database[name].delete_many({})).deleted_count
+    redis_deleted = await _delete_redis_namespace(
+        redis=redis,
+        namespace=settings.redis_namespace,
+    )
+    return ResetReport(
+        mode=ResetMode.APPLY,
+        mongo_counts=deleted,
+        redis_key_count=redis_deleted,
+        artifact_object_count=artifact_deleted,
+        jobs_without_history_clock=inspected.jobs_without_history_clock,
+        delivered_outbox_without_history_clock=(
+            inspected.delivered_outbox_without_history_clock
+        ),
+        audits_without_history_clock=inspected.audits_without_history_clock,
+        rollback_reference=inspected.rollback_reference,
+        artifact_inventory_reference=inspected.artifact_inventory_reference,
+    )
+
+
+def _payload(
+    *,
+    options: ResetOptions,
+    report: ResetReport,
+    status: str,
+) -> dict[str, object]:
+    """Build stable credential/body-free stdout and audit evidence.
+
+    Steps:
+    1. bind campaign identity/reason to exact deletion counts;
+    2. retain rollback and artifact inventory references;
+    3. stamp UTC without object keys, bodies, URLs, proxies, or credentials.
+
+    Side effects if changes:
+    - release reconciliation and rollback review consume this shape.
+    """
+
+    return {
+        "campaignId": options.campaign_id,
+        "reason": options.reason,
+        "mode": report.mode.value,
+        "status": status,
+        "mongoCounts": report.mongo_counts,
+        "mongoTotal": report.total_mongo_rows(),
+        "redisKeyCount": report.redis_key_count,
+        "artifactObjectCount": report.artifact_object_count,
+        "jobsWithoutHistoryClock": report.jobs_without_history_clock,
+        "deliveredOutboxWithoutHistoryClock": (
+            report.delivered_outbox_without_history_clock
+        ),
+        "auditsWithoutHistoryClock": report.audits_without_history_clock,
+        "rollbackReference": report.rollback_reference,
+        "artifactInventoryReference": report.artifact_inventory_reference,
+        "rollbackCondition": report.rollback_condition,
+        "recordedAt": datetime.now(timezone.utc).isoformat(),
+    }
+
+
+def start_audit(*, options: ResetOptions) -> Path:
+    """Create exclusive RUNNING evidence before the first external deletion.
+
+    Steps:
+    1. derive a sibling running path from the final destination;
+    2. create it exclusively with target/rollback authority only;
+    3. return the owned path for terminal promotion.
+
+    Side effects if changes:
+    - interrupted APPLY intentionally leaves a `.running.json` artifact.
+    """
+
+    if options.audit_output is None:
+        raise ScraperResetConfigurationError("audit output is required")
+    options.audit_output.parent.mkdir(parents=True, exist_ok=True)
+    running_path = options.audit_output.with_suffix(
+        options.audit_output.suffix + ".running.json"
+    )
+    with running_path.open("x", encoding="utf-8") as handle:
+        handle.write(
+            dumps(
+                {
+                    "campaignId": options.campaign_id,
+                    "reason": options.reason,
+                    "mode": options.mode.value,
+                    "status": "RUNNING",
+                    "rollbackReference": options.rollback_reference,
+                    "artifactInventoryReference": (
+                        options.artifact_inventory_reference
+                    ),
+                    "rollbackCondition": ROLLBACK_CONDITION,
+                    "recordedAt": datetime.now(timezone.utc).isoformat(),
+                },
+                sort_keys=True,
+            )
+            + "\n"
+        )
+    return running_path
+
+
+def complete_audit(
+    *,
+    options: ResetOptions,
+    report: ResetReport,
+    running_path: Path,
+) -> None:
+    """Atomically promote RUNNING evidence to the final count-only audit.
+
+    Steps:
+    1. reject an existing final destination;
+    2. replace only the owned running content with terminal counts;
+    3. atomically rename it to the immutable final path.
+
+    Side effects if changes:
+    - successful APPLY leaves one final artifact and no RUNNING ambiguity.
+    """
+
+    if options.audit_output is None:
+        raise ScraperResetConfigurationError("audit output is required")
+    if options.audit_output.exists():
+        raise FileExistsError(options.audit_output)
+    running_path.write_text(
+        dumps(
+            _payload(options=options, report=report, status="SUCCEEDED"), sort_keys=True
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+    running_path.replace(options.audit_output)
+
+
+async def amain(*, argv: Sequence[str] | None = None) -> None:
+    """Inspect or apply the exact Scraper reset and print safe evidence.
+
+    Steps:
+    1. parse/authorize before clients open and inspect dependencies;
+    2. on APPLY, create RUNNING audit and prove artifact namespace ownership;
+    3. delete referenced binaries, Mongo rows, and exact Redis keys in order;
+    4. close clients, promote audit, and print the same count-only evidence.
+
+    Side effects if changes:
+    - APPLY deletes only the configured local/test Scraper namespace;
+    - unexpected faults propagate and preserve metadata or RUNNING evidence.
+    """
+
+    options = parse_args(argv=argv)
+    settings = ScraperSettings()
+    assert_reset_authorized(settings=settings, options=options)
+    client = AsyncMongoClient[dict[str, object]](
+        settings.mongo_uri.get_secret_value(),
+        tz_aware=True,
+        uuidRepresentation="standard",
+    )
+    database = cast(MongoResetProtocol, client[settings.mongo_database])
+    redis_client = Redis.from_url(
+        settings.redis_uri.get_secret_value(),
+        decode_responses=True,
+    )
+    redis = cast(RedisResetProtocol, redis_client)
+    inspected = await inspect_state(
+        database=database,
+        redis=redis,
+        settings=settings,
+        options=options,
+    )
+    report = inspected
+    if options.mode is ResetMode.APPLY:
+        running_path = start_audit(options=options)
+        store = build_artifact_store(settings=settings)
+        await store.ensure_namespace_owner(
+            owner=settings.resolved_artifact_namespace_owner
+        )
+        report = await apply_reset(
+            database=database,
+            redis=redis,
+            store=store,
+            object_keys=iter_artifact_object_keys(database=database),
+            settings=settings,
+            inspected=inspected,
+        )
+        complete_audit(options=options, report=report, running_path=running_path)
+    await redis.aclose()
+    await client.close()
+    print(
+        dumps(
+            {
+                "environment": settings.environment.value,
+                "mongoDatabase": settings.mongo_database,
+                "redisNamespace": settings.redis_namespace,
+                "artifactOwner": settings.resolved_artifact_namespace_owner,
+                **_payload(options=options, report=report, status="SUCCEEDED"),
+            },
+            sort_keys=True,
+        )
+    )
+
+
+if __name__ == "__main__":
+    run(amain())