Skip to content

💫 Toolkit to help you get started with SDD or any other process!

17.7 KB
Raw Blame
"""Workflow and step catalog cache confinement regressions."""

from __future__ import annotations

import io
import json
import os
import subprocess
import time
from urllib.error import URLError

import pytest
import yaml
from typer.testing import CliRunner

from specify_cli import app
from specify_cli.workflows import _catalog_cache
from specify_cli.workflows.catalog import (
    WorkflowCatalog,
    WorkflowCatalogEntry,
    WorkflowCatalogError,
)
from specify_cli.workflows.step.catalog import (
    StepCatalog,
    StepCatalogEntry,
    StepCatalogError,
)

URL = "https://example.com/catalog.json"
SENTINEL = "isolated target must remain unchanged\n"


@pytest.fixture(params=["workflow", "step"])
def catalog_kind(request):
    if request.param == "workflow":
        return (
            WorkflowCatalog,
            WorkflowCatalogEntry,
            "workflows",
            "workflow-catalogs.yml",
            ["workflow", "search"],
        )
    return (
        StepCatalog,
        StepCatalogEntry,
        "steps",
        "step-catalogs.yml",
        ["workflow", "step", "search"],
    )


@pytest.fixture
def fetch(monkeypatch, catalog_kind):
    payload = {catalog_kind[2]: {}}
    calls = []

    class Response(io.BytesIO):
        def geturl(self):
            return URL

    def open_url(*args, **kwargs):
        calls.append(args[0])
        return Response(json.dumps(payload).encode())

    monkeypatch.setattr("specify_cli.authentication.http.open_url", open_url)
    return payload, calls


def symlink(link, target, *, directory=False):
    try:
        link.symlink_to(target, target_is_directory=directory)
    except (OSError, NotImplementedError) as exc:
        pytest.skip(f"Symlink creation unavailable: {exc}")


def junction(link, target):
    import _winapi

    _winapi.CreateJunction(str(target), str(link))


@pytest.mark.parametrize("leaf", ["data", "metadata"])
@pytest.mark.parametrize("dangling", [False, True])
def test_cache_leaf_cannot_redirect_write(
    tmp_path, catalog_kind, fetch, leaf, dangling
):
    catalog_cls, entry_cls, *_ = catalog_kind
    root = tmp_path / "project"
    root.mkdir()
    catalog = catalog_cls(root)
    paths = catalog._get_cache_paths(URL)
    paths[0].parent.mkdir(parents=True)
    victim = tmp_path / "victim"
    if not dangling:
        victim.write_text(SENTINEL)
    symlink(paths[leaf == "metadata"], victim)

    assert catalog._fetch_single_catalog(entry_cls(URL, "test", 1, False)) == fetch[0]
    if dangling:
        assert not victim.exists()
    else:
        assert victim.read_text() == SENTINEL


@pytest.mark.skipif(os.name == "nt", reason="Git symlink checkout is POSIX-specific")
@pytest.mark.parametrize("leaf", ["data", "metadata"])
def test_committed_symlink_clone_search_preserves_target(
    tmp_path, catalog_kind, fetch, monkeypatch, leaf
):
    catalog_cls, _, _, config_name, command = catalog_kind
    source = tmp_path / "source"
    source.mkdir()
    victim = tmp_path / "victim"
    victim.write_text(SENTINEL)
    paths = catalog_cls(source)._get_cache_paths(URL)
    paths[0].parent.mkdir(parents=True)
    link = paths[leaf == "metadata"]
    symlink(link, victim)
    (source / ".specify" / config_name).write_text(
        yaml.safe_dump(
            {
                "catalogs": [
                    {
                        "url": URL,
                        "name": "test",
                        "priority": 1,
                        "install_allowed": False,
                    }
                ],
            }
        )
    )

    def git(*args):
        return subprocess.run(
            ["git", *args], check=True, capture_output=True, text=True
        )

    git("init", "-q", str(source))
    git("-C", str(source), "add", ".")
    git(
        "-C",
        str(source),
        "-c",
        "user.name=Cache Test",
        "-c",
        "[email protected]",
        "-c",
        "commit.gpgsign=false",
        "commit",
        "-qm",
        "Isolated cache fixture",
    )
    clone = tmp_path / "clone"
    git("clone", "-q", "--no-local", str(source), str(clone))
    assert (clone / link.relative_to(source)).is_symlink()
    monkeypatch.delenv("SPECKIT_WORKFLOW_CATALOG_URL", raising=False)
    monkeypatch.delenv("SPECKIT_STEP_CATALOG_URL", raising=False)
    monkeypatch.chdir(clone)

    result = CliRunner().invoke(app, command)

    assert result.exit_code == 0, result.output
    assert fetch[1] == [URL]
    assert victim.read_text() == SENTINEL


