gabriel / musehub public
release_safety.py python
780 lines 34.2 KB
Raw
sha256:0ddcb29475cfe996169320691ffb2c5705e510191a4a944487df867959d81b36 fix(release): #275 tag the verified source revision, signed… Sonnet 5.5 minor ⚠ breaking 7 days ago
1 #!/usr/bin/env python3
2 """Safe muse release handling: publish, activate, roll back, clean up (musehub#114 Phase 6).
3
4 Each of these is a *separate* operation with its own authorization; none implies another.
5
6 publish gate-verified artifact -> storage, create-only. Never deletes, never overwrites.
7 activate move ONE environment's pointer to an already-published (version, sha256), guarded
8 by the pointer state the operator observed (compare-and-swap): satisfied requests
9 write nothing, a pointer that moved since is refused. Production additionally needs
10 explicit approval and must equal what staging runs.
11 rollback restore a pointer to an explicitly named published release, guarded by the pointer
12 state the operator observed; idempotent, and refused if the pointer has moved on.
13 cleanup dry-run by default; prints the exact deletion set. Deleting requires
14 ``--execute --confirm <digest-of-that-set>``.
15
16 Bucket layout (the bucket is shared by staging and production -- state is separated by key)::
17
18 muse-<version>.tar.gz immutable artifact (one version == one sha256, for ever)
19 muse-<version>.release.json immutable record: version, sha256, source revision, gate evidence
20 pointers/staging.json what staging should serve (only ``activate staging`` writes it)
21 pointers/production.json what production should serve (only approved ``activate production``)
22
23 Cleanup deletes only releases that (a) have a record whose sha256 matches the stored
24 artifact, (b) are not the active or rollback (``previous``) release of ANY environment,
25 and (c) fall outside the newest ``--keep`` by PEP 440 order. If either pointer is
26 missing, malformed or unreadable, or storage is unavailable, nothing is deletable.
27 Anything that cannot be positively proven safe is preserved.
28
29 Atomicity. Every write that must not race uses a storage-level conditional write, never a
30 read-then-write: artifacts/records are ``put_new`` (S3 ``If-None-Match: *``), and a pointer
31 that already exists is replaced with ``put_if_match`` (S3 ``If-Match: <etag read with it>``).
32 Backends that cannot provide these cannot be used for live releases.
33
34 Run from the musehub repo root::
35
36 python -m deploy.release_safety --bucket musehub-releases publish --artifact A --report R
37 """
38 from __future__ import annotations
39
40 import argparse
41 import hashlib
42 import json
43 import sys
44 from dataclasses import dataclass, field
45 from datetime import datetime, timedelta, timezone
46 from pathlib import Path
47 from typing import Any, Protocol
48
49 from deploy.prune_releases import stale_releases
50 from deploy.release_gate import DEFAULT_MAX_AGE, GateError, verify_report
51 from deploy.release_provenance import CheckoutState, ProvenanceError, observe_checkout
52 from musehub.release_pointer import (
53 ENVIRONMENTS,
54 POINTER_SCHEMA,
55 ReleasePointer,
56 ReleaseRef,
57 ReleaseSelectionError,
58 parse_pointer,
59 validate_sha256,
60 validate_version,
61 )
62
63 RECORD_SCHEMA = 1
64
65
66 class StorageError(Exception):
67 pass
68
69
70 class StorageUnavailable(StorageError):
71 """The backend could not be reached or answered unexpectedly. Always fail closed."""
72
73
74 class ObjectExists(StorageError):
75 """A create-only write found the key already present."""
76
77
78 class StaleState(StorageError):
79 """A conditional replace found the object changed (or gone) since it was read."""
80
81
82 class ReleaseSafetyError(Exception):
83 """An operation was refused to protect an existing release or environment."""
84
85
86 class Storage(Protocol):
87 def exists(self, key: str) -> bool: ...
88 def read(self, key: str) -> bytes: ...
89 def list_keys(self, prefix: str = "") -> list[str]: ...
90 def put_new(self, key: str, data: bytes) -> None: ... # create-only; ObjectExists if present
91 def read_versioned(self, key: str) -> tuple[bytes, str]: ... # bytes + opaque version token (S3 ETag)
92 def put_if_match(self, key: str, data: bytes, token: str) -> None: ... # replace iff unchanged; StaleState if not
93 def delete(self, key: str) -> None: ... # cleanup only
94
95
96 def _sha(data: bytes) -> str:
97 return hashlib.sha256(data).hexdigest()
98
99
100 def _artifact_key(version: str) -> str:
101 return f"muse-{version}.tar.gz"
102
103
104 def _record_key(version: str) -> str:
105 return f"muse-{version}.release.json"
106
107
108 def _pointer_key(environment: str) -> str:
109 return f"pointers/{environment}.json"
110
111
112 # ── publish ───────────────────────────────────────────────────────────────────
113
114
115 @dataclass(frozen=True)
116 class PublishResult:
117 status: str # "published" | "already_published" | "completed"
118 version: str
119 sha256: str
120
121
122 def publish(
123 storage: Storage,
124 artifact: Path,
125 report_text: str | None,
126 *,
127 now: datetime,
128 checkout: CheckoutState,
129 max_age: timedelta = DEFAULT_MAX_AGE,
130 ) -> PublishResult:
131 """Publish *artifact* iff the gate report authorizes exactly its bytes.
132
133 *checkout* is the Muse-observed state of the source checkout now; the report must have been
134 gated at exactly that revision on a clean tree.
135
136 Create-only: the same (version, bytes) is idempotent; the same version with
137 different bytes is refused. No pointer is touched and nothing is deleted.
138 """
139 candidate = verify_report(report_text, artifact, now=now, checkout=checkout, max_age=max_age) # raises GateError
140 data = artifact.read_bytes()
141 if _sha(data) != candidate.sha256: # re-check the bytes we are about to upload
142 raise GateError("artifact changed between verification and upload")
143 version, sha = candidate.version, candidate.sha256
144 akey, rkey = _artifact_key(version), _record_key(version)
145
146 # Advisory pre-check only (refuses early, before any write, on a record that already
147 # contradicts us). It is NOT what makes publication safe -- the create-only writes below are.
148 if storage.exists(rkey):
149 record = _read_record(storage, version)
150 if record is None:
151 raise ReleaseSafetyError(f"{rkey} exists but is malformed; refusing to publish over an unverifiable record")
152 if record["sha256"] != sha:
153 raise ReleaseSafetyError(
154 f"{_artifact_key(version)} is already published with different bytes (recorded sha256 {record['sha256']}, "
155 f"candidate {sha}); versions are immutable"
156 )
157
158 # Create-only, first: whoever loses a race finds the winner's object and compares identity.
159 artifact_created = _create_or_match(storage, akey, data, sha)
160 record_created = _create_record(storage, version, sha, _record_bytes(candidate, report_text or "", now))
161 if artifact_created and record_created:
162 return PublishResult("published", version, sha)
163 if not artifact_created and not record_created:
164 return PublishResult("already_published", version, sha)
165 return PublishResult("completed", version, sha)
166
167
168 def _create_or_match(storage: Storage, key: str, data: bytes, sha: str) -> bool:
169 """Create *key* iff absent. True if we created it; False if identical bytes were already there.
170
171 Different bytes under the same key are a hard refusal: a version is one artifact, for ever.
172 """
173 try:
174 storage.put_new(key, data)
175 return True
176 except ObjectExists:
177 pass
178 try:
179 stored = _sha(storage.read(key))
180 except KeyError as exc: # deleted between the refusal and the read: not something to guess about
181 raise StorageUnavailable(f"{key} vanished while verifying an existing object") from exc
182 if stored != sha:
183 raise ReleaseSafetyError(
184 f"{key} already exists with different bytes (stored sha256 {stored}, candidate {sha}); versions are immutable"
185 )
186 return False
187
188
189 def _create_record(storage: Storage, version: str, sha: str, record: bytes) -> bool:
190 """Create the release record iff absent; an existing record must be valid and describe *sha*."""
191 try:
192 storage.put_new(_record_key(version), record)
193 return True
194 except ObjectExists:
195 pass
196 existing = _read_record(storage, version)
197 if existing is None or existing["sha256"] != sha:
198 raise ReleaseSafetyError(f"{_record_key(version)} exists but is malformed or does not describe sha256 {sha}")
199 return False
200
201
202 def _record_bytes(candidate: Any, report_text: str, now: datetime) -> bytes:
203 return json.dumps(
204 {
205 "schema": RECORD_SCHEMA,
206 "version": candidate.version,
207 "sha256": candidate.sha256,
208 "source_revision": candidate.source_revision,
209 "installer_revision": candidate.installer_revision,
210 "gate_report_sha256": _sha(report_text.encode()),
211 "published_at": now.astimezone(timezone.utc).isoformat(),
212 },
213 indent=2,
214 sort_keys=True,
215 ).encode()
216
217
218 def _read_record(storage: Storage, version: str) -> dict[str, Any] | None:
219 """The parsed release record, or None if absent/invalid (callers treat None as unverified)."""
220 key = _record_key(version)
221 if not storage.exists(key):
222 return None
223 try:
224 record = json.loads(storage.read(key))
225 if (
226 isinstance(record, dict)
227 and record.get("schema") == RECORD_SCHEMA
228 and record.get("version") == version
229 and validate_sha256(record.get("sha256"))
230 ):
231 return record # type: ignore[no-any-return]
232 except (ValueError, ReleaseSelectionError):
233 pass
234 return None
235
236
237 def _verified_release(storage: Storage, version: str, sha256: str) -> None:
238 """Raise unless *version* has a valid record and a stored artifact, both matching *sha256*."""
239 record = _read_record(storage, version)
240 if record is None:
241 raise ReleaseSafetyError(f"no valid release record for {version}; it is not a published release")
242 if record["sha256"] != sha256:
243 raise ReleaseSafetyError(f"release {version} has sha256 {record['sha256']}, not the requested {sha256}")
244 akey = _artifact_key(version)
245 if not storage.exists(akey):
246 raise ReleaseSafetyError(f"artifact {akey} is missing from storage")
247 if _sha(storage.read(akey)) != sha256:
248 raise ReleaseSafetyError(f"stored {akey} does not hash to the recorded sha256 {sha256}")
249
250
251 # ── activate / rollback ───────────────────────────────────────────────────────
252
253
254 def _check_environment(environment: str) -> None:
255 if environment not in ENVIRONMENTS:
256 raise ReleaseSafetyError(f"unknown environment {environment!r}; expected one of {ENVIRONMENTS}")
257
258
259 def _read_pointer(storage: Storage, environment: str) -> ReleasePointer | None:
260 return _read_pointer_versioned(storage, environment)[0]
261
262
263 def _read_pointer_versioned(storage: Storage, environment: str) -> tuple[ReleasePointer | None, str | None]:
264 """(pointer, token). Both None when absent. The token is what a conditional replace must match."""
265 key = _pointer_key(environment)
266 try:
267 raw, token = storage.read_versioned(key)
268 except KeyError:
269 return None, None
270 try:
271 pointer = parse_pointer(raw.decode())
272 except (ReleaseSelectionError, UnicodeDecodeError) as exc:
273 raise ReleaseSafetyError(f"{key} is malformed: {exc}") from exc
274 if pointer.environment != environment:
275 raise ReleaseSafetyError(f"{key} claims environment {pointer.environment!r}")
276 return pointer, token
277
278
279 def _swap_pointer(storage: Storage, new: ReleasePointer, *, expected_token: str | None) -> ReleasePointer:
280 """Atomically install *new*: create-only if no pointer existed, else replace-iff-unchanged.
281
282 Raises ``ReleaseSafetyError`` if another writer got there first; the caller re-reads to decide
283 whether that writer already did what was asked.
284 """
285 key = _pointer_key(new.environment)
286 try:
287 if expected_token is None:
288 storage.put_new(key, new.to_json().encode())
289 else:
290 storage.put_if_match(key, new.to_json().encode(), expected_token)
291 except (ObjectExists, StaleState) as exc:
292 raise ReleaseSafetyError(f"{key} changed while this operation was in flight; nothing was overwritten") from exc
293 return new
294
295
296 def _require_production_approval(environment: str, approved: bool) -> None:
297 if environment == "production" and not approved:
298 raise ReleaseSafetyError("changing production requires explicit approval (--approve-production)")
299
300
301 @dataclass(frozen=True)
302 class ExpectedPointer:
303 """The pointer state the operator observed when they decided -- the "expected current" of the swap.
304
305 ``activated_at`` has microsecond resolution and every write sets it, so
306 (version, sha256, activated_at) identifies one exact pointer generation.
307 """
308
309 version: str | None = None
310 sha256: str | None = None
311 activated_at: str | None = None
312
313 @classmethod
314 def absent(cls) -> "ExpectedPointer":
315 return cls()
316
317 @property
318 def is_absent(self) -> bool:
319 return self.version is None and self.sha256 is None and self.activated_at is None
320
321 def matches(self, pointer: ReleasePointer | None) -> bool:
322 if pointer is None:
323 return self.is_absent
324 return (pointer.version, pointer.sha256, pointer.activated_at) == (self.version, self.sha256, self.activated_at)
325
326
327 def _validated_expectation(expect: ExpectedPointer) -> ExpectedPointer:
328 if expect.is_absent:
329 return expect
330 if expect.version is None or expect.sha256 is None or expect.activated_at is None:
331 raise ReleaseSafetyError("expected pointer state must be fully specified (version, sha256, activated_at) or explicitly absent")
332 try:
333 return ExpectedPointer(validate_version(expect.version), validate_sha256(expect.sha256), expect.activated_at)
334 except ReleaseSelectionError as exc:
335 raise ReleaseSafetyError(str(exc)) from exc
336
337
338 def _describe(pointer: ReleasePointer | None) -> str:
339 return "absent" if pointer is None else f"{pointer.version} ({pointer.sha256}) activated {pointer.activated_at}"
340
341
342 def _move_pointer(
343 storage: Storage,
344 environment: str,
345 target: ReleaseRef,
346 expect: ExpectedPointer,
347 *,
348 now: datetime,
349 verb: str,
350 ) -> ReleasePointer:
351 """The one compare-and-swap shared by activate and rollback.
352
353 * pointer already at *target* -> returned as is, nothing written (safe retry);
354 * pointer is exactly the *expect*ed one -> atomically replaced; the abandoned release becomes ``previous``;
355 * anything else (moved, stale, absent when one was expected, or vice versa) -> refused.
356
357 The final write is a storage-level conditional write against the token read together with the
358 pointer, so two racing operators cannot both succeed. If we lose that race but the winner
359 installed exactly our target, that is success (nothing for us to write).
360 """
361 current, token = _read_pointer_versioned(storage, environment)
362 if current is not None and (current.version, current.sha256) == (target.version, target.sha256):
363 return current
364 if not expect.matches(current):
365 raise ReleaseSafetyError(
366 f"stale {verb} request: {environment} is now {_describe(current)}, not the observed "
367 f"{'absent' if expect.is_absent else f'{expect.version} activated {expect.activated_at}'}; "
368 "the pointer changed since you looked -- re-inspect before deciding"
369 )
370 previous = None if current is None else ReleaseRef(current.version, current.sha256)
371 new = ReleasePointer(environment, target.version, target.sha256, previous, now.astimezone(timezone.utc).isoformat())
372 try:
373 return _swap_pointer(storage, new, expected_token=token)
374 except ReleaseSafetyError:
375 winner, _ = _read_pointer_versioned(storage, environment)
376 if winner is not None and (winner.version, winner.sha256) == (target.version, target.sha256):
377 return winner
378 raise
379
380
381 def activate(
382 storage: Storage,
383 environment: str,
384 version: str,
385 sha256: str,
386 *,
387 expect: ExpectedPointer,
388 now: datetime,
389 approve_production: bool = False,
390 ) -> ReleasePointer:
391 """Point *environment* at an already-published (version, sha256), given the pointer state the operator observed.
392
393 *expect* is required: ``ExpectedPointer.absent()`` for a first activation, otherwise the exact
394 (version, sha256, activated_at) read from ``pointers/<env>.json``. Writes only that pointer.
395 """
396 _check_environment(environment)
397 try:
398 version, sha256 = validate_version(version), validate_sha256(sha256)
399 except ReleaseSelectionError as exc:
400 raise ReleaseSafetyError(str(exc)) from exc
401 expect = _validated_expectation(expect)
402 _require_production_approval(environment, approve_production)
403 _verified_release(storage, version, sha256)
404 if environment == "production":
405 staging = _read_pointer(storage, "staging")
406 if staging is None or (staging.version, staging.sha256) != (version, sha256):
407 raise ReleaseSafetyError(
408 f"production may only take what staging currently runs; staging is "
409 f"{'unset' if staging is None else staging.version}, requested {version}"
410 )
411 return _move_pointer(storage, environment, ReleaseRef(version, sha256), expect, now=now, verb="activation")
412
413
414 def rollback(
415 storage: Storage,
416 environment: str,
417 *,
418 to_version: str,
419 to_sha256: str,
420 expect_version: str,
421 expect_sha256: str,
422 expect_activated_at: str,
423 now: datetime,
424 approve_production: bool = False,
425 ) -> ReleasePointer:
426 """Restore *environment* to the named published release, given the pointer state the operator observed.
427
428 Never a blind swap: see ``_move_pointer``. A missing or malformed pointer is refused (there is
429 nothing to roll back from), as is an unverified target.
430 """
431 _check_environment(environment)
432 try:
433 to_version, to_sha256 = validate_version(to_version), validate_sha256(to_sha256)
434 expect_version, expect_sha256 = validate_version(expect_version), validate_sha256(expect_sha256)
435 except ReleaseSelectionError as exc:
436 raise ReleaseSafetyError(str(exc)) from exc
437 _require_production_approval(environment, approve_production)
438 if _read_pointer(storage, environment) is None:
439 raise ReleaseSafetyError(f"{environment} has no release pointer; refusing to roll back")
440 _verified_release(storage, to_version, to_sha256)
441 return _move_pointer(
442 storage, environment, ReleaseRef(to_version, to_sha256),
443 ExpectedPointer(expect_version, expect_sha256, expect_activated_at), now=now, verb="rollback",
444 )
445
446
447 # ── cleanup ───────────────────────────────────────────────────────────────────
448
449
450 @dataclass(frozen=True)
451 class CleanupPlan:
452 deletions: list[str]
453 preserved: dict[str, str] = field(default_factory=dict)
454 blocked: str | None = None
455
456 @property
457 def digest(self) -> str:
458 return _sha("\n".join(self.deletions).encode())
459
460
461 def _inventory(storage: Storage) -> tuple[dict[str, str] | str, dict[str, str]]:
462 """(protected version -> reason | blocked-reason, verified version -> '').
463
464 Returns a ``str`` as first element when ownership is ambiguous, in which case
465 nothing may be deleted.
466 """
467 protected: dict[str, str] = {}
468 for env in ENVIRONMENTS:
469 try:
470 pointer = _read_pointer(storage, env)
471 except ReleaseSafetyError as exc:
472 return str(exc), {}
473 if pointer is None:
474 return f"{_pointer_key(env)} is missing: cannot establish what {env} depends on", {}
475 protected.setdefault(pointer.version, f"active in {env}")
476 if pointer.previous is not None:
477 protected.setdefault(pointer.previous.version, f"rollback target of {env}")
478 verified: dict[str, str] = {}
479 for key in storage.list_keys("muse-"):
480 if not key.endswith(".tar.gz"):
481 continue
482 raw = key.removeprefix("muse-").removesuffix(".tar.gz")
483 try:
484 version = validate_version(raw)
485 except ReleaseSelectionError:
486 continue # not a release artifact name: never a candidate
487 record = _read_record(storage, version)
488 if record is not None and _sha(storage.read(key)) == record["sha256"]:
489 verified[version] = record["sha256"]
490 return protected, verified
491
492
493 def plan_cleanup(storage: Storage, *, keep: int) -> CleanupPlan:
494 """Pure: compute (never perform) the deletion set. ``StorageUnavailable`` propagates."""
495 protected, verified = _inventory(storage)
496 if isinstance(protected, str):
497 return CleanupPlan(deletions=[], preserved={}, blocked=protected)
498 preserved: dict[str, str] = {}
499 for key in storage.list_keys("muse-"):
500 if key.endswith(".tar.gz"):
501 version = key.removeprefix("muse-").removesuffix(".tar.gz")
502 if version not in verified:
503 preserved[key] = "unverified: no valid record matching the stored bytes"
504 for version, reason in protected.items():
505 preserved[_artifact_key(version)] = reason
506 candidates = stale_releases([_artifact_key(v) for v in verified], keep) # oldest first, PEP 440
507 deletions: list[str] = []
508 for name in candidates:
509 version = name.removeprefix("muse-").removesuffix(".tar.gz")
510 if version in protected:
511 continue
512 deletions += [_record_key(version), name]
513 for version in verified:
514 if _artifact_key(version) not in deletions and _artifact_key(version) not in preserved:
515 preserved[_artifact_key(version)] = f"within the newest {keep}"
516 return CleanupPlan(deletions=deletions, preserved=preserved, blocked=None)
517
518
519 @dataclass(frozen=True)
520 class CleanupGuidance:
521 """What the operator may do next. ``confirm_args`` is set only when execution would actually be allowed."""
522
523 state: str # "executable" | "blocked" | "empty"
524 message: str
525 confirm_args: str | None = None
526
527
528 def cleanup_guidance(plan: CleanupPlan) -> CleanupGuidance:
529 """Pure. Never suggests ``--execute`` for a plan that ``execute_cleanup`` would refuse or that has nothing to delete."""
530 unverified = sorted(k for k, why in plan.preserved.items() if why.startswith("unverified"))
531 protected = sorted(k for k, why in plan.preserved.items() if why.startswith(("active in", "rollback target")))
532 notes = []
533 if protected:
534 notes.append(f"{len(protected)} release(s) protected as active/rollback targets")
535 if unverified:
536 notes.append(f"{len(unverified)} unverified artifact(s) preserved (no valid record matching their bytes): {', '.join(unverified)}")
537 suffix = ("; " + "; ".join(notes)) if notes else ""
538 if plan.blocked:
539 return CleanupGuidance("blocked", f"BLOCKED: nothing can be deleted until this is resolved: {plan.blocked}{suffix}")
540 if not plan.deletions:
541 return CleanupGuidance("empty", f"NOTHING TO DELETE: every release is protected, unverified or within the retention window{suffix}")
542 return CleanupGuidance(
543 "executable",
544 f"DRY RUN: nothing deleted. {len(plan.deletions)} object(s) would be deleted{suffix}. To delete exactly this set: --execute --confirm {plan.digest}",
545 f"--execute --confirm {plan.digest}",
546 )
547
548
549 def execute_cleanup(storage: Storage, plan: CleanupPlan, *, confirm: str) -> list[str]:
550 """Delete exactly *plan*, only if *confirm* is its digest and every target is still provably safe."""
551 if plan.blocked:
552 raise ReleaseSafetyError(f"cleanup is blocked: {plan.blocked}")
553 if confirm != plan.digest:
554 raise ReleaseSafetyError("confirm value does not match the digest of this deletion set; nothing deleted")
555 protected, verified = _inventory(storage)
556 if isinstance(protected, str):
557 raise ReleaseSafetyError(f"cleanup is blocked: {protected}")
558 for key in plan.deletions:
559 version = key.removeprefix("muse-").removesuffix(".tar.gz").removesuffix(".release.json")
560 if key not in (_artifact_key(version), _record_key(version)) or version not in verified or version in protected:
561 raise ReleaseSafetyError(f"stale or unauthorized deletion target {key}: not a verified, unprotected release; nothing deleted")
562 for key in plan.deletions:
563 storage.delete(key)
564 return list(plan.deletions)
565
566
567 # ── backends ──────────────────────────────────────────────────────────────────
568
569
570 class DirStorage:
571 """Directory-backed storage (rehearsals and tests)."""
572
573 def __init__(self, root: Path) -> None:
574 self.root = root
575
576 def _p(self, key: str) -> Path:
577 return self.root / key
578
579 def exists(self, key: str) -> bool:
580 return self._p(key).is_file()
581
582 def read(self, key: str) -> bytes:
583 return self._p(key).read_bytes()
584
585 def list_keys(self, prefix: str = "") -> list[str]:
586 return sorted(str(p.relative_to(self.root)) for p in self.root.rglob("*") if p.is_file() and str(p.relative_to(self.root)).startswith(prefix))
587
588 def put_new(self, key: str, data: bytes) -> None:
589 path = self._p(key)
590 path.parent.mkdir(parents=True, exist_ok=True)
591 try:
592 with path.open("xb") as fh:
593 fh.write(data)
594 except FileExistsError as exc:
595 raise ObjectExists(key) from exc
596
597 def read_versioned(self, key: str) -> tuple[bytes, str]:
598 try:
599 return self._p(key).read_bytes(), self._token(key)
600 except FileNotFoundError as exc:
601 raise KeyError(key) from exc
602
603 def _token(self, key: str) -> str:
604 """Identity of this exact write: content AND inode/mtime, so rewriting identical bytes (ABA) still invalidates it."""
605 path = self._p(key)
606 st = path.stat()
607 return f"{_sha(path.read_bytes())}:{st.st_ino}:{st.st_mtime_ns}"
608
609 def put_if_match(self, key: str, data: bytes, token: str) -> None:
610 """Replace iff the content still hashes to *token*; serialised by an exclusive lock on the root."""
611 import fcntl
612
613 path = self._p(key)
614 self.root.mkdir(parents=True, exist_ok=True)
615 with (self.root / ".lock").open("a") as lock:
616 fcntl.flock(lock, fcntl.LOCK_EX)
617 try:
618 current = self._token(key)
619 except FileNotFoundError as exc:
620 raise StaleState(key) from exc
621 if current != token:
622 raise StaleState(key)
623 tmp = path.with_name(path.name + ".tmp")
624 tmp.write_bytes(data)
625 tmp.replace(path)
626
627 def delete(self, key: str) -> None:
628 self._p(key).unlink()
629
630
631 class S3Storage:
632 """S3 backend. Create-only writes use ``If-None-Match: *`` so S3 itself refuses overwrites."""
633
634 def __init__(self, bucket: str, client: Any | None = None, region: str = "us-east-1") -> None:
635 if client is None:
636 import boto3
637
638 client = boto3.client("s3", region_name=region)
639 self.bucket, self.client = bucket, client
640
641 def _call(self, fn: Any, *, on_conflict: type[StorageError] = ObjectExists, **kwargs: Any) -> Any:
642 from botocore.exceptions import BotoCoreError, ClientError
643
644 try:
645 return fn(Bucket=self.bucket, **kwargs)
646 except ClientError as exc:
647 code = str(exc.response.get("Error", {}).get("Code", ""))
648 if code in ("PreconditionFailed", "ConditionalRequestConflict", "412", "409"):
649 raise on_conflict(kwargs.get("Key", "")) from exc
650 if code in ("404", "NoSuchKey", "NotFound"):
651 raise KeyError(kwargs.get("Key", "")) from exc
652 raise StorageUnavailable(f"S3 error {code or exc}") from exc
653 except BotoCoreError as exc:
654 raise StorageUnavailable(str(exc)) from exc
655
656 def exists(self, key: str) -> bool:
657 try:
658 self._call(self.client.head_object, Key=key)
659 except KeyError:
660 return False
661 return True
662
663 def read(self, key: str) -> bytes:
664 return bytes(self._call(self.client.get_object, Key=key)["Body"].read())
665
666 def list_keys(self, prefix: str = "") -> list[str]:
667 keys: list[str] = []
668 token: str | None = None
669 while True:
670 kwargs: dict[str, Any] = {"Prefix": prefix}
671 if token:
672 kwargs["ContinuationToken"] = token
673 page = self._call(self.client.list_objects_v2, **kwargs)
674 keys += [o["Key"] for o in page.get("Contents", [])]
675 if not page.get("IsTruncated"):
676 return sorted(keys)
677 token = page["NextContinuationToken"]
678
679 def put_new(self, key: str, data: bytes) -> None:
680 self._call(self.client.put_object, Key=key, Body=data, IfNoneMatch="*")
681
682 def read_versioned(self, key: str) -> tuple[bytes, str]:
683 obj = self._call(self.client.get_object, Key=key)
684 etag = obj.get("ETag")
685 if not isinstance(etag, str) or not etag:
686 raise StorageUnavailable(f"S3 returned no ETag for {key}; cannot make a conditional write")
687 return bytes(obj["Body"].read()), etag
688
689 def put_if_match(self, key: str, data: bytes, token: str) -> None:
690 """Conditional replace (``If-Match``). A key that vanished (404) is also stale, never recreated."""
691 try:
692 self._call(self.client.put_object, on_conflict=StaleState, Key=key, Body=data, IfMatch=token)
693 except KeyError as exc:
694 raise StaleState(key) from exc
695
696 def delete(self, key: str) -> None:
697 self._call(self.client.delete_object, Key=key)
698
699
700 # ── CLI ───────────────────────────────────────────────────────────────────────
701
702
703 def main(argv: list[str] | None = None) -> int:
704 parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
705 where = parser.add_mutually_exclusive_group(required=True)
706 where.add_argument("--bucket", help="S3 release bucket")
707 where.add_argument("--dir", type=Path, help="local directory acting as the bucket (rehearsal)")
708 sub = parser.add_subparsers(dest="command", required=True)
709
710 pub = sub.add_parser("publish")
711 pub.add_argument("--artifact", type=Path, required=True)
712 pub.add_argument("--report", type=Path, required=True)
713 pub.add_argument("--muse-repo", type=Path, required=True, help="source checkout the gates ran against; observed again now")
714 act = sub.add_parser("activate")
715 act.add_argument("--env", required=True)
716 act.add_argument("--version", required=True)
717 act.add_argument("--sha256", required=True)
718 act.add_argument("--approve-production", action="store_true")
719 seen = act.add_mutually_exclusive_group(required=True)
720 seen.add_argument("--expect-absent", action="store_true", help="the pointer must not exist yet (first activation)")
721 seen.add_argument("--expect-version", help="version the pointer showed when you decided (with --expect-sha256, --expect-activated-at)")
722 act.add_argument("--expect-sha256")
723 act.add_argument("--expect-activated-at")
724 rb = sub.add_parser("rollback")
725 rb.add_argument("--env", required=True)
726 rb.add_argument("--to-version", required=True)
727 rb.add_argument("--to-sha256", required=True)
728 rb.add_argument("--expect-version", required=True, help="version the pointer showed when you decided")
729 rb.add_argument("--expect-sha256", required=True)
730 rb.add_argument("--expect-activated-at", required=True)
731 rb.add_argument("--approve-production", action="store_true")
732 cl = sub.add_parser("cleanup", help="dry-run unless --execute AND --confirm <digest>")
733 cl.add_argument("--keep", type=int, required=True)
734 cl.add_argument("--execute", action="store_true")
735 cl.add_argument("--confirm", default="")
736 args = parser.parse_args(argv)
737
738 storage: Storage = S3Storage(args.bucket) if args.bucket else DirStorage(args.dir)
739 now = datetime.now(timezone.utc)
740 try:
741 if args.command == "publish":
742 report = args.report.read_text() if args.report.is_file() else None
743 result = publish(storage, args.artifact, report, now=now, checkout=observe_checkout(args.muse_repo))
744 print(json.dumps({"status": result.status, "version": result.version, "sha256": result.sha256}))
745 elif args.command == "activate":
746 if args.expect_absent:
747 expect = ExpectedPointer.absent()
748 elif args.expect_sha256 and args.expect_activated_at:
749 expect = ExpectedPointer(args.expect_version, args.expect_sha256, args.expect_activated_at)
750 else:
751 raise ReleaseSafetyError("--expect-version needs --expect-sha256 and --expect-activated-at")
752 print(activate(storage, args.env, args.version, args.sha256, expect=expect, now=now, approve_production=args.approve_production).to_json())
753 elif args.command == "rollback":
754 print(rollback(
755 storage, args.env, to_version=args.to_version, to_sha256=args.to_sha256,
756 expect_version=args.expect_version, expect_sha256=args.expect_sha256,
757 expect_activated_at=args.expect_activated_at, now=now, approve_production=args.approve_production,
758 ).to_json())
759 else:
760 plan = plan_cleanup(storage, keep=args.keep)
761 print(json.dumps({"blocked": plan.blocked, "deletions": plan.deletions, "preserved": plan.preserved, "digest": plan.digest}, indent=2))
762 guidance = cleanup_guidance(plan)
763 if guidance.state == "blocked":
764 print(guidance.message, file=sys.stderr)
765 return 1 # a blocked cleanup is a refusal, not a dry run to be confirmed
766 if guidance.state == "empty":
767 print(guidance.message, file=sys.stderr)
768 elif not args.execute:
769 print(guidance.message, file=sys.stderr)
770 else:
771 execute_cleanup(storage, plan, confirm=args.confirm)
772 print(f"deleted {len(plan.deletions)} objects", file=sys.stderr)
773 except (GateError, ProvenanceError, ReleaseSafetyError, StorageError) as exc:
774 print(f"REFUSED: {exc}", file=sys.stderr)
775 return 1
776 return 0
777
778
779 if __name__ == "__main__":
780 raise SystemExit(main())
File History 6 commits
sha256:0ddcb29475cfe996169320691ffb2c5705e510191a4a944487df867959d81b36 fix(release): #275 tag the verified source revision, signed… Sonnet 5.5 minor ⚠ 7 days ago
sha256:22ea76418f13ef089b10088cb0c77fe3cd3f3da50b325cb412073c7f2f46f7f5 fix(release): cleanup shows an execution command only when … Opus 5.5 patch 12 days ago
sha256:675003834b19b109f8cb126e543a064a7bd6256930dd4a80ffcfe87c6eff3f17 fix(release): idempotent concurrent publish (D3) and compar… Opus 5.5 minor ⚠ 12 days ago
sha256:04db68e43d9007348dbd726b2a3e52f73e83c5646a4511c07e19cb9a66e28b5f fix(release): gate provenance is observed from the checkout… Opus 5.5 minor ⚠ 12 days ago
sha256:9f814406166bc157b00dfd4078fb4516ad46e9844628da6bb3823e8448eca1e9 fix(release): rollback is an explicit, idempotent, stale-pr… Opus 5.5 minor ⚠ 12 days ago
sha256:6bdfa0ed7d0cfe13d40be53b23ab86de47653bc9a0f796b820fd3486b9abee8c feat(release): create-only publish, separate activate/rollb… Opus 5.5 patch 13 days ago