gabriel / musehub public
release_identity.py python
195 lines 9.7 KB
Raw
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