1"""Publish, probe, tag: the release train's receipt-cutting half.
3Runs where the release PR's squash landed, discovery reads the ref
4and nothing else: the members and their versions are the release's
5member list as committed at the ref. Names and versions come from the
6same place on purpose: reading names from the commit and versions
7from the working tree would pair this release's members with
8whatever a later release left in the tree, and the ``--ref``
9recovery runs from exactly such a checkout. The squash title is
10presentation, rebuilt from the same list, never parsed.
12The wave: a member becomes eligible when every in-set dependency it
13floors on has its receipt tag cut, and every eligible member runs
14its publish, index probe, tag chain concurrently. A failed member
15stops only its dependents; siblings complete and keep their tags,
16and a re-run walks past everything already tagged, the
17duplicate-tolerant publish making that safe.
18"""
20from __future__ import annotations
22import re
23import threading
24from collections.abc import Callable
25from concurrent.futures import ThreadPoolExecutor
26from dataclasses import dataclass
27from pathlib import Path
28from typing import TYPE_CHECKING, Protocol
30import livery.footman as footman
31from livery import git
32from livery.footman import fail
33from livery.workshop import _lifecycle
34from livery.workshop._packages import Package, discover_packages
36if TYPE_CHECKING:
37 from livery.workshop._registries import RegistryTarget
39#: The release set's own record, committed on the release branch by
40#: prepare: every member's directory, name and version. Discovery,
41#: the title check and the recovery read it at the squash, so a
42#: recovery re-prepare whose stamps are already on the base (and so
43#: touch nothing else) still names every member.
44MANIFEST = ".release-manifest.json"
47def read_manifest(text: str) -> tuple[tuple[str, str], ...] | None:
48 """(package dir, version) pairs from manifest *text*, or None.
50 None for unreadable content, which the caller refuses: without
51 the list there is no record of what the release contains.
52 """
53 import json
55 try:
56 data = json.loads(text)
57 members = data["members"]
58 pairs = tuple((str(m["dir"]), str(m["version"])) for m in members)
59 except (ValueError, KeyError, TypeError):
60 return None
61 return pairs or None
64#: How long a member waits for the index to serve its version.
65PROBE_TIMEOUT = 300.0
66PROBE_POLL = 5.0
69class Registry(Protocol):
70 """The one probe the wave needs; livery.forge.SimpleRegistry fits."""
72 def versions(self, name: str) -> tuple[str, ...]:
73 """The published versions of *name*."""
74 ...
77@dataclass(frozen=True)
78class Receipt:
79 """One member's publish outcome."""
81 package: Package
82 version: str
83 tag: str
84 published: bool # False when the duplicate tolerance skipped it
87def discover_release(root: Path, ref: str) -> tuple[tuple[Package, str], ...]:
88 """The members the release squash at *ref* releases, each with its version.
90 The members and their versions are the release's member list,
91 ``.release-manifest.json``, as committed at *ref*: the record the
92 release branch writes when it prepares the set. They come in
93 release order, every dependency before its dependents
94 ([livery.workshop.order_topologically][]). A rider file in the
95 squash changes nothing here, which is what makes hand-editing a
96 release branch safe.
98 Args:
99 root: The workspace root.
100 ref: The commit whose member list is read, as git names it.
102 Returns:
103 Each released member and the version the list states for it.
105 Raises:
106 Failed: when the commit carries no readable member list, since
107 it is then no release squash, naming the flag that points
108 the publish at the squash; and when the list names a member
109 the workspace does not hold.
110 """
111 from livery.workshop._graph import order_topologically
113 pairs = read_manifest(git.file_at(root, ref, MANIFEST))
114 if pairs is None:
115 fail(
116 f"this commit is not a release squash: it carries no readable"
117 f" {MANIFEST}, the member list a release branch commits. Publish"
118 " runs on the merge commit of a workflow.release PR; pass"
119 " --ref=<squash sha> when HEAD has moved past it."
120 )
121 listed = {p.member: p for p in discover_packages(root)}
122 chosen: list[Package] = []
123 stated: dict[str, str] = {}
124 for name, version in pairs:
125 member = listed.get(name)
126 if member is None:
127 fail(
128 f"the release manifest at {ref[:10]} names"
129 f" packages/{name}, which is not a workspace package"
130 )
131 chosen.append(member)
132 stated[member.path] = version
133 in_order = order_topologically(tuple(chosen))
134 return tuple((member, stated[member.path]) for member in in_order)
137_MINED_AT_RE = re.compile(r"^Mined-At: ([0-9a-f]{7,40})$", re.M)
140def mined_at(message: str) -> str:
141 """The mining point a release squash's *message* records, or ``""``.
143 The driver writes ``Mined-At: <sha>`` into the pull request body,
144 which becomes the squash's message at the merge. A commit without
145 the line is not a release squash: a branch's own stamp commit, or
146 a squash whose body was rewritten. The wave and the dispatch judge
147 a commit by this one rule.
148 """
149 match = _MINED_AT_RE.search(message)
150 return match.group(1) if match else ""
153def movement_check(root: Path, package: Package, ref: str) -> None:
154 """Refuse when commits the entry never saw ride in this squash.
156 The movement analysis's backstop. The driver records the mining
157 point in the squash body (``Mined-At: <sha>``), so the moved
158 range is exact: commits between the mining point and the squash's
159 parent touching this member's paths are code the stamped entry
160 does not cover. A squash without the line is not the driver's,
161 and publishing it is refused for the same reason.
162 """
163 point = mined_at(git.commit_message(root, ref))
164 if not point:164 ↛ 165line 164 didn't jump to line 165 because the condition on line 164 was never true
165 fail(
166 f"{package.name}: the squash at {ref[:10]} carries no Mined-At"
167 " line, so the movement backstop cannot run. Releases publish"
168 " only from workflow.release squashes; re-run the release to"
169 " produce one."
170 )
171 # The squash's first parent, spelled without a caret, which cmd.exe
172 # drops on its way to a git run through a `.cmd` launcher on Windows.
173 span = f"{point}..{ref}~1"
174 moved = git.log_paths(root, span, (f"packages/{package.member}",))
175 if moved:
176 listed = "\n".join(f" {s}" for s in moved)
177 fail(
178 f"{package.name}: commits the stamped entry never saw are in"
179 f" this squash:\n{listed}\n the release went stale after"
180 f" prepare. Re-run `{footman.prog()} workflow.release` to re-derive on the"
181 " moved base; publishing this squash would ship code the"
182 " changelog does not cover."
183 )
186def index_target(index_url: str, token: str) -> RegistryTarget:
187 """Make the python registry target an upload index names, *token* its credential.
189 The release train's wave hands it to each member that releases
190 python distributions, and the dev act to each member whose
191 distributions are all python's: both read and publish at the one
192 address the caller resolved.
193 """
194 from livery.workshop._registries import RegistryTarget
196 return RegistryTarget(
197 kind="python", url=index_url, publish_url=index_url, token=token
198 )
201def collected(package: Package) -> bool:
202 """Whether *package*'s ``dist/`` holds a file.
204 Inside CI a runner's checkout starts with no ``dist/``, so a file
205 there was collected from the artifact of a job that built the
206 member before the wave.
207 """
208 dist = package.directory / "dist"
209 return dist.is_dir() and any(path.is_file() for path in dist.iterdir())
212def probe_until_served(
213 registry: Registry,
214 name: str,
215 version: str,
216 *,
217 timeout: float = PROBE_TIMEOUT,
218 poll: float = PROBE_POLL,
219) -> None:
220 """Wait until the index serves *version*; the receipt's condition.
222 An accepted upload is not a served wheel, and the tag is a
223 receipt, so it waits on the probe, not the exit code.
224 """
225 from livery.workshop._verdict import FollowTimedOut, Pending, follow
227 def served() -> bool | Pending:
228 return True if version in registry.versions(name) else Pending()
230 try:
231 follow(
232 None,
233 served,
234 subject=f"{name} {version} on the index",
235 interval=poll,
236 timeout=timeout,
237 quiet=None,
238 retried=(),
239 )
240 except FollowTimedOut:
241 fail(
242 f"{name} {version} was uploaded but the index never served"
243 f" it within {timeout:.0f}s; re-run the publish once the"
244 " index settles, everything already tagged is walked past"
245 )
248def floor_probe(
249 package: Package,
250 by_path: dict[str, Package],
251 registry_for: Callable[[Package], Registry],
252 *,
253 coreleased: frozenset[str] = frozenset(),
254) -> None:
255 """Every declared floor must be servable before anything uploads.
257 A floor no index can satisfy strands every consumer at install
258 time, and refusing here is cheap where unpublishing is
259 impossible.
260 """
261 for edge in package.depends:
262 dependency = by_path.get(edge.path)
263 floor = getattr(edge, "floor", "")
264 if dependency is None or not floor:264 ↛ 265line 264 didn't jump to line 265 because the condition on line 264 was never true
265 continue
266 if f"{edge.path}/v{floor}" in coreleased:
267 continue # the wave itself serves this floor, receipts first
268 # The dependency's own registry: a floor across ecosystems (the
269 # extension on the library) lives in the conan target, not the
270 # python index.
271 served = registry_for(dependency).versions(dependency.name)
272 floor_key = tuple(int(x) for x in floor.split("."))
273 satisfied = any(
274 tuple(int(x) for x in v.split(".")) >= floor_key
275 for v in served
276 if v.replace(".", "").isdigit()
277 )
278 if not satisfied:
279 fail(
280 f"{package.name} floors {dependency.name} at {floor}, and"
281 " no served version satisfies it. Release"
282 f" {dependency.name} first (or in the same set), or the"
283 " uploaded wheel strands every consumer at install time."
284 )
287def cut_tag(root: Path, tag: str, ref: str) -> None:
288 """Cut and push the receipt, annotated, by name, idempotent."""
289 existing = git.tags(root)
290 if tag not in existing:
291 git.run(root, "tag", "-a", tag, ref, "-m", tag)
292 git.run(root, "push", "origin", tag)
295#: The words PyPI answers a new project's first upload with once one
296#: account has created as many projects as its limit allows for now.
297#: uv relays the server's message as text, and neither its exit code nor
298#: any structured output tells this refusal apart, so this match is the
299#: one place it is read; checked with uv 0.12.5.
300NEW_PROJECT_LIMIT = "Too many new projects created"
303def publish_release(
304 root: Path,
305 registry_for: Callable[[Package], Registry],
306 *,
307 ref: str = "",
308 index_url: str = "",
309 token: str = "",
310 probe_timeout: float = PROBE_TIMEOUT,
311 probe_poll: float = PROBE_POLL,
312 prebuilt: bool = False,
313) -> tuple[Receipt, ...]:
314 """The wave: verify, then publish, probe, tag per member.
316 Eligibility is dependency tags: a member starts when every in-set
317 dependency's receipt exists, independent members run abreast, a
318 failure stops only its dependents. Every read is *ref*-scoped.
319 Each member builds through its lifecycle's build, which judges the
320 tags of the wheels it writes, and publishes to the target of the
321 ecosystem its extensions release it to: the python target the
322 caller resolved, *index_url* with *token*, or the one the registry
323 ladder resolves for any other ecosystem. A member whose extensions
324 answer no registry, or more than one, refuses the wave before
325 anything uploads. With *prebuilt*, a member a job of the run builds
326 before the wave (the workspace's ``job-built-members`` answer) is
327 not built here: the wave publishes what the run collected into its
328 ``dist/``, and refuses one whose ``dist/`` holds nothing, naming
329 the job. Such a member's publish phase gets ``prebuilt`` true.
330 """
331 from livery.workshop._queries import JOB_BUILT_MEMBERS, answer
332 from livery.workshop._release import verify_release
334 resolved_ref = ref or git.head_sha(root)
335 discovered = discover_release(root, resolved_ref)
336 ordered = tuple(package for package, _version in discovered)
337 manifest = {package.name: version for package, version in discovered}
338 epoch = int(git.run(root, "log", "-1", "--format=%ct", resolved_ref).strip() or "0")
339 # Each member a job of the run builds before the wave, to the job.
340 built = answer(root, JOB_BUILT_MEMBERS) if prebuilt else {}
342 by_path = {p.path: p for p in discover_packages(root)}
343 coreleased = frozenset(f"{p.path}/v{manifest[p.name]}" for p in ordered)
344 from livery.workshop._registries import resolve_registry
346 # Each member goes to the target of the ecosystem its extensions
347 # release it to, and each target is resolved once, before anything
348 # uploads: a member with no registry or more than one, and a ladder
349 # that resolves no target, stop the wave while there is still nothing
350 # to undo. The python target is the one the caller resolved. A member
351 # that opts out of publishing needs no target and asks for none.
352 python_target = index_target(index_url, token)
353 targets = {python_target.kind: python_target}
354 releases_to = {p.path: _lifecycle.ecosystem(p) for p in ordered if p.publish}
355 for ecosystem in releases_to.values():
356 if ecosystem not in targets:
357 targets[ecosystem] = resolve_registry(root, ecosystem)
358 for package in ordered:
359 tag = f"{package.path}/v{manifest[package.name]}"
360 verify_release(root, tag, coreleased=coreleased)
361 movement_check(root, package, resolved_ref)
362 floor_probe(package, by_path, registry_for, coreleased=coreleased)
364 chosen = {p.path for p in ordered}
365 done: dict[str, threading.Event] = {p.path: threading.Event() for p in ordered}
366 receipts: dict[str, Receipt] = {}
367 failures: dict[str, BaseException] = {}
368 lock = threading.Lock()
369 # A registry may limit how many new projects one account creates in
370 # a period, as PyPI does. The members whose project the registry
371 # does not know yet upload one at a time, so a refusal stops at the
372 # first of them, and the ones after it do not try.
373 new_projects = [
374 p.name for p in ordered if p.publish and not registry_for(p).versions(p.name)
375 ]
376 first_upload = threading.Lock()
377 refused_new: list[str] = []
379 def _build_member(package: Package) -> None:
380 """Build the member, or trust what the job that builds it collected."""
381 job = built.get(package.path)
382 if job is None:
383 _lifecycle.build_release(package, root, epoch=epoch)
384 return
385 # The job built this member on each of its legs and the run
386 # collected what every leg made; a build here would replace
387 # that with what this runner's host alone can make.
388 if not collected(package):
389 fail(
390 f"{package.name}: --prebuilt, and dist/ holds nothing the {job}"
391 " job collected; re-run the release so that job builds it before"
392 " the wave"
393 )
395 def _first_upload(package: Package, version: str, target: RegistryTarget) -> bool:
396 """Upload a new project's first version, or name the limit that stops it."""
397 if refused_new:
398 raise SystemExit(
399 f"{package.name}: not uploaded: the registry already refused a"
400 f" new project in this wave ({refused_new[0]})"
401 )
402 try:
403 return _lifecycle.publish(
404 package,
405 root,
406 version=version,
407 target=target,
408 prebuilt=package.path in built,
409 )
410 except BaseException as exc:
411 if NEW_PROJECT_LIMIT not in str(exc):
412 raise
413 refused_new.append(package.name)
414 waiting = [name for name in new_projects if name not in receipts_named()]
415 raise SystemExit(
416 f"{package.name}: the registry refuses more new projects for now"
417 f" ({NEW_PROJECT_LIMIT}): it limits how many one account creates"
418 f" in a period. New projects still to create: {', '.join(waiting)}."
419 f" Re-dispatch later with `{footman.prog()} workflow.release.dispatch`;"
420 " the wave walks past what it already published."
421 ) from exc
423 def receipts_named() -> set[str]:
424 with lock:
425 return {receipt.package.name for receipt in receipts.values()}
427 def _run_member(package: Package) -> None:
428 version = manifest[package.name]
429 tag = f"{package.path}/v{version}"
430 try:
431 for edge in package.depends:
432 if edge.path in chosen:432 ↛ 431line 432 didn't jump to line 431 because the condition on line 432 was always true
433 done[edge.path].wait()
434 if edge.path in failures:
435 raise SystemExit(
436 f"{package.name}: its dependency"
437 f" {edge.path} failed, so this member never"
438 " started"
439 )
440 # A package that opts out of publishing is versioned,
441 # built and tagged by the train and never uploaded: the
442 # registry is neither probed nor written for it, and a
443 # re-run walks past its tag the way it walks past a
444 # served version. Its publish phase never runs.
445 if not package.publish:
446 if tag in git.tags(root):
447 print(
448 f" {package.name} v{version}: already tagged;"
449 " publish = false, done"
450 )
451 else:
452 _build_member(package)
453 cut_tag(root, tag, resolved_ref)
454 print(
455 f" {package.name} v{version}: publish = false; the"
456 " registry upload skips, the tag and the changelog stand"
457 )
458 with lock:
459 receipts[package.path] = Receipt(
460 package, version, tag, published=False
461 )
462 return
463 # A version the target already serves is walked past
464 # before any build or upload: a re-run after a died
465 # receipt, from CI or from a machine without a publish
466 # credential, must reach the tag. The duplicate rejection
467 # at the upload stays as the second net for two waves
468 # racing.
469 served = version in registry_for(package).versions(package.name)
470 if tag in git.tags(root) and served:
471 print(f" {package.name} v{version}: already tagged and served; done")
472 with lock:
473 receipts[package.path] = Receipt(
474 package, version, tag, published=False
475 )
476 return
477 _build_member(package)
478 # The member's publish phase owns the upload; the wave only
479 # hands it the target of the ecosystem it releases to.
480 target = targets[releases_to[package.path]]
481 if served:
482 print(
483 f" {package.name} v{version}: already served; walking"
484 " past the upload"
485 )
486 published = False
487 else:
488 if target.releases and tag not in git.tags(root):
489 # A release is addressed by its tag, so the tag
490 # exists before the assets do. The receipt is
491 # complete only once the probe sees them, which
492 # is why a tag alone no longer ends the member:
493 # a re-run finishes the upload.
494 cut_tag(root, tag, resolved_ref)
495 if package.name in new_projects:
496 with first_upload:
497 published = _first_upload(package, version, target)
498 else:
499 published = _lifecycle.publish(
500 package,
501 root,
502 version=version,
503 target=target,
504 prebuilt=package.path in built,
505 )
506 probe_until_served(
507 registry_for(package),
508 package.name,
509 version,
510 timeout=probe_timeout,
511 poll=probe_poll,
512 )
513 cut_tag(root, tag, resolved_ref)
514 with lock:
515 receipts[package.path] = Receipt(
516 package, version, tag, published=published
517 )
518 print(f" {package.name} v{version}: published, served, tagged")
519 except BaseException as exc:
520 with lock:
521 failures[package.path] = exc
522 raise
523 finally:
524 done[package.path].set()
526 with ThreadPoolExecutor(max_workers=max(len(ordered), 1)) as pool:
527 futures = [pool.submit(_run_member, p) for p in ordered]
528 for future in futures:
529 exc = future.exception()
530 if exc is not None and not isinstance(exc, SystemExit):
531 raise exc
532 if failures:
533 detail = "; ".join(f"{path}: {failures[path]}" for path in sorted(failures))
534 tagged = ", ".join(sorted(receipts)) or "none"
535 fail(
536 f"the wave stopped: {detail}\n receipts already cut: {tagged}."
537 " Fix the cause and re-run the publish; everything tagged is"
538 " walked past."
539 )
540 return tuple(receipts[p.path] for p in ordered)