Make clear_caches safe under concurrent pip-compile --rebuild

Two ``pip-compile --rebuild`` invocations sharing a ``cache_dir`` race
inside ``PyPIRepository.clear_caches``: both call ``rmtree`` on the
same download directory, and one will be midway through deleting it
while the other tries to walk it for fresh downloads, leaving a
partial tree the second resolver then trips over. ``ignore_errors=True``
hides the error but not the corruption.

Atomically rename the download directory to a per-PID sibling before
deleting it. The atomic rename is the only step a concurrent peer can
observe, so the peer either still sees the original directory or sees
nothing at all, never partial state. The renamed copy is then removed
opportunistically; if a racing peer beat us to the rename, the
``OSError`` is swallowed because the cache wipe has effectively already
happened.

Author: gaborbernat

changelog.d/2393.bugfix.md

@@ -0,0 +1,5 @@
+:meth:`piptools.repositories.PyPIRepository.clear_caches` is now safe to invoke
+concurrently against the same ``cache_dir``: the download directory is renamed
+atomically before deletion, so a parallel :command:`pip-compile --rebuild`
+lookup either still sees the old directory or no directory at all and never
+trips over a half-deleted tree (:issue:`2393`) -- by :user:`gaborbernat`.

piptools/repositories/pypi.py

@@ -104,7 +104,21 @@ def __init__(self, pip_args: list[str], cache_dir: str):
         )
 
     def clear_caches(self) -> None:
-        rmtree(self._download_dir, ignore_errors=True)
+        # Two ``pip-compile --rebuild`` runs against the same ``cache_dir``
+        # would otherwise have one ``rmtree`` wipe the other's in-flight
+        # downloads, leaving the second resolver staring at a half-deleted
+        # tree. Atomically rename out of the way first so a concurrent
+        # lookup either still sees the old directory or sees nothing at
+        # all, never partial state. The renamed copy is then deleted
+        # opportunistically.
+        if not os.path.exists(self._download_dir):
+            return
+        stale = f"{self._download_dir}.stale-{os.getpid()}"
+        try:
+            os.replace(self._download_dir, stale)
+        except OSError:
+            return
+        rmtree(stale, ignore_errors=True)
 
     @property
     def options(self) -> optparse.Values:

pyproject.toml

@@ -58,6 +58,7 @@ changelog = "https://github.com/jazzband/pip-tools/releases"
 [project.optional-dependencies]
 testing = [
   "pytest >= 7.2.0",
+  "pytest-mock >= 3.15.1",
   "pytest-rerunfailures",
   "pytest-xdist",
   "tomli-w",

tests/test_repository_pypi.py

@@ -1,13 +1,15 @@
 from __future__ import annotations
 
 import os
+from pathlib import Path
 from unittest import mock
 
 import pytest
 from pip._internal.models.candidate import InstallationCandidate
 from pip._internal.models.link import Link
 from pip._internal.utils.urls import path_to_url
 from pip._vendor.requests import HTTPError, Session
+from pytest_mock import MockerFixture
 
 from piptools.repositories import PyPIRepository
 from piptools.repositories.pypi import open_local_or_remote_file
@@ -169,6 +171,48 @@ def test_pip_cache_dir_is_empty(from_line, tmpdir):
     assert not pypi_repository.options.cache_dir
 
 
+@pytest.fixture
+def repo_with_cache_dir(tmp_path: Path) -> PyPIRepository:
+    return PyPIRepository([], cache_dir=str(tmp_path / "cache"))
+
+
+def test_clear_caches_removes_existing_download_dir(
+    repo_with_cache_dir: PyPIRepository,
+) -> None:
+    download_dir = Path(repo_with_cache_dir._download_dir)
+    download_dir.mkdir(parents=True, exist_ok=True)
+    (download_dir / "marker").write_text("x")
+
+    repo_with_cache_dir.clear_caches()
+
+    assert not download_dir.exists()
+
+
+def test_clear_caches_when_download_dir_missing_is_a_no_op(
+    repo_with_cache_dir: PyPIRepository,
+) -> None:
+    assert not Path(repo_with_cache_dir._download_dir).exists()
+
+    repo_with_cache_dir.clear_caches()
+
+    assert not Path(repo_with_cache_dir._download_dir).exists()
+
+
+def test_clear_caches_swallows_replace_failure(
+    repo_with_cache_dir: PyPIRepository, mocker: MockerFixture
+) -> None:
+    Path(repo_with_cache_dir._download_dir).mkdir(parents=True, exist_ok=True)
+    mocker.patch(
+        "piptools.repositories.pypi.os.replace",
+        side_effect=OSError("racing peer renamed first"),
+    )
+    rmtree = mocker.patch("piptools.repositories.pypi.rmtree")
+
+    repo_with_cache_dir.clear_caches()
+
+    rmtree.assert_not_called()
+
+
 @pytest.mark.parametrize(
     ("project_data", "expected_hashes"),
     (