nnnotes 0.1.0__py3-none-any.whl

nnnotes/cache.py

@@ -0,0 +1,289 @@
+"""Memo caches for work that repeats within a run: decoded textures, PNG encodings, shader dumps, decoded cue sheets.
+
+A bucket maps a content key to a value computed from exactly the inputs the key covers, so a hit returns what the
+computation would return: the extractors' outputs stay byte-identical with or without the cache. Buckets live in the
+process (LRU, bounded by a byte budget, thread-safe). Buckets that hold bytes can also keep them on disk
+(`configure(directory=...)`): processes of one build then share the results, and a later run with the same inputs
+reuses them. Keys of the disk layer are salted with the source of the module that produces the value and the
+versions of the libraries it calls, so a code or library change never reads an older result.
+
+    from nnnotes import cache
+    cache.configure(enabled=False)                # every get misses, nothing is stored
+    cache.configure(memory_mb=512, directory="work/cache")
+    PNG = cache.bucket("png", salt=cache.source_salt(__file__))
+    k = PNG.key(data, width, height)
+    png = PNG.get(k)
+    if png is None:
+        png = encode(...)
+        PNG.put(k, png)
+"""
+from __future__ import annotations
+
+import hashlib
+import os
+import secrets
+import struct
+import threading
+from collections import OrderedDict
+from importlib import metadata
+from pathlib import Path
+
+DISK_MAGIC = b"NNC1"
+DEFAULT_MEMORY_MB = 128
+
+_settings = {"enabled": True, "memory": DEFAULT_MEMORY_MB << 20, "directory": None, "closures": 4,
+             "closure_bytes": 512 << 20}
+_buckets: dict[str, "Bucket"] = {}
+_lock = threading.Lock()
+
+
+def configure(*, enabled: bool | None = None, memory_mb: int | None = None, directory=None,
+              closures: int | None = None, closure_mb: int | None = None) -> dict:
+    """Set the caches of this process: `enabled`; `memory_mb` (byte budget of each bucket); `directory` (disk layer
+    of the byte buckets; "" or None for none); `closures` / `closure_mb` (loaded bundle closures kept by
+    unity.load_closure, per thread: count and bundle bytes). Clears the buckets. Returns the settings."""
+    with _lock:
+        if enabled is not None:
+            _settings["enabled"] = bool(enabled)
+        if memory_mb is not None:
+            _settings["memory"] = max(0, int(memory_mb)) << 20
+        if directory is not None:
+            _settings["directory"] = Path(directory) if directory else None
+        if closures is not None:
+            _settings["closures"] = max(0, int(closures))
+        if closure_mb is not None:
+            _settings["closure_bytes"] = max(0, int(closure_mb)) << 20
+        for b in _buckets.values():
+            b.clear()
+        return settings()
+
+
+def settings() -> dict:
+    """The current settings (a copy)."""
+    return dict(_settings)
+
+
+def enabled() -> bool:
+    return _settings["enabled"]
+
+
+def bucket(name: str, *, salt: str = "", disk: bool = False, max_item: int | None = None) -> "Bucket":
+    """The process's bucket `name` (created on first use). `disk`: its values are bytes and may be kept on disk;
+    `max_item`: values larger than this many bytes are not kept (default: a quarter of the budget)."""
+    with _lock:
+        b = _buckets.get(name)
+        if b is None:
+            b = _buckets[name] = Bucket(name, salt, disk, max_item)
+        return b
+
+
+def stats() -> dict:
+    """Per bucket: items, bytes, hits, misses, disk hits, disk writes, disk write errors."""
+    return {n: b.stats() for n, b in sorted(_buckets.items())}
+
+
+def clear() -> None:
+    for b in _buckets.values():
+        b.clear()
+
+
+# ---------------------------------------------------------------- keys
+def _feed(h, part) -> None:
+    if isinstance(part, (bytes, bytearray, memoryview)):
+        mv = memoryview(part).cast("B")
+        h.update(b"b" + struct.pack("<Q", mv.nbytes))
+        h.update(mv)
+    elif isinstance(part, str):
+        b = part.encode("utf-8", "surrogatepass")
+        h.update(b"s" + struct.pack("<Q", len(b)) + b)
+    elif isinstance(part, (tuple, list)):
+        h.update(b"t" + struct.pack("<Q", len(part)))
+        for p in part:
+            _feed(h, p)
+    elif part is None or isinstance(part, (bool, int, float)):
+        r = repr(part).encode("ascii")
+        h.update(b"r" + struct.pack("<Q", len(r)) + r)
+    else:
+        raise TypeError(f"cache key part of type {type(part).__name__}")
+
+
+def key(*parts) -> str:
+    """sha256 hex of `parts` (bytes, str, int, float, bool, None and tuples / lists of them), unambiguous."""
+    h = hashlib.sha256()
+    _feed(h, parts)
+    return h.hexdigest()
+
+
+_salts: dict[str, str] = {}
+
+
+def source_salt(path, *dists: str) -> str:
+    """A salt for keys of values a module produces: sha256 of the module's source file and the installed versions
+    of the distributions `dists` (a missing one counts as "-")."""
+    p = Path(path)
+    k = f"{p}|{'|'.join(dists)}"
+    s = _salts.get(k)
+    if s is None:
+        versions = []
+        for d in dists:
+            try:
+                versions.append(f"{d}={metadata.version(d)}")
+            except metadata.PackageNotFoundError:
+                versions.append(f"{d}=-")
+        s = _salts[k] = key(p.read_bytes(), versions)
+    return s
+
+
+def file_id(path) -> tuple:
+    """(path, size, mtime) of a file: identifies an executable or input file in a key."""
+    p = Path(path)
+    st = p.stat()
+    return (str(p), st.st_size, st.st_mtime_ns)
+
+
+# ---------------------------------------------------------------- buckets
+class Bucket:
+    def __init__(self, name: str, salt: str, disk: bool, max_item: int | None):
+        self.name, self.salt, self.disk, self._max_item = name, salt, disk, max_item
+        self._items: OrderedDict[str, tuple] = OrderedDict()
+        self._bytes = 0
+        self._lock = threading.Lock()
+        self.hits = self.misses = self.disk_hits = self.disk_writes = self.disk_errors = 0
+
+    def key(self, *parts) -> str:
+        return key(self.name, self.salt, parts)
+
+    def _limit(self) -> int:
+        budget = _settings["memory"]
+        return budget // 4 if self._max_item is None else min(self._max_item, budget)
+
+    def get(self, k: str):
+        """The value stored under `k`, or None."""
+        if not _settings["enabled"]:
+            return None
+        with self._lock:
+            hit = self._items.get(k)
+            if hit is not None:
+                self._items.move_to_end(k)
+                self.hits += 1
+                return hit[0]
+        if self.disk and _settings["directory"] is not None:
+            data = _disk_read(self._path(k))
+            if data is not None:
+                with self._lock:
+                    self.disk_hits += 1
+                self._remember(k, data, len(data))
+                return data
+        with self._lock:
+            self.misses += 1
+        return None
+
+    def put(self, k: str, value, size: int | None = None) -> None:
+        """Store `value` (bytes for a disk bucket) under `k`; `size`: its byte size (default len(value))."""
+        if not _settings["enabled"]:
+            return
+        n = len(value) if size is None else int(size)
+        self._remember(k, value, n)
+        if self.disk and _settings["directory"] is not None and n <= max(self._limit(), 64 << 20):
+            ok = _disk_write(self._path(k), value)
+            with self._lock:
+                if ok:
+                    self.disk_writes += 1
+                else:
+                    self.disk_errors += 1
+
+    def _remember(self, k: str, value, n: int) -> None:
+        if n > self._limit():
+            return
+        with self._lock:
+            old = self._items.pop(k, None)
+            if old is not None:
+                self._bytes -= old[1]
+            self._items[k] = (value, n)
+            self._bytes += n
+            budget = _settings["memory"]
+            while self._bytes > budget and self._items:
+                _, (_, m) = self._items.popitem(last=False)
+                self._bytes -= m
+
+    def _path(self, k: str) -> Path:
+        return _settings["directory"] / self.name / k[:2] / k
+
+    def clear(self) -> None:
+        with self._lock:
+            self._items.clear()
+            self._bytes = 0
+
+    def stats(self) -> dict:
+        with self._lock:
+            return {"items": len(self._items), "bytes": self._bytes, "hits": self.hits, "misses": self.misses,
+                    "diskHits": self.disk_hits, "diskWrites": self.disk_writes, "diskErrors": self.disk_errors}
+
+
+def _disk_read(p: Path) -> bytes | None:
+    try:
+        raw = p.read_bytes()
+    except OSError:
+        return None
+    if len(raw) < 12 or raw[:4] != DISK_MAGIC:
+        return None
+    n, = struct.unpack_from("<Q", raw, 4)
+    return raw[12:] if len(raw) == 12 + n else None
+
+
+def temp_path(dst: Path) -> Path:
+    """A new temporary file name next to `dst` for writing it atomically: short whatever `dst`'s name (a long name
+    plus a suffix would pass the file system's name limit), random, so unique across processes and threads."""
+    return Path(dst).with_name(f".{secrets.token_hex(8)}.part")
+
+
+def write_atomic(dst: Path, data: bytes) -> None:
+    """Write `data` to `dst` through temp_path(dst) (created exclusively, default permissions) and a rename; the
+    temporary file is removed when anything fails."""
+    tmp = temp_path(dst)
+    try:
+        with open(tmp, "xb") as f:
+            f.write(data)
+        os.replace(tmp, dst)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def _disk_write(p: Path, data: bytes) -> bool:
+    """Write a disk entry atomically; False when the file system refused (counted as diskErrors: a cache that
+    cannot write only misses later, the result is the same)."""
+    try:
+        p.parent.mkdir(parents=True, exist_ok=True)
+        write_atomic(p, DISK_MAGIC + struct.pack("<Q", len(data)) + bytes(data))
+        return True
+    except OSError:
+        return False
+
+
+# ---------------------------------------------------------------- packing several blobs into one value
+def pack(meta: bytes, blobs: list[bytes]) -> bytes:
+    """One bytes value from a header and blobs (for disk buckets whose value is several files)."""
+    out = [struct.pack("<II", len(meta), len(blobs)), meta]
+    for b in blobs:
+        out += [struct.pack("<Q", len(b)), b]
+    return b"".join(out)
+
+
+def unpack(data: bytes) -> tuple[bytes, list[bytes]]:
+    n, count = struct.unpack_from("<II", data, 0)
+    pos = 8
+    meta = data[pos:pos + n]
+    pos += n
+    blobs = []
+    for _ in range(count):
+        m, = struct.unpack_from("<Q", data, pos)
+        pos += 8
+        blobs.append(data[pos:pos + m])
+        pos += m
+    if pos != len(data):
+        raise ValueError("packed cache value has trailing bytes")
+    return meta, blobs

