Archived
294 lines
19 KiB
Python
294 lines
19 KiB
Python
"""The trusted version write-back command (`finalize-version`): persist the VERIFIED, PUBLISHED effective version to the source, in pinned platform code only.
|
|
|
|
The isolated callback wiring is not deployed or tested. Direct push invocation remains supported; the explicit
|
|
--original-run route authenticates a distinct canonical workflow_dispatch against the completed original push.
|
|
|
|
It never checks out, builds or runs the source, never rebuilds, and invents no version. It consumes what already exists:
|
|
|
|
* the repository's own `.ci.yaml` at the release commit, read through the forge: a channel that matches the pushed branch or tag AND declares `version_write_back` is the only opt-in;
|
|
* the VERIFIED bundle of the release run, selected by the publisher's own `select_artifacts` (same run, attempt, tree, manifest, config and platform identity proofs, same recomputed build
|
|
inputs including the effective version), so the version written is exactly the `build_inputs.version` the bundle recorded;
|
|
* the publication evidence the trusted publisher already wrote: the Maven files read back byte-identical from the private registry and, where the channel asks for Central completion, the
|
|
terminal completion receipt of exactly this reactor (`source_lifecycle.postpublish`); an absent one is `NotYetPublished`, nothing is written, and a later invocation retries.
|
|
|
|
The write itself is `source_lifecycle`: a staging branch, one server-signed `PUT` of the root POM's `<revision>`, strict re-verification, a normal non-forced fast-forward push. The credential is
|
|
the job's own ephemeral token (`FORGE_TOKEN`), exactly as the existing `release-tag` phase; this module reads no secret, creates no credential and grants nothing.
|
|
"""
|
|
|
|
import json
|
|
import tempfile
|
|
import urllib.request
|
|
from collections.abc import Callable, Mapping
|
|
from dataclasses import dataclass
|
|
from pathlib import Path
|
|
from typing import Any, Final, cast, override
|
|
|
|
from platform_ci.configuration import ProjectConfiguration, ReleaseChannel, WriteBackPolicy, parse_project_configuration_text, parse_yaml_rejecting_duplicate_keys
|
|
from platform_ci.delivery import legacy
|
|
from platform_ci.delivery.adapters import selected_artifact_files
|
|
from platform_ci.delivery.errors import DeliveryError
|
|
from platform_ci.delivery.forge import ClientForge, CurrentRun, ForgeReader, RepositoryScope, current_workflow_trust, inspect_run, read_file, require_repository
|
|
from platform_ci.delivery.manifest import ManifestFile
|
|
from platform_ci.delivery.promotion import REUSE_MAX_ARTIFACT_BYTES, REUSE_RUNS_SCANNED
|
|
from platform_ci.delivery.publisher import RunInProgressError, select_artifacts
|
|
from platform_ci.delivery.release_tag import CONFIGURATION_PATH, TRUSTED_FORGE
|
|
from platform_ci.delivery.reuse import ReleaseArtifact
|
|
from platform_ci.delivery.reuse_forge import live_reuse_forge
|
|
from platform_ci.delivery.source_lifecycle import Fatal, NotYetPublished, SourceWriter, VersionGit, WriteContext, postpublish
|
|
from platform_ci.event_selection import EventFacts, channel_matches, push_facts, tag_facts
|
|
from platform_ci.plan import publication_requests
|
|
from platform_ci.runtimes import RuntimeCatalog, load_runtime_catalog
|
|
|
|
_BRANCH_PREFIX: Final = "refs/heads/"
|
|
_TAG_PREFIX: Final = "refs/tags/"
|
|
_COMMIT_LENGTH: Final = 40
|
|
MAVEN_FORMAT: Final = "maven"
|
|
_CANONICAL_PLATFORM_REPOSITORY_ID: Final = 3
|
|
_PUBLIC_METADATA_LIMIT: Final = 2_000_000
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class _Request:
|
|
"""The validated facts the workflow supplies: the pushed ref, the release commit, the repository and run identity, the token and the optional release run."""
|
|
|
|
ref: str
|
|
sha: str
|
|
branch: str
|
|
tag: str
|
|
repository: str
|
|
repository_id: int
|
|
run_id: int
|
|
attempt: int
|
|
platform: str
|
|
token: str
|
|
release_run: int | None
|
|
source_id: int
|
|
|
|
|
|
def _read_request(environment: Mapping[str, str]) -> _Request:
|
|
"""Validate the environment of a write-back; any missing or malformed fact is an error before a single read is made."""
|
|
if environment.get("CI_EVENT_NAME") != "push":
|
|
raise DeliveryError("a version write-back runs only for the push of a release branch or tag")
|
|
ref, sha = environment.get("CI_EVENT_REF", ""), environment.get("CI_SOURCE_REVISION", "")
|
|
branch, tag = ref.removeprefix(_BRANCH_PREFIX) if ref.startswith(_BRANCH_PREFIX) else "", ref.removeprefix(_TAG_PREFIX) if ref.startswith(_TAG_PREFIX) else ""
|
|
repository, repository_id = environment.get("CI_REPOSITORY", ""), environment.get("CI_REPOSITORY_ID", "")
|
|
run_id, attempt, platform = environment.get("CI_RUN_ID", ""), environment.get("CI_RUN_ATTEMPT", ""), environment.get("CI_PLATFORM_REVISION", "")
|
|
if not (bool(branch) ^ bool(tag)) or len(sha) != _COMMIT_LENGTH or not repository or not repository_id.isdigit() or not run_id.isdigit() or not attempt.isdigit() or len(platform) != _COMMIT_LENGTH:
|
|
raise DeliveryError("the pushed branch or tag, the release commit, the platform revision and the repository and run identity are required")
|
|
if environment.get("GITHUB_SERVER_URL", "").rstrip("/") != TRUSTED_FORGE:
|
|
raise DeliveryError("the runner's forge is not the trusted private forge")
|
|
token = environment.get("FORGE_TOKEN", "")
|
|
if not token:
|
|
raise DeliveryError("the job's own token is required")
|
|
release_run = environment.get("CI_RELEASE_RUN_ID", "")
|
|
if release_run and not release_run.isdigit():
|
|
raise DeliveryError("CI_RELEASE_RUN_ID must be a run number")
|
|
source_id = environment.get("CI_SCOPED_SOURCE_ID", "0")
|
|
if not source_id.isdigit():
|
|
raise DeliveryError("CI_SCOPED_SOURCE_ID must be a number")
|
|
return _Request(ref, sha, branch, tag, repository, int(repository_id), int(run_id), int(attempt), platform, token, int(release_run) if release_run else None, int(source_id))
|
|
|
|
|
|
def finalize_version( # noqa: PLR0913, PLR0917 - the injected clients replace the live ones only for tests
|
|
environment: Mapping[str, str],
|
|
forge: ForgeReader | None = None,
|
|
writer: Callable[..., tuple[int, Any]] | None = None,
|
|
git: VersionGit | None = None,
|
|
registry_reader: Callable[..., tuple[int, bytes]] | None = None,
|
|
completion_reader: Callable[..., tuple[int, bytes]] | None = None,
|
|
runtimes: RuntimeCatalog | None = None,
|
|
*,
|
|
original_run: int | None = None,
|
|
) -> list[str]:
|
|
"""Write back the version of the release identified by the environment; return one line describing the outcome. Any doubt is an error, never a skip.
|
|
|
|
Required environment (all set by the workflow, none by the source): the event name `push`, the pushed ref (`refs/heads/<branch>` or `refs/tags/<tag>`), the exact release commit, the repository
|
|
and run identity, this run's attempt, the canonical source id and workflow sha, the platform revision, and the job's token. Optional `CI_RELEASE_RUN_ID` names the release run to consume
|
|
(otherwise the publisher's own run selection applies). Injected clients replace the live ones only for tests.
|
|
"""
|
|
if original_run is None:
|
|
request = _read_request(environment)
|
|
client = forge
|
|
trusted_original = None
|
|
else:
|
|
request, client, trusted_original = _callback_request(environment, original_run, forge)
|
|
sha, branch, tag = request.sha, request.branch, request.tag
|
|
scope = RepositoryScope(request.repository, request.repository_id, REUSE_MAX_ARTIFACT_BYTES, REUSE_RUNS_SCANNED, frozenset({request.platform}))
|
|
client = client or live_reuse_forge(request.token, scope)
|
|
require_repository(client, scope)
|
|
trusted = trusted_original or current_workflow_trust(client, scope, CurrentRun(request.run_id, sha, request.source_id, environment.get("CI_WORKFLOW_SHA", "")))
|
|
if trusted is None:
|
|
raise DeliveryError("the forge does not prove this run was executed by the canonical workflow, so no release run can be trusted")
|
|
content = read_file(client, request.repository, CONFIGURATION_PATH, sha)
|
|
if content is None:
|
|
return ["no .ci.yaml at the release commit: nothing to write back"]
|
|
project = parse_project_configuration_text(content.decode("utf-8"))
|
|
facts = push_facts(branch, sha) if branch else tag_facts(tag, sha)
|
|
channels = _write_back_channels(project, facts)
|
|
if not channels:
|
|
return [f"no channel matching {request.ref} declares version_write_back: nothing to write back"]
|
|
policy = _one_policy(channels)
|
|
target_branch = branch or policy.target_branch
|
|
planned = [publication for publication in publication_requests(project, [channel.name for channel in channels]) if publication["format"] == MAVEN_FORMAT]
|
|
if not planned:
|
|
raise DeliveryError("the channels that write a version back publish no Maven package at this commit, so there is no verified publication to wait for")
|
|
ctx = WriteContext(request.repository, sha, target_branch, request.run_id, request.attempt, tag)
|
|
owner = request.repository.split("/", 1)[0] # the enrolled owner always equals the repository's: `enrollment.py` rejects any other
|
|
with tempfile.TemporaryDirectory() as scratch:
|
|
try:
|
|
artifacts, _notes = select_artifacts(client, trusted, runtimes or load_runtime_catalog(), project, sha, facts, planned, request.release_run, Path(scratch))
|
|
except RunInProgressError as error:
|
|
raise NotYetPublished(str(error)) from error
|
|
evidence: list[tuple[ReleaseArtifact, tuple[ManifestFile, ...], str]] = []
|
|
for publication in planned:
|
|
artifact = artifacts[publication["target"]]
|
|
inputs = artifact.manifest.build_inputs
|
|
if inputs is None:
|
|
raise Fatal(f"the verified bundle of {publication['target']!r} records no build inputs, so no version can be written back")
|
|
evidence.append((artifact, selected_artifact_files(artifact, publication["artifact"]), inputs.version))
|
|
versions = {version for _, _, version in evidence}
|
|
if len(versions) != 1:
|
|
raise Fatal(f"the verified bundles record different versions {sorted(versions)}; one POM cannot carry them")
|
|
version = next(iter(versions))
|
|
first, *rest = evidence
|
|
result = postpublish(
|
|
ctx,
|
|
policy,
|
|
artifact=first[0],
|
|
files=first[1],
|
|
version=version,
|
|
owner=owner,
|
|
repository_id=request.repository_id,
|
|
central_required=any(channel.central_completion for channel in channels),
|
|
writer=writer or SourceWriter(request.token, ctx),
|
|
registry_reader=registry_reader or legacy.package_client(request.token, owner, "maven"),
|
|
completion_reader=completion_reader or legacy.package_client(request.token, owner, "generic"),
|
|
git=git or VersionGit(TRUSTED_FORGE, request.repository, request.token),
|
|
extra_evidence=tuple((artifact, files) for artifact, files, _ in rest),
|
|
)
|
|
detail = f" ({result['reason']})" if result["reason"] else ""
|
|
pushed = f" {result['pushed_sha'][:12]}" if result["pushed_sha"] else ""
|
|
return [f"version write-back of {version} to {target_branch}: {result['status']}{pushed}{detail}"]
|
|
|
|
|
|
def _write_back_channels(project: ProjectConfiguration, facts: EventFacts) -> list[ReleaseChannel]:
|
|
"""Return the channels this push matches that opted in to a version write-back."""
|
|
return [channel for channel in project.channels if channel.version_write_back is not None and channel_matches(channel, facts)]
|
|
|
|
|
|
def _one_policy(channels: list[ReleaseChannel]) -> WriteBackPolicy:
|
|
"""Return the single policy of the matching channels; two different ones would give two targets for one write and are an error."""
|
|
policies = {channel.version_write_back for channel in channels}
|
|
if len(policies) != 1:
|
|
raise DeliveryError(f"channels {sorted(channel.name for channel in channels)} declare different version_write_back policies for one event")
|
|
(policy,) = policies
|
|
if policy is None:
|
|
raise DeliveryError("a channel selected for a version write-back declares no version_write_back policy")
|
|
return policy
|
|
|
|
|
|
def _callback_request(environment: Mapping[str, str], original_run: int, forge: ForgeReader | None) -> tuple[_Request, ForgeReader, RepositoryScope]:
|
|
"""Authenticate the callback and original push separately. Never substitute a push event in the callback environment."""
|
|
if environment.get("CI_EVENT_NAME") != "workflow_dispatch" or original_run <= 0:
|
|
raise DeliveryError("an original-run callback requires a workflow_dispatch and a positive original run id")
|
|
# Validate common runner facts without pretending this dispatch is a source push.
|
|
ref = environment.get("CI_EVENT_REF", "")
|
|
repository = environment.get("CI_REPOSITORY", "")
|
|
sha = environment.get("CI_SOURCE_REVISION", "")
|
|
ids = [environment.get(key, "") for key in ("CI_REPOSITORY_ID", "CI_RUN_ID", "CI_RUN_ATTEMPT", "CI_SCOPED_SOURCE_ID")]
|
|
platform, workflow = environment.get("CI_PLATFORM_REVISION", ""), environment.get("CI_WORKFLOW_SHA", "")
|
|
token = environment.get("FORGE_TOKEN", "")
|
|
if not all(value.isdigit() and int(value) > 0 for value in ids) or any(len(value) != _COMMIT_LENGTH or any(c not in "0123456789abcdef" for c in value) for value in (sha, platform, workflow)):
|
|
raise DeliveryError("callback repository/run/source identity and full platform/workflow/source revisions are required")
|
|
if not repository or not token or environment.get("GITHUB_SERVER_URL", "").rstrip("/") != TRUSTED_FORGE:
|
|
raise DeliveryError("the callback requires its own token and trusted forge/repository")
|
|
repository_id, callback_id, attempt, source_id = map(int, ids)
|
|
if callback_id == original_run:
|
|
raise DeliveryError("a callback cannot name itself as its original run")
|
|
scope = RepositoryScope(repository, repository_id, REUSE_MAX_ARTIFACT_BYTES, REUSE_RUNS_SCANNED, frozenset({platform}))
|
|
client = forge or live_reuse_forge(token, scope)
|
|
require_repository(client, scope)
|
|
callback = current_workflow_trust(client, scope, CurrentRun(callback_id, sha, source_id, workflow))
|
|
if callback is None or len(callback.scoped_workflows) != 1 or next(iter(callback.scoped_workflows)).workflow_file != "finalize-version.yaml":
|
|
raise DeliveryError("callback is not the pinned canonical scoped finalizer")
|
|
original_value = client.get(f"/repos/{repository}/actions/runs/{original_run}")
|
|
if not isinstance(original_value, dict):
|
|
raise DeliveryError("the original run is not a source push at this exact callback commit")
|
|
original = cast("dict[str, Any]", original_value)
|
|
if original.get("head_sha") != sha or original.get("event") != "push":
|
|
raise DeliveryError("the original run is not a source push at this exact callback commit")
|
|
original_ref = str(original.get("path", "")).partition("@")[2]
|
|
if original_ref != ref or not original_ref.startswith(("refs/heads/", "refs/tags/")):
|
|
raise DeliveryError("callback and original push refs differ or are not fully qualified")
|
|
trusted = current_workflow_trust(client, scope, CurrentRun(original_run, sha, source_id))
|
|
if trusted is None:
|
|
raise DeliveryError("the original push was not executed by the canonical workflow")
|
|
if platform != _canonical_build_revision(trusted):
|
|
raise DeliveryError("callback build helper differs from the original canonical pipeline's immutable build pin")
|
|
facts = inspect_run(client, trusted, original_run)
|
|
if facts.status != "completed" or facts.conclusion != "success" or facts.head_sha != sha or facts.event != "push":
|
|
raise DeliveryError("the exact original push and its required jobs must have completed successfully")
|
|
if facts.attempt != environment.get("CI_ORIGINAL_ATTEMPT"):
|
|
raise DeliveryError("the original push attempt changed after publication handoff")
|
|
branch = ref.removeprefix(_BRANCH_PREFIX) if ref.startswith(_BRANCH_PREFIX) else ""
|
|
tag = ref.removeprefix(_TAG_PREFIX) if ref.startswith(_TAG_PREFIX) else ""
|
|
# Staging names use THIS callback's run/attempt. Artifact selection deliberately remains default:
|
|
# the completed source push may reuse the earlier PR's verified bundles and have none of its own.
|
|
return _Request(ref, sha, branch, tag, repository, repository_id, callback_id, attempt, platform, token, None, source_id), client, trusted
|
|
|
|
|
|
class _NoCanonicalRedirect(urllib.request.HTTPRedirectHandler):
|
|
"""The public canonical workflow read never redirects or carries a credential."""
|
|
|
|
@override
|
|
def redirect_request(self, *args: object, **kwargs: object) -> None:
|
|
return None
|
|
|
|
|
|
def _canonical_build_revision(trusted: RepositoryScope) -> str:
|
|
"""Read the literal build pin from the pipeline YAML at the server-proven canonical workflow commit."""
|
|
if len(trusted.scoped_workflows) == 1:
|
|
workflow = next(iter(trusted.scoped_workflows))
|
|
revision = workflow.callee_workflow_sha
|
|
if not revision and workflow.source_repository_id == _CANONICAL_PLATFORM_REPOSITORY_ID and workflow.workflow_file == "pipeline.yaml":
|
|
revision = workflow.workflow_sha
|
|
elif len(trusted.workflow_references) == 1:
|
|
reference = next(iter(trusted.workflow_references))
|
|
prefix = "self:KofTwentyTwo/platform-ci/.gitea/scoped_workflows/pipeline.yaml@"
|
|
revision = reference.removeprefix(prefix) if reference.startswith(prefix) else ""
|
|
else:
|
|
revision = ""
|
|
if len(revision) != _COMMIT_LENGTH or any(char not in "0123456789abcdef" for char in revision):
|
|
raise DeliveryError("original run has no independently proved canonical pipeline commit")
|
|
repository = "KofTwentyTwo/platform-ci"
|
|
filename = ".gitea/scoped_workflows/pipeline.yaml"
|
|
expected_path = f"/repos/{repository}/contents/{filename}?ref={revision}"
|
|
opener = urllib.request.build_opener(_NoCanonicalRedirect())
|
|
|
|
def public_get(path: str) -> object:
|
|
if path != expected_path:
|
|
raise DeliveryError("canonical metadata reader refuses any other repository, file or revision")
|
|
# Only public platform code leaves/enters this request: no source SHA, source data or credential.
|
|
request = urllib.request.Request(TRUSTED_FORGE + "/api/v1" + expected_path, method="GET") # noqa: S310 - fixed trusted HTTPS origin, exact immutable path, no redirects
|
|
with opener.open(request, timeout=30) as response:
|
|
raw = response.read(_PUBLIC_METADATA_LIMIT + 1)
|
|
if len(raw) > _PUBLIC_METADATA_LIMIT:
|
|
raise DeliveryError("canonical pipeline metadata exceeds the existing file bound")
|
|
return cast("object", json.loads(raw))
|
|
|
|
def no_download(_path: str, _destination: Path, _limit: int) -> None:
|
|
raise DeliveryError("canonical workflow metadata reader downloads no artifact")
|
|
|
|
content = read_file(ClientForge(public_get, no_download), repository, filename, revision)
|
|
document = parse_yaml_rejecting_duplicate_keys(content.decode("utf-8")) if content is not None else None
|
|
if not isinstance(document, dict):
|
|
raise DeliveryError("canonical pipeline YAML is absent or malformed")
|
|
fields = cast("dict[str, Any]", document)
|
|
environment = fields.get("env")
|
|
if not isinstance(environment, dict):
|
|
raise DeliveryError("canonical pipeline has no literal build helper pin")
|
|
build = cast("dict[str, Any]", environment).get("PLATFORM_CI_REVISION")
|
|
if not isinstance(build, str) or len(build) != _COMMIT_LENGTH or any(char not in "0123456789abcdef" for char in build):
|
|
raise DeliveryError("canonical pipeline build helper pin is not an immutable commit")
|
|
return build
|