primarysource 0.1.0__py3-none-any.whl

primarysource/home.py

@@ -0,0 +1,65 @@
+"""Where a library keeps its data, and writing there without leaving half a file.
+
+One variable per library (`<APP>_HOME`), else a per-user data directory, never the working directory and never
+a path beside the installed package: nistlib and usblib default to `parents[2]/data`, which points into
+site-packages once installed from a wheel.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from collections.abc import Mapping
+from pathlib import Path
+
+from primarysource.fsutil import atomic_write as atomic_write  # moved to fsutil; kept here for importers
+
+
+def resolve_home(app: str, environ: Mapping[str, str] | None = None, platform: str | None = None) -> Path:
+    """`$<APP>_HOME` if set, else the per-user data directory for `app`. Nothing is created."""
+    env = os.environ if environ is None else environ
+    system = sys.platform if platform is None else platform
+    explicit = env.get(f"{app.upper()}_HOME")
+    if explicit:
+        return Path(explicit)
+    if system == "win32" and env.get("LOCALAPPDATA"):
+        return Path(env["LOCALAPPDATA"]) / app
+    if system == "darwin":
+        return Path.home() / "Library" / "Application Support" / app
+    if env.get("XDG_DATA_HOME"):
+        return Path(env["XDG_DATA_HOME"]) / app
+    return Path.home() / ".local" / "share" / app
+
+
+def collection_home(
+    name: str,
+    legacy_app: str | None = None,
+    environ: Mapping[str, str] | None = None,
+    platform: str | None = None,
+) -> Path:
+    """Where one collection keeps its library (PLAN.md §5.8). The first that applies:
+
+    1. `$<LEGACY_APP>_HOME`, e.g. `RFCLIB_HOME`: an explicit setting from before the move keeps working;
+    2. `$PRIMARYSOURCE_<NAME>_HOME`, e.g. `PRIMARYSOURCE_ISO_HOME`: one collection somewhere of its own (another
+       drive, a mounted volume) while the others stay where they are;
+    3. `$PRIMARYSOURCE_HOME/<name>`;
+    4. the legacy app's per-user directory (`%LOCALAPPDATA%\\rfclib`), if it already exists, so an existing
+       library is found instead of an empty one being started beside it;
+    5. the per-user `primarysource/<name>`.
+
+    Nothing is created.
+    """
+    env = dict(os.environ if environ is None else environ)
+    legacy_var = f"{legacy_app.upper()}_HOME" if legacy_app else ""
+    if legacy_app and env.get(legacy_var):
+        return Path(env[legacy_var])
+    own = env.get(f"PRIMARYSOURCE_{name.upper()}_HOME")
+    if own:
+        return Path(own)
+    if env.get("PRIMARYSOURCE_HOME"):
+        return Path(env["PRIMARYSOURCE_HOME"]) / name
+    if legacy_app:
+        old = resolve_home(legacy_app, env, platform)
+        if old.is_dir():
+            return old
+    return resolve_home("primarysource", env, platform) / name

primarysource/iana/__init__.py

@@ -0,0 +1,32 @@
+"""IANA protocol registries as a primarysource collection: `iana`.
+
+The registries are structured XML under `https://www.iana.org/assignments/`, dedicated to the public domain
+(CC0 1.0) by IANA and the IETF for the Protocol Registries; `docs/iana.md` has the terms, the format and the ref
+grammar. Nothing is shipped: `primarysource iana import <name>` (at most one request a second) fetches files into
+`$PRIMARYSOURCE_HOME/iana/`.
+
+Importing this package needs only the standard library; `mcp` is imported by `server.py` when the collection is
+served (`primarysource mcp --collection iana`). `primarysource iana ...` runs `cli.py`.
+"""
+
+from __future__ import annotations
+
+from primarysource.iana.reader import DOC, GRAMMAR
+from primarysource.model import Unit
+from primarysource.registry import Collection
+
+COLLECTION = Collection(
+    name="iana",
+    title="IANA protocol registries (assignments)",
+    prefix="iana_",
+    unit=Unit.BLOCK,
+    grammar=GRAMMAR,
+    server="primarysource.iana.server:server",
+    cli="primarysource.iana.cli:main",
+)
+"""Refs: `dns-parameters§dns-parameters-4` (a registry, by its IANA id), `bgp-parameters§bgp-parameters-2#3` (the
+record whose value is 3), `bgp-parameters§bgp-parameters-2¶4` (the 4th record in file order). `§` names the
+registry id, `#` a value, `¶n` the nth record. `dns-parameters#dns-parameters-4`, IANA's own URL fragment, names
+the registry too. The unit is the record: each is one line of the registry's columns and its RFC citations."""
+
+__all__ = ["COLLECTION", "DOC"]