@pytest.mark.parametrize("ancestor", [".specify", "workflows", "steps", ".cache"])
def test_symlinked_cache_ancestor_cannot_redirect_write(
    tmp_path, catalog_kind, fetch, ancestor
):
    catalog_cls, entry_cls, *_ = catalog_kind
    if catalog_cls is WorkflowCatalog and ancestor == "steps":
        pytest.skip("Workflow caches have no steps ancestor")
    root = tmp_path / "project"
    root.mkdir()
    catalog = catalog_cls(root)
    rel = catalog.cache_dir.relative_to(root)
    index = rel.parts.index(ancestor)
    parent = root.joinpath(*rel.parts[:index])
    parent.mkdir(parents=True, exist_ok=True)
    outside = tmp_path / "outside"
    outside.mkdir()
    symlink(parent / ancestor, outside, directory=True)

    assert catalog._fetch_single_catalog(entry_cls(URL, "test", 1, False)) == fetch[0]
    assert list(outside.iterdir()) == []


def test_regular_cache_fresh_refresh_and_stale_fallback(
    tmp_path, catalog_kind, fetch, monkeypatch
):
    catalog_cls, entry_cls, *_ = catalog_kind
    catalog = catalog_cls(tmp_path)
    entry = entry_cls(URL, "test", 1, False)
    data, metadata = catalog._get_cache_paths(URL)

    assert catalog._fetch_single_catalog(entry) == fetch[0]
    assert json.loads(data.read_text()) == fetch[0]
    assert json.loads(metadata.read_text())["url"] == URL
    assert catalog._is_url_cache_valid(URL)
    assert catalog._fetch_single_catalog(entry) == fetch[0]
    assert fetch[1] == [URL]
    assert catalog._fetch_single_catalog(entry, force_refresh=True) == fetch[0]
    assert fetch[1] == [URL, URL]
    metadata.write_text(json.dumps({"fetched_at": time.time() - 7200}))

    def unavailable(*args, **kwargs):
        raise URLError("isolated offline test")

    monkeypatch.setattr("specify_cli.authentication.http.open_url", unavailable)
    assert catalog._fetch_single_catalog(entry) == fetch[0]


@pytest.mark.parametrize("leaf", ["data", "metadata"])
@pytest.mark.parametrize("fresh", [False, True])
def test_symlinked_cache_is_not_read(
    tmp_path, catalog_kind, fetch, monkeypatch, leaf, fresh
):
    catalog_cls, entry_cls, field, *_ = catalog_kind
    catalog = catalog_cls(tmp_path)
    data, metadata = catalog._get_cache_paths(URL)
    data.parent.mkdir(parents=True)
    poisoned = {field: {"outside": {"name": "Outside"}}}
    timestamp = time.time() if fresh else 0
    data.write_text(json.dumps(poisoned))
    metadata.write_text(json.dumps({"fetched_at": timestamp}))
    target = tmp_path / "outside.json"
    path = (data, metadata)[leaf == "metadata"]
    target.write_bytes(path.read_bytes())
    path.unlink()
    symlink(path, target)

    if fresh:
        assert (
            catalog._fetch_single_catalog(entry_cls(URL, "test", 1, False)) == fetch[0]
        )
        assert fetch[1] == [URL]
    else:

        def unavailable(*args, **kwargs):
            raise URLError("isolated offline test")

        monkeypatch.setattr("specify_cli.authentication.http.open_url", unavailable)
        if leaf == "data":
            with pytest.raises(
                (WorkflowCatalogError, StepCatalogError),
                match="Failed to fetch catalog",
            ):
                catalog._fetch_single_catalog(entry_cls(URL, "test", 1, False))
        else:
            # An unsafe metadata leaf cannot make the cache fresh, but a safe
            # data leaf remains usable as the ordinary stale/offline fallback.
            assert (
                catalog._fetch_single_catalog(entry_cls(URL, "test", 1, False))
                == poisoned
            )


