nab-index 0.0.1__tar.gz

nab_index-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Damian Shaw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nab_index-0.0.1/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: nab-index
+Version: 0.0.1
+Summary: PyPI Simple-API client and on-disk cache for nab
+Project-URL: Homepage, https://github.com/notatallshaw/nab
+Project-URL: Documentation, https://nab.readthedocs.io/
+Project-URL: Issues, https://github.com/notatallshaw/nab/issues
+Project-URL: Source, https://github.com/notatallshaw/nab
+Project-URL: Changelog, https://github.com/notatallshaw/nab/blob/main/CHANGELOG.md
+Author-email: Damian Shaw <damian.peter.shaw@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: packaging>=24.0
+Requires-Dist: typing-extensions>=4.6
+Requires-Dist: urllib3>=2.0
+Provides-Extra: httpx
+Requires-Dist: httpx[http2]>=0.28; extra == 'httpx'
+Provides-Extra: niquests
+Requires-Dist: niquests>=3.18; extra == 'niquests'
+Description-Content-Type: text/markdown
+
+# nab-index
+
+PyPI Simple-API client and on-disk cache used by
+[`nab-python`](https://pypi.org/project/nab-python/) and
+[`nab`](https://pypi.org/project/nab/).
+
+It provides:
+
+- A small async transport interface with three drop-in backends:
+  - `urllib3` (default; pulled in by the base install).
+  - `httpx` (extra: `nab-index[httpx]`).
+  - `niquests` (extra: `nab-index[niquests]`).
+- A Simple-API client with JSON and HTML decoders.
+- A disk cache for project listings and file metadata responses.
+- A multi-index router (ordered named indexes plus per-package
+  overrides guarded by PEP 508 markers).
+- A small VCS clone helper used by the higher-level VCS policy.
+
+## When to use it
+
+Use `nab-index` if you need a typed PyPI Simple-API client with an
+on-disk cache.  Most users want
+[`nab`](https://pypi.org/project/nab/) instead.
+
+The API is currently under rapid experimentation, if you use it
+pin to an exact version.

nab_index-0.0.1/README.md

@@ -0,0 +1,26 @@
+# nab-index
+
+PyPI Simple-API client and on-disk cache used by
+[`nab-python`](https://pypi.org/project/nab-python/) and
+[`nab`](https://pypi.org/project/nab/).
+
+It provides:
+
+- A small async transport interface with three drop-in backends:
+  - `urllib3` (default; pulled in by the base install).
+  - `httpx` (extra: `nab-index[httpx]`).
+  - `niquests` (extra: `nab-index[niquests]`).
+- A Simple-API client with JSON and HTML decoders.
+- A disk cache for project listings and file metadata responses.
+- A multi-index router (ordered named indexes plus per-package
+  overrides guarded by PEP 508 markers).
+- A small VCS clone helper used by the higher-level VCS policy.
+
+## When to use it
+
+Use `nab-index` if you need a typed PyPI Simple-API client with an
+on-disk cache.  Most users want
+[`nab`](https://pypi.org/project/nab/) instead.
+
+The API is currently under rapid experimentation, if you use it
+pin to an exact version.

nab_index-0.0.1/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "nab-index"
+version = "0.0.1"
+description = "PyPI Simple-API client and on-disk cache for nab"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Damian Shaw", email = "damian.peter.shaw@gmail.com" },
+]
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "packaging>=24.0",
+    "typing_extensions>=4.6",
+    "urllib3>=2.0",
+]
+
+[project.optional-dependencies]
+httpx = ["httpx[http2]>=0.28"]
+niquests = ["niquests>=3.18"]
+
+[project.urls]
+Homepage = "https://github.com/notatallshaw/nab"
+Documentation = "https://nab.readthedocs.io/"
+Issues = "https://github.com/notatallshaw/nab/issues"
+Source = "https://github.com/notatallshaw/nab"
+Changelog = "https://github.com/notatallshaw/nab/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

nab_index-0.0.1/src/nab_index/__init__.py

@@ -0,0 +1 @@
+"""PyPI Simple-API client and on-disk cache."""

nab_index-0.0.1/src/nab_index/_naming.py

@@ -0,0 +1,25 @@
+"""PEP 503 name canonicalisation for nab-index.
+
+Wraps :func:`packaging.utils.canonicalize_name` so the local- and
+multi-index modules share a single helper.  ``packaging`` is already
+a runtime dependency (see ``pyproject.toml``), so deferring to it
+avoids the divergent regexes the helpers used to carry.
+"""
+
+from __future__ import annotations
+
+from packaging.utils import canonicalize_name
+
+__all__ = [
+    "canonical",
+]
+
+
+def canonical(name: str) -> str:
+    """Return ``name`` as its PEP 503 canonical form.
+
+    Lower-cases the input and collapses runs of ``-``, ``_``, ``.``
+    to a single ``-`` per PEP 503.  Leading and trailing dashes are
+    preserved (consistent with :func:`packaging.utils.canonicalize_name`).
+    """
+    return canonicalize_name(name)

nab_index-0.0.1/src/nab_index/cache.py

@@ -0,0 +1,277 @@
+"""On-disk cache for nab-index.
+
+Stores PEP 691 Simple API responses (raw JSON body plus a sidecar
+cache policy file) and PEP 658 wheel metadata (raw text, treated as
+immutable). The cache is consulted by :class:`CachedAsyncSimpleClient`
+before any HTTP transport call.
+
+Layout under ``root``:
+
+    simple-v0/<index>/<package>.json       <- raw PyPI JSON body
+    simple-v0/<index>/<package>.policy     <- {fetched_at, max_age, etag}
+    metadata-v0/<index>/<package>/<version>.metadata
+    sdist-pkginfo-v0/<index>/<package>/<version>.txt
+
+A versioned bucket name (``simple-v0``) gives zero-cost schema
+migration: when the on-disk format changes, bump the suffix and the
+old directory is harmless.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import json
+import os
+import tempfile
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+__all__ = [
+    "CacheBackend",
+    "CachePolicy",
+    "NullCache",
+    "OfflineError",
+    "OnDiskCache",
+]
+
+
+CACHE_VERSION_SIMPLE = "v0"
+CACHE_VERSION_METADATA = "v0"
+CACHE_VERSION_SDIST = "v0"
+
+DEFAULT_PYPI_URLS = frozenset(
+    [
+        "https://pypi.org/simple",
+        "http://pypi.org/simple",
+    ]
+)
+
+
+class OfflineError(Exception):
+    """Raised when offline mode is set and a needed entry is not cached."""
+
+
+@dataclass(frozen=True, slots=True)
+class CachePolicy:
+    """RFC 9111-style freshness policy for one Simple API entry."""
+
+    fetched_at: int
+    max_age: int
+    etag: str | None
+
+    def is_fresh(self, now: int | None = None) -> bool:
+        """Return True if the entry is still within its freshness window."""
+        current = int(time.time()) if now is None else now
+        return current - self.fetched_at < self.max_age
+
+
+def _index_dirname(index_url: str) -> str:
+    """Return a stable, filesystem-safe directory name for an index URL."""
+    if index_url.rstrip("/") in DEFAULT_PYPI_URLS:
+        return "pypi"
+    return hashlib.sha256(index_url.encode("utf-8")).hexdigest()[:16]
+
+
+def _atomic_write(path: Path, data: bytes) -> None:
+    """Write ``data`` to ``path`` atomically via tempfile + replace.
+
+    The temp file is created in the destination directory so the rename
+    is a same-filesystem operation. A partial write or a crash leaves
+    the target file untouched.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=path.name + ".", suffix=".tmp")
+    tmp_path = Path(tmp)
+    try:
+        with os.fdopen(fd, "wb") as f:
+            f.write(data)
+        tmp_path.replace(path)
+    except BaseException:
+        with contextlib.suppress(OSError):
+            tmp_path.unlink()
+        raise
+
+
+def _read_text(path: Path) -> str | None:
+    """Return ``path``'s UTF-8 contents, or ``None`` if the file is absent."""
+    try:
+        return path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+
+
+class OnDiskCache:
+    """File-per-key cache for Simple API and wheel metadata."""
+
+    def __init__(self, root: Path, index_url: str) -> None:
+        """Create a cache rooted at ``root`` for ``index_url``."""
+        self._root = root
+        self._index = _index_dirname(index_url)
+        self._simple_dir = root / f"simple-{CACHE_VERSION_SIMPLE}" / self._index
+        self._metadata_dir = root / f"metadata-{CACHE_VERSION_METADATA}" / self._index
+        self._sdist_dir = root / f"sdist-pkginfo-{CACHE_VERSION_SDIST}" / self._index
+        self._sdist_pyproject_dir = (
+            root / f"sdist-pyproject-{CACHE_VERSION_SDIST}" / self._index
+        )
+
+    def _simple_paths(self, package: str) -> tuple[Path, Path]:
+        body = self._simple_dir / f"{package}.json"
+        policy = self._simple_dir / f"{package}.policy"
+        return (body, policy)
+
+    def get_simple(self, package: str) -> tuple[bytes, CachePolicy] | None:
+        """Return ``(body_bytes, policy)`` if cached, else ``None``."""
+        body_path, policy_path = self._simple_paths(package)
+        try:
+            policy_bytes = policy_path.read_bytes()
+            body = body_path.read_bytes()
+        except OSError:
+            return None
+        try:
+            policy_doc = json.loads(policy_bytes)
+            policy = CachePolicy(
+                fetched_at=int(policy_doc["fetched_at"]),
+                max_age=int(policy_doc["max_age"]),
+                etag=policy_doc.get("etag"),
+            )
+        except (ValueError, KeyError, TypeError):
+            return None
+        return (body, policy)
+
+    def put_simple(self, package: str, body: bytes, policy: CachePolicy) -> None:
+        """Write the body and the policy sidecar atomically."""
+        body_path, policy_path = self._simple_paths(package)
+        _atomic_write(body_path, body)
+        _atomic_write(policy_path, _encode_policy(policy))
+
+    def refresh_simple_policy(self, package: str, policy: CachePolicy) -> None:
+        """Replace the policy sidecar without touching the body.
+
+        Called after a 304 Not Modified, where the cached body is still
+        valid but the freshness window has slid forward.
+        """
+        _, policy_path = self._simple_paths(package)
+        _atomic_write(policy_path, _encode_policy(policy))
+
+    def get_metadata(self, package: str, version: str) -> str | None:
+        """Return cached PEP 658 metadata text, or ``None`` on miss."""
+        return _read_text(self._metadata_dir / package / f"{version}.metadata")
+
+    def put_metadata(self, package: str, version: str, text: str) -> None:
+        """Write PEP 658 metadata text. Treated as immutable."""
+        _atomic_write(
+            self._metadata_dir / package / f"{version}.metadata",
+            text.encode("utf-8"),
+        )
+
+    def get_sdist_pkginfo(self, package: str, version: str) -> str | None:
+        """Return cached sdist PKG-INFO text, or ``None`` on miss."""
+        return _read_text(self._sdist_dir / package / f"{version}.txt")
+
+    def put_sdist_pkginfo(self, package: str, version: str, text: str) -> None:
+        """Write sdist PKG-INFO text. Treated as immutable."""
+        _atomic_write(
+            self._sdist_dir / package / f"{version}.txt", text.encode("utf-8")
+        )
+
+    def get_sdist_pyproject(self, package: str, version: str) -> str | None:
+        """Return cached sdist pyproject.toml text, or ``None`` on miss."""
+        return _read_text(self._sdist_pyproject_dir / package / f"{version}.toml")
+
+    def put_sdist_pyproject(self, package: str, version: str, text: str) -> None:
+        """Write sdist pyproject.toml text. Treated as immutable."""
+        _atomic_write(
+            self._sdist_pyproject_dir / package / f"{version}.toml",
+            text.encode("utf-8"),
+        )
+
+
+def _encode_policy(policy: CachePolicy) -> bytes:
+    return json.dumps(
+        {
+            "fetched_at": policy.fetched_at,
+            "max_age": policy.max_age,
+            "etag": policy.etag,
+        }
+    ).encode("utf-8")
+
+
+class CacheBackend(Protocol):
+    """Protocol shared by :class:`OnDiskCache` and :class:`NullCache`."""
+
+    def get_simple(self, package: str) -> tuple[bytes, CachePolicy] | None:
+        """Return ``(body_bytes, policy)`` if cached, else ``None``."""
+        ...
+
+    def put_simple(self, package: str, body: bytes, policy: CachePolicy) -> None:
+        """Store a Simple API body and its freshness policy."""
+        ...
+
+    def refresh_simple_policy(self, package: str, policy: CachePolicy) -> None:
+        """Update the policy for an existing entry without rewriting the body."""
+        ...
+
+    def get_metadata(self, package: str, version: str) -> str | None:
+        """Return cached PEP 658 metadata text, or ``None`` on miss."""
+        ...
+
+    def put_metadata(self, package: str, version: str, text: str) -> None:
+        """Store PEP 658 metadata text. Treated as immutable."""
+        ...
+
+    def get_sdist_pkginfo(self, package: str, version: str) -> str | None:
+        """Return cached sdist PKG-INFO text, or ``None`` on miss."""
+        ...
+
+    def put_sdist_pkginfo(self, package: str, version: str, text: str) -> None:
+        """Store sdist PKG-INFO text. Treated as immutable."""
+        ...
+
+    def get_sdist_pyproject(self, package: str, version: str) -> str | None:
+        """Return cached sdist pyproject.toml text, or ``None`` on miss."""
+        ...
+
+    def put_sdist_pyproject(self, package: str, version: str, text: str) -> None:
+        """Store sdist pyproject.toml text. Treated as immutable."""
+        ...
+
+
+class NullCache:
+    """No-op cache backend used when persistence is disabled.
+
+    Lets :class:`CachedAsyncSimpleClient` be used unconditionally so
+    the call site does not branch on whether a cache is configured.
+    Each method is a docstring-only stub: gets implicitly return
+    ``None`` (a permanent miss) and puts implicitly do nothing.
+    Argument names match :class:`CacheBackend` for Protocol conformance.
+    """
+
+    def get_simple(self, package: str) -> tuple[bytes, CachePolicy] | None:
+        """Return ``None`` (always a miss)."""
+
+    def put_simple(self, package: str, body: bytes, policy: CachePolicy) -> None:
+        """Discard the entry."""
+
+    def refresh_simple_policy(self, package: str, policy: CachePolicy) -> None:
+        """Discard the policy refresh."""
+
+    def get_metadata(self, package: str, version: str) -> str | None:
+        """Return ``None`` (always a miss)."""
+
+    def put_metadata(self, package: str, version: str, text: str) -> None:
+        """Discard the entry."""
+
+    def get_sdist_pkginfo(self, package: str, version: str) -> str | None:
+        """Return ``None`` (always a miss)."""
+
+    def put_sdist_pkginfo(self, package: str, version: str, text: str) -> None:
+        """Discard the entry."""
+
+    def get_sdist_pyproject(self, package: str, version: str) -> str | None:
+        """Return ``None`` (always a miss)."""
+
+    def put_sdist_pyproject(self, package: str, version: str, text: str) -> None:
+        """Discard the entry."""

nab_index-0.0.1/src/nab_index/cached_client.py

@@ -0,0 +1,236 @@
+"""Disk-cached PyPI Simple API client.
+
+Wraps :class:`AsyncSimpleClient`. Consults an :class:`OnDiskCache`
+before any HTTP transport call. Honors a small subset of RFC 9111:
+fresh entries are served directly, stale entries are revalidated with
+``If-None-Match``, and PEP 658 metadata + sdist PKG-INFO are treated
+as immutable (cached forever; never revalidated).
+
+Cache hits short-circuit before any HTTP code runs. With a fully
+populated cache the client never opens a socket.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+from typing import TYPE_CHECKING
+
+from .cache import CacheBackend, CachePolicy, OfflineError
+from .client import (
+    DEFAULT_INDEX,
+    SdistFile,
+    WheelFile,
+    _extract_sdist_files,
+    _parse_files,
+)
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+    from .transport import AsyncHttpTransport, HttpResponse
+
+__all__ = [
+    "CachedAsyncSimpleClient",
+]
+
+
+_JSON_ACCEPT = "application/vnd.pypi.simple.v1+json"
+_DEFAULT_MAX_AGE = 600
+_HTTP_NOT_MODIFIED = 304
+_MAX_AGE_RE = re.compile(r"max-age\s*=\s*(\d+)")
+
+
+def _parse_max_age(cache_control: str | None) -> int:
+    if cache_control is None:
+        return _DEFAULT_MAX_AGE
+    match = _MAX_AGE_RE.search(cache_control)
+    if match is None:
+        return _DEFAULT_MAX_AGE
+    return int(match.group(1))
+
+
+def _header(response: HttpResponse, key: str) -> str | None:
+    """Case-insensitive header lookup.
+
+    The :class:`HttpResponse` Protocol only promises a plain
+    :class:`Mapping`. All real transports (httpx, niquests, urllib3)
+    return case-insensitive header containers, but we don't rely on
+    that here so a plain-dict fake also works.
+    """
+    headers = response.headers
+    target = key.lower()
+    for name, value in headers.items():
+        if name.lower() == target:
+            return value
+    return None
+
+
+class CachedAsyncSimpleClient:
+    """Async PyPI Simple API client with on-disk caching.
+
+    Distinct from :class:`AsyncSimpleClient`: the metadata methods
+    take ``(package, version)`` so the cache can key by package
+    coordinate rather than URL. The interface mirrors what
+    :class:`FetchCoordinator` actually needs.
+    """
+
+    def __init__(
+        self,
+        transport: AsyncHttpTransport,
+        cache: CacheBackend,
+        index_url: str = DEFAULT_INDEX,
+        *,
+        offline: bool = False,
+    ) -> None:
+        """Create a cached client wrapping ``transport``."""
+        self._transport = transport
+        self._cache = cache
+        self._index_url = index_url.rstrip("/") + "/"
+        self._offline = offline
+
+    async def aclose(self) -> None:
+        """Close the underlying transport."""
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> Self:
+        """Enter the async context manager."""
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        """Exit the async context manager and close the transport."""
+        await self.aclose()
+
+    async def get_files(self, package: str) -> list[WheelFile | SdistFile]:
+        """Return parsed Simple API file list for ``package``.
+
+        Cache hit + fresh: parses cached body, no network.
+        Cache hit + stale + online: conditional revalidation; on 304
+        the body is reused, on 200 the body is replaced.
+        Cache hit + offline: cached body is returned regardless of age.
+        Cache miss + offline: raises :class:`OfflineError`.
+        Cache miss + online: fetches, caches, returns.
+        """
+        cached = self._cache.get_simple(package)
+        if cached is not None:
+            body, policy = cached
+            if policy.is_fresh() or self._offline:
+                return _parse_files(json.loads(body), self._index_url, package)
+            return await self._revalidate_simple(package, body, policy)
+
+        if self._offline:
+            msg = f"No cached listing for {package} (offline mode)"
+            raise OfflineError(msg)
+        return await self._fetch_simple(package)
+
+    async def _revalidate_simple(
+        self, package: str, body: bytes, policy: CachePolicy
+    ) -> list[WheelFile | SdistFile]:
+        url = f"{self._index_url}{package}/"
+        headers = {"Accept": _JSON_ACCEPT}
+        if policy.etag is not None:
+            headers["If-None-Match"] = policy.etag
+        response = await self._transport.get(url, headers=headers)
+        if response.status_code == _HTTP_NOT_MODIFIED:
+            new_policy = CachePolicy(
+                fetched_at=int(time.time()),
+                max_age=_parse_max_age(_header(response, "cache-control")),
+                etag=_header(response, "etag") or policy.etag,
+            )
+            self._cache.refresh_simple_policy(package, new_policy)
+            return _parse_files(json.loads(body), self._index_url, package)
+
+        response.raise_for_status()
+        new_body = response.content
+        new_policy = CachePolicy(
+            fetched_at=int(time.time()),
+            max_age=_parse_max_age(_header(response, "cache-control")),
+            etag=_header(response, "etag"),
+        )
+        self._cache.put_simple(package, new_body, new_policy)
+        return _parse_files(json.loads(new_body), self._index_url, package)
+
+    async def _fetch_simple(self, package: str) -> list[WheelFile | SdistFile]:
+        url = f"{self._index_url}{package}/"
+        response = await self._transport.get(url, headers={"Accept": _JSON_ACCEPT})
+        response.raise_for_status()
+        body = response.content
+        policy = CachePolicy(
+            fetched_at=int(time.time()),
+            max_age=_parse_max_age(_header(response, "cache-control")),
+            etag=_header(response, "etag"),
+        )
+        self._cache.put_simple(package, body, policy)
+        return _parse_files(json.loads(body), self._index_url, package)
+
+    async def get_metadata_text(
+        self, package: str, version: str, metadata_url: str
+    ) -> str:
+        """Return PEP 658 metadata text for ``(package, version)``.
+
+        Treated as immutable: cached forever, never revalidated.
+        Cache miss + offline raises :class:`OfflineError`.
+        """
+        cached = self._cache.get_metadata(package, version)
+        if cached is not None:
+            return cached
+
+        if self._offline:
+            msg = f"No cached metadata for {package}=={version} (offline mode)"
+            raise OfflineError(msg)
+
+        response = await self._transport.get(metadata_url)
+        response.raise_for_status()
+        text = response.text
+        self._cache.put_metadata(package, version, text)
+        return text
+
+    async def get_sdist_files(
+        self, package: str, version: str, sdist_url: str
+    ) -> tuple[str | None, str | None]:
+        """Return ``(pkg_info, pyproject_toml)`` for an sdist, caching both.
+
+        Cache miss + offline raises :class:`OfflineError`.  Either
+        element may be ``None`` if the corresponding file is absent
+        from the archive (or the archive cannot be parsed).  Both are
+        treated as immutable: cached forever, never revalidated.
+        """
+        pkg_info = self._cache.get_sdist_pkginfo(package, version)
+        pyproject_toml = self._cache.get_sdist_pyproject(package, version)
+        if pkg_info is not None:
+            return (pkg_info, pyproject_toml)
+
+        if self._offline:
+            msg = f"No cached sdist PKG-INFO for {package}=={version} (offline mode)"
+            raise OfflineError(msg)
+
+        response = await self._transport.get(sdist_url)
+        response.raise_for_status()
+        pkg_info, pyproject_toml = _extract_sdist_files(response.content)
+
+        if pkg_info is not None:
+            self._cache.put_sdist_pkginfo(package, version, pkg_info)
+        if pyproject_toml is not None:
+            self._cache.put_sdist_pyproject(package, version, pyproject_toml)
+
+        return (pkg_info, pyproject_toml)
+
+    async def get_sdist_archive(
+        self, package: str, version: str, sdist_url: str
+    ) -> bytes:
+        """Return the raw bytes of an sdist archive.
+
+        Used by the ``BUILD_REMOTE`` path when a real backend invocation
+        is required.  No on-disk caching is performed: archives are
+        large, builds are rare, and the in-memory index already
+        deduplicates within a single resolve.  Offline mode raises
+        :class:`OfflineError` because there is no slot to read from.
+        """
+        del package, version  # offline check below is the only use
+        if self._offline:
+            msg = f"sdist archive fetch unavailable in offline mode ({sdist_url})"
+            raise OfflineError(msg)
+        response = await self._transport.get(sdist_url)
+        response.raise_for_status()
+        return response.content