ixt-cli 0.8.0__py3-none-any.whl

ixt/backends/binary_resolver.py

@@ -0,0 +1,307 @@
+"""Asset URL resolution helpers for the binary backend.
+
+Pure resolution logic kept orthogonal to ``BinaryBackend``: turning a
+release tag + asset name into a reusable ``{tag}``/``{version}`` pattern,
+and a fast-path that synthesizes a ``Release`` directly from a cached
+pattern plus either a known tag or a ``releases/latest`` redirect —
+bypassing the forge API.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from ixt.config.asset_index import (
+    AssetIndexEntry,
+    canonical_github_spec,
+    load_configured_asset_index,
+    load_learned_asset_index,
+    platform_key,
+)
+from ixt.config.settings import Settings
+from ixt.net.source import Asset, Release, RepoSpec
+
+_METADATA_FILE = "binary_metadata.json"
+
+# Direct-download fast path: probe at most this many candidate asset names
+# (canonical platform aliases first) before deferring to the release API.
+_FAST_PATH_MAX_PROBES = 3
+_FAST_PATH_HEAD_TIMEOUT = 30
+
+
+def derive_asset_pattern(asset_name: str, tag: str) -> str | None:
+    """Turn a resolved asset name into a ``{tag}``/``{version}`` template.
+
+    Replaces the tag (longest) first, then the stripped version on what
+    remains. If the asset name does not embed the version, returns the
+    constant asset name as the pattern. The fast-path later validates the
+    interpolated URL with HEAD and falls back to the release API on 404.
+    """
+    if not asset_name or not tag:
+        return None
+
+    version = tag.removeprefix("v")
+    pattern = asset_name
+    if tag and tag in pattern:
+        pattern = pattern.replace(tag, "{tag}")
+    if version and version != tag and version in pattern:
+        pattern = pattern.replace(version, "{version}")
+    return pattern
+
+
+def _read_pattern_from_env(env_dir: Path) -> str | None:
+    """Return a learned/backfilled asset pattern from an installed env."""
+    ixt_json = env_dir / "ixt.json"
+    if ixt_json.exists():
+        try:
+            from ixt.config.models import ToolRecord
+
+            pattern = ToolRecord.load_json(ixt_json).asset_pattern
+        except Exception:
+            pattern = None
+        if pattern:
+            return pattern
+
+    metadata = env_dir / _METADATA_FILE
+    if not metadata.exists():
+        return None
+    try:
+        with metadata.open(encoding="utf-8") as f:
+            data = json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return None
+
+    asset_name = data.get("asset_name")
+    tag = data.get("tag")
+    if not isinstance(asset_name, str) or not isinstance(tag, str):
+        return None
+    return derive_asset_pattern(asset_name, tag)
+
+
+def _fast_path_release(
+    repo_spec: RepoSpec,
+    env_dir: Path | None,
+    *,
+    known_tag: str | None = None,
+    asset_pattern: str | None = None,
+    pattern_name: str | None = None,
+    invalidate_cache_on_error: bool = True,
+    allow_partial_version: bool = False,
+    settings: Settings | None = None,
+) -> Release | None:
+    """Synthesize a Release without calling the forge API.
+
+    Works on fresh install *and* upgrade: looks for a learned pattern in
+    an explicit pattern first, then the global metadata cache, then the per-tool
+    metadata (if the tool is already installed). Resolves the latest tag via
+    the ``releases/latest`` redirect unless *known_tag* is supplied,
+    interpolates the pattern, and verifies the most common candidate URLs
+    via concurrent HEAD requests — rarer alias spellings defer to the
+    release API. Only GitHub is supported; GitLab releases still go
+    through the API.
+
+    *known_tag* (when supplied by an upgrade that already resolved the
+    latest tag) is reused verbatim, skipping the ``releases/latest`` HEAD.
+    """
+    if repo_spec.platform != "github":
+        return None
+
+    index_entry = _index_entry(repo_spec, settings=settings)
+    if asset_pattern is None and index_entry is not None:
+        indexed = _indexed_asset_release(repo_spec, index_entry, known_tag=known_tag)
+        if indexed is not None:
+            return indexed
+        if allow_partial_version:
+            return None
+
+    from ixt.config import asset_pattern_cache
+
+    pattern_source = "explicit" if asset_pattern else "cache"
+    learned_cache = False
+    pattern = asset_pattern
+    if pattern is None and index_entry is not None:
+        platform_pattern = index_entry.patterns.get(platform_key())
+        if platform_pattern:
+            pattern = platform_pattern
+            pattern_source = f"asset-index:{index_entry.source}"
+    if pattern is None:
+        pattern = asset_pattern_cache.get(repo_spec.owner, repo_spec.repo)
+        learned_cache = pattern is not None
+    if pattern is None and env_dir is not None:
+        pattern = _read_pattern_from_env(env_dir)
+        if pattern:
+            pattern_source = "env"
+            asset_pattern_cache.set_(repo_spec.owner, repo_spec.repo, pattern)
+    if not pattern:
+        return None
+
+    if known_tag:
+        tag: str | None = known_tag
+    else:
+        from ixt.net.github_api import fetch_latest_tag
+
+        tag = fetch_latest_tag(
+            repo_spec.owner,
+            repo_spec.repo,
+            timeout=_FAST_PATH_HEAD_TIMEOUT,
+        )
+    if not tag:
+        return None
+    candidates = _asset_name_candidates(repo_spec, pattern, tag, pattern_name=pattern_name)
+    asset_name = _probe_candidates(repo_spec, tag, candidates)
+    if asset_name is not None:
+        url = _download_url(repo_spec.owner, repo_spec.repo, tag, asset_name)
+        return Release(
+            tag=tag,
+            assets=[Asset(name=asset_name, url=url)],
+            resolution_source=("cache:asset_patterns.json" if learned_cache else pattern_source),
+        )
+
+    # Learned pattern no longer matches — drop it so we relearn on fallback.
+    # Explicit patterns should not mutate the user's learned cache.
+    from ixt.libs.logger import get_logger
+
+    get_logger("binary").debug(
+        f"asset pattern stale for {repo_spec.owner}/{repo_spec.repo} "
+        "— invalidating cache, falling back to release API"
+    )
+    if pattern_source in {"cache", "env"} and invalidate_cache_on_error:
+        asset_pattern_cache.invalidate(repo_spec.owner, repo_spec.repo)
+    return None
+
+
+def _index_entry(
+    repo_spec: RepoSpec,
+    *,
+    settings: Settings | None,
+) -> AssetIndexEntry | None:
+    canonical = canonical_github_spec(repo_spec)
+    if canonical is None:
+        return None
+    configured = load_configured_asset_index(settings=settings)
+    if canonical in configured:
+        return configured[canonical]
+    learned = load_learned_asset_index(settings=settings)
+    return learned.get(canonical)
+
+
+def _indexed_asset_release(
+    repo_spec: RepoSpec,
+    entry: AssetIndexEntry,
+    *,
+    known_tag: str | None,
+) -> Release | None:
+    indexed = entry.assets.get(platform_key())
+    if indexed is None:
+        return None
+    if known_tag is not None and not _tag_matches(known_tag, indexed.tag):
+        return None
+    if known_tag is None and repo_spec.version:
+        if _is_partial_version(repo_spec.version):
+            if not _matches_partial(indexed.tag, repo_spec.version):
+                return None
+        elif not _tag_matches(repo_spec.version, indexed.tag):
+            return None
+
+    url = indexed.url or _download_url(repo_spec.owner, repo_spec.repo, indexed.tag, indexed.asset)
+    return Release(
+        tag=indexed.tag,
+        assets=[Asset(name=indexed.asset, url=url)],
+        resolution_source=f"asset-index:{entry.source}",
+    )
+
+
+def _tag_matches(requested: str, actual: str) -> bool:
+    if requested == actual:
+        return True
+    return requested.removeprefix("v") == actual.removeprefix("v")
+
+
+def _is_partial_version(version: str) -> bool:
+    from ixt.libs.semver import is_partial_version
+
+    return is_partial_version(version)
+
+
+def _matches_partial(tag: str, partial: str) -> bool:
+    from ixt.libs.semver import matches_partial
+
+    return matches_partial(tag, partial)
+
+
+def _asset_name_candidates(
+    repo_spec: RepoSpec,
+    pattern: str,
+    tag: str,
+    *,
+    pattern_name: str | None = None,
+) -> list[str]:
+    """Interpolate direct-download asset names for all platform aliases."""
+    from ixt.config.heuristics import get_platform_aliases
+
+    version = tag.removeprefix("v")
+    name = pattern_name or repo_spec.repo
+    os_values, arch_values = get_platform_aliases()
+    if "{os}" not in pattern:
+        os_values = [""]
+    if "{arch}" not in pattern:
+        arch_values = [""]
+
+    candidates: list[str] = []
+    seen: set[str] = set()
+    for os_value in os_values:
+        for arch_value in arch_values:
+            asset_name = (
+                pattern.replace("{name}", name)
+                .replace("{tag}", tag)
+                .replace("{version}", version)
+                .replace("{os}", os_value)
+                .replace("{arch}", arch_value)
+            )
+            if asset_name not in seen:
+                candidates.append(asset_name)
+                seen.add(asset_name)
+    return candidates
+
+
+def _download_url(owner: str, repo: str, tag: str, asset_name: str) -> str:
+    return f"https://github.com/{owner}/{repo}/releases/download/{tag}/{asset_name}"
+
+
+def _probe_candidates(repo_spec: RepoSpec, tag: str, candidates: list[str]) -> str | None:
+    """Return the first existing asset among the most common candidates.
+
+    Only the top :data:`_FAST_PATH_MAX_PROBES` names (canonical platform
+    aliases first) are probed, concurrently, via HEAD on the CDN. Rarer
+    alias spellings are left to the release API rather than fanning out a
+    long tail of requests. The usual single-candidate case (a learned
+    pattern with literal ``os``/``arch``) is probed directly, no threads.
+    """
+    from ixt.net.http import HttpError, get_final_url
+
+    probed = candidates[:_FAST_PATH_MAX_PROBES]
+    if not probed:
+        return None
+
+    def _exists(asset_name: str) -> bool:
+        try:
+            get_final_url(
+                _download_url(repo_spec.owner, repo_spec.repo, tag, asset_name),
+                timeout=_FAST_PATH_HEAD_TIMEOUT,
+            )
+        except HttpError:
+            return False
+        return True
+
+    if len(probed) == 1:
+        return probed[0] if _exists(probed[0]) else None
+
+    from concurrent.futures import ThreadPoolExecutor
+
+    with ThreadPoolExecutor(max_workers=len(probed)) as pool:
+        hits = list(pool.map(_exists, probed))
+    for asset_name, ok in zip(probed, hits, strict=True):
+        if ok:
+            return asset_name
+    return None