@pytest.mark.parametrize("leaf", ["data", "metadata"])
def test_cache_replacement_preserves_hardlink_target(
    tmp_path, catalog_kind, fetch, leaf
):
    catalog_cls, entry_cls, *_ = catalog_kind
    catalog = catalog_cls(tmp_path)
    paths = catalog._get_cache_paths(URL)
    paths[0].parent.mkdir(parents=True)
    victim = tmp_path / "victim"
    victim.write_text(SENTINEL)
    os.link(victim, paths[leaf == "metadata"])

    assert catalog._fetch_single_catalog(entry_cls(URL, "test", 1, False)) == fetch[0]
    assert victim.read_text() == SENTINEL
    assert json.loads(paths[leaf == "metadata"].read_text())


@pytest.mark.skipif(os.name == "nt", reason="POSIX descriptor swap regression")
@pytest.mark.parametrize("leaf", ["data", "metadata"])
def test_leaf_swap_at_commit_cannot_redirect_write(
    tmp_path, catalog_kind, monkeypatch, leaf
):
    catalog_cls, *_ = catalog_kind
    path = catalog_cls(tmp_path)._get_cache_paths(URL)[leaf == "metadata"]
    victim = tmp_path / "victim"
    victim.write_text(SENTINEL)
    replace = os.replace

    def swap_then_replace(source, destination, **kwargs):
        symlink(path, victim)
        return replace(source, destination, **kwargs)

    monkeypatch.setattr(os, "replace", swap_then_replace)
    _catalog_cache.write_cache_json(tmp_path, path, {"safe": True})

    assert victim.read_text() == SENTINEL
    assert not path.is_symlink()
    assert json.loads(path.read_text()) == {"safe": True}


@pytest.mark.skipif(os.name == "nt", reason="POSIX descriptor swap regression")
@pytest.mark.parametrize("ancestor", [".specify", "workflows", "steps", ".cache"])
@pytest.mark.parametrize("leaf", ["data", "metadata"])
def test_ancestor_swap_at_commit_cannot_redirect_write(
    tmp_path,
    catalog_kind,
    monkeypatch,
    ancestor,
    leaf,
):
    catalog_cls, *_ = catalog_kind
    if catalog_cls is WorkflowCatalog and ancestor == "steps":
        pytest.skip("Workflow caches have no steps ancestor")
    root = tmp_path / "project"
    root.mkdir()
    path = catalog_cls(root)._get_cache_paths(URL)[leaf == "metadata"]
    parts = path.parent.relative_to(root).parts
    index = parts.index(ancestor)
    swapped = root.joinpath(*parts[: index + 1])
    retained = swapped.with_name(f"{swapped.name}-retained")
    outside = tmp_path / "outside"
    outside.mkdir()
    replace = os.replace

    def swap_then_replace(source, destination, **kwargs):
        swapped.rename(retained)
        symlink(swapped, outside, directory=True)
        return replace(source, destination, **kwargs)

    monkeypatch.setattr(os, "replace", swap_then_replace)
    _catalog_cache.write_cache_json(root, path, {"safe": True})

    assert list(outside.iterdir()) == []
    retained_leaf = retained.joinpath(*parts[index + 1 :], path.name)
    assert json.loads(retained_leaf.read_text()) == {"safe": True}
    assert not list(retained_leaf.parent.glob("*.tmp"))