primarysource/iana/catalogue.json

@@ -0,0 +1,244 @@
+{
+  "schema": 1,
+  "note": "Catalogue metadata only. Registry content is fetched by the importer into $PRIMARYSOURCE_HOME/iana/ and never belongs in this repository.",
+  "terms": {
+    "licence": "CC0-1.0",
+    "placement": "layer",
+    "terms_url": "https://www.iana.org/help/licensing-terms",
+    "terms_read": "2026-11-13",
+    "summary": "Joint IANA/IETF statement (revised 2021-11-10): the Protocol Registries linked from iana.org/protocols may be freely used by any party for any purpose, under the CC0 1.0 dedication. It excludes the root zone, .INT and .ARPA, the IDN repository, the number registries and RIR allocation data (IP address and AS number registries) and the Time Zone Database. No warranty; third-party rights are not guaranteed absent. Nothing on iana.org or robots.txt states a request rate; the importer sends at most one request per second."
+  },
+  "registries": [
+    {
+      "name": "dns-parameters",
+      "title": "DNS parameters (classes, RR types, opcodes, rcodes, EDNS, EDE)",
+      "url": "https://www.iana.org/assignments/dns-parameters/dns-parameters.xml",
+      "likely_users": "namespy",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "dns-sec-alg-numbers",
+      "title": "DNS Security Algorithm Numbers",
+      "url": "https://www.iana.org/assignments/dns-sec-alg-numbers/dns-sec-alg-numbers.xml",
+      "likely_users": "namespy",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "dnskey-flags",
+      "title": "DNSKEY RR Flags",
+      "url": "https://www.iana.org/assignments/dnskey-flags/dnskey-flags.xml",
+      "likely_users": "namespy",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "ds-rr-types",
+      "title": "Delegation Signer (DS) Resource Record Type Digest Algorithms",
+      "url": "https://www.iana.org/assignments/ds-rr-types/ds-rr-types.xml",
+      "likely_users": "namespy",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "dnssec-nsec3-parameters",
+      "title": "DNSSEC NSEC3 Parameters",
+      "url": "https://www.iana.org/assignments/dnssec-nsec3-parameters/dnssec-nsec3-parameters.xml",
+      "likely_users": "namespy",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "dns-svcb",
+      "title": "DNS Service Bindings (SVCB)",
+      "url": "https://www.iana.org/assignments/dns-svcb/dns-svcb.xml",
+      "likely_users": "namespy",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "bootp-dhcp-parameters",
+      "title": "DHCP and BOOTP parameters (options, message types)",
+      "url": "https://www.iana.org/assignments/bootp-dhcp-parameters/bootp-dhcp-parameters.xml",
+      "likely_users": "leasespy",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "dhcpv6-parameters",
+      "title": "DHCPv6 parameters",
+      "url": "https://www.iana.org/assignments/dhcpv6-parameters/dhcpv6-parameters.xml",
+      "likely_users": "leasespy",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "bgp-parameters",
+      "title": "BGP parameters (message types, path attributes, capabilities, error codes)",
+      "url": "https://www.iana.org/assignments/bgp-parameters/bgp-parameters.xml",
+      "likely_users": "rtrkit, pathattr, bmpkit",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "bgp-extended-communities",
+      "title": "BGP Extended Communities",
+      "url": "https://www.iana.org/assignments/bgp-extended-communities/bgp-extended-communities.xml",
+      "likely_users": "pathattr, bmpkit",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "bgp-well-known-communities",
+      "title": "BGP Well-known Communities",
+      "url": "https://www.iana.org/assignments/bgp-well-known-communities/bgp-well-known-communities.xml",
+      "likely_users": "pathattr, bmpkit",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "bgp-tunnel-encapsulation",
+      "title": "BGP Tunnel Encapsulation",
+      "url": "https://www.iana.org/assignments/bgp-tunnel-encapsulation/bgp-tunnel-encapsulation.xml",
+      "likely_users": "pathattr",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "bgp-ls-parameters",
+      "title": "BGP-LS parameters",
+      "url": "https://www.iana.org/assignments/bgp-ls-parameters/bgp-ls-parameters.xml",
+      "likely_users": "pathattr, bmpkit",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "rpki",
+      "title": "Resource Public Key Infrastructure (RPKI) parameters",
+      "url": "https://www.iana.org/assignments/rpki/rpki.xml",
+      "likely_users": "rtrkit, rpkit",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "stun-parameters",
+      "title": "STUN parameters (methods, attributes, error codes)",
+      "url": "https://www.iana.org/assignments/stun-parameters/stun-parameters.xml",
+      "likely_users": "turnkit",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "tls-parameters",
+      "title": "TLS parameters (cipher suites, groups, signature schemes, alerts)",
+      "url": "https://www.iana.org/assignments/tls-parameters/tls-parameters.xml",
+      "likely_users": "certledger, ctspy",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "tls-extensiontype-values",
+      "title": "TLS extension types",
+      "url": "https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xml",
+      "likely_users": "certledger, ctspy",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "http-methods",
+      "title": "HTTP method registry",
+      "url": "https://www.iana.org/assignments/http-methods/http-methods.xml",
+      "likely_users": "h3tunnel, sfields",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "http-status-codes",
+      "title": "HTTP status codes",
+      "url": "https://www.iana.org/assignments/http-status-codes/http-status-codes.xml",
+      "likely_users": "h3tunnel, sfields",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "http-fields",
+      "title": "HTTP field name registry",
+      "url": "https://www.iana.org/assignments/http-fields/http-fields.xml",
+      "likely_users": "sfields",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "pkix-parameters",
+      "title": "PKIX parameters",
+      "url": "https://www.iana.org/assignments/pkix-parameters/pkix-parameters.xml",
+      "likely_users": "pkix, certledger",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "protocol-numbers",
+      "title": "IP protocol numbers",
+      "url": "https://www.iana.org/assignments/protocol-numbers/protocol-numbers.xml",
+      "likely_users": "pathattr, syslogkit",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "address-family-numbers",
+      "title": "Address family numbers",
+      "url": "https://www.iana.org/assignments/address-family-numbers/address-family-numbers.xml",
+      "likely_users": "bmpkit, pathattr",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "icmp-parameters",
+      "title": "ICMP parameters",
+      "url": "https://www.iana.org/assignments/icmp-parameters/icmp-parameters.xml",
+      "likely_users": "namespy",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "icmpv6-parameters",
+      "title": "ICMPv6 parameters",
+      "url": "https://www.iana.org/assignments/icmpv6-parameters/icmpv6-parameters.xml",
+      "likely_users": "namespy",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "ikev2-parameters",
+      "title": "IKEv2 parameters",
+      "url": "https://www.iana.org/assignments/ikev2-parameters/ikev2-parameters.xml",
+      "likely_users": "srtpkit",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "ipfix",
+      "title": "IP Flow Information Export (IPFIX) entities",
+      "url": "https://www.iana.org/assignments/ipfix/ipfix.xml",
+      "likely_users": "syslogkit",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "ppp-numbers",
+      "title": "Point-to-Point Protocol field assignments",
+      "url": "https://www.iana.org/assignments/ppp-numbers/ppp-numbers.xml",
+      "likely_users": "leasespy",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "radius-types",
+      "title": "RADIUS types",
+      "url": "https://www.iana.org/assignments/radius-types/radius-types.xml",
+      "likely_users": "tacacs",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "syslog-parameters",
+      "title": "Syslog parameters",
+      "url": "https://www.iana.org/assignments/syslog-parameters/syslog-parameters.xml",
+      "likely_users": "syslogkit",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "ethernet-numbers",
+      "title": "Ethernet numbers",
+      "url": "https://www.iana.org/assignments/ethernet-numbers/ethernet-numbers.xml",
+      "likely_users": "leasespy",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "ntp-parameters",
+      "title": "NTP parameters",
+      "url": "https://www.iana.org/assignments/ntp-parameters/ntp-parameters.xml",
+      "likely_users": "ntspy",
+      "read": "2026-11-13"
+    },
+    {
+      "name": "tcp-parameters",
+      "title": "TCP parameters (options, flags)",
+      "url": "https://www.iana.org/assignments/tcp-parameters/tcp-parameters.xml",
+      "likely_users": "h3tunnel",
+      "read": "2026-11-13"
+    }
+  ]
+}

