release_identity.py
python
sha256:dd6439fc2ba2a90b18964d0bd1e112f6155992872f09024de3a7962cb8911441
fix(release): release_identity runs on the operator's plain…
Opus 5.5
minor
⚠ breaking
5 days ago
| 1 | """MuseHub release identity: the one place a build's version identity and release manifest are derived. |
| 2 | |
| 3 | A MuseHub build is identified by its declared version, not by an operational counter: |
| 4 | |
| 5 | * the **declaration** is ``[project].version`` in ``pyproject.toml``, canonical PEP 440 (``0.2.3rc1``); |
| 6 | * its **SemVer** form comes from :func:`deploy.pep440_to_semver_tag.pep440_to_semver_tag` (``v0.2.3-rc.1``); the |
| 7 | image carries it without the ``v`` (``0.2.3-rc.1``) as a create-only tag next to the existing |
| 8 | ``<revision8>-<timestamp>`` tag, which stays the primary, rollback-compatible identity; |
| 9 | * the **release manifest** (``musehub-<semver>.release.json``) records what was built: version, full source revision, |
| 10 | branch, build time, provenance, and per component the platform and image digest. It is written once and never |
| 11 | changed. Where a build is deployed is recorded separately, by the deploy evidence, never in this file. |
| 12 | |
| 13 | See ``docs/versioning.md`` (MuseHub release identity). |
| 14 | |
| 15 | Usage:: |
| 16 | |
| 17 | python -m deploy.release_identity version <pyproject.toml> |
| 18 | python -m deploy.release_identity manifest --pyproject P --revision sha256:<64> --branch dev \\ |
| 19 | --built-at 2026-11-11T19:30:00Z --image-tag <rev8>-<ts> --engine-revision sha256:<64> \\ |
| 20 | --registry-digest <registry>=sha256:<64> [...] --environment staging [...] --out FILE |
| 21 | """ |
| 22 | from __future__ import annotations |
| 23 | |
| 24 | import argparse |
| 25 | import datetime as dt |
| 26 | import json |
| 27 | import os |
| 28 | import re |
| 29 | import sys |
| 30 | from pathlib import Path |
| 31 | |
| 32 | # Standard library only: deploy/push.sh runs this with the operator's plain ``python3``, which need not have |
| 33 | # ``packaging``. The conversion below must equal deploy/pep440_to_semver_tag.py for every input both accept; that is |
| 34 | # pinned by tests/test_release_identity.py (TestSingleSourceOfTruth), which runs where ``packaging`` is installed. |
| 35 | |
| 36 | SCHEMA = 1 |
| 37 | PRODUCT = "musehub" |
| 38 | PLATFORM = "linux/amd64" |
| 39 | #: Web/API and the background worker run the same image; each keeps its own entry so a later split needs no schema change. |
| 40 | COMPONENTS = ("api", "worker") |
| 41 | _REVISION = re.compile(r"sha256:[0-9a-f]{64}") |
| 42 | _DIGEST = re.compile(r"sha256:[0-9a-f]{64}") |
| 43 | _IMAGE_TAG = re.compile(r"[0-9a-f]{8}-[0-9]{14}") |
| 44 | _DOCKER_TAG = re.compile(r"[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}") |
| 45 | _N = r"(?:0|[1-9][0-9]*)" |
| 46 | #: Canonical PEP 440 spelling (what ``str(packaging.version.Version(v))`` returns): lower case, no separators or ``v``. |
| 47 | _CANONICAL_PEP440 = re.compile( |
| 48 | rf"(?:{_N}!)?{_N}(?:\.{_N})*(?:(?:a|b|rc){_N})?(?:\.post{_N})?(?:\.dev{_N})?(?:\+[a-z0-9]+(?:\.[a-z0-9]+)*)?" |
| 49 | ) |
| 50 | #: The releasable subset: MAJOR.MINOR.PATCH with an optional a/b/rc number (no epoch, post, dev or local part). |
| 51 | _RELEASE = re.compile(rf"({_N})\.({_N})\.({_N})(?:(a|b|rc)({_N}))?") |
| 52 | #: Must equal deploy/pep440_to_semver_tag.py (bases whose rc tags predate the dotted form). |
| 53 | _HISTORICAL_RC_BASES = frozenset({(0, 2, 0), (0, 2, 1)}) |
| 54 | _STAGE_NAMES = {"a": "alpha", "b": "beta", "rc": "rc"} |
| 55 | |
| 56 | |
| 57 | class ReleaseIdentityError(ValueError): |
| 58 | """The declaration or a manifest input cannot name a release.""" |
| 59 | |
| 60 | |
| 61 | def declared_version(pyproject: Path) -> str: |
| 62 | """The canonical PEP 440 ``[project].version`` of *pyproject*; refuses a non-canonical spelling.""" |
| 63 | # No tomllib: push.sh's python3 may predate 3.11 (deploy/build_context.py runs on 3.9). The declaration is one |
| 64 | # double-quoted ``version = "..."`` line inside the [project] table, which is all this reads. |
| 65 | try: |
| 66 | text = pyproject.read_text(encoding="utf-8") |
| 67 | except OSError as exc: |
| 68 | raise ReleaseIdentityError(f"{pyproject}: unreadable ({exc})") from exc |
| 69 | section = re.search(r"^\[project\][ \t]*$(.*?)(?=^\[|\Z)", text, re.M | re.S) |
| 70 | found = re.findall(r'^version[ \t]*=[ \t]*"([^"\n]*)"[ \t]*(?:#.*)?$', section.group(1), re.M) if section else [] |
| 71 | if len(found) != 1: |
| 72 | raise ReleaseIdentityError(f"{pyproject}: expected exactly one double-quoted version in [project], found {len(found)}") |
| 73 | raw = found[0] |
| 74 | if not _CANONICAL_PEP440.fullmatch(raw): |
| 75 | raise ReleaseIdentityError(f"{pyproject}: {raw!r} is not a canonical PEP 440 version") |
| 76 | return raw |
| 77 | |
| 78 | |
| 79 | def identity(pep440: str) -> dict[str, str]: |
| 80 | """``{pep440, semver, tag, image_tag}`` for a release version. Dev, post and local versions have no release identity.""" |
| 81 | m = _RELEASE.fullmatch(pep440) |
| 82 | if not m: |
| 83 | raise ReleaseIdentityError( |
| 84 | f"{pep440!r} cannot be released: only canonical MAJOR.MINOR.PATCH with an optional a/b/rc number has a SemVer form" |
| 85 | ) |
| 86 | major, minor, micro, stage, number = m.groups() |
| 87 | base = f"{major}.{minor}.{micro}" |
| 88 | if stage is None: |
| 89 | semver = base |
| 90 | elif stage == "rc" and (int(major), int(minor), int(micro)) in _HISTORICAL_RC_BASES: |
| 91 | semver = f"{base}-rc{number}" |
| 92 | else: |
| 93 | semver = f"{base}-{_STAGE_NAMES[stage]}.{number}" |
| 94 | tag = f"v{semver}" |
| 95 | if not _DOCKER_TAG.fullmatch(semver): |
| 96 | raise ReleaseIdentityError(f"SemVer {semver!r} is not a valid image tag") |
| 97 | return {"pep440": pep440, "semver": semver, "tag": tag, "image_tag": semver} |
| 98 | |
| 99 | |
| 100 | def build_manifest( |
| 101 | *, |
| 102 | pep440: str, |
| 103 | revision: str, |
| 104 | branch: str, |
| 105 | built_at: str, |
| 106 | image_tag: str, |
| 107 | engine_revision: str, |
| 108 | registry_digests: dict[str, str], |
| 109 | environments: list[str], |
| 110 | repository: str = "musehub/musehub", |
| 111 | ) -> dict[str, object]: |
| 112 | """The immutable manifest of one build. Every field is validated; nothing is defaulted silently.""" |
| 113 | ident = identity(pep440) |
| 114 | for name, value, pattern in (("revision", revision, _REVISION), ("engine revision", engine_revision, _REVISION)): |
| 115 | if not pattern.fullmatch(value): |
| 116 | raise ReleaseIdentityError(f"{name} {value!r} is not sha256:<64 hex>") |
| 117 | if not _IMAGE_TAG.fullmatch(image_tag) or not revision.removeprefix("sha256:").startswith(image_tag[:8]): |
| 118 | raise ReleaseIdentityError(f"image tag {image_tag!r} is not <first 8 of {revision}>-<14-digit timestamp>") |
| 119 | try: |
| 120 | when = dt.datetime.strptime(built_at, "%Y-%m-%dT%H:%M:%SZ") |
| 121 | except ValueError as exc: |
| 122 | raise ReleaseIdentityError(f"built_at {built_at!r} is not YYYY-MM-DDTHH:MM:SSZ") from exc |
| 123 | if not branch or not registry_digests or not environments: |
| 124 | raise ReleaseIdentityError("branch, at least one registry digest and at least one environment are required") |
| 125 | for registry, digest in registry_digests.items(): |
| 126 | if not registry or not _DIGEST.fullmatch(digest): |
| 127 | raise ReleaseIdentityError(f"registry digest {registry!r}={digest!r} is not <registry>=sha256:<64 hex>") |
| 128 | images = [ |
| 129 | {"registry": reg, "repository": repository, "tag": image_tag, "semver_tag": ident["image_tag"], "digest": dig} |
| 130 | for reg, dig in sorted(registry_digests.items()) |
| 131 | ] |
| 132 | os_name, arch = PLATFORM.split("/") |
| 133 | return { |
| 134 | "schema": SCHEMA, |
| 135 | "product": PRODUCT, |
| 136 | "version": {"pep440": ident["pep440"], "semver": ident["semver"], "tag": ident["tag"]}, |
| 137 | "source": {"revision": revision, "branch": branch}, |
| 138 | "built_at": when.strftime("%Y-%m-%dT%H:%M:%SZ"), |
| 139 | "provenance": {"builder": "deploy/push.sh", "muse_engine_revision": engine_revision}, |
| 140 | "components": [{"name": c, "os": os_name, "arch": arch, "images": images} for c in COMPONENTS], |
| 141 | "intended_environments": sorted(set(environments)), |
| 142 | } |
| 143 | |
| 144 | |
| 145 | def write_once(manifest: dict[str, object], out: Path) -> str: |
| 146 | """Write *manifest* to *out* create-only. Re-writing identical bytes is a no-op; different bytes are refused.""" |
| 147 | text = json.dumps(manifest, indent=2, sort_keys=True) + "\n" |
| 148 | if out.exists(): |
| 149 | if out.read_text(encoding="utf-8") == text: |
| 150 | return "unchanged" |
| 151 | raise ReleaseIdentityError(f"{out} already records a different build; a release version is never reused") |
| 152 | out.parent.mkdir(parents=True, exist_ok=True) |
| 153 | tmp = out.with_name(f".{out.name}.tmp") |
| 154 | tmp.write_text(text, encoding="utf-8") |
| 155 | os.replace(tmp, out) |
| 156 | return "written" |
| 157 | |
| 158 | |
| 159 | def main(argv: list[str] | None = None) -> int: |
| 160 | parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) |
| 161 | sub = parser.add_subparsers(dest="cmd", required=True) |
| 162 | v = sub.add_parser("version", help="print the release identity of a pyproject.toml as JSON") |
| 163 | v.add_argument("pyproject", type=Path) |
| 164 | m = sub.add_parser("manifest", help="write the immutable release manifest of one build") |
| 165 | m.add_argument("--pyproject", type=Path, required=True) |
| 166 | m.add_argument("--revision", required=True) |
| 167 | m.add_argument("--branch", required=True) |
| 168 | m.add_argument("--built-at", required=True) |
| 169 | m.add_argument("--image-tag", required=True) |
| 170 | m.add_argument("--engine-revision", required=True) |
| 171 | m.add_argument("--registry-digest", action="append", default=[], metavar="REGISTRY=DIGEST") |
| 172 | m.add_argument("--environment", action="append", default=[]) |
| 173 | m.add_argument("--out", type=Path, required=True) |
| 174 | args = parser.parse_args(argv) |
| 175 | try: |
| 176 | if args.cmd == "version": |
| 177 | print(json.dumps(identity(declared_version(args.pyproject)), sort_keys=True)) |
| 178 | return 0 |
| 179 | digests = dict(item.split("=", 1) for item in args.registry_digest if "=" in item) |
| 180 | if len(digests) != len(args.registry_digest): |
| 181 | raise ReleaseIdentityError("--registry-digest must be REGISTRY=sha256:<64 hex>") |
| 182 | manifest = build_manifest( |
| 183 | pep440=declared_version(args.pyproject), revision=args.revision, branch=args.branch, |
| 184 | built_at=args.built_at, image_tag=args.image_tag, engine_revision=args.engine_revision, |
| 185 | registry_digests=digests, environments=args.environment, |
| 186 | ) |
| 187 | print(f"{write_once(manifest, args.out)}: {args.out}") |
| 188 | return 0 |
| 189 | except ReleaseIdentityError as exc: |
| 190 | print(f"release identity refused: {exc}", file=sys.stderr) |
| 191 | return 1 |
| 192 | |
| 193 | |
| 194 | if __name__ == "__main__": |
| 195 | sys.exit(main()) |
File History
2 commits
sha256:dd6439fc2ba2a90b18964d0bd1e112f6155992872f09024de3a7962cb8911441
fix(release): release_identity runs on the operator's plain…
Opus 5.5
minor
⚠
5 days ago
sha256:c8e165f9c0e0c8c2f888cea908ff5b6b51548acd1b6dbdf7ed11a06211cbe0eb
feat(release): MuseHub builds carry a SemVer release identi…
Opus 5.5
minor
⚠
5 days ago