Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

feature/Symlinked-methodstoml-read · L-261001-671b1d (#1315)

Louis Choquelde1e553fe365
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7b2eb8917..0aaab5cfc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,15 @@
# Changelog
+## [Unreleased]
+
+### Fixed
+
+- **A symlink in a fetched package is a 422 on the API server**: `MethodPackageSymlinkError`, raised when a package fetched by `method_ref` carries a symlink, is now answered as a 422 the method's author can act on, where it was a 500 server fault.
+
+### Security
+
+- **Locating a fetched package never follows a symlinked `METHODS.toml`**: when `pipelex run <address>`, fetch-on-miss or the API server's `method_ref` scans a fetched repository for its packages, a `METHODS.toml` that is a symlink, or is not a regular file, is now skipped and reported without being opened. A repository could commit one linking to a file on the fetching machine and get that file's values back in the error message, even under strict error disclosure, or link it to `/dev/zero` and make the read run without end. The read now also stops at the manifest size ceiling whatever size the file reports, and a manifest that is not valid UTF-8, or a directory named `METHODS.toml`, is skipped and reported instead of failing the whole fetch.
+
## [v0.71.0] - 2026-10-01
### Highlights
diff --git a/api/pipelex_api/exception_handlers.py b/api/pipelex_api/exception_handlers.py
index 06c38e50f..3b0101290 100644
--- a/api/pipelex_api/exception_handlers.py
+++ b/api/pipelex_api/exception_handlers.py
@@ -340,6 +340,10 @@ _ERROR_TYPE_STATUS_OVERRIDES: dict[str, int] = {
# cannot be processed under this deployment's bounds → 422 (not 413, which is about
# the request entity itself).
"MethodPackageTooLargeError": 422,
+ # - The selected package carries a symlink, file or directory, which fetched packages must
+ # not: a rule about the fetched content that the method's author fixes by removing the
+ # link → 422, like the ceilings above (not 403, kept for refusing in-process Python).
+ "MethodPackageSymlinkError": 422,
# - The method's Python declares structure classes, whether it was sent as a bundle or
# fetched by `method_ref`: a policy refusal (hosted execution accepts MTHDS concepts and
# sandboxed PipeFuncs, not in-process Python) → 403, the same status as the bundle
diff --git a/api/pipelex_api/method_cache.py b/api/pipelex_api/method_cache.py
index e43294ad5..f69ab8785 100644
--- a/api/pipelex_api/method_cache.py
+++ b/api/pipelex_api/method_cache.py
@@ -157,6 +157,7 @@ class MethodCloneCache:
MethodPackageNotFoundError: If no package matches the requested address.
MethodPackageAmbiguityError: If more than one package matches.
MethodPackageTooLargeError: If the selected package exceeds the ceilings.
+ MethodPackageSymlinkError: If the selected package contains a symlink.
"""
commit_sha = resolve_remote_commit_sha(ref=ref, clone_url=clone_url)
clone_dir = self._root / commit_sha
diff --git a/api/tests/unit/test_exception_handlers.py b/api/tests/unit/test_exception_handlers.py
index b34dee41e..fe360da9e 100644
--- a/api/tests/unit/test_exception_handlers.py
+++ b/api/tests/unit/test_exception_handlers.py
@@ -27,6 +27,7 @@ from pipelex.base_exceptions import (
from pipelex.cogt.inference.error_classification import ProviderErrorMetadata, UserAction, UserActionKind
from pipelex.cogt.inference.provider_name import ProviderName
from pipelex.config import get_config
+from pipelex.methods.exceptions import MethodPackageSymlinkError
from pipelex.pipe_run.exceptions import AsyncExecutionNotEnabledError
from pipelex.pipeline.exceptions import PipelineManagerAlreadyExistsError
from pipelex.plugins.contract import PLUGIN_API_VERSION
@@ -263,6 +264,15 @@ async def pipeline_run_id_conflict_route() -> None:
raise PipelineManagerAlreadyExistsError(msg)
+@_router.get("/method-package-symlink")
+async def method_package_symlink_route() -> None:
+ # Pipelex raises this from ``ensure_package_within_bounds`` when a package fetched
+ # by ``method_ref`` carries a symlink. The API maps it to 422 (see
+ # ``_ERROR_TYPE_STATUS_OVERRIDES``).
+ msg = "Method package 'github.com/acme/linked' contains a symlink ('vendored') — fetched packages must not contain symlinks."
+ raise MethodPackageSymlinkError(msg)
+
+
@_router.get("/synthetic-transport-error")
async def synthetic_transport_error_route() -> None:
msg = "orchestrator cluster unreachable"
@@ -943,6 +953,23 @@ class TestExceptionHandlers:
assert body["type"].endswith("/pipeline-manager-already-exists-error/")
assert body["request_id"] == response.headers[REQUEST_ID_HEADER]
+ def test_method_package_symlink_maps_to_422(self, mocker: MockerFixture):
+ # ``MethodPackageSymlinkError`` carries no ``error_domain`` (-> 500 under the
+ # default mapping), but a symlink in a fetched package is a rule about the
+ # fetched content that its author fixes, not a server fault: the API overrides
+ # it to 422, like the fetched-package ceilings, and logs it at warning.
+ log_spy = mocker.patch("pipelex_api.exception_handlers.log")
+ response = _build_client().get("/method-package-symlink")
+ assert response.status_code == 422
+ assert response.headers["content-type"] == PROBLEM_JSON_MEDIA_TYPE
+ body = response.json()
+ assert body["status"] == 422
+ assert body["error_type"] == "MethodPackageSymlinkError"
+ assert "contains a symlink ('vendored')" in body["detail"]
+ assert body["request_id"] == response.headers[REQUEST_ID_HEADER]
+ log_spy.warning.assert_called_once()
+ log_spy.error.assert_not_called()
+
def test_pipeline_run_id_conflict_logs_at_warning_post_override_status(self, mocker: MockerFixture):
# A duplicate pipeline_run_id is a client-visible 409 conflict, not a
# server fault: disposition is keyed off the final HTTP status, so it
diff --git a/docs/api-server/error-responses.md b/docs/api-server/error-responses.md
index c80909d7a..f376724d3 100644
--- a/docs/api-server/error-responses.md
+++ b/docs/api-server/error-responses.md
@@ -163,7 +163,7 @@ A few specific statuses bypass the domain mapping:
- **429** — an upstream inference provider rate-limited the run. `Retry-After` is set when the originating error carries `provider_metadata.retry_after_seconds`. Only `POST /v1/execute` runs inference, so only `/execute` can produce it.
- **501** — a request shape the published contract accepts but this server cannot serve. `error_type = "AsyncExecutionNotEnabledError"`: this deployment does not provide async pipeline execution (`POST /v1/start`). `error_type = "MethodRefNotSupported"`: the request selected its closure by a **registry-form** `method_ref` — not a `github.com/...` address — and no server-side method registry resolves those yet. Address-form references are fetched and resolved server-side (see [Pipe Run](pipe-run.md#running-a-method-by-address-method_ref)); use one of those, or submit inline `files[]`. Both 501s are permanent under the current deployment — do not retry.
-The `method_ref` resolution errors are also mapped explicitly rather than through the domain table: `MethodRefParseError`, `MethodFetchError`, `MethodPackageAmbiguityError` and `MethodPackageTooLargeError` are **422** (the caller can fix the reference, pin a tag, or shrink the package), `MethodPackageNotFoundError` is the **404** above, and `MethodStructuresRefusedError` is a **403**, whether the method was fetched by `method_ref` or sent as a bundle. These pipelex `MethodRefError` subclasses do not classify an `error_domain`, so without the explicit mapping they would fall through to the 500 default — which would misreport caller-fixable failures as server faults.
+The `method_ref` resolution errors are also mapped explicitly rather than through the domain table: `MethodRefParseError`, `MethodFetchError`, `MethodPackageAmbiguityError`, `MethodPackageTooLargeError` and `MethodPackageSymlinkError` are **422** (the caller can fix the reference, pin a tag, shrink the package, or remove the symlink it carries), `MethodPackageNotFoundError` is the **404** above, and `MethodStructuresRefusedError` is a **403**, whether the method was fetched by `method_ref` or sent as a bundle. These pipelex `MethodRefError` subclasses do not classify an `error_domain`, so without the explicit mapping they would fall through to the 500 default — which would misreport caller-fixable failures as server faults.
Every route that takes a JSON body refuses one whose arrays and objects nest more than 128 levels deep, the body's own envelope included, with a **422** `InvalidJSON` whose `detail` says the body is nested too deeply. The depth is checked before the body is parsed, so the answer does not depend on the Python version or the stack size the server runs with. The bound is fixed rather than configurable, and real inputs stay far below it.
diff --git a/docs/api-server/pipe-run.md b/docs/api-server/pipe-run.md
index 5503e74ce..c9c9b15c6 100644
--- a/docs/api-server/pipe-run.md
+++ b/docs/api-server/pipe-run.md
@@ -270,6 +270,7 @@ Both `/execute` and `/start` accept **`method_ref`** — a globally resolvable a
| No package matches the address (message lists what the repo contains) | 404 | `MethodPackageNotFoundError` |
| More than one package matches | 422 | `MethodPackageAmbiguityError` |
| Package exceeds the fetched-package ceilings | 422 | `MethodPackageTooLargeError` |
+| Package contains a symlink (file or directory) | 422 | `MethodPackageSymlinkError` |
| Package declares Python structure classes | 403 | `MethodStructuresRefusedError` |
| Package ships `.py` on a non-sandbox deployment | 403 | `CustomCodeRequiresSandbox` |
diff --git a/docs/tools/cli/run-by-address.md b/docs/tools/cli/run-by-address.md
index b4151ae4e..45e8ab44b 100644
--- a/docs/tools/cli/run-by-address.md
+++ b/docs/tools/cli/run-by-address.md
@@ -60,7 +60,7 @@ What decides whether Python in a method is acceptable is **where it would execut
## Bounds
-Fetched packages are bounded: the clone has a fixed timeout, and the selected package is capped in file count and total bytes (tunable via the `PIPELEX_MAX_FETCHED_PACKAGE_FILES` and `PIPELEX_MAX_FETCHED_PACKAGE_TOTAL_KIB` environment variables). The manifest scan that locates the package is bounded too: at most `PIPELEX_MAX_SCANNED_MANIFESTS` manifests are considered per repository, and a `METHODS.toml` larger than `PIPELEX_MAX_MANIFEST_FILE_KIB` is skipped and reported rather than read. Content exceeding the caps is rejected with a clear error. Symlinks are refused outright: a fetched package containing one (file or directory) is rejected, because a link's target would bypass the content scans.
+Fetched packages are bounded: the clone has a fixed timeout, and the selected package is capped in file count and total bytes (tunable via the `PIPELEX_MAX_FETCHED_PACKAGE_FILES` and `PIPELEX_MAX_FETCHED_PACKAGE_TOTAL_KIB` environment variables). The manifest scan that locates the package is bounded too: at most `PIPELEX_MAX_SCANNED_MANIFESTS` manifests are considered per repository, and each `METHODS.toml` is read only if it is a regular file. A `METHODS.toml` that is a symlink, or is not a regular file, is skipped and reported without ever being opened, so a repository cannot make the scan read a file outside the clone. The read itself stops at `PIPELEX_MAX_MANIFEST_FILE_KIB`, whatever size the file reports, and a manifest over that ceiling, or not valid UTF-8, is skipped and reported too. Content exceeding the caps is rejected with a clear error. Symlinks are refused outright: a fetched package containing one (file or directory) is rejected, because a link's target would bypass the content scans.
## Referencing a Method by Address from Your Own Method
diff --git a/pipelex/methods/package_locator.py b/pipelex/methods/package_locator.py
index 328dbbb70..7ec24060b 100644
--- a/pipelex/methods/package_locator.py
+++ b/pipelex/methods/package_locator.py
@@ -10,6 +10,8 @@ Address comparison is case-insensitive: GitHub owner and repository names are
case-insensitive, and manifests in the wild mix their casing.
"""
+import os
+import stat
from pathlib import Path
from mthds.package.discovery import MANIFEST_FILENAME
@@ -47,46 +49,104 @@ class PackageScan(BaseModel):
model_config = ConfigDict(frozen=True)
candidates: list[PackageCandidate] = Field(default_factory=empty_list_factory_of(PackageCandidate))
- invalid_manifests: list[str] = Field(default_factory=list)
+ skipped_manifests: list[str] = Field(default_factory=list)
+
+
+class _ManifestRead(BaseModel):
+ """What reading one manifest yielded: its text, or the reason it was skipped."""
+
+ model_config = ConfigDict(frozen=True)
+
+ text: str | None = None
+ skip_reason: str | None = None
+
+
+def _read_manifest_text(*, manifest_path: Path) -> _ManifestRead:
+ """Read one fetched manifest, accepting only a regular file within the size ceiling.
+
+ Nothing about a fetched manifest is trusted. `lstat` establishes its type without following
+ a link, so a symlink, which could point anywhere on the fetching machine, and any other
+ file that is not regular are skipped without ever being opened. The read is bounded by
+ itself rather than by a size reported beforehand, which a link to a device such as
+ `/dev/zero` reports as 0. A skip reason never names a link's target or an absolute path,
+ both of which belong to the fetching machine.
+ """
+ try:
+ mode = manifest_path.lstat().st_mode
+ except OSError:
+ return _ManifestRead(skip_reason="could not be inspected, skipped")
+ if stat.S_ISLNK(mode):
+ return _ManifestRead(skip_reason="is a symlink, skipped (fetched manifests must be regular files)")
+ if not stat.S_ISREG(mode):
+ return _ManifestRead(skip_reason="is not a regular file, skipped")
+ try:
+ with manifest_path.open("rb") as handle:
+ raw = handle.read(MAX_MANIFEST_FILE_BYTES + 1)
+ except OSError:
+ return _ManifestRead(skip_reason="could not be read, skipped")
+ if len(raw) > MAX_MANIFEST_FILE_BYTES:
+ return _ManifestRead(skip_reason=f"exceeds the manifest size ceiling of {MAX_MANIFEST_FILE_BYTES} bytes, skipped")
+ try:
+ return _ManifestRead(text=raw.decode("utf-8"))
+ except UnicodeDecodeError:
+ return _ManifestRead(skip_reason="is not valid UTF-8, skipped")
+
+
+def _manifest_paths(*, clone_root: Path) -> list[Path]:
+ """Every entry named `METHODS.toml` in the clone, whatever its type, sorted.
+
+ The walk lists entries by name without inspecting them, so a dangling symlink and a
+ directory named like a manifest are found too, on every Python version (`Path.rglob`
+ drops a dangling link on 3.11), and reach the reading rule to be skipped and reported.
+ It never descends into a symlinked directory, and it prunes `.git`.
+ """
+ manifest_paths: list[Path] = []
+ for dir_path, dir_names, file_names in os.walk(clone_root, followlinks=False):
+ dir_names[:] = [dir_name for dir_name in dir_names if dir_name not in _SKIPPED_DIR_NAMES]
+ manifest_paths.extend(Path(dir_path) / entry_name for entry_name in (*dir_names, *file_names) if entry_name == MANIFEST_FILENAME)
+ return sorted(manifest_paths)
def scan_packages_in_clone(*, clone_root: Path) -> PackageScan:
- """Scan a clone for packages, tolerating unparseable manifests.
+ """Scan a clone for packages, skipping and reporting every manifest it cannot use.
- The scan is bounded — the repository is fetched content: at most
- ``MAX_SCANNED_MANIFESTS`` manifests are considered, and a manifest larger than
- ``MAX_MANIFEST_FILE_BYTES`` is skipped (and reported) rather than read.
+ The scan is bounded, since the repository is fetched content: at most
+ ``MAX_SCANNED_MANIFESTS`` manifests are considered, and each is read only if it is a
+ regular file. A manifest that is a symlink or not a regular file is skipped without being
+ opened, so the scan never reads outside the clone; one that holds more than
+ ``MAX_MANIFEST_FILE_BYTES`` is skipped after a read that stops at the ceiling; one that is
+ not valid UTF-8 or fails to parse is skipped too. Each skip is noted with the manifest's
+ path relative to the clone.
Args:
clone_root: The root directory of the fetched clone.
Returns:
- The scan result: valid candidates and a note for each manifest that failed to parse.
+ The scan result: valid candidates and a note for each skipped manifest.
Raises:
MethodPackageTooLargeError: If the repository contains more manifests than the scan ceiling.
"""
candidates: list[PackageCandidate] = []
- invalid_manifests: list[str] = []
+ skipped_manifests: list[str] = []
manifest_count = 0
- for manifest_path in sorted(clone_root.rglob(MANIFEST_FILENAME)):
- relative_parts = manifest_path.relative_to(clone_root).parts
- if any(part in _SKIPPED_DIR_NAMES for part in relative_parts):
- continue
+ for manifest_path in _manifest_paths(clone_root=clone_root):
manifest_count += 1
if manifest_count > MAX_SCANNED_MANIFESTS:
msg = f"The fetched repository contains more than {MAX_SCANNED_MANIFESTS} {MANIFEST_FILENAME} manifests; refusing to scan further."
raise MethodPackageTooLargeError(msg)
- if manifest_path.stat().st_size > MAX_MANIFEST_FILE_BYTES:
- invalid_manifests.append(f"{'/'.join(relative_parts)}: exceeds the manifest size ceiling of {MAX_MANIFEST_FILE_BYTES} bytes, skipped")
+ relative_path = manifest_path.relative_to(clone_root).as_posix()
+ manifest_read = _read_manifest_text(manifest_path=manifest_path)
+ if manifest_read.text is None:
+ skipped_manifests.append(f"{relative_path}: {manifest_read.skip_reason}")
continue
try:
- manifest = parse_methods_toml(manifest_path.read_text(encoding="utf-8"))
+ manifest = parse_methods_toml(manifest_read.text)
except ManifestError as exc:
- invalid_manifests.append(f"{'/'.join(relative_parts)}: {exc.message}")
+ skipped_manifests.append(f"{relative_path}: {exc.message}")
continue
candidates.append(PackageCandidate(package_dir=manifest_path.parent, manifest=manifest))
- return PackageScan(candidates=candidates, invalid_manifests=invalid_manifests)
+ return PackageScan(candidates=candidates, skipped_manifests=skipped_manifests)
def _matches(*, candidate: PackageCandidate, requested: str, clone_root: Path) -> bool:
@@ -111,7 +171,8 @@ def locate_package_in_clone(*, clone_root: Path, requested_address: str) -> Pack
Raises:
MethodPackageNotFoundError: If no package matches; the message lists the packages
- the clone does contain (and any manifests that failed to parse).
+ the clone does contain, and every manifest the scan skipped (a symlink, a file that
+ is not regular, one over the size ceiling, not UTF-8, or failing to parse) with why.
MethodPackageAmbiguityError: If more than one package matches; the message lists them.
"""
scan = scan_packages_in_clone(clone_root=clone_root)
@@ -126,9 +187,9 @@ def locate_package_in_clone(*, clone_root: Path, requested_address: str) -> Pack
msg = f"No package at address '{requested_address}' in the fetched repository. Packages it contains: {available}."
else:
msg = f"No package (no {MANIFEST_FILENAME}) found in the repository fetched for '{requested_address}'."
- if scan.invalid_manifests:
- details = "; ".join(scan.invalid_manifests)
- msg = f"{msg} Manifests that failed to parse: {details}"
+ if scan.skipped_manifests:
+ details = "; ".join(scan.skipped_manifests)
+ msg = f"{msg} Manifests skipped: {details}"
raise MethodPackageNotFoundError(msg)
matched = ", ".join(sorted(f"{candidate.full_address} ({candidate.package_dir.name}/)" for candidate in matches))
diff --git a/tests/unit/pipelex/methods/test_package_locator.py b/tests/unit/pipelex/methods/test_package_locator.py
index b3b17a727..85631a55c 100644
--- a/tests/unit/pipelex/methods/test_package_locator.py
+++ b/tests/unit/pipelex/methods/test_package_locator.py
@@ -3,7 +3,8 @@
from __future__ import annotations
import re
-from typing import TYPE_CHECKING
+from pathlib import Path
+from typing import TYPE_CHECKING, Self
import pytest
@@ -11,8 +12,6 @@ from pipelex.methods.exceptions import MethodPackageAmbiguityError, MethodPackag
from pipelex.methods.package_locator import locate_package_in_clone, scan_packages_in_clone
if TYPE_CHECKING:
- from pathlib import Path
-
from pytest_mock import MockerFixture
@@ -28,7 +27,7 @@ def _write_manifest(package_dir: Path, *, address: str, name: str | None = None,
class TestPackageLocator:
- """Tests for locating a package by manifest identity (repo-root and library-repo layouts)."""
+ """Tests for locating a package by manifest identity (repo-root and library-repo layouts), and for how the scan reads each manifest."""
def test_repo_root_package_matches_by_address(self, tmp_path: Path) -> None:
"""A repo-root package whose manifest address equals the requested address is located."""
@@ -109,7 +108,7 @@ class TestPackageLocator:
locate_package_in_clone(clone_root=tmp_path, requested_address="github.com/Pipelex/methods")
def test_oversized_manifest_is_skipped_and_reported(self, mocker: MockerFixture, tmp_path: Path) -> None:
- """A manifest larger than the size ceiling is never read; the miss names it."""
+ """A manifest larger than the size ceiling is never parsed; the miss names it."""
big_dir = tmp_path / "big"
big_dir.mkdir()
(big_dir / "METHODS.toml").write_text("# " + "x" * 2048, encoding="utf-8")
@@ -147,3 +146,126 @@ class TestPackageLocator:
scan = scan_packages_in_clone(clone_root=tmp_path)
assert [candidate.full_address for candidate in scan.candidates] == ["github.com/acme/real/real"]
+
+ # How the scan reads one manifest: a fetched repository can commit a `METHODS.toml` that is a
+ # symlink, a directory or arbitrary bytes, and none of them may make the scan read outside the
+ # clone, read without end, or crash. Only a regular file within the size ceiling is read, as UTF-8.
+
+ def test_symlinked_manifest_is_skipped_unread(self, tmp_path: Path) -> None:
+ """A symlinked manifest pointing outside the clone is never read: its target's values stay out of the miss.
+
+ A valid sibling package in the same clone is still located, so the scan goes on past the skip.
+ """
+ clone_root = tmp_path / "clone"
+ _write_manifest(clone_root / "real", address="github.com/acme/tools", name="real")
+ outside_file = tmp_path / "host-settings.toml"
+ outside_file.write_text('secret_token = "sentinel-value-1234"\n', encoding="utf-8")
+ linked_dir = clone_root / "linked"
+ linked_dir.mkdir()
+ (linked_dir / "METHODS.toml").symlink_to(outside_file)
+
+ scan = scan_packages_in_clone(clone_root=clone_root)
+
+ assert [candidate.full_address for candidate in scan.candidates] == ["github.com/acme/tools/real"]
+ assert scan.skipped_manifests == ["linked/METHODS.toml: is a symlink, skipped (fetched manifests must be regular files)"]
+
+ located = locate_package_in_clone(clone_root=clone_root, requested_address="github.com/acme/tools/real")
+ assert located.package_dir == clone_root / "real"
+
+ with pytest.raises(MethodPackageNotFoundError) as exc_info:
+ locate_package_in_clone(clone_root=clone_root, requested_address="github.com/acme/tools/missing")
+ message = str(exc_info.value)
+ assert "Manifests skipped: linked/METHODS.toml: is a symlink" in message
+ assert "sentinel-value-1234" not in message
+ assert "secret_token" not in message
+ assert str(tmp_path) not in message
+
+ @pytest.mark.timeout(10)
+ @pytest.mark.skipif(not Path("/dev/zero").exists(), reason="needs a /dev/zero device")
+ def test_symlink_to_an_endless_device_is_skipped_unread(self, tmp_path: Path) -> None:
+ """A manifest linked to /dev/zero reports a size of 0 but would read forever: the scan never opens it."""
+ (tmp_path / "METHODS.toml").symlink_to(Path("/dev/zero"))
+
+ scan = scan_packages_in_clone(clone_root=tmp_path)
+
+ assert scan.candidates == []
+ assert scan.skipped_manifests == ["METHODS.toml: is a symlink, skipped (fetched manifests must be regular files)"]
+
+ def test_dangling_symlinked_manifest_is_skipped(self, tmp_path: Path) -> None:
+ """A dangling symlinked manifest is reported as a symlink, rather than escaping as a FileNotFoundError."""
+ (tmp_path / "METHODS.toml").symlink_to(tmp_path / "nowhere.toml")
+
+ with pytest.raises(MethodPackageNotFoundError) as exc_info:
+ locate_package_in_clone(clone_root=tmp_path, requested_address="github.com/acme/dangling")
+
+ message = str(exc_info.value)
+ assert "METHODS.toml: is a symlink" in message
+ assert "nowhere.toml" not in message
+ assert str(tmp_path) not in message
+
+ def test_directory_named_like_a_manifest_is_skipped(self, tmp_path: Path) -> None:
+ """A directory named METHODS.toml is reported as not a regular file, rather than escaping as an IsADirectoryError."""
+ (tmp_path / "pkg" / "METHODS.toml").mkdir(parents=True)
+
+ scan = scan_packages_in_clone(clone_root=tmp_path)
+
+ assert scan.candidates == []
+ assert scan.skipped_manifests == ["pkg/METHODS.toml: is not a regular file, skipped"]
+
+ def test_manifest_that_is_not_utf8_is_skipped(self, tmp_path: Path) -> None:
+ """A manifest of invalid UTF-8 bytes is reported, rather than escaping as a UnicodeDecodeError."""
+ package_dir = tmp_path / "pkg"
+ package_dir.mkdir()
+ (package_dir / "METHODS.toml").write_bytes(b'[package]\naddress = "\xff\xfe"\n')
+
+ scan = scan_packages_in_clone(clone_root=tmp_path)
+
+ assert scan.candidates == []
+ assert scan.skipped_manifests == ["pkg/METHODS.toml: is not valid UTF-8, skipped"]
+
+ def test_the_read_stops_at_the_size_ceiling(self, mocker: MockerFixture, tmp_path: Path) -> None:
+ """The read itself is bounded: a regular file whose content outruns any size reported for it is cut at the ceiling.
+
+ The stream stands in for such a file and fails the test on a read without a bound.
+ """
+ (tmp_path / "METHODS.toml").write_text("# placeholder", encoding="utf-8")
+ mocker.patch("pipelex.methods.package_locator.MAX_MANIFEST_FILE_BYTES", 1024)
+ read_sizes: list[int] = []
+
+ class _EndlessStream:
+ def __enter__(self) -> Self:
+ return self
+
+ def __exit__(self, *exc_info: object) -> None:
+ return None
+
+ def read(self, size: int = -1) -> bytes:
+ if size < 0:
+ msg = "the manifest was read without a bound"
+ raise AssertionError(msg)
+ read_sizes.append(size)
+ return b"#" * size
+
+ mocker.patch.object(Path, "open", return_value=_EndlessStream())
+
+ scan = scan_packages_in_clone(clone_root=tmp_path)
+
+ assert read_sizes == [1025]
+ assert scan.skipped_manifests == ["METHODS.toml: exceeds the manifest size ceiling of 1024 bytes, skipped"]
+
+ def test_symlinked_directory_is_not_descended(self, tmp_path: Path) -> None:
+ """A symlinked directory pointing outside the clone is not walked, so a manifest behind it is no candidate.
+
+ The scan only ever meets links named METHODS.toml themselves because the walk does not follow
+ directory links; this pins that against a future Python or a walker that would.
+ """
+ clone_root = tmp_path / "clone"
+ clone_root.mkdir()
+ outside_dir = tmp_path / "outside"
+ _write_manifest(outside_dir, address="github.com/acme/outside", name="outside")
+ (clone_root / "vendored").symlink_to(outside_dir, target_is_directory=True)
+
+ scan = scan_packages_in_clone(clone_root=clone_root)
+
+ assert scan.candidates == []
+ assert scan.skipped_manifests == []