primarysource/iana/catalogue.py

@@ -0,0 +1,69 @@
+"""The catalogue of registries the portfolio needs, and IANA's terms for them. Metadata only, never content.
+
+`catalogue.json` is package data. Each entry has the registry file's name, its URL and the date the URL was last
+confirmed to serve a registry file (`read`). `likely_users` names the portfolio projects that want the data and is
+indicative, not a dependency declaration. Any other registry under `https://www.iana.org/assignments/` can be
+imported by name too (`primarysource iana import <name>`); the catalogue is the list the portfolio needs.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from importlib import resources
+from typing import Any
+
+from primarysource.errors import LibError
+
+BASE = "https://www.iana.org/assignments/"
+NAME = re.compile(r"[a-z0-9][a-z0-9._-]*")
+
+
+@dataclass(frozen=True, slots=True)
+class Terms:
+    licence: str
+    placement: str
+    terms_url: str
+    terms_read: str
+    summary: str
+
+
+@dataclass(frozen=True, slots=True)
+class Entry:
+    name: str
+    title: str
+    url: str
+    likely_users: str
+    read: str
+
+
+def url_for(name: str) -> str:
+    """`https://www.iana.org/assignments/<name>/<name>.xml`, the layout every registry file follows."""
+    if not NAME.fullmatch(name) or ".." in name:
+        raise LibError(
+            f"{name!r} is not a registry file name", "names are lowercase letters, digits, '-', '_' and '.'"
+        )
+    return f"{BASE}{name}/{name}.xml"
+
+
+def _load() -> tuple[Terms, tuple[Entry, ...]]:
+    raw: dict[str, Any] = json.loads(
+        resources.files("primarysource.iana").joinpath("catalogue.json").read_text("utf-8")
+    )
+    t = raw["terms"]
+    terms = Terms(t["licence"], t["placement"], t["terms_url"], t["terms_read"], t["summary"])
+    entries = tuple(
+        Entry(e["name"], e["title"], e["url"], e.get("likely_users", ""), e["read"]) for e in raw["registries"]
+    )
+    for entry in entries:
+        if entry.url != url_for(entry.name):
+            raise ValueError(f"catalogue entry {entry.name!r} has an unexpected URL {entry.url!r}")
+    return terms, entries
+
+
+TERMS, ENTRIES = _load()
+
+
+def entry(name: str) -> Entry | None:
+    return next((e for e in ENTRIES if e.name == name), None)

primarysource/iana/cli.py

@@ -0,0 +1,69 @@
+"""`primarysource iana ...`: the collection's own commands.
+
+primarysource iana list
+primarysource iana import <name>... | --all [--force] [--interval SECONDS]
+primarysource iana read <ref> [--max-tokens N]
+primarysource iana lookup <registry-ref> <value>
+primarysource iana search <text> [--file NAME] [--limit N] [--start N]
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from primarysource.errors import LibError
+from primarysource.iana import importer, reader
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="primarysource iana", description="IANA protocol registries")
+    commands = parser.add_subparsers(dest="command", required=True)
+    commands.add_parser("list", help="the catalogue, marked imported or not")
+    imp = commands.add_parser("import", help="fetch registry XML from iana.org (at most 1 request per second)")
+    imp.add_argument("names", nargs="*", help="registry file names, e.g. dns-parameters")
+    imp.add_argument("--all", action="store_true", help="every registry in the catalogue")
+    imp.add_argument("--force", action="store_true", help="fetch even if the server says nothing changed")
+    imp.add_argument("--interval", type=float, default=importer.MIN_INTERVAL, help="seconds between requests (>= 1)")
+    read = commands.add_parser("read", help="read by ref")
+    read.add_argument("ref")
+    read.add_argument("--max-tokens", type=int, default=2000)
+    look = commands.add_parser("lookup", help="the record(s) with a value")
+    look.add_argument("registry")
+    look.add_argument("value")
+    find = commands.add_parser("search", help="find records containing every word")
+    find.add_argument("text")
+    find.add_argument("--file")
+    find.add_argument("--limit", type=int, default=20)
+    find.add_argument("--start", type=int, default=0)
+    return parser
+
+
+def _out(text: str) -> int:
+    # UTF-8 bytes: registry text has names a Windows console code page cannot encode
+    sys.stdout.flush()
+    sys.stdout.buffer.write((text if text.endswith("\n") else text + "\n").encode("utf-8"))
+    sys.stdout.buffer.flush()
+    return 0
+
+
+def main(argv: Sequence[str]) -> int:
+    args = _parser().parse_args(list(argv))
+    try:
+        if args.command == "list":
+            return _out(reader.listing())
+        if args.command == "import":
+            names = importer.catalogue_names() if args.all else args.names
+            report = importer.import_registries(names, force=args.force, interval=args.interval)
+            for o in report.outcomes:
+                print(f"{o.name}: {o.status}, updated {o.updated or '-'}, {o.size:,} bytes, sha256 {o.sha256[:16]}")
+            return 0
+        if args.command == "read":
+            return _out(reader.read(args.ref, max_tokens=args.max_tokens))
+        if args.command == "lookup":
+            return _out(reader.lookup(args.registry, args.value))
+        return _out(reader.search(args.text, file=args.file, limit=args.limit, start=args.start))
+    except LibError as exc:
+        print(exc.as_text(), file=sys.stderr)
+        return 1