@pytest.mark.skipif(os.name == "nt", reason="POSIX no-follow open regression")
def test_directory_swap_before_open_is_refused(tmp_path, catalog_kind, monkeypatch):
    catalog_cls, *_ = catalog_kind
    catalog = catalog_cls(tmp_path)
    catalog.cache_dir.mkdir(parents=True)
    path = catalog._get_cache_paths(URL)[0]
    outside = tmp_path / "outside"
    outside.mkdir()
    original_open = os.open

    def swap_then_open(name, flags, *args, **kwargs):
        if name == ".cache":
            catalog.cache_dir.rename(catalog.cache_dir.with_name("retained"))
            symlink(catalog.cache_dir, outside, directory=True)
        return original_open(name, flags, *args, **kwargs)

    monkeypatch.setattr(os, "open", swap_then_open)
    monkeypatch.setattr(os, "supports_dir_fd", os.supports_dir_fd | {swap_then_open})
    with pytest.raises(OSError):
        _catalog_cache.write_cache_json(tmp_path, path, {"safe": True})
    assert list(outside.iterdir()) == []


@pytest.mark.parametrize("leaf", ["data", "metadata"])
def test_failed_replace_preserves_existing_cache_and_logs(
    tmp_path,
    catalog_kind,
    fetch,
    monkeypatch,
    caplog,
    leaf,
):
    catalog_cls, entry_cls, *_ = catalog_kind
    catalog = catalog_cls(tmp_path)
    path = catalog._get_cache_paths(URL)[leaf == "metadata"]
    path.parent.mkdir(parents=True)
    path.write_text(SENTINEL)
    original_replace = os.replace

    def fail_replace(source, destination, **kwargs):
        if str(destination).endswith(path.name):
            raise PermissionError("isolated replace failure")
        return original_replace(source, destination, **kwargs)

    monkeypatch.setattr(os, "replace", fail_replace)
    assert (
        catalog._fetch_single_catalog(entry_cls(URL, "test", 1, False), True)
        == fetch[0]
    )
    assert path.read_text() == SENTINEL
    assert "Could not safely cache" in caplog.text
    assert "isolated replace failure" in caplog.text
    assert not list(path.parent.glob("*.tmp"))


def test_serialization_failure_preserves_existing_cache(tmp_path, catalog_kind):
    catalog_cls, *_ = catalog_kind
    path = catalog_cls(tmp_path)._get_cache_paths(URL)[0]
    path.parent.mkdir(parents=True)
    path.write_text(SENTINEL)

    with pytest.raises(TypeError):
        _catalog_cache.write_cache_json(tmp_path, path, {"invalid": object()})

    assert path.read_text() == SENTINEL
    assert not list(path.parent.glob("*.tmp"))


@pytest.mark.skipif(os.name != "nt", reason="Windows resolved-root cache regression")
def test_path_io_uses_pinned_directory_not_original_alias(tmp_path, catalog_kind):
    catalog_cls, *_ = catalog_kind
    root = tmp_path / "project"
    root.mkdir()
    alias = tmp_path / "original-alias"
    junction(alias, root)
    path = catalog_cls(alias)._get_cache_paths(URL)[0]
    _catalog_cache.write_cache_json(alias, path, {"safe": True})

    with _catalog_cache._cache_directory(alias, path.parent, create=False) as pinned:
        assert pinned == path.parent.resolve()
        assert pinned != path.parent
    assert _catalog_cache.read_cache_json(alias, path) == {"safe": True}
    assert json.loads(catalog_cls(root)._get_cache_paths(URL)[0].read_text()) == {
        "safe": True
    }


