dn42-ipdb 0.1.1__tar.gz

dn42_ipdb-0.1.1/.gitignore

@@ -0,0 +1,14 @@
+.cache/
+.tmp/
+node_modules/
+dist/
+target/
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+*.pyc
+python/build/
+python/dist/
+*.tgz

dn42_ipdb-0.1.1/LICENSE

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

dn42_ipdb-0.1.1/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.5
+Name: dn42-ipdb
+Version: 0.1.1
+Summary: Local GeoIP2-compatible DN42 intelligence and verified database updates
+Project-URL: Repository, https://github.com/bird-chinese-community/DN42-IPDB-SDK
+Project-URL: Issues, https://github.com/bird-chinese-community/DN42-IPDB-SDK/issues
+Author-email: BIRD Chinese Community <sdk.opensouce@birdcc.link>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: filelock<4,>=3.20
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: maxminddb<4,>=3.0
+Description-Content-Type: text/markdown
+
+# dn42-ipdb
+
+```sh
+pip install dn42-ipdb
+```
+
+```python
+import asyncio
+from dn42_ipdb import download_release, lookup, lookup_asn, open_cached_bundle
+
+
+async def main():
+    await download_release(".cache/dn42")
+    with open_cached_bundle(".cache/dn42") as database:
+        print(lookup(database, "172.23.33.0"))
+        print(lookup_asn(database, 4242420803))
+
+
+asyncio.run(main())
+```
+
+`open_cached_bundle(cache_dir)` opens the verified current bundle without
+network activity. `metadata(bundle)` returns MMDB metadata and
+`release_metadata(bundle)` returns the release JSON metadata. A match contains
+`prefix_length` and `data`. Unknown IP networks are absent from `records`;
+unknown ASNs return `None`.
+
+`download_release` accepts a `base_url` HTTPS mirror and a `timeout` in seconds.
+Loopback HTTP is accepted for tests. The default timeout is 30 seconds and
+task cancellation stops pending downloads. Each database or JSON sidecar is
+limited to 32 MiB; the checksum manifest to 64 KiB. The Python cache lives
+under `cache_dir/python`.
+
+The SDK reads verified bytes with MaxMind's pure Python `MODE_FD` reader.
+The official `geoip2` typed reader also supports the bundle. Use its memory
+mode on Windows with `maxminddb` 3.2.0:
+
+```python
+from geoip2.database import Reader
+from maxminddb import MODE_MEMORY
+
+with Reader("asn.mmdb", mode=MODE_MEMORY) as database:
+    print(database.asn("172.23.33.0").autonomous_system_number)
+```
+
+The 3.2.0 Windows C extension can decode DN42's unsigned ASN values as
+negative numbers. The [upstream correction](https://github.com/maxmind/MaxMind-DB-Reader-python/commit/51791b8b5d970f92dc7c5fa645bde2c7bd15475d)
+is on its development branch. SDK CI validates all four official GeoIP2 typed
+methods in memory mode on every platform, and its default mode on Linux and
+macOS.
+
+Copyright 2026 BIRD Chinese Community. MIT license.

dn42_ipdb-0.1.1/README.md

@@ -0,0 +1,52 @@
+# dn42-ipdb
+
+```sh
+pip install dn42-ipdb
+```
+
+```python
+import asyncio
+from dn42_ipdb import download_release, lookup, lookup_asn, open_cached_bundle
+
+
+async def main():
+    await download_release(".cache/dn42")
+    with open_cached_bundle(".cache/dn42") as database:
+        print(lookup(database, "172.23.33.0"))
+        print(lookup_asn(database, 4242420803))
+
+
+asyncio.run(main())
+```
+
+`open_cached_bundle(cache_dir)` opens the verified current bundle without
+network activity. `metadata(bundle)` returns MMDB metadata and
+`release_metadata(bundle)` returns the release JSON metadata. A match contains
+`prefix_length` and `data`. Unknown IP networks are absent from `records`;
+unknown ASNs return `None`.
+
+`download_release` accepts a `base_url` HTTPS mirror and a `timeout` in seconds.
+Loopback HTTP is accepted for tests. The default timeout is 30 seconds and
+task cancellation stops pending downloads. Each database or JSON sidecar is
+limited to 32 MiB; the checksum manifest to 64 KiB. The Python cache lives
+under `cache_dir/python`.
+
+The SDK reads verified bytes with MaxMind's pure Python `MODE_FD` reader.
+The official `geoip2` typed reader also supports the bundle. Use its memory
+mode on Windows with `maxminddb` 3.2.0:
+
+```python
+from geoip2.database import Reader
+from maxminddb import MODE_MEMORY
+
+with Reader("asn.mmdb", mode=MODE_MEMORY) as database:
+    print(database.asn("172.23.33.0").autonomous_system_number)
+```
+
+The 3.2.0 Windows C extension can decode DN42's unsigned ASN values as
+negative numbers. The [upstream correction](https://github.com/maxmind/MaxMind-DB-Reader-python/commit/51791b8b5d970f92dc7c5fa645bde2c7bd15475d)
+is on its development branch. SDK CI validates all four official GeoIP2 typed
+methods in memory mode on every platform, and its default mode on Linux and
+macOS.
+
+Copyright 2026 BIRD Chinese Community. MIT license.

dn42_ipdb-0.1.1/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dn42-ipdb"
+version = "0.1.1"
+description = "Local GeoIP2-compatible DN42 intelligence and verified database updates"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{ name = "BIRD Chinese Community", email = "sdk.opensouce@birdcc.link" }]
+dependencies = ["maxminddb>=3.0,<4", "httpx>=0.28,<1", "filelock>=3.20,<4"]
+
+[project.urls]
+Repository = "https://github.com/bird-chinese-community/DN42-IPDB-SDK"
+Issues = "https://github.com/bird-chinese-community/DN42-IPDB-SDK/issues"
+
+[dependency-groups]
+dev = [
+  "pytest>=8.4",
+  "ruff>=0.14",
+  "mypy>=1.18",
+  "aiohttp>=3.12",
+  "geoip2>=5.1",
+  "semver>=3.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dn42_ipdb"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/LICENSE", "/README.md", "/pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py314"
+line-length = 88
+
+[tool.mypy]
+python_version = "3.14"
+strict = true

dn42_ipdb-0.1.1/src/dn42_ipdb/__init__.py

@@ -0,0 +1,325 @@
+import asyncio
+import hashlib
+import ipaddress
+import json
+import os
+import re
+import shutil
+import tempfile
+from collections.abc import Iterator
+from contextlib import ExitStack, contextmanager
+from importlib.metadata import version
+from io import BytesIO
+from pathlib import Path
+from secrets import token_hex
+from urllib.parse import urljoin, urlsplit
+
+import httpx
+import maxminddb
+from filelock import AsyncFileLock, FileLock
+
+__version__ = version("dn42-ipdb")
+DEFAULT_RELEASE_URL = "https://github.com/bird-chinese-community/DN42-IPDB-Releases/releases/latest/download/"
+MAX_DATABASE_BYTES = 32 * 1024 * 1024
+MAX_MANIFEST_BYTES = 64 * 1024
+ARTIFACT_TYPES = {
+    "country": ("country.mmdb", "DN42-GeoIP2-Country", "DN42-Country"),
+    "city": ("city.mmdb", "DN42-GeoIP2-City", "DN42-City"),
+    "asn": ("asn.mmdb", "DN42-GeoLite2-ASN", "DN42-ASN"),
+    "connection_type": (
+        "connection-type.mmdb",
+        "DN42-GeoIP2-Connection-Type",
+        "DN42-Connection-Type",
+    ),
+}
+ARTIFACT_FILES = [item[0] for item in ARTIFACT_TYPES.values()] + [
+    "asn-index.json",
+    "metadata.json",
+    "LICENSE-Unicode.txt",
+]
+type Record = dict[str, object]
+type Bundle = tuple[dict[str, maxminddb.Reader], dict[str, Record], Record]
+
+
+def _read_bounded(path: Path, limit: int) -> bytes:
+    with path.open("rb") as stream:
+        if not path.is_file() or os.fstat(stream.fileno()).st_size > limit:
+            raise ValueError(f"Invalid cache file size: {path}")
+        data = stream.read(limit + 1)
+        if len(data) > limit:
+            raise ValueError(f"Cache file exceeds size limit: {path}")
+        return data
+
+
+@contextmanager
+def open_bundle(directory: str | Path) -> Iterator[Bundle]:
+    """Load an immutable in-memory release for local lookups."""
+    path = Path(directory)
+    index = json.loads(_read_bounded(path / "asn-index.json", MAX_DATABASE_BYTES))
+    release = json.loads(_read_bounded(path / "metadata.json", MAX_DATABASE_BYTES))
+    if (
+        not isinstance(index, dict)
+        or index.get("schema_version") != "2"
+        or not isinstance(index.get("asns"), dict)
+    ):
+        raise ValueError("Invalid ASN index schema")
+    if (
+        not isinstance(release, dict)
+        or not release.get("release_repository")
+        or not release.get("copyright")
+    ):
+        raise ValueError("Invalid release metadata")
+    readers = {}
+    try:
+        for key, (filename, kind, legacy) in ARTIFACT_TYPES.items():
+            data = _read_bounded(path / filename, MAX_DATABASE_BYTES)
+            reader = maxminddb.open_database(BytesIO(data), mode=maxminddb.MODE_FD)
+            readers[key] = reader
+            if reader.metadata().database_type not in {kind, legacy}:
+                raise ValueError(f"{filename}: expected {kind} database")
+        yield readers, index["asns"], release
+    finally:
+        for reader in readers.values():
+            reader.close()
+
+
+def lookup(bundle: Bundle, address: str) -> Record:
+    """Return raw GeoIP2-compatible records, preserving the dn42 extension."""
+    if "%" in address:
+        raise ValueError(f"Invalid IP address: {address}")
+    ip = ipaddress.ip_address(address)
+    records = {}
+    for key, reader in bundle[0].items():
+        record, prefix_length = reader.get_with_prefix_len(str(ip))
+        if record:
+            records[key] = {"prefix_length": prefix_length, "data": record}
+    return {"ip": str(ip), "records": records}
+
+
+def lookup_asn(bundle: Bundle, asn: int) -> Record | None:
+    """Return member-prefix observations without classifying the entire AS."""
+    if isinstance(asn, bool) or not isinstance(asn, int) or not 0 <= asn <= 4294967295:
+        raise ValueError(f"Invalid ASN: {asn}")
+    return bundle[1].get(str(asn))
+
+
+def metadata(bundle: Bundle) -> dict[str, Record]:
+    output = {}
+    for key, reader in bundle[0].items():
+        value = reader.metadata()
+        output[key] = {
+            "database_type": value.database_type,
+            "description": value.description,
+            "build_epoch": value.build_epoch,
+            "languages": value.languages,
+            "ip_version": value.ip_version,
+        }
+    return output
+
+
+def release_metadata(bundle: Bundle) -> Record:
+    return bundle[2]
+
+
+def _verify(directory: Path, checksums: dict[str, str]) -> None:
+    for filename in ARTIFACT_FILES:
+        data = _read_bounded(directory / filename, MAX_DATABASE_BYTES)
+        if hashlib.sha256(data).hexdigest() != checksums[filename]:
+            raise ValueError(f"Checksum mismatch: {filename}")
+    with open_bundle(directory):
+        pass
+
+
+def _read_pointer(cache: Path) -> tuple[str, dict[str, str]] | None:
+    data = _read_bounded(cache / "current.json", MAX_MANIFEST_BYTES)
+    try:
+        pointer = json.loads(data)
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(pointer, dict):
+        return None
+    current = pointer.get("version")
+    checksums = pointer.get("checksums")
+    if (
+        not isinstance(current, str)
+        or re.fullmatch(r"[0-9a-f]{64}", current) is None
+        or not isinstance(checksums, dict)
+    ):
+        return None
+    for filename in ARTIFACT_FILES:
+        digest = checksums.get(filename)
+        if not isinstance(digest, str) or re.fullmatch(r"[0-9a-f]{64}", digest) is None:
+            return None
+    return current, checksums
+
+
+@contextmanager
+def open_cached_bundle(cache_dir: str | Path) -> Iterator[Bundle]:
+    """Read the verified current cache without network activity."""
+    cache = Path(cache_dir) / "python"
+    with ExitStack() as stack:
+        with FileLock(cache / ".update.lock", timeout=0):
+            pointer = _read_pointer(cache)
+            if pointer is None:
+                raise ValueError(f"Invalid cache pointer: {cache / 'current.json'}")
+            current, checksums = pointer
+            directory = cache / current
+            _verify(directory, checksums)
+            bundle = stack.enter_context(open_bundle(directory))
+        yield bundle
+
+
+async def _download(
+    client: httpx.AsyncClient, address: str, limit: int, base: str
+) -> bytes:
+    initial = urlsplit(base)
+    current = address
+    for redirects in range(11):
+        target = urlsplit(current)
+        if (
+            target.username
+            or target.password
+            or (
+                target.scheme != "https"
+                and not (
+                    initial.scheme == "http"
+                    and target.netloc == initial.netloc
+                    and target.scheme == "http"
+                )
+            )
+        ):
+            raise ValueError("Insecure release redirect")
+        async with client.stream("GET", current, follow_redirects=False) as response:
+            if response.is_redirect:
+                location = response.headers.get("location")
+                if not location or redirects == 10:
+                    raise ValueError("Invalid release redirect")
+                current = urljoin(current, location)
+                continue
+            response.raise_for_status()
+            length = response.headers.get("content-length")
+            if length is not None and int(length) > limit:
+                raise ValueError(f"Download {address}: size limit exceeded")
+            chunks = []
+            size = 0
+            async for chunk in response.aiter_bytes():
+                size += len(chunk)
+                if size > limit:
+                    raise ValueError(f"Download {address}: size limit exceeded")
+                chunks.append(chunk)
+            return b"".join(chunks)
+    raise ValueError("Invalid release redirect")
+
+
+async def download_release(
+    cache_dir: str | Path,
+    *,
+    base_url: str = DEFAULT_RELEASE_URL,
+    timeout: float = 30,
+) -> Record:
+    """Verify seven files before activating a bundle in cache_dir/python."""
+    if not cache_dir:
+        raise ValueError("cache_dir is required")
+    base = urlsplit(base_url)
+    loopback = base.scheme == "http" and base.hostname in {"127.0.0.1", "::1"}
+    if (
+        not base.hostname
+        or base.username
+        or base.password
+        or (base.scheme != "https" and not loopback)
+    ):
+        raise ValueError("Release URL requires HTTPS or loopback HTTP")
+    if not base_url.endswith("/"):
+        base_url += "/"
+    cache = Path(cache_dir) / "python"
+    cache.mkdir(parents=True, exist_ok=True, mode=0o700)
+    async with (
+        asyncio.timeout(timeout),
+        AsyncFileLock(cache / ".update.lock", timeout=timeout),
+        httpx.AsyncClient(
+            timeout=timeout,
+            follow_redirects=False,
+            headers={"user-agent": f"DN42-IPDB-SDK-Python/{__version__}"},
+        ) as client,
+    ):
+        checksums = json.loads(
+            await _download(
+                client,
+                urljoin(base_url, "checksums.json"),
+                MAX_MANIFEST_BYTES,
+                base_url,
+            )
+        )
+        if not isinstance(checksums, dict):
+            raise TypeError("Invalid checksum manifest")
+        for filename in ARTIFACT_FILES:
+            digest = checksums.get(filename)
+            if (
+                not isinstance(digest, str)
+                or re.fullmatch(r"[0-9a-f]{64}", digest) is None
+            ):
+                raise ValueError(f"Invalid checksum for {filename}")
+        previous = None
+        recovered_cache = False
+        current = cache / "current.json"
+        if current.exists():
+            pointer = _read_pointer(cache)
+            if pointer is None:
+                recovered_cache = True
+            else:
+                previous, old_checksums = pointer
+                directory = cache / previous
+                if all(
+                    old_checksums[name] == checksums[name] for name in ARTIFACT_FILES
+                ):
+                    _verify(directory, checksums)
+                    return {"directory": str(directory), "changed": False}
+        stage = Path(tempfile.mkdtemp(prefix=".stage-", dir=cache))
+        try:
+            for filename in ARTIFACT_FILES:
+                data = await _download(
+                    client, urljoin(base_url, filename), MAX_DATABASE_BYTES, base_url
+                )
+                if hashlib.sha256(data).hexdigest() != checksums[filename]:
+                    raise ValueError(f"Checksum mismatch: {filename}")
+                (stage / filename).write_bytes(data)
+            _verify(stage, checksums)
+            current_version = token_hex(32)
+            destination = cache / current_version
+            pending = cache / f".current-{current_version}"
+            committed = False
+            try:
+                pending.write_text(
+                    json.dumps({"version": current_version, "checksums": checksums}),
+                    encoding="utf-8",
+                )
+                for entry in cache.iterdir():
+                    if (
+                        entry.is_symlink()
+                        or not entry.is_dir()
+                        or re.fullmatch(r"[0-9a-f]{64}", entry.name) is None
+                        or entry.name in {current_version, previous}
+                    ):
+                        continue
+                    files = list(entry.iterdir())
+                    if len(files) == len(ARTIFACT_FILES) and all(
+                        not file.is_symlink()
+                        and file.is_file()
+                        and file.name in ARTIFACT_FILES
+                        for file in files
+                    ):
+                        shutil.rmtree(entry)
+                os.replace(stage, destination)
+                os.replace(pending, current)
+                committed = True
+                result: Record = {"directory": str(destination), "changed": True}
+                if recovered_cache:
+                    result["recovered_cache"] = True
+                return result
+            finally:
+                if not committed and destination.exists():
+                    shutil.rmtree(destination)
+                pending.unlink(missing_ok=True)
+        finally:
+            if stage.exists():
+                shutil.rmtree(stage)

dn42_ipdb-0.1.1/tests/data/LICENSE-Unicode.txt

@@ -0,0 +1,41 @@
+UNICODE LICENSE V3
+
+COPYRIGHT AND PERMISSION NOTICE
+
+Copyright © 2015-2024 Unicode, Inc.
+
+NOTICE TO USER: Carefully read the following legal agreement. BY
+DOWNLOADING, INSTALLING, COPYING OR OTHERWISE USING DATA FILES, AND/OR
+SOFTWARE, YOU UNEQUIVOCALLY ACCEPT, AND AGREE TO BE BOUND BY, ALL OF THE
+TERMS AND CONDITIONS OF THIS AGREEMENT. IF YOU DO NOT AGREE, DO NOT
+DOWNLOAD, INSTALL, COPY, DISTRIBUTE OR USE THE DATA FILES OR SOFTWARE.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of data files and any associated documentation (the "Data Files") or
+software and any associated documentation (the "Software") to deal in the
+Data Files or Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, and/or sell
+copies of the Data Files or Software, and to permit persons to whom the
+Data Files or Software are furnished to do so, provided that either (a)
+this copyright and permission notice appear with all copies of the Data
+Files or Software, or (b) this copyright and permission notice appear in
+associated Documentation.
+
+THE DATA FILES AND SOFTWARE ARE 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 OF
+THIRD PARTY RIGHTS.
+
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE
+BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES,
+OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE DATA
+FILES OR SOFTWARE.
+
+Except as contained in this notice, the name of a copyright holder shall
+not be used in advertising or otherwise to promote the sale, use or other
+dealings in these Data Files or Software without prior written
+authorization of the copyright holder.
+
+SPDX-License-Identifier: Unicode-3.0

dn42_ipdb-0.1.1/tests/data/asn-index.json

@@ -0,0 +1,132 @@
+{
+  "asns": {
+    "4242420001": {
+      "asn": 4242420001,
+      "as_name": "TestNetwork",
+      "registered_countries": [
+        {
+          "iso_code": "DE",
+          "names": {
+            "en": "Germany"
+          }
+        }
+      ],
+      "prefixes": [
+        "172.20.0.0/24",
+        "172.20.0.1/32",
+        "fd42:1234::/48",
+        "fd42:1234::1/128"
+      ],
+      "observed_network_types": [
+        "anycast",
+        "public-resolver"
+      ],
+      "observations": [
+        {
+          "target": "172.20.0.1",
+          "asn": 4242420001,
+          "kind": "irr",
+          "status": "exact",
+          "method": "registry-route-object",
+          "source": "data/route/test",
+          "authority": "registry-object",
+          "observed_at": "2023-11-14T22:13:20Z"
+        },
+        {
+          "target": "172.20.0.1",
+          "kind": "network_type",
+          "value": "public-resolver",
+          "status": "observed",
+          "method": "dns-query",
+          "source": "dns://172.20.0.1:53",
+          "authority": "dns-response",
+          "observed_at": "2023-11-14T22:13:20Z"
+        },
+        {
+          "target": "172.20.0.1",
+          "kind": "network_type",
+          "value": "anycast",
+          "status": "published",
+          "method": "published-service",
+          "source": "https://example.org/dns",
+          "authority": "service-documentation",
+          "observed_at": "2023-11-14T22:13:20Z"
+        },
+        {
+          "target": "172.20.0.1",
+          "kind": "ptr",
+          "value": "resolver.test.dn42.",
+          "status": "observed",
+          "method": "dns-ptr",
+          "source": "dns://172.20.0.1:53",
+          "authority": "dns-response",
+          "observed_at": "2023-11-14T22:13:20Z"
+        },
+        {
+          "target": "172.20.0.1",
+          "asn": 4242420001,
+          "kind": "roa",
+          "status": "valid",
+          "method": "dn42-registry-derived-roa",
+          "source": "https://example.org/roa.json",
+          "authority": "registry-derived",
+          "observed_at": "2023-11-14T22:13:20Z"
+        },
+        {
+          "target": "fd42:1234::1",
+          "asn": 4242420001,
+          "kind": "irr",
+          "status": "exact",
+          "method": "registry-route-object",
+          "source": "data/route/test",
+          "authority": "registry-object",
+          "observed_at": "2023-11-14T22:13:20Z"
+        },
+        {
+          "target": "fd42:1234::1",
+          "kind": "network_type",
+          "value": "public-resolver",
+          "status": "observed",
+          "method": "dns-query",
+          "source": "dns://172.20.0.1:53",
+          "authority": "dns-response",
+          "observed_at": "2023-11-14T22:13:20Z"
+        },
+        {
+          "target": "fd42:1234::1",
+          "kind": "network_type",
+          "value": "anycast",
+          "status": "published",
+          "method": "published-service",
+          "source": "https://example.org/dns",
+          "authority": "service-documentation",
+          "observed_at": "2023-11-14T22:13:20Z"
+        },
+        {
+          "target": "fd42:1234::1",
+          "kind": "ptr",
+          "value": "resolver.test.dn42.",
+          "status": "observed",
+          "method": "dns-ptr",
+          "source": "dns://172.20.0.1:53",
+          "authority": "dns-response",
+          "observed_at": "2023-11-14T22:13:20Z"
+        },
+        {
+          "target": "fd42:1234::1",
+          "asn": 4242420001,
+          "kind": "roa",
+          "status": "valid",
+          "method": "dn42-registry-derived-roa",
+          "source": "https://example.org/roa.json",
+          "authority": "registry-derived",
+          "observed_at": "2023-11-14T22:13:20Z"
+        }
+      ]
+    }
+  },
+  "built_at": "2023-11-14T22:13:20Z",
+  "copyright": "Copyright 2026 BIRD Chinese Community (database compilation). Source data retains its respective ownership and licenses.",
+  "release_repository": "https://github.com/bird-chinese-community/DN42-IPDB-Releases",
+  "schema_version": "2"
+}

dn42_ipdb-0.1.1/tests/data/metadata.json

@@ -0,0 +1,36 @@
+{
+  "attributions": [
+    {
+      "license": "Unicode-3.0",
+      "license_file": "LICENSE-Unicode.txt",
+      "name": "Unicode CLDR English names",
+      "source": "https://github.com/unicode-org/cldr-json/tree/7d2b9cb11cec08f4d333ad73209deb3df0711c3b"
+    }
+  ],
+  "built_at": "2023-11-14T22:13:20Z",
+  "copyright": "Copyright 2026 BIRD Chinese Community (database compilation). Source data retains its respective ownership and licenses.",
+  "database_types": {
+    "asn.mmdb": "DN42-GeoLite2-ASN",
+    "city.mmdb": "DN42-GeoIP2-City",
+    "connection-type.mmdb": "DN42-GeoIP2-Connection-Type",
+    "country.mmdb": "DN42-GeoIP2-Country"
+  },
+  "generator": "DN42-IPDB",
+  "ip_version": 6,
+  "languages": [
+    "en"
+  ],
+  "publisher": "BIRD Chinese Community",
+  "registry_commit": "",
+  "registry_committed_at": "0001-01-01T00:00:00Z",
+  "release_repository": "https://github.com/bird-chinese-community/DN42-IPDB-Releases",
+  "schema_version": "2",
+  "semantics": {
+    "connection_type": "Explicit access classification only; absent when unknown. Overlay tunnels do not identify subscriber access technology.",
+    "location": "Operator-authorized GeoFeed claim; registry registration country is separate.",
+    "network_types": "Published service roles or observed BGP path characteristics; method and source describe the evidence.",
+    "ptr": "Reverse DNS observations apply only to their queried host address.",
+    "roa_status": "Registry-derived DN42 origin policy; method and origin ASN are attached to each observation. No cryptographic RPKI validation is implied."
+  },
+  "source_documents": []
+}

dn42_ipdb-0.1.1/tests/hold_lock.py

@@ -0,0 +1,8 @@
+import sys
+from pathlib import Path
+
+from filelock import FileLock
+
+with FileLock(Path(sys.argv[1]) / ".update.lock"):
+    print("locked", flush=True)
+    sys.stdin.read(1)

dn42_ipdb-0.1.1/tests/test_geoip2.py

@@ -0,0 +1,32 @@
+import sys
+from pathlib import Path
+
+import pytest
+from geoip2.database import Reader
+from maxminddb import MODE_AUTO, MODE_MEMORY
+
+FIXTURES = Path(__file__).with_name("data")
+
+
+@pytest.mark.parametrize(
+    "mode", [MODE_MEMORY] if sys.platform == "win32" else [MODE_MEMORY, MODE_AUTO]
+)
+def test_official_geoip2_readers(mode):
+    for address in ["172.20.0.1", "fd42:1234::1"]:
+        with Reader(FIXTURES / "country.mmdb", mode=mode) as database:
+            country = database.country(address)
+            assert country.country.iso_code == "US"
+            assert country.country.name == "United States"
+            assert country.registered_country.iso_code == "DE"
+            assert country.registered_country.name == "Germany"
+        with Reader(FIXTURES / "city.mmdb", mode=mode) as database:
+            city = database.city(address)
+            assert city.city.name == "Test City"
+            assert city.subdivisions.most_specific.name == "California"
+        with Reader(FIXTURES / "asn.mmdb", mode=mode) as database:
+            asn = database.asn(address)
+            assert asn.autonomous_system_number == 4242420001
+            assert asn.autonomous_system_organization == "TestNetwork"
+        with Reader(FIXTURES / "connection-type.mmdb", mode=mode) as database:
+            connection = database.connection_type(address)
+            assert connection.network is not None

dn42_ipdb-0.1.1/tests/test_ipdb.py

@@ -0,0 +1,254 @@
+import asyncio
+import hashlib
+import json
+import subprocess
+import sys
+import threading
+from contextlib import contextmanager
+from pathlib import Path
+
+import httpx
+import pytest
+from aiohttp import web
+from dn42_ipdb import (
+    ARTIFACT_FILES,
+    download_release,
+    lookup,
+    lookup_asn,
+    metadata,
+    open_bundle,
+    open_cached_bundle,
+    release_metadata,
+)
+from filelock import Timeout
+
+FIXTURES = Path(__file__).with_name("data")
+
+
+@contextmanager
+def fixture_server():
+    files = {name: (FIXTURES / name).read_bytes() for name in ARTIFACT_FILES}
+    state = {
+        "files": files,
+        "requests": [],
+        "failure": "",
+        "stall": False,
+        "bad_manifest": False,
+        "bad_checksum": False,
+        "redirect": "",
+    }
+    loop = asyncio.new_event_loop()
+
+    async def handle(request):
+        name = request.match_info["name"]
+        state["requests"].append(name)
+        if state["redirect"]:
+            raise web.HTTPFound(state["redirect"])
+        if name == state["failure"]:
+            return web.Response(status=503)
+        if name == "checksums.json":
+            checksums = (
+                {}
+                if state["bad_manifest"]
+                else {
+                    name: hashlib.sha256(data).hexdigest()
+                    for name, data in files.items()
+                }
+            )
+            if state["bad_checksum"]:
+                checksums["city.mmdb"] = "0" * 64
+            return web.json_response(checksums)
+        if state["stall"] and name == "city.mmdb":
+            await asyncio.sleep(10)
+        data = files.get(name)
+        return web.Response(body=data) if data is not None else web.Response(status=404)
+
+    async def start():
+        app = web.Application()
+        app.router.add_get("/{name}", handle)
+        runner = web.AppRunner(app, shutdown_timeout=0.1)
+        await runner.setup()
+        site = web.TCPSite(runner, "127.0.0.1", 0)
+        await site.start()
+        return runner
+
+    thread = threading.Thread(target=loop.run_forever, daemon=True)
+    thread.start()
+    runner = asyncio.run_coroutine_threadsafe(start(), loop).result(5)
+    address = runner.addresses[0]
+    try:
+        yield f"http://127.0.0.1:{address[1]}/", state
+    finally:
+        asyncio.run_coroutine_threadsafe(runner.cleanup(), loop).result(5)
+        loop.call_soon_threadsafe(loop.stop)
+        thread.join(5)
+        loop.close()
+
+
+def test_local_lookup():
+    with open_bundle(FIXTURES) as database:
+        for address in ["172.20.0.1", "fd42:1234::1"]:
+            result = lookup(database, address)
+            assert (
+                result["records"]["asn"]["data"]["autonomous_system_number"]
+                == 4242420001
+            )
+            assert (
+                result["records"]["city"]["data"]["country"]["names"]["en"]
+                == "United States"
+            )
+            assert result["records"]["city"]["data"]["dn42"]["schema_version"] == "2"
+        assert lookup_asn(database, 4242420001)["asn"] == 4242420001
+        assert lookup_asn(database, 4242420999) is None
+        assert lookup(database, "203.0.113.1")["records"] == {}
+        with pytest.raises(ValueError):
+            lookup(database, "bad-ip")
+        with pytest.raises(ValueError):
+            lookup_asn(database, -1)
+        assert len(metadata(database)) == 4
+        assert "DN42-IPDB-Releases" in release_metadata(database)["release_repository"]
+
+
+def test_download_reuse_and_local_cache(tmp_path):
+    with fixture_server() as (url, state):
+        first = asyncio.run(download_release(tmp_path, base_url=url))
+        assert first["changed"] is True
+        assert len(state["requests"]) == 8
+        second = asyncio.run(download_release(tmp_path, base_url=url))
+        assert second == {"directory": first["directory"], "changed": False}
+        assert len(state["requests"]) == 9
+        with open_cached_bundle(tmp_path) as database:
+            assert lookup_asn(database, 4242420001)["asn"] == 4242420001
+            lookup(database, "172.20.0.1")
+        assert len(state["requests"]) == 9
+
+
+def test_reject_insecure_redirect_before_request(tmp_path):
+    with fixture_server() as (url, state), fixture_server() as (target, target_state):
+        state["redirect"] = f"{target}checksums.json"
+        with pytest.raises(ValueError, match="Insecure release redirect"):
+            asyncio.run(download_release(tmp_path, base_url=url))
+        assert len(state["requests"]) == 1
+        assert target_state["requests"] == []
+
+
+def test_update_failures_preserve_pointer(tmp_path):
+    with fixture_server() as (url, state):
+        asyncio.run(download_release(tmp_path, base_url=url))
+        pointer = tmp_path / "python/current.json"
+        original = pointer.read_bytes()
+        state["files"]["metadata.json"] = json.dumps(
+            {
+                "schema_version": "2",
+                "release_repository": "test",
+                "copyright": "BIRDCC",
+                "revision": 1,
+            }
+        ).encode()
+        state["failure"] = "asn.mmdb"
+        with pytest.raises(httpx.HTTPStatusError, match="503"):
+            asyncio.run(download_release(tmp_path, base_url=url))
+        assert pointer.read_bytes() == original
+        state["failure"] = ""
+        state["files"]["city.mmdb"] = state["files"]["asn.mmdb"]
+        with pytest.raises(ValueError, match="expected.*City"):
+            asyncio.run(download_release(tmp_path, base_url=url))
+        assert pointer.read_bytes() == original
+        state["bad_checksum"] = True
+        with pytest.raises(ValueError, match="Checksum mismatch"):
+            asyncio.run(download_release(tmp_path, base_url=url))
+        assert pointer.read_bytes() == original
+        state["bad_manifest"] = True
+        with pytest.raises(ValueError, match="Invalid checksum"):
+            asyncio.run(download_release(tmp_path, base_url=url))
+        assert pointer.read_bytes() == original
+        with open_cached_bundle(tmp_path) as database:
+            assert lookup_asn(database, 4242420001)["asn"] == 4242420001
+
+
+def test_cancel_before_publication(tmp_path):
+    with fixture_server() as (url, state):
+        state["stall"] = True
+
+        async def run():
+            task = asyncio.create_task(download_release(tmp_path, base_url=url))
+            await asyncio.sleep(0.1)
+            task.cancel()
+            with pytest.raises(asyncio.CancelledError):
+                await task
+
+        asyncio.run(run())
+        assert not (tmp_path / "python/current.json").exists()
+
+
+def test_retention_with_loaded_reader(tmp_path):
+    with fixture_server() as (url, state):
+        first = asyncio.run(download_release(tmp_path, base_url=url))
+        custom = tmp_path / "python" / ("f" * 64)
+        custom.mkdir()
+        (custom / "user.txt").write_text("keep")
+        with open_cached_bundle(tmp_path) as database:
+            for revision in [1, 2, 3]:
+                state["files"]["metadata.json"] = json.dumps(
+                    {
+                        "schema_version": "2",
+                        "release_repository": "test",
+                        "copyright": "BIRDCC",
+                        "revision": revision,
+                    }
+                ).encode()
+                asyncio.run(download_release(tmp_path, base_url=url))
+            assert not Path(first["directory"]).exists()
+            assert (
+                lookup(database, "172.20.0.1")["records"]["city"]["data"]["dn42"][
+                    "schema_version"
+                ]
+                == "2"
+            )
+            assert lookup_asn(database, 4242420001)["asn"] == 4242420001
+        assert (custom / "user.txt").read_text() == "keep"
+        assert (
+            len(
+                [
+                    entry
+                    for entry in (tmp_path / "python").iterdir()
+                    if len(entry.name) == 64
+                ]
+            )
+            == 3
+        )
+
+
+def test_cross_process_lock(tmp_path):
+    with fixture_server() as (url, _):
+        asyncio.run(download_release(tmp_path, base_url=url))
+        child = subprocess.Popen(
+            [
+                sys.executable,
+                str(Path(__file__).with_name("hold_lock.py")),
+                str(tmp_path / "python"),
+            ],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            text=True,
+        )
+        try:
+            assert child.stdout.readline() == "locked\n"
+            with pytest.raises(Timeout), open_cached_bundle(tmp_path):
+                pass
+            with pytest.raises(TimeoutError):
+                asyncio.run(download_release(tmp_path, base_url=url, timeout=0.1))
+        finally:
+            child.communicate("x", timeout=5)
+        assert child.returncode == 0
+
+
+def test_recover_malformed_pointer(tmp_path):
+    with fixture_server() as (url, _):
+        asyncio.run(download_release(tmp_path, base_url=url))
+        (tmp_path / "python/current.json").write_text("{")
+        result = asyncio.run(download_release(tmp_path, base_url=url))
+        assert result["changed"] is True
+        assert result["recovered_cache"] is True
+        with open_cached_bundle(tmp_path) as database:
+            assert lookup_asn(database, 4242420001)["asn"] == 4242420001