portolan-python 0.1.3__tar.gz → 0.1.5__tar.gz

{portolan_python-0.1.3 → portolan_python-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: portolan-python
-Version: 0.1.3
+Version: 0.1.5
 Summary: A lightweight Python implementation of the Portolan specification.
 Author: Portolan contributors
 License: Apache-2.0

{portolan_python-0.1.3 → portolan_python-0.1.5}/docs/distribution.md

@@ -8,8 +8,8 @@ preferred package index for published versions.
 Push a tag that matches the version in `pyproject.toml`:
 
 ```bash
-git tag v0.1.0
-git push origin v0.1.0
+git tag v0.1.5
+git push origin v0.1.5
 ```
 
 The release workflow runs the tests, builds both distributions, checks their
@@ -25,7 +25,7 @@ Install the wheel attached to a release:
 
 ```bash
 python -m pip install \
-  https://github.com/jemacchi/portolan-python/releases/download/v0.1.0/portolan_python-0.1.0-py3-none-any.whl
+  https://github.com/jemacchi/portolan-python/releases/download/v0.1.5/portolan_python-0.1.5-py3-none-any.whl
 ```
 
 This path needs no package index account.
@@ -35,7 +35,7 @@ This path needs no package index account.
 Install a published version from PyPI with:
 
 ```bash
-python -m pip install portolan-python==0.1.0
+python -m pip install portolan-python==0.1.5
 ```
 
 Omit the version constraint to install the latest published version.

{portolan_python-0.1.3 → portolan_python-0.1.5}/docs/examples.md

@@ -10,14 +10,14 @@ GitHub:
 
 ```bash
 python -m pip install \
-  https://github.com/jemacchi/portolan-python/releases/download/v0.1.0/portolan_python-0.1.0-py3-none-any.whl
+  https://github.com/jemacchi/portolan-python/releases/download/v0.1.5/portolan_python-0.1.5-py3-none-any.whl
 ```
 
 You can also install the source at a specific tag:
 
 ```bash
 python -m pip install \
-  "portolan-python @ git+https://github.com/jemacchi/portolan-python.git@v0.1.0"
+  "portolan-python @ git+https://github.com/jemacchi/portolan-python.git@v0.1.5"
 ```
 
 ## List collections and assets

{portolan_python-0.1.3 → portolan_python-0.1.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "portolan-python"
-version = "0.1.3"
+version = "0.1.5"
 description = "A lightweight Python implementation of the Portolan specification."
 readme = "README.md"
 requires-python = ">=3.10"

{portolan_python-0.1.3 → portolan_python-0.1.5}/src/portolan/registry.py

@@ -3,12 +3,17 @@
 from __future__ import annotations
 
 import json
+import os
+import shutil
+import tempfile
 from collections.abc import Callable
+from contextlib import contextmanager
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
+from urllib.error import HTTPError
 from urllib.parse import urljoin, urlparse
-from urllib.request import Request, urlopen
+from urllib.request import HTTPRedirectHandler, Request, build_opener
 
 JsonObject = dict[str, Any]
 
@@ -70,6 +75,7 @@ def download_registry_catalog(
     catalog_url: str,
     output_dir: Path,
     *,
+    expected_catalog_id: str | None = None,
     fetch_json: Callable[[str], JsonObject] | None = None,
 ) -> Path:
     """Download a published catalog snapshot for local workflows."""
@@ -77,17 +83,34 @@ def download_registry_catalog(
     fetch = fetch_json or _fetch_json
     catalog = fetch(catalog_url)
     catalog_id = str(catalog.get("id") or _fallback_catalog_id(catalog_url))
-    if catalog_id in {"", ".", ".."} or Path(catalog_id).name != catalog_id or "\\" in catalog_id:
-        raise ValueError(f"Catalog id must be a safe directory name: {catalog_id}")
+    _validate_catalog_id(catalog_id)
+    if expected_catalog_id is not None:
+        _validate_catalog_id(expected_catalog_id)
+        if catalog_id != expected_catalog_id:
+            raise ValueError(
+                f"Catalog id '{catalog_id}' does not match registry id '{expected_catalog_id}'"
+            )
     catalog_root = output_dir / catalog_id
-    _write_catalog_tree(catalog_url, catalog, catalog_url, catalog_root, fetch)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    with _catalog_lock(output_dir, catalog_id):
+        _validate_catalog_root(output_dir, catalog_root)
+        staging_root = Path(
+            tempfile.mkdtemp(prefix=f".{catalog_id}.staging-", dir=output_dir.resolve())
+        )
+        try:
+            _write_catalog_tree(catalog_url, catalog, catalog_url, staging_root, fetch)
+            _publish_snapshot(staging_root, catalog_root, output_dir)
+        except BaseException:
+            shutil.rmtree(staging_root, ignore_errors=True)
+            raise
     return catalog_root
 
 
 def _fetch_json(url: str) -> JsonObject:
     _validate_remote_url(url)
     request = Request(url, headers={"User-Agent": "portolan-python"})
-    with urlopen(request, timeout=30) as response:
+    opener = build_opener(_SameOriginRedirectHandler(url))
+    with opener.open(request, timeout=30) as response:
         data = json.loads(response.read().decode("utf-8"))
     if not isinstance(data, dict):
         raise TypeError(f"Expected JSON object from {url}")
@@ -100,6 +123,75 @@ def _validate_remote_url(url: str) -> None:
         raise ValueError(f"Registry URL must use HTTP or HTTPS: {url}")
 
 
+class _SameOriginRedirectHandler(HTTPRedirectHandler):
+    def __init__(self, original_url: str) -> None:
+        self._origin = _url_origin(original_url)
+        super().__init__()
+
+    def redirect_request(
+        self,
+        req: Request,
+        fp: Any,
+        code: int,
+        msg: str,
+        headers: Any,
+        newurl: str,
+    ) -> Request | None:
+        if _url_origin(newurl) != self._origin:
+            raise HTTPError(newurl, code, f"Redirect changed origin: {newurl}", headers, fp)
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+
+def _url_origin(url: str) -> tuple[str, str]:
+    parsed = urlparse(url)
+    return parsed.scheme.lower(), parsed.netloc.lower()
+
+
+def _validate_catalog_id(catalog_id: str) -> None:
+    if catalog_id in {"", ".", ".."} or Path(catalog_id).name != catalog_id or "\\" in catalog_id:
+        raise ValueError(f"Catalog id must be a safe directory name: {catalog_id}")
+
+
+@contextmanager
+def _catalog_lock(output_dir: Path, catalog_id: str) -> Any:
+    lock_path = output_dir.resolve() / f".{catalog_id}.lock"
+    try:
+        descriptor = os.open(lock_path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+    except FileExistsError as err:
+        raise RuntimeError(f"Catalog download is already in progress: {catalog_id}") from err
+    os.close(descriptor)
+    try:
+        yield
+    finally:
+        lock_path.unlink(missing_ok=True)
+
+
+def _validate_catalog_root(output_dir: Path, catalog_root: Path) -> None:
+    if catalog_root.is_symlink():
+        raise ValueError(f"Catalog directory must not be a symlink: {catalog_root}")
+    if not catalog_root.resolve().is_relative_to(output_dir.resolve()):
+        raise ValueError(f"Catalog directory escapes output directory: {catalog_root}")
+
+
+def _publish_snapshot(staging_root: Path, catalog_root: Path, output_dir: Path) -> None:
+    _validate_catalog_root(output_dir, catalog_root)
+    backup_root = Path(
+        tempfile.mkdtemp(prefix=f".{catalog_root.name}.backup-", dir=output_dir.resolve())
+    )
+    backup_root.rmdir()
+    had_previous = catalog_root.exists()
+    if had_previous:
+        catalog_root.rename(backup_root)
+    try:
+        staging_root.rename(catalog_root)
+    except BaseException:
+        if had_previous:
+            backup_root.rename(catalog_root)
+        raise
+    if had_previous:
+        shutil.rmtree(backup_root)
+
+
 def _write_catalog_tree(
     document_url: str,
     document: JsonObject,
@@ -123,34 +215,54 @@ def _write_catalog_tree(
     target.parent.mkdir(parents=True, exist_ok=True)
     if document.get("type") == "Collection":
         document = _with_absolute_asset_hrefs(document_url, document)
+
+    links = document.get("links")
+    if isinstance(links, list):
+        rewritten_links: list[Any] = []
+        for link in links:
+            rewritten_link = link
+            if isinstance(link, dict) and link.get("rel") == "child":
+                href = link.get("href")
+                if isinstance(href, str):
+                    child_url = urljoin(document_url, href)
+                    child_target = _target_document_path(root_url, child_url, output_root)
+                    owner = targets.get(child_target)
+                    if owner is not None and owner != child_url:
+                        raise ValueError(
+                            "Registry documents map to the same local path: "
+                            f"{owner}, {child_url}"
+                        )
+                    if child_url in visited:
+                        if owner == child_url:
+                            rewritten_link = {
+                                **link,
+                                "href": _relative_local_href(target, child_target),
+                            }
+                    else:
+                        child = fetch_json(child_url)
+                        if child.get("type") in {"Catalog", "Collection"}:
+                            _write_catalog_tree(
+                                child_url,
+                                child,
+                                root_url,
+                                output_root,
+                                fetch_json,
+                                visited,
+                                targets,
+                            )
+                            rewritten_link = {
+                                **link,
+                                "href": _relative_local_href(target, child_target),
+                            }
+            rewritten_links.append(rewritten_link)
+        document = {**document, "links": rewritten_links}
+
     target.write_text(json.dumps(document, indent=2) + "\n", encoding="utf-8")
 
-    for link in document.get("links", []):
-        if not isinstance(link, dict) or link.get("rel") != "child":
-            continue
-        href = link.get("href")
-        if not isinstance(href, str):
-            continue
-        child_url = urljoin(document_url, href)
-        if child_url in visited:
-            continue
-        child_target = _target_document_path(root_url, child_url, output_root)
-        owner = targets.get(child_target)
-        if owner is not None and owner != child_url:
-            raise ValueError(
-                f"Registry documents map to the same local path: {owner}, {child_url}"
-            )
-        child = fetch_json(child_url)
-        if child.get("type") in {"Catalog", "Collection"}:
-            _write_catalog_tree(
-                child_url,
-                child,
-                root_url,
-                output_root,
-                fetch_json,
-                visited,
-                targets,
-            )
+
+def _relative_local_href(parent_target: Path, child_target: Path) -> str:
+    relative_path = os.path.relpath(child_target, start=parent_target.parent)
+    return Path(relative_path).as_posix()
 
 
 def _with_absolute_asset_hrefs(document_url: str, collection: JsonObject) -> JsonObject:

{portolan_python-0.1.3 → portolan_python-0.1.5}/tests/test_registry_api.py

@@ -3,12 +3,16 @@
 from __future__ import annotations
 
 import json
+from email.message import Message
 from pathlib import Path
 from typing import Any
+from urllib.error import HTTPError
+from urllib.request import Request
 
 import pytest
 
 from portolan import download_registry_catalog, load_registry_entries
+from portolan.registry import _SameOriginRedirectHandler
 
 pytestmark = pytest.mark.unit
 
@@ -185,10 +189,51 @@ def test_download_registry_catalog_writes_snapshot_with_absolute_asset_hrefs(
     collection = json.loads(
         (catalog_root / "roads" / "collection.json").read_text(encoding="utf-8")
     )
-    assert catalog["links"][0]["href"] == "./roads/collection.json"
+    assert catalog["links"][0]["href"] == "roads/collection.json"
     assert collection["assets"]["data"]["href"] == "https://example.test/demo/roads/roads.parquet"
 
 
+def test_download_registry_catalog_rewrites_downloaded_children_to_local_hrefs(
+    tmp_path: Path,
+) -> None:
+    root_url = "https://example.test/demo/catalog.json"
+    child_url = "https://example.test/demo/roads/collection.json"
+    item_url = "https://example.test/demo/roads/item.json"
+    responses = {
+        root_url: {
+            "type": "Catalog",
+            "id": "demo",
+            "links": [
+                {"rel": "self", "href": root_url},
+                {"rel": "child", "href": child_url},
+                {"rel": "child", "href": item_url},
+            ],
+        },
+        child_url: {
+            **_collection("roads", {}),
+            "links": [{"rel": "child", "href": root_url}],
+        },
+        item_url: {"type": "Feature", "id": "road-1"},
+    }
+
+    catalog_root = download_registry_catalog(
+        root_url,
+        tmp_path,
+        fetch_json=lambda url: responses[url],
+    )
+
+    catalog = json.loads((catalog_root / "catalog.json").read_text(encoding="utf-8"))
+    collection = json.loads(
+        (catalog_root / "roads" / "collection.json").read_text(encoding="utf-8")
+    )
+    assert catalog["links"] == [
+        {"rel": "self", "href": root_url},
+        {"rel": "child", "href": "roads/collection.json"},
+        {"rel": "child", "href": item_url},
+    ]
+    assert collection["links"] == [{"rel": "child", "href": "../catalog.json"}]
+
+
 def test_download_registry_catalog_skips_child_cycles(tmp_path: Path) -> None:
     root_url = "https://example.test/demo/catalog.json"
     child_url = "https://example.test/demo/roads/collection.json"
@@ -266,14 +311,82 @@ def test_download_registry_catalog_rejects_symlink_escape(tmp_path: Path) -> Non
         child_url: _collection("linked", {}),
     }
 
-    with pytest.raises(ValueError, match="escapes catalog root"):
+    download_registry_catalog(
+        root_url,
+        output_dir,
+        fetch_json=lambda url: responses[url],
+    )
+
+    assert not (outside_dir / "collection.json").exists()
+    assert (catalog_root / "linked" / "collection.json").exists()
+
+
+def test_download_registry_catalog_rejects_catalog_root_symlink(tmp_path: Path) -> None:
+    output_dir = tmp_path / "output"
+    outside_dir = tmp_path / "outside"
+    output_dir.mkdir()
+    outside_dir.mkdir()
+    (output_dir / "demo").symlink_to(outside_dir, target_is_directory=True)
+
+    with pytest.raises(ValueError, match="Catalog directory must not be a symlink"):
         download_registry_catalog(
-            root_url,
+            "https://example.test/demo/catalog.json",
             output_dir,
-            fetch_json=lambda url: responses[url],
+            fetch_json=lambda url: {"type": "Catalog", "id": "demo", "links": []},
         )
 
-    assert not (outside_dir / "collection.json").exists()
+    assert list(outside_dir.iterdir()) == []
+
+
+def test_download_registry_catalog_rejects_registry_id_mismatch(tmp_path: Path) -> None:
+    with pytest.raises(ValueError, match="does not match registry id"):
+        download_registry_catalog(
+            "https://example.test/demo/catalog.json",
+            tmp_path,
+            expected_catalog_id="selected-catalog",
+            fetch_json=lambda url: {"type": "Catalog", "id": "other-catalog", "links": []},
+        )
+
+    assert not (tmp_path / "selected-catalog").exists()
+
+
+def test_download_registry_catalog_preserves_snapshot_when_child_fetch_fails(
+    tmp_path: Path,
+) -> None:
+    catalog_root = tmp_path / "demo"
+    catalog_root.mkdir()
+    previous = catalog_root / "catalog.json"
+    previous.write_text('{"id": "previous"}\n', encoding="utf-8")
+    root_url = "https://example.test/demo/catalog.json"
+
+    def fetch_json(url: str) -> dict[str, Any]:
+        if url == root_url:
+            return {
+                "type": "Catalog",
+                "id": "demo",
+                "links": [{"rel": "child", "href": "./missing.json"}],
+            }
+        raise HTTPError(url, 503, "Unavailable", hdrs=Message(), fp=None)
+
+    with pytest.raises(HTTPError):
+        download_registry_catalog(root_url, tmp_path, fetch_json=fetch_json)
+
+    assert previous.read_text(encoding="utf-8") == '{"id": "previous"}\n'
+    assert not list(tmp_path.glob(".demo.staging-*"))
+
+
+def test_same_origin_redirect_handler_rejects_cross_origin_redirect() -> None:
+    handler = _SameOriginRedirectHandler("https://example.test/demo/catalog.json")
+
+    with pytest.raises(HTTPError, match="Redirect changed origin"):
+        handler.redirect_request(
+            Request("https://example.test/demo/child.json"),
+            fp=None,
+            code=302,
+            msg="Found",
+            headers={},
+            newurl="http://127.0.0.1/private",
+        )
 
 
 def test_download_registry_catalog_rejects_local_path_collisions(tmp_path: Path) -> None:

{portolan_python-0.1.3 → portolan_python-0.1.5}/uv.lock

@@ -468,7 +468,7 @@ wheels = [
 
 [[package]]
 name = "portolan-python"
-version = "0.1.3"
+version = "0.1.5"
 source = { editable = "." }
 
 [package.optional-dependencies]