nnnotes/catalog.py

@@ -0,0 +1,373 @@
+"""Addressables catalog access: dependency closures, a bundle cache, remote and APK-local bundles.
+
+Remote bundles are fetched from the region's CDN and decrypted (addressables.decrypt); local bundles (shipped inside
+the APK) are read from a user-supplied base.apk. Nothing here bundles or redistributes game data: it only reads
+what the user points it at into a local cache the user controls.
+"""
+from __future__ import annotations
+
+import http.client
+import sys
+import threading
+import urllib.parse
+import urllib.request
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from .addressables import BundleKey, decrypt, parse, parse_locations, remote_path
+from .cache import write_atomic as _write_atomic
+from .config import ConfigError, apk_missing
+
+LOCAL_PREFIX = "{UnityEngine.AddressableAssets.Addressables.RuntimePath}"
+APK_AA_DIR = "assets/aa/"          # + "Android/<bundle>"
+APK_CATALOG = "assets/aa/catalog.bin"
+APK_OFFSET_BASE = 1 << 40          # namespace for APK catalog entry offsets
+
+
+@dataclass(frozen=True)
+class Bundle:
+    offset: int
+    internal_id: str
+    name: str          # bare file name (embeds content hash)
+    remote: bool       # True: on CDN; False: shipped inside the APK
+
+
+def location_kind(internal_id: str) -> str:
+    """What a location names: "bundle" or "raw" (a file on the CDN or in the APK, `.bundle` or not), "asset" (a path
+    inside a bundle), else "other"."""
+    if remote_path(internal_id) is not None or internal_id.startswith(LOCAL_PREFIX):
+        return "bundle" if internal_id.endswith(".bundle") else "raw"
+    if internal_id.startswith(("Assets/", "Packages/")):
+        return "asset"
+    return "other"
+
+
+def file_name(internal_id: str) -> str:
+    """The name of a bundle or raw file location: its path below the platform directory (`Android/`), which for a
+    bundle is its bare file name."""
+    rel = remote_path(internal_id)
+    if rel is None:
+        rel = internal_id[len(LOCAL_PREFIX):] if internal_id.startswith(LOCAL_PREFIX) else internal_id
+    head, sep, tail = rel.partition("/Android/")
+    return tail if sep else rel.rsplit("/", 1)[-1]
+
+
+def _unityfs(data: bytes, name: str, key: BundleKey | None) -> bytes:
+    if data[:7] == b"UnityFS":
+        return data
+    if key is None:
+        raise RuntimeError(f"bundle {name} is encrypted and no bundle key was given")
+    return decrypt(data, name, key)
+
+
+class Catalog:
+    """Remote content catalog, merged with the APK's local catalog when an APK is given.
+
+    The game loads both: the APK catalog (embedded assets, e.g. ADV settings and
+    shared prefabs) and the remote catalog (downloadable content). Entry offsets
+    are per-catalog, so APK entries are moved into their own offset namespace.
+
+    `cdn`: the region's CDN base (needed only to download what the cache lacks); `bundle_key`: the bundle
+    decryption key (needed only for bundles not yet in the cache). Either may be a function that returns it, called
+    the first time it is needed (a ConfigError it raises is raised naming the file that needed the setting).
+    """
+
+    def __init__(self, catalog_bytes: bytes, cache_dir: Path, *, cdn=None, bundle_key=None, apk: Path | None = None):
+        self._settings = {"cdn": cdn, "bundle_key": bundle_key}
+        self.cache_dir = Path(cache_dir)
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        self.apk = Path(apk) if apk else None
+        self._sources = {"remote": catalog_bytes}
+        self._locations: list[dict] | None = None
+        self._parsed: tuple | None = None
+        if self.apk is not None:
+            with zipfile.ZipFile(self.apk) as z:
+                self._sources["apk"] = z.read(APK_CATALOG)
+
+    def _parse(self) -> tuple:
+        """(entries, by offset, by primary key), parsed the first time a lookup needs them (a command that only
+        wants the catalog files, sources(), does not pay for it)."""
+        if self._parsed is None:
+            entries = parse(self._sources["remote"])
+            if "apk" in self._sources:
+                for e in parse(self._sources["apk"]):
+                    e["offset"] += APK_OFFSET_BASE
+                    e["dependencies"] = [d + APK_OFFSET_BASE for d in e["dependencies"]]
+                    entries.append(e)
+            by_key: dict[str, list[dict]] = {}
+            for e in entries:
+                by_key.setdefault(e["primary_key"], []).append(e)
+            self._parsed = (entries, {e["offset"]: e for e in entries}, by_key)
+        return self._parsed
+
+    @property
+    def entries(self) -> list[dict]:
+        return self._parse()[0]
+
+    @property
+    def _by_off(self) -> dict[int, dict]:
+        return self._parse()[1]
+
+    @property
+    def _by_key(self) -> dict[str, list[dict]]:
+        return self._parse()[2]
+
+    # --- construction ------------------------------------------------------
+    @classmethod
+    def load(cls, language: str, cache_dir: Path, *, cdn=None, bundle_key=None,
+             apk: Path | None = None) -> "Catalog":
+        """The remote catalog of `language` from the cache, downloaded from the CDN on first use (`cdn` /
+        `bundle_key`: as for Catalog)."""
+        cache_dir = Path(cache_dir)
+        cat = cls.cache_file(language, cache_dir)
+        if not cat.exists():
+            cdn = _setting(cdn, cat.name)
+            if not cdn:
+                raise FileNotFoundError(f"{cat} not cached and no CDN base given")
+            cat.parent.mkdir(parents=True, exist_ok=True)
+            _write_atomic(cat, download(cdn.rstrip("/") + f"/asset/Android/{cat.name}"))
+        return cls(cat.read_bytes(), cache_dir, cdn=cdn, bundle_key=bundle_key, apk=apk)
+
+    def _setting(self, name: str, needed_by: str):
+        """The `cdn` / `bundle_key` given to the catalog, its function called (once) now that `needed_by` needs it."""
+        v = self._settings[name] = _setting(self._settings[name], needed_by)
+        return v
+
+    @property
+    def cdn(self) -> str | None:
+        """The CDN base as given (None while it is given as a function not called yet)."""
+        v = self._settings["cdn"]
+        return None if callable(v) or not v else v.rstrip("/")
+
+    @staticmethod
+    def cache_file(language: str, cache_dir: Path) -> Path:
+        """Where the remote catalog of `language` is cached."""
+        return Path(cache_dir) / f"catalog_main_{language}.bin"
+
+    # --- lookup ------------------------------------------------------------
+    def keys(self, prefix: str = "") -> list[str]:
+        return sorted(k for k in self._by_key if k.startswith(prefix))
+
+    def has(self, key: str) -> bool:
+        return key in self._by_key
+
+    def entries_for(self, key: str) -> list[dict]:
+        return list(self._by_key.get(key, []))
+
+    def _entry(self, key: str) -> dict:
+        ents = self._by_key.get(key)
+        if not ents:
+            raise KeyError(key)
+        # Prefer the asset location (Assets/...) over a bundle alias.
+        for e in ents:
+            if e["internal_id"].startswith("Assets/") or e["internal_id"].startswith("Packages/"):
+                return e
+        return ents[0]
+
+    @staticmethod
+    def _as_bundle(e: dict) -> Bundle | None:
+        iid = e["internal_id"]
+        if iid.endswith(".bundle") and remote_path(iid) is not None:
+            return Bundle(e["offset"], iid, iid.rsplit("/", 1)[1], remote=True)
+        if iid.startswith(LOCAL_PREFIX) and iid.endswith(".bundle"):
+            return Bundle(e["offset"], iid, iid.rsplit("/", 1)[1], remote=False)
+        return None
+
+    def sources(self) -> dict[str, bytes]:
+        """The catalog files this catalog was made of: {"remote": bytes, "apk": bytes (with an APK)}."""
+        return dict(self._sources)
+
+    def locations(self) -> list[dict]:
+        """Every location of the remote catalog and (with an APK) of the APK catalog, fully decoded
+        (addressables.parse_locations), with `catalog` ("remote" / "apk") and `kind` (location_kind). Offsets and
+        dependencies are those of `entries` (APK ones in their own namespace)."""
+        if self._locations is None:
+            out = []
+            for name, base in (("remote", 0), ("apk", APK_OFFSET_BASE)):
+                if name not in self._sources:
+                    continue
+                for e in parse_locations(self._sources[name]):
+                    e["offset"] += base
+                    e["dependencies"] = [d + base for d in e["dependencies"]]
+                    e["catalog"] = name
+                    e["kind"] = location_kind(e["internal_id"])
+                    out.append(e)
+            self._locations = out
+        return [dict(e) for e in self._locations]
+
+    def bundles(self) -> list[Bundle]:
+        """Every bundle file the catalogs name (remote and APK-local), one per file name, sorted by name. A file the
+        APK catalog lists gets the APK catalog's location (the remote catalog's references to APK files may describe
+        another build), else its first location."""
+        out: dict[str, Bundle] = {}
+        for e in sorted(self.entries, key=lambda e: (e["offset"] < APK_OFFSET_BASE, e["offset"])):
+            b = self._as_bundle(e)
+            if b is not None:
+                out.setdefault(b.name, b)
+        return [out[n] for n in sorted(out)]
+
+    def raw_files(self) -> list[dict]:
+        """Every raw file the catalogs name (a CDN or APK file that is not a bundle, e.g. CRI ACB/AWB/USM data), one
+        entry per file name (file_name), sorted by name, preferring the APK catalog's as bundles() does. Remote ones
+        are what fetch_raw takes."""
+        out: dict[str, dict] = {}
+        for e in sorted(self.entries, key=lambda e: (e["offset"] < APK_OFFSET_BASE, e["offset"])):
+            if location_kind(e["internal_id"]) == "raw":
+                out.setdefault(file_name(e["internal_id"]), e)
+        return [out[n] for n in sorted(out)]
+
+    def resolve(self, key: str) -> list[Bundle]:
+        """Full bundle closure for an addressable key (BFS over dependencies)."""
+        seen: set[int] = set()
+        out: dict[int, Bundle] = {}
+        stack = [self._entry(key)["offset"]]
+        while stack:
+            off = stack.pop()
+            if off in seen:
+                continue
+            seen.add(off)
+            e = self._by_off.get(off)
+            if e is None:
+                continue
+            b = self._as_bundle(e)
+            if b is not None:
+                out.setdefault(b.offset, b)
+            for d in e["dependencies"]:
+                if d not in seen:
+                    stack.append(d)
+        return list(out.values())
+
+    # --- fetch -------------------------------------------------------------
+    def cached(self, b: Bundle) -> Path | None:
+        """The file fetch(b) returns when the bundle is in the cache already, else None."""
+        dst = self.cache_dir / "bundles" / b.name
+        return dst if dst.is_file() and dst.stat().st_size > 0 else None
+
+    def cached_raw(self, e: dict) -> Path | None:
+        """The file fetch_raw(e) returns when it is in the cache already, else None."""
+        rel = remote_path(e["internal_id"])
+        dst = self.cache_dir / "raw" / rel.lstrip("/") if rel is not None else None
+        return dst if dst is not None and dst.is_file() and dst.stat().st_size > 0 else None
+
+    def fetch(self, b: Bundle) -> Path:
+        """Local path to the decrypted bundle (CDN download or APK read)."""
+        dst = self.cache_dir / "bundles" / b.name
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        if dst.exists() and dst.stat().st_size > 0:
+            return dst
+        if b.remote:
+            url = self._url(b.internal_id)
+            key = self._setting("bundle_key", b.name)   # before the download: a missing key fails first
+            data = download(url)
+        else:
+            if self.apk is None:
+                raise apk_missing(f"bundle {b.name}")
+            rel = b.internal_id[len(LOCAL_PREFIX):].lstrip("/")
+            with zipfile.ZipFile(self.apk) as z:
+                data = z.read(APK_AA_DIR + rel)
+            key = self._setting("bundle_key", b.name) if data[:7] != b"UnityFS" else None
+        _write_atomic(dst, _unityfs(data, b.name, key))
+        return dst
+
+    def _url(self, internal_id: str) -> str:
+        name = internal_id.rsplit('/', 1)[-1]
+        cdn = self._setting("cdn", name)
+        if not cdn:
+            raise RuntimeError(f"{name} not cached and no CDN base given")
+        return cdn.rstrip("/") + remote_path(internal_id)
+
+    def fetch_key(self, key: str) -> list[Path]:
+        """Every bundle of the key's closure; APK-local ones only when an APK is set."""
+        return [self.fetch(b) for b in self.resolve(key) if b.remote or self.apk]
+
+    def fetch_raw(self, e: dict) -> Path:
+        """A non-bundle CDN asset (e.g. CRI ACB/AWB data) as stored -- no decryption."""
+        iid = e["internal_id"]
+        rel = remote_path(iid)
+        if rel is None:
+            raise ValueError(f"not a CDN asset: {iid}")
+        dst = self.cache_dir / "raw" / rel.lstrip("/")
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        if not (dst.exists() and dst.stat().st_size > 0):
+            _write_atomic(dst, download(self._url(iid)))
+        return dst
+
+    def apk_bundle(self, name_contains: str) -> Path:
+        """An APK-local addressable bundle whose file name contains the substring."""
+        if self.apk is None:
+            raise apk_missing("an APK bundle")
+        with zipfile.ZipFile(self.apk) as z:
+            names = [n for n in z.namelist()
+                     if n.startswith(APK_AA_DIR) and n.endswith(".bundle")
+                     and name_contains in n.rsplit("/", 1)[1]]
+            if len(names) != 1:
+                raise KeyError(f"{name_contains!r}: {len(names)} APK bundles match")
+            name = names[0].rsplit("/", 1)[1]
+            dst = self.cache_dir / "bundles" / name
+            if not (dst.exists() and dst.stat().st_size > 0):
+                dst.parent.mkdir(parents=True, exist_ok=True)
+                data = z.read(names[0])
+                key = self._setting("bundle_key", name) if data[:7] != b"UnityFS" else None
+                _write_atomic(dst, _unityfs(data, name, key))
+        return dst
+
+
+_KEPT = threading.local()                  # per thread: {(scheme, host): an open connection}
+_AGENT = "Python-urllib/%d.%d" % sys.version_info[:2]      # what urllib.request sends
+
+
+def download(url: str, timeout: float = 120) -> bytes:
+    """The body of `url`. HTTP(S) goes over one connection per thread and host, kept open between files (a new
+    connection per file costs more than a small bundle's transfer); a stale kept connection is replaced once. Other
+    schemes, a proxy from the environment, and any answer but a complete 200 (a redirect, an error) go through
+    urllib.request, as before, which follows or raises."""
+    parts = urllib.parse.urlsplit(url)
+    if parts.scheme not in ("http", "https") or _proxied(parts):
+        return _urlopen(url, timeout)
+    conns = _KEPT.__dict__.setdefault("conns", {})
+    key = (parts.scheme, parts.netloc)
+    path = (parts.path or "/") + (f"?{parts.query}" if parts.query else "")
+    for _ in range(2):
+        conn, kept = conns.pop(key, None), True
+        if conn is None:
+            kept = False
+            make = http.client.HTTPSConnection if parts.scheme == "https" else http.client.HTTPConnection
+            conn = make(parts.netloc, timeout=timeout)
+        try:
+            conn.request("GET", path, headers={"User-Agent": _AGENT})
+            r = conn.getresponse()
+            body = r.read()
+        except (http.client.HTTPException, OSError):
+            conn.close()
+            if kept:
+                continue                           # closed by the server while idle: once more, on a new one
+            break
+        if r.status != 200 or r.will_close:
+            conn.close()
+        else:
+            conns[key] = conn
+        if r.status == 200:
+            return body
+        break
+    return _urlopen(url, timeout)
+
+
+def _proxied(parts) -> bool:
+    proxies = urllib.request.getproxies()
+    return parts.scheme in proxies and not urllib.request.proxy_bypass(parts.hostname or "")
+
+
+def _urlopen(url: str, timeout: float) -> bytes:
+    with urllib.request.urlopen(url, timeout=timeout) as r:
+        return r.read()
+
+
+def _setting(v, needed_by: str):
+    """`v`, or what it returns when it is a function; its ConfigError names `needed_by` (what is not cached)."""
+    if not callable(v):
+        return v
+    try:
+        return v()
+    except ConfigError as e:
+        raise ConfigError(f"{needed_by} is not in the cache: {e}") from None