Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions docs/product/release-readiness.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,18 @@ backup if older code cannot read the current data. Use `loopx update plan
qualification. Re-running the curl installer remains a repair path when an
archive wrapper is too broken to run its own updater.

Installing or updating to a `main` runtime snapshot requires a supported
`default_contract` in its descriptor, including when a preview revision is pinned.
If that evidence is missing, the update plan reports a blocked target and the
public installer stops before downloading the archive. Historical descriptors
remain readable. Legacy `stable` releases remain installable with matching
archive metadata, and rollback continues to use the existing local release.

安装或更新到 `main` 运行时快照时,描述符必须包含受支持的 `default_contract`,
指定预览提交时也适用。缺少此证据时,更新计划会标明目标受阻,公开安装器会在下载
归档前停止。历史描述符仍可读取,归档元数据一致的旧版 `stable` 仍可安装,回退仍
使用已有本地发行版。

For contributors, keep the clone-plus-canary path:

```bash
Expand Down
27 changes: 17 additions & 10 deletions loopx/cli_commands/update_artifact.py
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,9 @@ def validate_default_contract(value: object) -> dict[str, Any]:
return dict(value)


def validate_manifest(value: dict[str, Any], *, revision: str | None = None) -> dict[str, Any]:
def validate_manifest(
value: dict[str, Any], *, revision: str | None = None, for_activation: bool = False,
) -> dict[str, Any]:
if value.get("schema_version") != RUNTIME_ARTIFACT_SCHEMA_VERSION:
raise ValueError("Unsupported runtime artifact metadata")
if not SHA.fullmatch(str(value.get("source_revision", ""))):
Expand All @@ -132,14 +134,17 @@ def validate_manifest(value: dict[str, Any], *, revision: str | None = None) ->
raise ValueError("Runtime artifact has no bounded download sources")
for url in urls:
safe_url(url)
# Historical v1 snapshots remain readable. Newly produced artifacts and
# the publisher require the observed contract; absence is not qualification.
if "default_contract" in value:
validate_default_contract(value["default_contract"])
channel = value.get("channel")
if for_activation and channel not in ("main", "stable"):
raise ValueError("Runtime artifact has no supported installation channel")
# Published legacy stable releases remain installable. Historical preview
# metadata can still be read, but installing it requires a qualified default.
if "default_contract" in value or (for_activation and channel == "main"):
validate_default_contract(value.get("default_contract"))
return dict(value)


def resolve_artifact(repo: str, ref: str) -> dict[str, Any]:
def resolve_artifact(repo: str, ref: str, *, for_activation: bool = False) -> dict[str, Any]:
if not REPOSITORY_PATTERN.fullmatch(repo):
raise ValueError("Update repo must use GitHub owner/name syntax")
if ref == "stable":
Expand All @@ -160,7 +165,9 @@ def resolve_artifact(repo: str, ref: str) -> dict[str, Any]:
if not (SHA.fullmatch(ref) and isinstance(exc.__cause__, HTTPError) and exc.__cause__.code == 404):
raise
metadata = read_json(f"https://github.com/{repo}/releases/download/runtime-main/loopx-runtime-{ref}.json")
artifact = validate_manifest(metadata, revision=ref if SHA.fullmatch(ref) else None)
artifact = validate_manifest(
metadata, revision=ref if SHA.fullmatch(ref) else None, for_activation=for_activation,
)
if ref in {"main", "stable"} and artifact.get("channel") != ref:
raise ValueError("Runtime artifact belongs to another channel")
return artifact
Expand Down Expand Up @@ -407,7 +414,7 @@ def consume(name, stream):