@pytest.mark.skipif(os.name != "nt", reason="Windows handle pinning regression")
@pytest.mark.parametrize("ancestor", [".specify", "workflows", "steps", ".cache"])
def test_windows_directory_handle_prevents_swap(tmp_path, catalog_kind, ancestor):
    catalog_cls, *_ = catalog_kind
    if catalog_cls is WorkflowCatalog and ancestor == "steps":
        pytest.skip("Workflow caches have no steps ancestor")
    catalog = catalog_cls(tmp_path)
    catalog.cache_dir.mkdir(parents=True)
    parts = catalog.cache_dir.relative_to(tmp_path).parts
    path = tmp_path.joinpath(*parts[: parts.index(ancestor) + 1])
    with (
        _catalog_cache._cache_directory(tmp_path, catalog.cache_dir, create=False),
        pytest.raises(OSError),
    ):
        path.rename(path.with_name("swapped"))

    path.rename(path.with_name("swapped"))


@pytest.mark.skipif(os.name != "nt", reason="Windows native file handle regression")
@pytest.mark.parametrize(
    ("kind", "directory", "allowed"),
    [
        ("directory", True, True),
        ("file", False, True),
        ("junction", True, False),
        ("symlink", False, False),
        ("file", True, False),
        ("directory", False, False),
    ],
)
def test_windows_handle_rejects_reparse_points_and_wrong_types(
    tmp_path,
    kind,
    directory,
    allowed,
):
    path = tmp_path / "path"
    if kind == "directory":
        path.mkdir()
    elif kind == "file":
        path.write_text(SENTINEL)
    elif kind == "junction":
        target = tmp_path / "target"
        target.mkdir()
        junction(path, target)
    else:
        target = tmp_path / "target"
        target.write_text(SENTINEL)
        symlink(path, target)

    if allowed:
        with _catalog_cache._windows_handle(path, directory=directory) as handle:
            assert handle is not None
            with pytest.raises(OSError):
                path.rename(path.with_name("renamed"))
        path.rename(path.with_name("renamed"))
    else:
        with (
            pytest.raises(OSError),
            _catalog_cache._windows_handle(
                path,
                directory=directory,
            ),
        ):
            pytest.fail("An unsafe Windows path was accepted")
        path.rename(path.with_name("renamed"))


@pytest.mark.skipif(os.name != "nt", reason="Windows native junction cache regression")
@pytest.mark.parametrize("ancestor", [".specify", "workflows", "steps", ".cache"])
def test_windows_junction_ancestor_cannot_redirect_write(
    tmp_path,
    catalog_kind,
    fetch,
    caplog,
    ancestor,
):
    catalog_cls, entry_cls, *_ = catalog_kind
    if catalog_cls is WorkflowCatalog and ancestor == "steps":
        pytest.skip("Workflow caches have no steps ancestor")
    root = tmp_path / "project"
    root.mkdir()
    catalog = catalog_cls(root)
    parts = catalog.cache_dir.relative_to(root).parts
    index = parts.index(ancestor)
    parent = root.joinpath(*parts[:index])
    parent.mkdir(parents=True, exist_ok=True)
    outside = tmp_path / "outside"
    outside.mkdir()
    junction(parent / ancestor, outside)

    assert catalog._fetch_single_catalog(entry_cls(URL, "test", 1, False)) == fetch[0]
    assert list(outside.iterdir()) == []
    assert "Could not safely cache" in caplog.text


@pytest.mark.skipif(os.name == "nt", reason="POSIX capability refusal regression")
def test_unsupported_safe_io_continues_discovery_with_warning(
    tmp_path,
    catalog_kind,
    fetch,
    monkeypatch,
    caplog,
):
    catalog_cls, entry_cls, *_ = catalog_kind
    catalog = catalog_cls(tmp_path)
    monkeypatch.setattr(os, "supports_dir_fd", set())

    assert catalog._fetch_single_catalog(entry_cls(URL, "test", 1, False)) == fetch[0]
    assert not catalog.cache_dir.exists()
    assert "Safe catalog cache I/O is unsupported" in caplog.text