"""The one writer of every delivery (v2.2.18). A delivery is products.json, coupons.json, report.json and catalog.json (the store's observation history) of one run. They are published together or not at all: 1. every file is written to a new, never-reused folder releases//// and read back; 2. only then is the single pointer latest//CURRENT.json replaced, with one conditional write (local: the SHA-256 of the pointer read; Blob: If-Match on its ETag). The pointer names the release folder, the SHA-256 of every file in it, the release it replaces and the release history of the store. Until step 2 succeeds the pointer still names the previous release, whose files were never touched, so a failure at any write (a coupon file that cannot be written, a lost connection, a killed process) leaves the previous delivery whole. Readers go through the pointer and check each file's SHA-256, so a mixed delivery cannot be read. A run that is not a full delivery (only some categories, a limited coupon lookup, a fallback source) is written as a sample release under samples/// and never touches the pointer. Stores written by v2.2.17 and earlier have no pointer; their latest//*.json and state//catalog.json are read as the baseline until the first v2.2.18 publish, and never written again. """ from __future__ import annotations import hashlib import json import secrets from datetime import datetime, timezone from .storage import PreconditionFailed DELIVERY_FILES = ("products.json", "coupons.json", "report.json", "catalog.json") _LEGACY = {"products.json": "latest/{loc}/products.json", "coupons.json": "latest/{loc}/coupons.json", "report.json": "latest/{loc}/report.json", "catalog.json": "state/{loc}/catalog.json"} class PublishFailed(Exception): """The delivery was not published; the previous delivery is unchanged.""" class DeliveryDamaged(Exception): """A release file does not match the SHA-256 its pointer names: it is not read.""" def sha256_text(text: str) -> str: return hashlib.sha256(text.encode("utf-8")).hexdigest() def _utc() -> str: return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ") class Delivery: def __init__(self, storage, loc_key: str): self.storage, self.loc = storage, loc_key self.pointer_key = f"latest/{loc_key}/CURRENT.json" # --- reading ------------------------------------------------------------------------------------------- def current(self) -> dict | None: text, _ = self.storage.read_with_etag(self.pointer_key) if text is None: return None ptr = json.loads(text) if not isinstance(ptr, dict) or not ptr.get("run_id") or not isinstance(ptr.get("files"), dict): raise DeliveryDamaged(f"{self.pointer_key} is not a valid delivery pointer") return ptr def baseline(self, run_id: str) -> dict | None: """The newest published delivery that is not run_id itself (a refinish of the published run compares with the release it replaced). {"legacy": True} for a store last written by v2.2.17; None when there is none.""" ptr = self.current() if ptr is None: if self.storage.exists(_LEGACY["products.json"].format(loc=self.loc)): return {"legacy": True, "run_id": None} return None if ptr["run_id"] != run_id: return ptr return ptr.get("previous") def read(self, release: dict | None, name: str) -> str | None: """One file of a release (as returned by current()/baseline()), checked against its SHA-256.""" if not release: return None if release.get("legacy"): key = _LEGACY[name].format(loc=self.loc) return self.storage.read_text(key) if self.storage.exists(key) else None want = release["files"].get(name) if want is None: return None text = self.storage.read_text(release["release"] + name) if sha256_text(text) != want: raise DeliveryDamaged(f"{release['release']}{name} does not match the SHA-256 in its pointer") return text # --- writing ------------------------------------------------------------------------------------------- def _write_verified(self, prefix: str, files: dict[str, str]) -> dict[str, str]: hashes = {} for name, text in files.items(): try: self.storage.write_text(prefix + name, text) back = self.storage.read_text(prefix + name) except Exception as exc: # noqa: BLE001 - any storage failure means: not published raise PublishFailed(f"writing {prefix}{name} failed: {type(exc).__name__}: {exc}") from exc if back != text: raise PublishFailed(f"{prefix}{name} read back differently") hashes[name] = sha256_text(text) return hashes def publish(self, run_id: str, files: dict[str, str], summary: dict) -> dict: missing = [n for n in DELIVERY_FILES if n not in files] if missing: raise PublishFailed(f"a delivery needs {', '.join(DELIVERY_FILES)}; missing {missing}") prefix = f"releases/{self.loc}/{run_id}/{datetime.now(timezone.utc).strftime('%Y%m%dT%H%M%SZ')}-{secrets.token_hex(3)}/" hashes = self._write_verified(prefix, files) try: old_text, etag = self.storage.read_with_etag(self.pointer_key) except Exception as exc: # noqa: BLE001 raise PublishFailed(f"reading {self.pointer_key} failed: {exc}") from exc old = json.loads(old_text) if old_text else None entry = {"run_id": run_id, "release": prefix, "published_utc": _utc(), **summary} pointer = {"run_id": run_id, "release": prefix, "files": hashes, "published_utc": entry["published_utc"], "summary": summary, "previous": ({k: old[k] for k in ("run_id", "release", "files", "published_utc")} if old else None), "history": ((old or {}).get("history") or []) + [entry]} text = json.dumps(pointer, indent=1, ensure_ascii=False) try: self.storage.write_if_match(self.pointer_key, text, etag) except PreconditionFailed as exc: raise PublishFailed(f"{self.pointer_key} changed during the publish (another writer?): {exc}") from exc except Exception as exc: # noqa: BLE001 raise PublishFailed(f"writing {self.pointer_key} failed: {type(exc).__name__}: {exc}") from exc back, _ = self.storage.read_with_etag(self.pointer_key) if back != text: raise PublishFailed(f"{self.pointer_key} read back differently") return pointer def release_sample(self, run_id: str, files: dict[str, str]) -> str: """A run that is not a full delivery: its files under samples/, the pointer untouched.""" prefix = f"samples/{self.loc}/{run_id}/" self._write_verified(prefix, files) return prefix