def install_artifact(manifest: dict[str, Any], *, env: dict[str, str], timeout_seconds: int,
progress=lambda _event: None):
manifest = validate_manifest(manifest)
manifest = validate_manifest(manifest, for_activation=True)
started = time.monotonic()
archive = download_artifact(manifest, progress=progress, timeout=timeout_seconds)
progress({"stage": "verify"})
Expand All @@ -416,7 +423,7 @@ def install_artifact(manifest: dict[str, Any], *, env: dict[str, str], timeout_s
identity = json.loads((root / "runtime-artifact.json").read_text(encoding="utf-8"))
if identity.get("source_revision") != manifest["source_revision"] or identity.get("package_version") != manifest["package_version"]:
raise ValueError("Runtime identity disagrees with its release metadata")
if "default_contract" in manifest and identity.get("default_contract") != manifest["default_contract"]:
if identity.get("default_contract") != manifest.get("default_contract"):
raise ValueError("Runtime default contract disagrees with its release metadata")
selected = dict(env)
selected.update({"LOOPX_RESOLVED_SOURCE_GIT_COMMIT": manifest["source_revision"],
Expand Down Expand Up @@ -449,7 +456,7 @@ def report(event):
raise ValueError("An existing CLI has another or unknown owner; use its `loopx upgrade` or original package manager")
selected_repo = args.repo or (os.environ.get("LOOPX_REPO") if os.environ.get("LOOPX_UPDATE_REPO_EXPLICIT") == "1" else None) or installed.get("repo") or "loopx-project/loopx"
selected_ref = args.ref or (os.environ.get("LOOPX_REF") if os.environ.get("LOOPX_UPDATE_REF_EXPLICIT") == "1" else None) or installed.get("ref") or "stable"
manifest = resolve_artifact(selected_repo, selected_ref)
manifest = resolve_artifact(selected_repo, selected_ref, for_activation=True)
if installed and target_direction(selected_repo, installed.get("git_commit"), manifest["source_revision"]) not in {"ahead", "identical"} and os.environ.get("LOOPX_ALLOW_DOWNGRADE") != "1":
raise ValueError("Older, diverged or unverified target; inspect it before explicitly setting LOOPX_ALLOW_DOWNGRADE=1")
env = dict(os.environ, LOOPX_REPO=selected_repo, LOOPX_REF=selected_ref, LOOPX_UPDATE_CHANNEL=selected_ref, LOOPX_UPDATE_EVENTS="1")
Expand Down
2 changes: 1 addition & 1 deletion loopx/cli_commands/update_source.py
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ def prepare_target(payload: dict[str, Any], *, freshness: dict, resolve_remote:
if source["distribution"] == "runtime":
if resolve_remote:
try:
artifact = resolve_artifact(source["repo"], source["ref"])
artifact = resolve_artifact(source["repo"], source["ref"], for_activation=True)
source["artifact"] = artifact
target = artifact["source_revision"]
version = artifact["package_version"]
Expand Down
27 changes: 22 additions & 5 deletions tests/test_update_artifact.py
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,20 @@ def test_qualified_scope_and_historical_metadata_remain_readable():
assert update.validate_manifest(current) == current


def test_archive_contract_mismatch_stops_before_installer(tmp_path, monkeypatch):
def test_markerless_preview_remains_readable_but_stops_before_download(monkeypatch):
descriptor = manifest(b"runtime", "https://publisher.invalid/runtime")
assert update.validate_manifest(descriptor) == descriptor

def unexpected_download(*_args, **_kwargs):
pytest.fail("Unqualified runtime reached archive download")

monkeypatch.setattr(update, "download_artifact", unexpected_download)
with pytest.raises(ValueError, match="unqualified for public adoption"):
update.install_artifact(descriptor, env={}, timeout_seconds=10)


@pytest.mark.parametrize("channel", ["main", "stable"])
def test_archive_contract_mismatch_stops_before_installer(tmp_path, monkeypatch, channel):
archive = tmp_path / "runtime.tar.gz"
identity = json.dumps({"source_revision": "a" * 40, "package_version": "1.2.3",
"default_contract": {"surface": "complete_turn"}}).encode()
Expand All @@ -126,8 +139,9 @@ def test_archive_contract_mismatch_stops_before_installer(tmp_path, monkeypatch)
member = tarfile.TarInfo(name)
member.size = len(content)
target.addfile(member, io.BytesIO(content))
descriptor = {**manifest(archive.read_bytes(), "https://publisher.invalid/runtime"),
"default_contract": dict(update.PUBLIC_DEFAULT_CONTRACT)}
descriptor = {**manifest(archive.read_bytes(), "https://publisher.invalid/runtime"), "channel": channel}
if channel == "main":
descriptor["default_contract"] = dict(update.PUBLIC_DEFAULT_CONTRACT)
monkeypatch.setattr(update, "download_artifact", lambda *_a, **_kw: archive)
calls = []
monkeypatch.setattr(update, "run_installer", lambda *_a, **_kw: calls.append("activate"))
Expand Down Expand Up @@ -373,10 +387,13 @@ def test_bootstrap_inherits_snapshot_choice_without_taking_over_a_package_owner(
monkeypatch.setenv("LOOPX_UPDATE_REPO_EXPLICIT", "0")
monkeypatch.setattr(sys, "argv", ["update-artifact.py"])
selected = []
monkeypatch.setattr(update, "resolve_artifact", lambda repo, ref: selected.append((repo, ref)) or manifest(b"x", "https://example.com/runtime"))
def resolve(repo, ref, *, for_activation=False):
selected.append((repo, ref, for_activation))
return manifest(b"x", "https://example.com/runtime")
monkeypatch.setattr(update, "resolve_artifact", resolve)
monkeypatch.setattr(update, "install_artifact", lambda *_a, **_kw: (subprocess.CompletedProcess([], 0, "", ""), {}))
assert update.main() == 0
assert selected == [("example/fork", "main")]
assert selected == [("example/fork", "main", True)]
entry.unlink()
entry.touch() # pip/another installer owns a regular console entry.
assert update.main() == 1
Expand Down
27 changes: 25 additions & 2 deletions tests/test_update_operation.py
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ def test_runtime_check_uses_one_qualified_version_and_revision(monkeypatch):
def no_branch_probe(*_args):
raise AssertionError("The mutable branch version must not describe a qualified artifact")
monkeypatch.setattr("loopx.self_update._source_version_check", no_branch_probe)
monkeypatch.setattr(update_source, "resolve_artifact", lambda *_: {
monkeypatch.setattr(update_source, "resolve_artifact", lambda *_, **kwargs: {
"source_revision": "2" * 40, "package_version": "1.2.3"})
monkeypatch.setattr(update_source, "target_direction", lambda *_: "ahead")
plan = build_update_plan(action="check", doctor_payload=doctor_payload(), resolve_remote=True)
Expand All @@ -46,7 +46,7 @@ def no_branch_probe(*_args):
def test_target_is_resolved_before_any_mutation_and_downgrade_needs_intent(monkeypatch, direction, accepted):
from loopx.cli_commands import update_source
artifact = {"source_revision": "2" * 40, "package_version": "1.0.0"}
monkeypatch.setattr(update_source, "resolve_artifact", lambda *_: artifact)
monkeypatch.setattr(update_source, "resolve_artifact", lambda *_, **kwargs: artifact)
monkeypatch.setattr(update_source, "target_direction", lambda *_: direction)
plan = build_update_plan(action="apply", doctor_payload=doctor_payload(), resolve_remote=True)
assert plan["source"]["resolved_revision"] == artifact["source_revision"]
Expand All @@ -55,6 +55,29 @@ def test_target_is_resolved_before_any_mutation_and_downgrade_needs_intent(monke
assert override["plan"]["apply_supported"] is True


@pytest.mark.parametrize("ref", ["main", "2" * 40])
def test_update_plan_blocks_unqualified_preview_even_if_downgrade_is_allowed(monkeypatch, ref):
from loopx.cli_commands import update_artifact, update_source

descriptor = {
"schema_version": update_artifact.RUNTIME_ARTIFACT_SCHEMA_VERSION,
"source_revision": "2" * 40,
"package_version": "1.2.3",
"channel": "main",
"size": 7,
"sha256": "a" * 64,
"urls": ["https://publisher.invalid/runtime.tar.gz"],
}
monkeypatch.setattr(update_artifact, "read_json", lambda _url: descriptor)
monkeypatch.setattr(update_source, "target_direction", lambda *_: "ahead")
plan = build_update_plan(ref=ref, action="apply", doctor_payload=doctor_payload(),
resolve_remote=True, allow_downgrade=True)
assert plan["source"]["target_status"] == "blocked"
assert plan["plan"]["apply_supported"] is False
assert not plan["plan"]["mutates_release_install"]
assert "unqualified for public adoption" in plan["plan"]["blocked_reason"]


def test_installer_uses_frozen_revision_but_persists_channel_and_proxy(monkeypatch):
monkeypatch.setenv("HTTPS_PROXY", "http://operator-proxy.invalid:8080")
source = _source_config(repo=None, ref="main", archive_url=None, build_from_source=True)
Expand Down
Loading