primarysource/iana/importer.py

@@ -0,0 +1,157 @@
+"""Fetch registry XML from iana.org into `$PRIMARYSOURCE_HOME/iana/`.
+
+Polite by construction: at most one request per `interval` seconds (never under 1.0), an identifying User-Agent,
+conditional requests (`If-Modified-Since`) so an unchanged file costs a 304, no redirects followed, only
+`https://www.iana.org/assignments/<name>/<name>.xml`, and a response size ceiling. Each file is parsed with the
+hardened reader and its root id checked against the name before anything is written; the bytes are stored
+exactly as served, atomically, and `manifest.json` records sha256, size and the registry's `updated` date.
+
+The transport is a parameter, so tests inject one; the default uses `urllib`.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+
+from primarysource.errors import LibError
+from primarysource.home import atomic_write
+from primarysource.iana import xmlsafe
+from primarysource.iana.catalogue import BASE, ENTRIES, url_for
+from primarysource.iana.model import from_tree
+from primarysource.iana.store import MANIFEST, MAX_BYTES, home, read_manifest
+
+USER_AGENT = "primarysource-iana/0.1 (local registry mirror; at most 1 request per second)"
+MIN_INTERVAL = 1.0
+
+
+@dataclass(frozen=True, slots=True)
+class Response:
+    status: int
+    headers: Mapping[str, str]
+    body: bytes
+
+
+Transport = Callable[[str, Mapping[str, str]], Response]
+"""`transport(url, request_headers) -> Response`. It must not follow redirects and must bound the body."""
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, *_args: object, **_kwargs: object) -> None:
+        return None
+
+
+def urllib_transport(url: str, headers: Mapping[str, str]) -> Response:
+    """The default transport: one GET, https to www.iana.org only, no redirects, body capped at MAX_BYTES."""
+    if not url.startswith(BASE):
+        raise LibError(f"refusing to fetch {url!r}", f"only {BASE}<name>/<name>.xml is fetched")
+    opener = urllib.request.build_opener(_NoRedirect)
+    request = urllib.request.Request(url, headers=dict(headers))  # noqa: S310 - the https prefix is checked above
+    try:
+        with opener.open(request, timeout=60) as reply:
+            body = reply.read(MAX_BYTES + 1)
+            return Response(reply.status, {k.lower(): v for k, v in reply.headers.items()}, body)
+    except urllib.error.HTTPError as exc:
+        return Response(exc.code, {k.lower(): v for k, v in exc.headers.items()}, b"")
+    except (urllib.error.URLError, TimeoutError, OSError) as exc:
+        raise LibError(f"could not reach {url}: {exc}", "check the network and try again") from exc
+
+
+@dataclass(frozen=True, slots=True)
+class Outcome:
+    name: str
+    status: str
+    """`fetched`, `unchanged` (HTTP 304) or `identical` (HTTP 200 with the sha256 already held)."""
+    sha256: str
+    size: int
+    updated: str
+    path: Path
+
+
+@dataclass(slots=True)
+class Report:
+    outcomes: list[Outcome] = field(default_factory=list)
+
+
+def catalogue_names() -> list[str]:
+    return [e.name for e in ENTRIES]
+
+
+def import_registries(
+    names: Sequence[str],
+    *,
+    base: Path | None = None,
+    transport: Transport | None = None,
+    interval: float = MIN_INTERVAL,
+    force: bool = False,
+    sleep: Callable[[float], None] = time.sleep,
+    clock: Callable[[], float] = time.monotonic,
+    user_agent: str = USER_AGENT,
+    now: Callable[[], datetime] = lambda: datetime.now(UTC),
+) -> Report:
+    """Fetch each named registry file. The first failure stops the run and leaves earlier files in place."""
+    if os.environ.get("PRIMARYSOURCE_READONLY"):
+        raise LibError("the library is read-only (PRIMARYSOURCE_READONLY is set), so nothing is fetched", "unset it")
+    if interval < MIN_INTERVAL:
+        raise LibError(f"an interval under {MIN_INTERVAL:g} second is refused", "registries are fetched politely")
+    wanted = list(dict.fromkeys(names))
+    if not wanted:
+        raise LibError("no registry named", "name one, e.g. dns-parameters, or use --all for the catalogue")
+    urls = {name: url_for(name) for name in wanted}  # validates every spelling before the first request
+    send: Transport = transport or urllib_transport
+    root = base or home()
+    root.mkdir(parents=True, exist_ok=True)
+    files = read_manifest(root)
+    report = Report()
+    last: float | None = None
+    for name in wanted:
+        if last is not None:
+            wait = interval - (clock() - last)
+            if wait > 0:
+                sleep(wait)
+        url = urls[name]
+        headers = {"User-Agent": user_agent, "Accept": "application/xml"}
+        previous = files.get(name, {})
+        target = root / f"{name}.xml"
+        if not force and target.is_file() and previous.get("last_modified"):
+            headers["If-Modified-Since"] = str(previous["last_modified"])
+        last = clock()
+        reply = send(url, headers)
+        if reply.status == 304 and target.is_file() and previous:
+            size = int(previous.get("size", 0))
+            report.outcomes.append(
+                Outcome(
+                    name, "unchanged", str(previous.get("sha256", "")), size, str(previous.get("updated", "")), target
+                )
+            )
+            continue
+        if reply.status != 200:
+            raise LibError(
+                f"{url} answered HTTP {reply.status}", "check the name against https://www.iana.org/protocols"
+            )
+        if len(reply.body) > MAX_BYTES:
+            raise LibError(f"{url} is over {MAX_BYTES:,} bytes", "this is not the expected registry file")
+        parsed = from_tree(xmlsafe.parse(reply.body, MAX_BYTES), name)
+        digest = hashlib.sha256(reply.body).hexdigest()
+        status = "identical" if target.is_file() and previous.get("sha256") == digest else "fetched"
+        atomic_write(target, reply.body)
+        files[name] = {
+            "url": url,
+            "sha256": digest,
+            "size": len(reply.body),
+            "updated": parsed.updated,
+            "fetched": now().isoformat(timespec="seconds"),
+            "last_modified": {k.lower(): v for k, v in reply.headers.items()}.get("last-modified", ""),
+        }
+        manifest = json.dumps({"schema": 1, "files": files}, indent=2, sort_keys=True) + "\n"
+        atomic_write(root / MANIFEST, manifest.encode("utf-8"))
+        report.outcomes.append(Outcome(name, status, digest, len(reply.body), parsed.updated, target))
+    return report