passageway-sdk 0.3.0__tar.gz

passageway_sdk-0.3.0/.gitignore

@@ -0,0 +1,11 @@
+docs/superpowers/
+.superpowers/
+.env
+.DS_Store
+.venv/
+__pycache__/
+.pytest_cache/
+.models/
+dist/
+site/
+.playwright-mcp/

passageway_sdk-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcel Bruckner
+
+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.

passageway_sdk-0.3.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.5
+Name: passageway-sdk
+Version: 0.3.0
+Summary: Write a passageway connector as three small functions: the protocol plumbing is done for you
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Provides-Extra: web
+Requires-Dist: httpx>=0.28.1; extra == 'web'
+Requires-Dist: truststore>=0.10; extra == 'web'
+Description-Content-Type: text/markdown
+
+# passageway-sdk
+
+Write a [passageway](https://passageway.marceltov.de/) connector as three small functions. No dependencies; `passageway-sdk[web]` adds a polite web client for connectors that read a website.
+
+```python
+from passageway_sdk import Connector
+
+class Notes(Connector):
+    def versions(self): ...      # {id: version} for every item
+    def fetch(self, ids): ...    # an item record per id
+
+Notes.main()
+```
+
+The SDK dispatches the mode, reads the ids, buffers the output (all or nothing), maps errors to exit codes and validates each item. Reference: https://passageway.marceltov.de/reference/sdk/ and the [guide](https://passageway.marceltov.de/guides/write-a-connector/).

passageway_sdk-0.3.0/README.md

@@ -0,0 +1,15 @@
+# passageway-sdk
+
+Write a [passageway](https://passageway.marceltov.de/) connector as three small functions. No dependencies; `passageway-sdk[web]` adds a polite web client for connectors that read a website.
+
+```python
+from passageway_sdk import Connector
+
+class Notes(Connector):
+    def versions(self): ...      # {id: version} for every item
+    def fetch(self, ids): ...    # an item record per id
+
+Notes.main()
+```
+
+The SDK dispatches the mode, reads the ids, buffers the output (all or nothing), maps errors to exit codes and validates each item. Reference: https://passageway.marceltov.de/reference/sdk/ and the [guide](https://passageway.marceltov.de/guides/write-a-connector/).

passageway_sdk-0.3.0/passageway_sdk/__init__.py

@@ -0,0 +1,191 @@
+"""Write a passageway connector as three small functions; the protocol plumbing is done here.
+
+Subclass Connector, implement versions() and fetch() (and changed() if the source can answer it cheaply), and call
+YourConnector.main(). The reference is https://passageway.marceltov.de/reference/connector-protocol/.
+"""
+
+import json
+import os
+import sys
+from collections.abc import Iterable, Mapping
+from datetime import datetime
+from typing import NoReturn, TextIO
+
+from passageway_sdk.markdown import first_h1, split_markdown, strip_code
+
+__all__ = ["Connector", "SettingsError", "SourceError", "first_h1", "split_markdown", "strip_code", "validate_item"]
+
+PROTOCOL = "1"
+MODES = "check|list|fetch|changed"
+
+
+class SettingsError(Exception):
+    """The settings are wrong. The connector exits 2 with the message on stderr and prints nothing."""
+
+
+class SourceError(Exception):
+    """The source failed (down, refused, unreadable). The connector exits 1 with the message and prints nothing."""
+
+
+def _check(ok: bool, message: str) -> None:
+    if not ok:
+        raise ValueError(message)
+
+
+def _strings(record: dict, key: str, *, non_empty: bool = False) -> None:
+    values = record.get(key, [])
+    _check(isinstance(values, list) and all(isinstance(v, str) and (v or not non_empty) for v in values),
+           f"'{key}' must be a list of {'non-empty ' if non_empty else ''}strings")
+
+
+def validate_item(record: object) -> None:
+    """Raises ValueError if the record is not a valid item (the same rules the core applies)."""
+    _check(isinstance(record, dict), "a record must be a JSON object")
+    for key in ("title", "url", "version"):
+        _check(isinstance(record.get(key), str), f"'{key}' must be a string")
+    _check(isinstance(record.get("id"), str) and record["id"], "'id' must be a non-empty string")
+    sections = record.get("sections")
+    _check(isinstance(sections, list), "'sections' must be a list")
+    for s in sections:
+        _check(isinstance(s, dict) and isinstance(s.get("text"), str), "a section needs a string 'text'")
+        _check(s.get("heading") is None or isinstance(s["heading"], str), "'heading' must be a string")
+    weight = record.get("weight", 1.0)
+    _check(isinstance(weight, (int, float)) and not isinstance(weight, bool) and 0 <= weight <= 2,
+           "'weight' must be a number from 0 to 2")
+    _strings(record, "path")
+    _strings(record, "labels")
+    _strings(record, "links", non_empty=True)
+    _check(record.get("updated") is None or isinstance(record["updated"], str), "'updated' must be a string")
+
+
+class Connector:
+    """One source. Subclass it; settings arrive in __init__ as the environment."""
+
+    name = "connector"  # prefixes the messages on stderr
+    expected_errors: tuple[type[Exception], ...] = ()  # extra exceptions that mean "the source failed" (exit 1)
+
+    def __init__(self, env: Mapping[str, str]):
+        """Read and validate the settings; raise SettingsError if they are wrong."""
+
+    def versions(self) -> dict[str, str]:
+        """Every item that exists, as id -> version. The version changes when the content changes."""
+        raise NotImplementedError
+
+    def fetch(self, ids: list[str]) -> Iterable[dict]:
+        """The item record for each requested id that still exists."""
+        raise NotImplementedError
+
+    def changed(self, since: datetime) -> Iterable[dict]:
+        """Optional: items changed since `since` (timezone-aware). Print nothing if that is not cheap."""
+        return ()
+
+    def count(self) -> int:
+        return len(self.versions())
+
+    def warn(self, message: str) -> None:
+        """Report something odd (a skipped file, say) on stderr without failing the call."""
+        self.__dict__.setdefault("_warnings", []).append(message)
+
+    # -- the plumbing ------------------------------------------------------------------------
+
+    @classmethod
+    def run(cls, argv: list[str], env: Mapping[str, str], stdin: TextIO, stdout: TextIO, stderr: TextIO,
+            **options) -> int:
+        """Run one mode and return the exit code. Output is written only if everything succeeded.
+
+        A SettingsError gives 2, a SourceError or an expected error 1. Any other exception is a bug in the connector and
+        propagates (the process then exits 1 with a traceback); nothing has been written by then either.
+        """
+        mode = argv[1] if len(argv) > 1 else ""
+        if mode not in MODES.split("|"):
+            print(f"usage: {os.path.basename(argv[0]) if argv else 'connector'} {MODES} (changed takes --since <UTC time>)",
+                  file=stderr)
+            return 2
+        since = None
+        if mode == "changed" and cls.changed is not Connector.changed:  # a connector without `changed` has no use for the time
+            try:
+                since = _since(argv)
+            except ValueError as e:
+                print(f"{cls.name}: {e}", file=stderr)
+                return 2
+        connector = None
+        try:
+            connector = cls(env, **options)
+            lines = connector._lines(mode, stdin, since)
+        except SettingsError as e:
+            _show_warnings(connector, stderr)
+            print(f"{cls.name}: {e}", file=stderr)
+            return 2
+        except (SourceError, *cls.expected_errors) as e:
+            _show_warnings(connector, stderr)
+            print(f"{cls.name}: {e}", file=stderr)
+            return 1
+        _show_warnings(connector, stderr)
+        stdout.write("".join(lines))
+        return 0
+
+    @classmethod
+    def main(cls) -> NoReturn:
+        sys.exit(cls.run(sys.argv, os.environ, sys.stdin, sys.stdout, sys.stderr))
+
+    def _lines(self, mode: str, stdin: TextIO, since: datetime | None) -> list[str]:
+        if mode == "check":
+            count = self.count()
+            if isinstance(count, bool) or not isinstance(count, int) or count < 0:
+                raise SourceError(f"count() must return a whole number from 0, got {count!r}")
+            return [_line({"ok": True, "count": count, "protocol": PROTOCOL})]
+        if mode == "list":
+            return [_line(_listed(i, v)) for i, v in self.versions().items()]
+        if mode == "changed":
+            return [_line(_valid(item)) for item in self.changed(since)]
+        ids = _ids(stdin)
+        lines = []
+        for item in self.fetch(ids):
+            if _valid(item)["id"] not in ids:
+                raise SourceError(f"fetch returned {item['id']!r}, which was not requested")
+            lines.append(_line(item))
+        return lines
+
+
+def _show_warnings(connector: "Connector | None", stderr: TextIO) -> None:
+    for message in getattr(connector, "_warnings", ()):
+        print(f"{connector.name}: warning: {message}", file=stderr)
+
+
+def _line(record: dict) -> str:
+    return json.dumps(record) + "\n"  # ASCII-safe on purpose: a locale without UTF-8 must not crash the output
+
+
+def _valid(item: object) -> dict:
+    try:
+        validate_item(item)
+    except ValueError as e:
+        label = item.get("id") if isinstance(item, dict) else None
+        raise SourceError(f"invalid item{f' {label!r}' if label else ''}: {e}") from None
+    return item
+
+
+def _listed(item_id: object, version: object) -> dict:
+    if not (isinstance(item_id, str) and item_id and isinstance(version, str)):
+        raise SourceError(f"invalid list entry {item_id!r}: an id is a non-empty string and a version a string")
+    return {"id": item_id, "version": version}
+
+
+def _ids(stdin: TextIO) -> list[str]:
+    try:
+        ids = [json.loads(line)["id"] for line in stdin if line.strip()]
+        if not all(isinstance(i, str) and i for i in ids):
+            raise ValueError
+        return ids
+    except (ValueError, KeyError, TypeError):
+        raise SourceError("fetch expects one JSON object per line on stdin, each with a non-empty string 'id'") from None
+
+
+def _since(argv: list[str]) -> datetime:
+    try:
+        value = datetime.fromisoformat(argv[argv.index("--since") + 1].replace("Z", "+00:00"))
+    except (ValueError, IndexError):
+        raise ValueError("changed needs --since <UTC time>, e.g. 2026-01-01T00:00:00Z") from None
+    if value.tzinfo is None:
+        raise ValueError("--since must carry a timezone, e.g. 2026-01-01T00:00:00Z")
+    return value

passageway_sdk-0.3.0/passageway_sdk/markdown.py

@@ -0,0 +1,78 @@
+"""Markdown helpers for connectors: cut a document into sections at its headings, and see it without code."""
+
+import re
+from collections.abc import Iterator
+
+_FENCE = re.compile(r"^ {0,3}(`{3,}|~{3,})(.*)$")
+_HEADING = re.compile(r"^ {0,3}(#{1,6})[ \t]+(.*?)(?:[ \t]+#+)?[ \t]*$")
+_INLINE_CODE = re.compile(r"(?<!`)(`+)(?!`)[^\n]+?(?<!`)\1(?!`)")  # a span closes with a run of exactly the same length
+SEPARATOR = " › "
+
+
+def _lines(text: str) -> Iterator[tuple[str, bool]]:
+    """Each line with whether it is inside a fenced code block (the fence lines themselves count as inside)."""
+    fence = ""  # the opening fence while inside a block
+    for line in text.splitlines():
+        match = _FENCE.match(line)
+        if not fence:
+            # the info string of a backtick fence cannot contain a backtick: "```a`b" is not a fence
+            opens = bool(match) and not (match.group(1)[0] == "`" and "`" in match.group(2))
+            if opens:
+                fence = match.group(1)
+            yield line, opens
+        else:
+            # a closing fence: the same character, at least as long, and nothing after it
+            if match and match.group(1)[0] == fence[0] and len(match.group(1)) >= len(fence) and not match.group(2).strip():
+                fence = ""
+            yield line, True
+
+
+def split_markdown(text: str, *, skip_first_h1: bool = False) -> list[dict]:
+    """Sections for an item: {"heading": "Setup › Linux", "text": "…"}, one per heading level (# to ######).
+
+    The heading is the trail of the parent headings. Text before the first heading has heading None. A `#` inside a fenced
+    code block is not a heading. Sections without text are dropped (their heading stays in the trail of their children).
+    With skip_first_h1 the first level-1 heading is left out of the trail, because it is the title of the item.
+    """
+    sections: list[dict] = []
+    trail: list[tuple[int, str]] = []
+    lines: list[str] = []
+    heading: str | None = None
+    seen_h1 = False
+
+    def flush() -> None:
+        body = "\n".join(lines).strip()
+        if body:
+            sections.append({"heading": heading, "text": body})
+        lines.clear()
+
+    for line, in_code in _lines(text):
+        match = None if in_code else _HEADING.match(line)
+        if not match or not match.group(2).strip():
+            lines.append(line)
+            continue
+        flush()
+        level, title = len(match.group(1)), match.group(2).strip()
+        if skip_first_h1 and level == 1 and not seen_h1:
+            seen_h1 = True
+            trail = []  # the title is above everything: what follows starts again from the top
+        else:
+            trail = [t for t in trail if t[0] < level] + [(level, title)]
+        heading = SEPARATOR.join(t[1] for t in trail) or None
+    flush()
+    return sections
+
+
+def strip_code(text: str) -> str:
+    """The text without fenced code blocks and inline code, e.g. to find the links a document really contains."""
+    outside = "\n".join(line for line, in_code in _lines(text) if not in_code)
+    return _INLINE_CODE.sub("", outside)
+
+
+def first_h1(text: str) -> str | None:
+    """The text of the first level-1 heading outside code, or None: the title of a document that has no other."""
+    for line, in_code in _lines(text):
+        match = None if in_code else _HEADING.match(line)
+        if match and len(match.group(1)) == 1 and match.group(2).strip():
+            return match.group(2).strip()
+    return None

passageway_sdk-0.3.0/passageway_sdk/settings.py

@@ -0,0 +1,44 @@
+"""Read connector settings from the environment: every value is a string, and a wrong one is a SettingsError."""
+
+from collections.abc import Mapping
+
+from passageway_sdk import SettingsError
+
+
+def names(env: Mapping[str, str], key: str) -> tuple[str, ...]:
+    """A list setting: values separated by `|`, blanks dropped; empty if the setting is missing."""
+    return tuple(p.strip() for p in env.get(key, "").split("|") if p.strip())
+
+
+def whole(env: Mapping[str, str], key: str, default: int, low: int = 1) -> int:
+    """A whole number of at least `low`."""
+    raw = env.get(key, "").strip()
+    try:
+        value = int(raw) if raw else default
+    except ValueError:
+        raise SettingsError(f"{key} must be a whole number, got {raw!r}") from None
+    if value < low:
+        raise SettingsError(f"{key} must be at least {low}, got {value}")
+    return value
+
+
+def flag(env: Mapping[str, str], key: str, default: bool) -> bool:
+    """`true` or `false`, in any case."""
+    raw = env.get(key, "").strip().lower()
+    if not raw:
+        return default
+    if raw not in ("true", "false"):
+        raise SettingsError(f"{key} must be true or false, got {raw!r}")
+    return raw == "true"
+
+
+def seconds(env: Mapping[str, str], key: str, default: float) -> float:
+    """A number of seconds that is not negative."""
+    raw = env.get(key, "").strip()
+    try:
+        value = float(raw) if raw else default
+    except ValueError:
+        raise SettingsError(f"{key} must be a number of seconds, got {raw!r}") from None
+    if value < 0:
+        raise SettingsError(f"{key} must not be negative, got {value}")
+    return value

passageway_sdk-0.3.0/passageway_sdk/web.py

@@ -0,0 +1,142 @@
+"""A read-mostly web client for connectors and embedders. Needs the extra: `pip install passageway-sdk[web]`."""
+
+import json as jsonlib
+import ssl
+import time
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Any, NamedTuple
+
+from passageway_sdk import SourceError
+
+try:
+    import httpx
+    import truststore
+except ImportError as e:  # the SDK itself has no dependencies; this module is the one that has
+    raise ImportError("passageway_sdk.web needs httpx and truststore: install passageway-sdk[web]") from e
+
+
+class Reply(NamedTuple):
+    status: int
+    text: str  # decoded as UTF-8, undecodable bytes replaced
+    content_type: str
+    headers: Mapping[str, str] = MappingProxyType({})  # names in lower case
+
+    def json(self) -> Any:
+        return jsonlib.loads(self.text)
+
+
+class TooLarge(SourceError):
+    """The reply was larger than the limit."""
+
+
+class HttpError(SourceError):
+    """The server answered with a status the call cannot go on with: a 5xx or 429 that retries did not clear, or any
+    non-200 when the call was `required`."""
+
+    def __init__(self, url: str, status: int, message: str | None = None, attempts: int = 1):
+        super().__init__(message or f"{url}: HTTP {status}")
+        self.url, self.status, self.attempts = url, status, attempts  # attempts > 1: a retry policy gave up
+
+
+class NetworkError(SourceError):
+    """The server could not be reached or went silent (a connection or timeout error)."""
+
+    def __init__(self, url: str, detail: str):
+        super().__init__(f"{url}: {detail}")
+        self.url, self.detail = url, detail
+
+
+@dataclass(frozen=True)
+class Retry:
+    """Wait and try again when the server asks to come back later (seconds)."""
+
+    statuses: tuple[int, ...] = (429, 502, 503, 504)
+    network: bool = False  # also retry when the server cannot be reached or times out
+    budget: float = 900  # the most that is waited in total for one request before giving up
+    max_backoff: float = 60  # the longest wait the client picks itself: 1, 2, 4, … up to this
+    max_after: float = 300  # the longest wait a Retry-After header may ask for
+    say_from: float = 10  # a wait this long is reported to `log`, shorter ones stay quiet
+
+
+class Web:
+    """HTTP with the operating system's trust store (never certifi's bundle), a pause between requests and a size cap.
+
+    A failure to reach the server, or a 5xx or 429 that a `retry` policy did not clear, raises SourceError (HttpError for a
+    status), so a source that is down fails the whole call and never looks empty. Any other status is returned for the
+    connector to judge; `required=True` raises on it too. Turning TLS checking off (`verify=False`) is an explicit switch.
+    """
+
+    def __init__(self, user_agent: str | None = None, *, base_url: str = "", headers: Mapping[str, str] | None = None,
+                 verify: bool = True, follow_redirects: bool = True, pause: float = 0.2, timeout: float = 30.0,
+                 max_bytes: int = 2_000_000, retry: Retry | None = None, log: Callable[[str], None] | None = None, transport: "httpx.BaseTransport | None" = None,
+                 sleep: Callable[[float], None] = time.sleep):
+        all_headers = {**({"User-Agent": user_agent} if user_agent else {}), **(headers or {})}
+        self._http = httpx.Client(base_url=base_url, headers=all_headers, timeout=timeout, follow_redirects=follow_redirects,
+                                  transport=transport, verify=truststore.SSLContext(ssl.PROTOCOL_TLS_CLIENT) if verify else False)
+        self._pause, self._max_bytes, self._retry, self._log, self._sleep, self._last = pause, max_bytes, retry, log, sleep, None
+
+    def get(self, url: str, *, params: Mapping[str, str] | None = None, required: bool = False, max_bytes: int | None = None,
+            retry_if: Callable[[Reply], str | None] | None = None) -> Reply:
+        return self.request("GET", url, params=params, required=required, max_bytes=max_bytes, retry_if=retry_if)
+
+    def request(self, method: str, url: str, *, params: Mapping[str, str] | None = None, json: Any = None, required: bool = False,
+                max_bytes: int | None = None, retry_if: Callable[[Reply], str | None] | None = None) -> Reply:
+        """`retry_if(reply)` may name a reason to try again although the status is fine (an API that answers 200 with
+        "I am lagging"); it counts against the same budget as a busy status."""
+        limit, waited, attempt = max_bytes or self._max_bytes, 0.0, 0
+        retry = self._retry
+        if retry_if and not retry:
+            raise ValueError("retry_if needs a retry policy: pass retry=Retry(...) to Web")
+        while True:
+            attempt += 1
+            retry_after = None
+            try:
+                reply, retry_after = self._once(method, url, params, json, limit)
+                reason = f"HTTP {reply.status}"
+                if again := retry_if(reply) if retry_if else None:
+                    reason = again
+                elif not (retry and reply.status in retry.statuses):
+                    if reply.status >= 500 or reply.status == 429 or (required and reply.status != 200):
+                        raise HttpError(url, reply.status)
+                    return reply
+            except NetworkError as e:
+                if not (retry and retry.network):
+                    raise
+                reply, reason = None, e.detail
+            if waited >= retry.budget:
+                message = f"{url}: giving up after {attempt} attempts and {waited:.0f} s of waiting: {reason}"
+                raise HttpError(url, reply.status, message, attempt) if reply else NetworkError(url, message.removeprefix(f"{url}: "))
+            wait = min(self._wait(attempt, retry_after), retry.budget - waited)
+            if wait >= retry.say_from and self._log:
+                self._log(f"{reason} on {method} {url}: waiting {wait:.0f} s ({waited:.0f} s of {retry.budget:.0f} s waited)")
+            self._sleep(wait)
+            waited += wait
+
+    def _wait(self, attempt: int, retry_after: str | None) -> float:
+        backoff = min(float(2 ** (attempt - 1)), self._retry.max_backoff)
+        try:
+            return max(backoff, min(float(retry_after), self._retry.max_after)) if retry_after else backoff
+        except ValueError:
+            return backoff
+
+    def _once(self, method: str, url: str, params, json, limit: int) -> tuple[Reply, str | None]:
+        if self._last is not None and (wait := self._pause - (time.monotonic() - self._last)) > 0:
+            self._sleep(wait)
+        try:
+            with self._http.stream(method, url, params=params, json=json) as response:
+                body = bytearray()
+                for chunk in response.iter_bytes():
+                    body += chunk
+                    if len(body) > limit:
+                        raise TooLarge(f"{url}: larger than {limit} bytes")
+                headers = {k.lower(): v for k, v in response.headers.items()}
+                reply = Reply(response.status_code, body.decode("utf-8", errors="replace"), headers.get("content-type", ""), headers)
+                return reply, headers.get("retry-after")
+        except httpx.TransportError as e:
+            raise NetworkError(url, f"{type(e).__name__}: {e}") from e
+        except httpx.HTTPError as e:
+            raise SourceError(f"{url}: {e}") from e
+        finally:
+            self._last = time.monotonic()

passageway_sdk-0.3.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["hatchling==1.33.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "passageway-sdk"
+version = "0.3.0"
+description = "Write a passageway connector as three small functions: the protocol plumbing is done for you"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+dependencies = []
+
+[project.optional-dependencies]
+web = ["httpx>=0.28.1", "truststore>=0.10"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["passageway_sdk"]
+
+[dependency-groups]
+dev = ["pytest>=8.3", "passageway", "httpx>=0.28.1", "truststore>=0.10"]
+
+[tool.uv.sources]
+passageway = { workspace = true }

passageway_sdk-0.3.0/tests/test_markdown.py

@@ -0,0 +1,77 @@
+from passageway_sdk import split_markdown, strip_code
+
+
+def sections(text, **kw):
+    return [(s["heading"], s["text"]) for s in split_markdown(text, **kw)]
+
+
+def test_text_before_the_first_heading_is_a_section_without_heading():
+    assert sections("Intro text.\n\n## Setup\nInstall it.") == [(None, "Intro text."), ("Setup", "Install it.")]
+
+
+def test_the_heading_is_the_trail_of_its_parents():
+    text = "# Guide\n\n## Setup\nA\n\n### Linux\nB\n\n### Mac\nC\n\n## Usage\nD"
+    assert sections(text) == [("Guide › Setup", "A"), ("Guide › Setup › Linux", "B"),
+                              ("Guide › Setup › Mac", "C"), ("Guide › Usage", "D")]
+
+
+def test_the_first_h1_can_be_left_out_because_it_is_the_title():
+    text = "# Guide\nIntro.\n\n## Setup\nA\n\n# Second\nB"
+    assert sections(text, skip_first_h1=True) == [(None, "Intro."), ("Setup", "A"), ("Second", "B")]
+
+
+def test_a_level_can_be_skipped_and_a_shallower_heading_resets_the_trail():
+    assert sections("## A\nx\n\n##### Deep\ny\n\n## B\nz") == [("A", "x"), ("A › Deep", "y"), ("B", "z")]
+
+
+def test_headings_without_text_are_dropped_but_stay_in_the_trail():
+    assert sections("## A\n### B\ntext") == [("A › B", "text")]
+
+
+def test_a_hash_inside_a_fenced_code_block_is_not_a_heading():
+    text = "## Setup\n```bash\n# install\nmake\n```\nAfter.\n\n~~~\n## also not\n~~~\n"
+    assert sections(text) == [("Setup", "```bash\n# install\nmake\n```\nAfter.\n\n~~~\n## also not\n~~~")]
+
+
+def test_a_longer_fence_is_not_closed_by_a_shorter_one():
+    text = "## A\n````\n```\n## inside\n```\n````\nend"
+    assert sections(text) == [("A", "````\n```\n## inside\n```\n````\nend")]
+
+
+def test_heading_syntax_rules():
+    assert sections("#NoSpace\ntext") == [(None, "#NoSpace\ntext")]  # needs a space
+    assert sections("####### seven\ntext") == [(None, "####### seven\ntext")]
+    assert sections("## Closed ##\ntext") == [("Closed", "text")]
+    assert sections("   ## Indented up to three\ntext") == [("Indented up to three", "text")]
+    assert sections("    ## four spaces is code\ntext") == [(None, "## four spaces is code\ntext")]  # not a heading
+
+
+def test_empty_input_has_no_sections():
+    assert split_markdown("") == [] and split_markdown("\n\n  \n") == []
+
+
+def test_strip_code_removes_fenced_blocks_and_inline_code():
+    text = "See [a](a.md).\n```\n[b](b.md)\n```\nand `[c](c.md)` but [d](d.md)."
+    out = strip_code(text)
+    assert "a.md" in out and "d.md" in out and "b.md" not in out and "c.md" not in out
+
+
+def test_first_h1_is_the_first_level_one_heading_outside_code():
+    from passageway_sdk import first_h1
+    assert first_h1("intro\n\n# Real title\n\n# Second") == "Real title"
+    assert first_h1("```\n# not a title\n```\n## Sub\n# Title `with code` ##") == "Title `with code`"
+    assert first_h1("## Only a sub heading") is None and first_h1("") is None
+
+
+def test_a_first_h1_that_comes_after_other_headings_resets_the_trail_when_skipped():
+    assert sections("## Setup\nx\n# Appendix\ny\n## A\nz", skip_first_h1=True) == [("Setup", "x"), (None, "y"), ("A", "z")]
+
+
+def test_strip_code_handles_spans_that_contain_a_backtick():
+    assert "e.md" in strip_code("x ``a`b`` [`f()`](e.md)")
+    out = strip_code("a ``x ` [c](d.md)`` b")
+    assert "d.md" not in out and out.startswith("a") and out.endswith("b")
+
+
+def test_a_backtick_fence_whose_info_string_has_a_backtick_is_not_a_fence():
+    assert sections("```foo`bar\n## B\ntext") == [(None, "```foo`bar"), ("B", "text")]

passageway_sdk-0.3.0/tests/test_sdk.py

@@ -0,0 +1,296 @@
+import io
+import json
+import subprocess
+import sys
+import textwrap
+from datetime import datetime, timezone
+
+import pytest
+
+from passageway.protocol import Connector as CoreConnector, parse_item
+from passageway.testing.contract import check_connector
+from passageway_sdk import Connector, SettingsError, SourceError
+
+ITEM = {"id": "a", "title": "Doc a", "url": "http://x/a", "version": "1", "sections": [{"heading": None, "text": "body"}]}
+
+
+class Demo(Connector):
+    name = "demo connector"
+
+    def __init__(self, env, **options):
+        self.items = {"a": ITEM, "b": {**ITEM, "id": "b", "version": "2"}}
+        if env.get("BAD"):
+            raise SettingsError("BAD must not be set")
+        self.fail = env.get("FAIL")
+        self.options = options
+
+    def versions(self):
+        if self.fail == "source":
+            raise SourceError("the source is down")
+        if self.fail == "crash":
+            raise RuntimeError("a bug")
+        return {i: r["version"] for i, r in self.items.items()}
+
+    def fetch(self, ids):
+        for i in ids:
+            if i in self.items:
+                yield self.items[i]
+            if self.fail == "late" and i == "a":
+                raise SourceError("died after the first item")
+
+
+def call(cls, mode, *, stdin="", env=None, extra=()):
+    out, err = io.StringIO(), io.StringIO()
+    code = cls.run(["prog", mode, *extra], env or {}, io.StringIO(stdin), out, err)
+    return code, [json.loads(line) for line in out.getvalue().splitlines()], err.getvalue()
+
+
+def test_check_counts_the_versions_and_names_the_protocol():
+    assert call(Demo, "check")[:2] == (0, [{"ok": True, "count": 2, "protocol": "1"}])
+
+
+def test_list_prints_id_and_version_per_item():
+    assert call(Demo, "list")[:2] == (0, [{"id": "a", "version": "1"}, {"id": "b", "version": "2"}])
+
+
+def test_fetch_reads_ids_from_stdin_and_skips_blank_lines():
+    code, records, _ = call(Demo, "fetch", stdin='{"id": "b"}\n\n{"id": "zzz"}\n')
+    assert code == 0 and [r["id"] for r in records] == ["b"]
+
+
+def test_changed_is_optional_and_prints_nothing_by_default():
+    assert call(Demo, "changed", extra=["--since", "2026-01-01T00:00:00Z"])[:2] == (0, [])
+
+
+def test_changed_receives_an_aware_datetime():
+    seen = []
+
+    class Changing(Demo):
+        def changed(self, since):
+            seen.append(since)
+            return [ITEM]
+
+    assert call(Changing, "changed", extra=["--since", "2026-01-01T00:00:00Z"])[1] == [ITEM]
+    assert seen == [datetime(2026, 1, 1, tzinfo=timezone.utc)]
+
+
+@pytest.mark.parametrize("extra", [[], ["--since"], ["--since", "yesterday"], ["--since", "2026-01-01T00:00:00"]])
+def test_a_connector_that_implements_changed_needs_a_valid_since(extra):
+    class Changing(Demo):
+        def changed(self, since):
+            return [ITEM]
+
+    code, records, err = call(Changing, "changed", extra=extra)
+    assert code == 2 and records == [] and "--since" in err
+
+
+def test_a_connector_without_changed_does_not_care_about_since():
+    assert call(Demo, "changed")[:2] == (0, [])
+
+
+def test_an_unknown_mode_is_a_usage_error():
+    code, records, err = call(Demo, "bogus")
+    assert code == 2 and records == [] and "usage" in err
+
+
+def test_bad_settings_exit_2_with_the_message_and_no_output():
+    code, records, err = call(Demo, "list", env={"BAD": "1"})
+    assert code == 2 and records == [] and err.strip() == "demo connector: BAD must not be set"
+
+
+def test_a_source_failure_exits_1_with_the_message_and_no_traceback():
+    code, records, err = call(Demo, "list", env={"FAIL": "source"})
+    assert code == 1 and records == [] and err.strip() == "demo connector: the source is down"
+
+
+def test_all_or_nothing_a_failure_after_some_items_prints_nothing():
+    code, records, _ = call(Demo, "fetch", stdin='{"id": "a"}\n{"id": "b"}\n', env={"FAIL": "late"})
+    assert code == 1 and records == []
+
+
+def test_an_unexpected_error_is_not_swallowed():
+    with pytest.raises(RuntimeError):
+        call(Demo, "list", env={"FAIL": "crash"})
+
+
+def test_expected_errors_can_be_declared_by_the_connector():
+    class Declares(Demo):
+        expected_errors = (KeyError,)
+
+        def versions(self):
+            raise KeyError("missing")
+
+    assert call(Declares, "list")[0] == 1
+
+
+def test_a_bad_stdin_line_is_a_source_error():
+    code, records, err = call(Demo, "fetch", stdin="not json\n")
+    assert code == 1 and records == [] and "fetch" in err
+
+
+def test_options_reach_the_constructor():
+    seen = {}
+
+    class Optioned(Demo):
+        def __init__(self, env, **options):
+            super().__init__(env)
+            seen.update(options)
+
+    out = io.StringIO()
+    Optioned.run(["prog", "list"], {}, io.StringIO(), out, io.StringIO(), pause=0)
+    assert seen == {"pause": 0}
+
+
+@pytest.mark.parametrize("bad", [
+    {**ITEM, "id": ""}, {**ITEM, "version": 1}, {**ITEM, "sections": "x"}, {**ITEM, "sections": [{"heading": "H"}]},
+    {**ITEM, "weight": 3}, {**ITEM, "weight": True}, {**ITEM, "path": "P"}, {**ITEM, "links": [""]},
+    {k: v for k, v in ITEM.items() if k != "url"}, [],
+])
+def test_an_invalid_item_is_a_source_error_naming_the_problem(bad):
+    class Bad(Demo):
+        def fetch(self, ids):
+            yield bad
+
+    code, records, err = call(Bad, "fetch", stdin='{"id": "a"}\n')
+    assert code == 1 and records == [] and "invalid item" in err
+
+
+@pytest.mark.parametrize("bad", [
+    {**ITEM, "id": ""}, {**ITEM, "version": 1}, {**ITEM, "weight": 3}, {**ITEM, "links": [""]},
+    {**ITEM, "sections": [{"heading": 3, "text": "x"}]}, {**ITEM, "updated": 5},
+])
+def test_the_sdk_and_the_core_validate_alike(bad):
+    class Bad(Demo):
+        def fetch(self, ids):
+            yield bad
+
+    sdk_accepts = call(Bad, "fetch", stdin='{"id": "a"}\n')[0] == 0
+    try:
+        parse_item(bad)
+        core_accepts = True
+    except ValueError:
+        core_accepts = False
+    assert sdk_accepts is core_accepts is False
+
+
+def test_output_is_ascii_safe_so_a_locale_without_utf8_cannot_crash_it():
+    class Umlaut(Demo):
+        def fetch(self, ids):
+            yield {**ITEM, "title": "Köln Süd"}
+
+    out = io.StringIO()
+    Umlaut.run(["prog", "fetch"], {}, io.StringIO('{"id": "a"}\n'), out, io.StringIO())
+    assert out.getvalue().isascii() and json.loads(out.getvalue())["title"] == "Köln Süd"
+
+
+FOLDER = '''
+import hashlib
+from pathlib import Path
+
+from passageway_sdk import Connector, SettingsError
+
+
+class Folder(Connector):
+    name = "folder connector"
+
+    def __init__(self, env):
+        self.root = Path(env.get("FOLDER", "")).resolve()
+        if not self.root.is_dir():
+            raise SettingsError(f"FOLDER must be an existing folder, got {env.get('FOLDER')!r}")
+
+    def files(self):
+        return {p.relative_to(self.root).as_posix(): p for p in sorted(self.root.rglob("*.txt"))}
+
+    def versions(self):
+        return {i: hashlib.sha256(p.read_bytes()).hexdigest()[:12] for i, p in self.files().items()}
+
+    def fetch(self, ids):
+        for i, p in self.files().items():
+            if i in ids:
+                yield {"id": i, "title": p.stem, "url": p.as_uri(), "version": self.versions()[i],
+                       "sections": [{"heading": None, "text": p.read_text(encoding="utf-8")}]}
+
+
+Folder.main()
+'''
+
+
+def test_a_folder_connector_is_under_thirty_lines_and_passes_the_contract_check(tmp_path):
+    assert len(FOLDER.strip().splitlines()) < 30
+    script = tmp_path / "folder.py"
+    script.write_text(FOLDER)
+    notes = tmp_path / "notes"
+    (notes / "sub").mkdir(parents=True)
+    (notes / "a.txt").write_text("Alpha note.")
+    (notes / "sub" / "b.txt").write_text("Beta note.")
+    connector = CoreConnector("folder", [sys.executable, str(script)], env={"FOLDER": str(notes)})
+    check_connector(connector)
+    assert {i.id for i in connector.fetch(["a.txt", "sub/b.txt"])} == {"a.txt", "sub/b.txt"}
+
+
+def test_main_exits_with_the_code_as_a_real_process(tmp_path):
+    script = tmp_path / "folder.py"
+    script.write_text(FOLDER)
+    run = subprocess.run([sys.executable, str(script), "list"], capture_output=True, text=True,
+                         env={"PATH": "/usr/bin", "FOLDER": str(tmp_path / "missing")})
+    assert run.returncode == 2 and run.stdout == "" and "FOLDER must be an existing folder" in run.stderr
+
+
+@pytest.mark.parametrize("line", ['{"id": 1}', '{"id": null}', '{"id": ""}', '[]', '{"name": "a"}'])
+def test_fetch_ids_must_be_non_empty_strings(line):
+    code, records, err = call(Demo, "fetch", stdin=line + "\n")
+    assert code == 1 and records == [] and "fetch expects" in err
+
+
+@pytest.mark.parametrize("versions", [{"": "1"}, {2: "1"}, {"a": 3}, {"a": None}])
+def test_list_entries_are_validated_like_the_core_does(versions):
+    class Listing(Demo):
+        def versions(self):
+            return versions
+
+    code, records, err = call(Listing, "list")
+    assert code == 1 and records == [] and "invalid" in err
+
+
+@pytest.mark.parametrize("count", [-1, 1.5, "3", True, None])
+def test_a_custom_count_must_be_a_whole_number_from_zero(count):
+    class Counting(Demo):
+        def count(self):
+            return count
+
+    code, records, err = call(Counting, "check")
+    assert code == 1 and records == [] and "count" in err
+
+
+def test_fetch_may_only_return_requested_ids():
+    class Greedy(Demo):
+        def fetch(self, ids):
+            yield {**ITEM, "id": "zzz"}
+
+    code, records, err = call(Greedy, "fetch", stdin='{"id": "a"}\n')
+    assert code == 1 and records == [] and "zzz" in err and "not requested" in err
+
+
+def test_the_usage_message_names_the_program():
+    assert "prog" in call(Demo, "bogus")[2]
+
+
+def test_warnings_go_to_stderr_and_do_not_fail_the_call():
+    class Warns(Demo):
+        def versions(self):
+            self.warn("skipped notes/big.md: larger than 1 MiB")
+            return super().versions()
+
+    code, records, err = call(Warns, "list")
+    assert code == 0 and len(records) == 2
+    assert err.strip() == "demo connector: warning: skipped notes/big.md: larger than 1 MiB"
+
+
+def test_warnings_are_also_shown_when_the_call_fails():
+    class WarnsThenFails(Demo):
+        def versions(self):
+            self.warn("odd file")
+            raise SourceError("the source is down")
+
+    code, records, err = call(WarnsThenFails, "list")
+    assert code == 1 and records == [] and "warning: odd file" in err and "the source is down" in err

passageway_sdk-0.3.0/tests/test_settings.py

@@ -0,0 +1,31 @@
+import pytest
+
+from passageway_sdk import SettingsError
+from passageway_sdk.settings import flag, names, seconds, whole
+
+
+def test_names_splits_at_a_bar_and_drops_blanks():
+    assert names({"A": " x | y ||z "}, "A") == ("x", "y", "z")
+    assert names({}, "A") == ()
+
+
+def test_whole_reads_a_whole_number_with_a_default_and_a_floor():
+    assert whole({}, "N", 5) == 5
+    assert whole({"N": " 7 "}, "N", 5) == 7
+    assert whole({"N": "0"}, "N", 5, low=0) == 0
+    for bad in ("x", "1.5", "0"):
+        with pytest.raises(SettingsError, match="N"):
+            whole({"N": bad}, "N", 5)
+
+
+def test_flag_reads_true_or_false_only():
+    assert flag({}, "F", True) is True and flag({"F": "False"}, "F", True) is False and flag({"F": " true "}, "F", False) is True
+    with pytest.raises(SettingsError, match="F"):
+        flag({"F": "maybe"}, "F", True)
+
+
+def test_seconds_reads_a_number_that_is_not_negative():
+    assert seconds({}, "S", 0.2) == 0.2 and seconds({"S": "0"}, "S", 0.2) == 0.0
+    for bad in ("x", "-1"):
+        with pytest.raises(SettingsError, match="S"):
+            seconds({"S": bad}, "S", 0.2)

passageway_sdk-0.3.0/tests/test_web.py

@@ -0,0 +1,204 @@
+import httpx
+import pytest
+import truststore
+
+from passageway_sdk import SourceError
+from passageway_sdk.web import TooLarge, Web
+
+
+def web(handler, **options):
+    return Web("test-agent", transport=httpx.MockTransport(handler), sleep=lambda s: None, **options)
+
+
+def ok(request):
+    return httpx.Response(200, headers={"Content-Type": "text/html"}, text="hello")
+
+
+def test_a_reply_has_status_text_and_content_type():
+    reply = web(ok).get("https://x.example/")
+    assert (reply.status, reply.text, reply.content_type) == (200, "hello", "text/html")
+
+
+def test_the_user_agent_is_sent():
+    seen = []
+    web(lambda r: seen.append(r.headers["user-agent"]) or httpx.Response(200)).get("https://x.example/")
+    assert seen == ["test-agent"]
+
+
+def test_a_missing_page_is_a_reply_unless_it_is_required():
+    handler = lambda r: httpx.Response(404)  # noqa: E731
+    assert web(handler).get("https://x.example/").status == 404
+    with pytest.raises(SourceError, match="404"):
+        web(handler).get("https://x.example/", required=True)
+
+
+@pytest.mark.parametrize("status", [429, 500, 503])
+def test_a_busy_or_failing_server_fails_the_call(status):
+    with pytest.raises(SourceError, match=str(status)):
+        web(lambda r: httpx.Response(status)).get("https://x.example/")
+
+
+def test_a_network_error_fails_the_call():
+    def refuse(request):
+        raise httpx.ConnectError("refused")
+
+    with pytest.raises(SourceError, match="refused"):
+        web(refuse).get("https://x.example/")
+
+
+def test_a_reply_over_the_limit_is_too_large_and_the_limit_can_be_set_per_call():
+    big = lambda r: httpx.Response(200, content=b"x" * 100)  # noqa: E731
+    with pytest.raises(TooLarge):
+        web(big, max_bytes=10).get("https://x.example/")
+    assert len(web(big, max_bytes=10).get("https://x.example/", max_bytes=1000).text) == 100
+    assert issubclass(TooLarge, SourceError)
+
+
+def test_requests_are_spaced_by_the_pause():
+    waits = []
+    client = Web("a", pause=5, transport=httpx.MockTransport(ok), sleep=waits.append)
+    client.get("https://x.example/")
+    client.get("https://x.example/")
+    assert len(waits) == 1 and 0 < waits[0] <= 5  # the first request does not wait
+
+
+def test_https_uses_the_system_trust_store():
+    assert isinstance(Web("a")._http._transport._pool._ssl_context, truststore.SSLContext)
+
+
+def test_text_that_is_not_utf8_is_replaced_not_fatal():
+    assert web(lambda r: httpx.Response(200, content=b"caf\xe9")).get("https://x.example/").text == "caf�"
+
+
+# ---- a client for an API: base address, headers, TLS switch, redirects, retries, other methods ----------------------------
+
+from passageway_sdk.web import HttpError, NetworkError, Retry  # noqa: E402
+
+
+def test_a_base_url_and_default_headers_apply_to_every_request():
+    seen = []
+    client = web(lambda r: seen.append((str(r.url), r.headers["authorization"])) or httpx.Response(200),
+                 base_url="https://api.example/v1", headers={"Authorization": "Bearer t"}, pause=0)
+    client.get("/notes", params={"q": "a b"})
+    assert seen == [("https://api.example/v1/notes?q=a+b", "Bearer t")]
+
+
+def test_a_server_error_carries_its_status():
+    with pytest.raises(HttpError) as raised:
+        web(lambda r: httpx.Response(503)).get("https://x.example/")
+    assert raised.value.status == 503 and isinstance(raised.value, SourceError)
+    with pytest.raises(HttpError) as raised:
+        web(lambda r: httpx.Response(401)).get("https://x.example/", required=True)
+    assert raised.value.status == 401
+
+
+def test_turning_tls_checking_off_is_an_explicit_switch():
+    assert Web("a", verify=False)._http._transport._pool._ssl_context.verify_mode == ssl_none()
+
+
+def ssl_none():
+    import ssl
+
+    return ssl.CERT_NONE
+
+
+def test_redirects_are_followed_unless_refused():
+    def handler(request):
+        return httpx.Response(302, headers={"Location": "https://y.example/"}) if request.url.host == "x.example" else httpx.Response(200)
+
+    assert web(handler).get("https://x.example/").status == 200
+    assert web(handler, follow_redirects=False).get("https://x.example/").status == 302
+
+
+def test_a_post_sends_json_and_a_reply_reads_as_json():
+    seen = []
+
+    def handler(request):
+        seen.append((request.method, request.content))
+        return httpx.Response(200, json={"ok": True})
+
+    reply = web(handler).request("POST", "https://x.example/", json={"a": 1})
+    assert seen == [("POST", b'{"a":1}')] and reply.json() == {"ok": True}
+
+
+def test_a_retry_policy_waits_for_a_busy_server_and_then_succeeds():
+    replies = iter([httpx.Response(429, headers={"Retry-After": "7"}), httpx.Response(503), httpx.Response(200, text="ok")])
+    waits = []
+    client = Web("a", pause=0, retry=Retry(), transport=httpx.MockTransport(lambda r: next(replies)), sleep=waits.append)
+    assert client.get("https://x.example/").text == "ok"
+    assert waits[0] == 7 and 0 < waits[1] <= 60  # Retry-After is honoured, otherwise a backoff
+
+
+def test_a_retry_policy_gives_up_after_its_budget():
+    waits = []
+    client = Web("a", pause=0, retry=Retry(budget=10, max_backoff=4), transport=httpx.MockTransport(lambda r: httpx.Response(503)),
+                 sleep=waits.append)
+    with pytest.raises(HttpError, match="503"):
+        client.get("https://x.example/")
+    assert 0 < sum(waits) <= 10
+
+
+def test_without_a_retry_policy_nothing_is_retried():
+    calls = []
+    with pytest.raises(HttpError):
+        web(lambda r: calls.append(1) or httpx.Response(503)).get("https://x.example/")
+    assert len(calls) == 1
+
+
+def test_a_wait_is_clipped_to_the_budget_and_the_give_up_message_says_how_long_it_waited():
+    waits = []
+    client = Web("a", pause=0, retry=Retry(budget=10, max_backoff=4), transport=httpx.MockTransport(lambda r: httpx.Response(503)),
+                 sleep=waits.append)
+    with pytest.raises(HttpError, match=r"giving up after 5 attempts and 10 s of waiting: HTTP 503") as raised:
+        client.get("https://x.example/")
+    assert waits == [1, 2, 4, 3] and raised.value.attempts == 5 and raised.value.status == 503
+
+
+def test_a_long_wait_is_reported_to_the_log_as_it_starts():
+    replies = iter([httpx.Response(429, headers={"Retry-After": "40"}), httpx.Response(200)])
+    said = []
+    client = Web("a", pause=0, retry=Retry(), log=said.append, transport=httpx.MockTransport(lambda r: next(replies)), sleep=lambda s: None)
+    client.get("https://x.example/p")
+    assert said == ["HTTP 429 on GET https://x.example/p: waiting 40 s (0 s of 900 s waited)"]
+
+
+def test_network_errors_are_retried_only_when_the_policy_says_so():
+    calls = []
+
+    def flaky(request):
+        calls.append(1)
+        if len(calls) == 1:
+            raise httpx.ConnectError("refused")
+        return httpx.Response(200, text="ok")
+
+    with pytest.raises(NetworkError):
+        web(flaky).get("https://x.example/")
+    calls.clear()
+    client = Web("a", pause=0, retry=Retry(network=True), transport=httpx.MockTransport(flaky), sleep=lambda s: None)
+    assert client.get("https://x.example/").text == "ok"
+
+
+def test_a_reply_has_its_headers_in_lower_case():
+    client = web(lambda r: httpx.Response(302, headers={"Location": "https://y.example/"}), follow_redirects=False)
+    assert client.get("https://x.example/").headers["location"] == "https://y.example/"
+
+
+def test_a_reply_the_caller_calls_busy_is_retried_like_a_busy_status():
+    replies = iter([httpx.Response(200, text="lag"), httpx.Response(200, text="lag"), httpx.Response(200, text="done")])
+    waits, said = [], []
+    client = Web("a", pause=0, retry=Retry(say_from=1), log=said.append, transport=httpx.MockTransport(lambda r: next(replies)),
+                 sleep=waits.append)
+    reply = client.get("https://x.example/", retry_if=lambda r: "maxlag" if r.text == "lag" else None)
+    assert reply.text == "done" and waits == [1, 2] and said[0].startswith("maxlag on GET")
+
+
+def test_a_reply_that_stays_busy_gives_up_with_the_reason():
+    client = Web("a", pause=0, retry=Retry(budget=3), transport=httpx.MockTransport(lambda r: httpx.Response(200, text="lag")),
+                 sleep=lambda s: None)
+    with pytest.raises(HttpError, match="giving up after 3 attempts and 3 s of waiting: maxlag"):
+        client.get("https://x.example/", retry_if=lambda r: "maxlag")
+
+
+def test_retry_if_needs_a_retry_policy():
+    with pytest.raises(ValueError, match="retry"):
+        web(ok).get("https://x.example/", retry_if=lambda r: "x")