feat(asn): IP→ASN enrichment via iptoasn.com bulk dump

Mirrors decnet/geoip/ end-to-end: paths/base/factory/lookup at the
package level, iptoasn/ subpackage holds the data-source-specific
fetch+parse+provider. AsnLookup is bisect-indexed over (start, end,
AsnInfo) ranges with a pickled cache invalidated on raw-file mtime
bump.

Why iptoasn (and not bgp.tools / Team Cymru): public-domain dump,
zero attribution, no UA mandate, daily refresh — keeps DECNET stealth
intact (the geoip/rir module's "never identify as DECNET" comment
applies the same way here). bgp.tools' ToS would have required an
identifying UA, conflicting with feedback_stealth.

Public surface: decnet.asn.enrich_ip(ip) -> (asn, name, source) or
all-None on miss/disabled. Same shape as decnet.geoip.enrich_ip so
the profiler can compose them in one call site.

tests/asn/conftest.py

@@ -0,0 +1,22 @@
+"""Per-package fixtures — sandbox the ASN provider into a tmp dir so no
+real /var/lib/decnet paths get touched and no real iptoasn URL gets
+fetched."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def _asn_sandbox(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    monkeypatch.setenv("DECNET_ASN_ENABLED", "true")
+    monkeypatch.setenv("DECNET_ASN_ROOT", str(tmp_path))
+    import decnet.asn as _a
+    import decnet.asn.factory as _f
+    import decnet.asn.paths as _p
+    monkeypatch.setattr(_p, "ASN_ROOT", tmp_path)
+    _a._lookup = None
+    _a._provider_name = None
+    _f.reset_cache()
+    return tmp_path

tests/asn/test_lookup.py

@@ -0,0 +1,74 @@
+"""AsnLookup index tests."""
+from __future__ import annotations
+
+import ipaddress
+from pathlib import Path
+
+from decnet.asn.lookup import AsnInfo, AsnLookup
+
+
+def _ip(s: str) -> int:
+    return int(ipaddress.IPv4Address(s))
+
+
+def _fixture_lookup() -> AsnLookup:
+    return AsnLookup.from_ranges([
+        (_ip("8.8.8.0"),    _ip("8.8.8.255"),     AsnInfo(15169, "GOOGLE")),
+        (_ip("1.0.0.0"),    _ip("1.0.0.255"),     AsnInfo(13335, "CLOUDFLARENET")),
+        (_ip("46.101.0.0"), _ip("46.101.255.255"), AsnInfo(14061, "DIGITALOCEAN")),
+    ])
+
+
+def test_asn_hits_known_ranges() -> None:
+    lookup = _fixture_lookup()
+    assert lookup.asn("8.8.8.8").asn == 15169
+    assert lookup.asn("1.0.0.5").name == "CLOUDFLARENET"
+    assert lookup.asn("46.101.10.20").asn == 14061
+
+
+def test_asn_misses_gap() -> None:
+    lookup = _fixture_lookup()
+    assert lookup.asn("9.0.0.0") is None
+
+
+def test_asn_private_returns_none() -> None:
+    lookup = _fixture_lookup()
+    for ip in ("10.0.0.1", "192.168.1.1", "172.16.0.1", "127.0.0.1", "0.0.0.0"):
+        assert lookup.asn(ip) is None, ip
+
+
+def test_asn_ipv6_returns_none() -> None:
+    lookup = _fixture_lookup()
+    assert lookup.asn("2001:db8::1") is None
+    assert lookup.asn("::1") is None
+
+
+def test_asn_invalid_returns_none() -> None:
+    lookup = _fixture_lookup()
+    assert lookup.asn("not-an-ip") is None
+    assert lookup.asn("") is None
+
+
+def test_lookup_roundtrips_through_pickle(tmp_path: Path) -> None:
+    lookup = _fixture_lookup()
+    cache = tmp_path / "idx.pkl"
+    lookup.save(cache)
+    loaded = AsnLookup.load(cache)
+    assert len(loaded) == len(lookup)
+    assert loaded.asn("8.8.8.8").asn == 15169
+    assert loaded.asn("8.8.8.8").name == "GOOGLE"
+
+
+def test_from_ranges_last_writer_wins_on_collision() -> None:
+    lookup = AsnLookup.from_ranges([
+        (_ip("1.0.0.0"), _ip("1.0.0.255"), AsnInfo(1, "first")),
+        (_ip("1.0.0.0"), _ip("1.0.0.255"), AsnInfo(2, "second")),
+    ])
+    assert lookup.asn("1.0.0.5").asn == 2
+
+
+def test_boundary_inclusive() -> None:
+    lookup = _fixture_lookup()
+    assert lookup.asn("8.8.8.0").asn == 15169
+    assert lookup.asn("8.8.8.255").asn == 15169
+    assert lookup.asn("8.8.9.0") is None

tests/asn/test_parse.py

@@ -0,0 +1,57 @@
+"""Parser tests for the iptoasn TSV dump."""
+from __future__ import annotations
+
+import gzip
+import ipaddress
+from pathlib import Path
+
+from decnet.asn.iptoasn.parse import parse_file
+
+
+_FIXTURE_TSV = (
+    "1.0.0.0\t1.0.0.255\t13335\tUS\tCLOUDFLARENET\n"
+    "8.8.8.0\t8.8.8.255\t15169\tUS\tGOOGLE\n"
+    # ASN 0 sentinel — must be skipped.
+    "100.64.0.0\t100.127.255.255\t0\tNone\tNot routed\n"
+    # Malformed addresses — skipped.
+    "garbage\tnonsense\t12345\tXX\twhatever\n"
+    # Reversed range (end < start) — skipped.
+    "10.0.0.10\t10.0.0.5\t99999\tXX\tBackwards\n"
+    # Valid row with empty description.
+    "46.101.0.0\t46.101.255.255\t14061\tDE\t\n"
+)
+
+
+def test_parse_plain_tsv(tmp_path: Path) -> None:
+    fixture = tmp_path / "ip2asn-v4.tsv"
+    fixture.write_text(_FIXTURE_TSV)
+    ranges = list(parse_file(fixture))
+    asns = {r[2].asn for r in ranges}
+    assert asns == {13335, 15169, 14061}
+
+
+def test_parse_gzipped(tmp_path: Path) -> None:
+    fixture = tmp_path / "ip2asn-v4.tsv.gz"
+    with gzip.open(fixture, "wt", encoding="utf-8") as fh:
+        fh.write(_FIXTURE_TSV)
+    ranges = list(parse_file(fixture))
+    asns = {r[2].asn for r in ranges}
+    assert 13335 in asns and 15169 in asns
+
+
+def test_parse_range_boundaries(tmp_path: Path) -> None:
+    fixture = tmp_path / "ip2asn-v4.tsv"
+    fixture.write_text(_FIXTURE_TSV)
+    ranges = [r for r in parse_file(fixture) if r[2].asn == 15169]
+    assert len(ranges) == 1
+    start, end, info = ranges[0]
+    assert start == int(ipaddress.IPv4Address("8.8.8.0"))
+    assert end == int(ipaddress.IPv4Address("8.8.8.255"))
+    assert info.name == "GOOGLE"
+
+
+def test_parse_empty_description_kept(tmp_path: Path) -> None:
+    fixture = tmp_path / "ip2asn-v4.tsv"
+    fixture.write_text(_FIXTURE_TSV)
+    ranges = [r for r in parse_file(fixture) if r[2].asn == 14061]
+    assert ranges[0][2].name == ""

tests/asn/test_provider.py

@@ -0,0 +1,95 @@
+"""IptoasnProvider + factory + public API tests."""
+from __future__ import annotations
+
+import gzip
+from pathlib import Path
+
+import pytest
+
+
+def _seed_fixture(root: Path, content: str = "8.8.8.0\t8.8.8.255\t15169\tUS\tGOOGLE\n") -> None:
+    target = root / "ip2asn-v4.tsv.gz"
+    with gzip.open(target, "wt", encoding="utf-8") as fh:
+        fh.write(content)
+
+
+def test_factory_returns_iptoasn_by_default() -> None:
+    from decnet.asn.factory import get_provider
+
+    provider = get_provider()
+    assert provider.name == "iptoasn"
+
+
+def test_factory_rejects_unknown_provider(monkeypatch: pytest.MonkeyPatch) -> None:
+    from decnet.asn import factory
+
+    monkeypatch.setenv("DECNET_ASN_PROVIDER", "nope")
+    factory.reset_cache()
+    with pytest.raises(ValueError):
+        factory.get_provider()
+
+
+def test_provider_build_lookup_empty_when_no_files(tmp_path: Path) -> None:
+    from decnet.asn.iptoasn.provider import IptoasnProvider
+
+    p = IptoasnProvider()
+    lookup = p.build_lookup()
+    assert len(lookup) == 0
+    assert lookup.asn("8.8.8.8") is None
+
+
+def test_provider_build_lookup_reads_present_file(tmp_path: Path) -> None:
+    from decnet.asn.iptoasn.provider import IptoasnProvider
+
+    _seed_fixture(tmp_path)
+    p = IptoasnProvider()
+    lookup = p.build_lookup()
+    info = lookup.asn("8.8.8.8")
+    assert info is not None
+    assert info.asn == 15169
+    assert info.name == "GOOGLE"
+
+
+def test_provider_uses_cache_when_fresh(tmp_path: Path) -> None:
+    from decnet.asn.iptoasn.provider import IptoasnProvider
+
+    _seed_fixture(tmp_path)
+    p = IptoasnProvider()
+    a = p.build_lookup()
+    assert (tmp_path / ".iptoasn_index.pkl").exists()
+
+    p2 = IptoasnProvider()
+    b = p2.build_lookup()
+    assert len(b) == len(a)
+
+
+def test_enrich_ip_short_circuits_when_disabled(monkeypatch: pytest.MonkeyPatch) -> None:
+    import decnet.asn as asn
+
+    monkeypatch.setenv("DECNET_ASN_ENABLED", "false")
+    assert asn.enrich_ip("8.8.8.8") == (None, None, None)
+
+
+def test_enrich_ip_returns_asn_and_source(tmp_path: Path) -> None:
+    from decnet.asn import enrich_ip
+
+    _seed_fixture(tmp_path)
+    asn, name, src = enrich_ip("8.8.8.8")
+    assert asn == 15169
+    assert name == "GOOGLE"
+    assert src == "iptoasn"
+
+
+def test_enrich_ip_private_returns_none(tmp_path: Path) -> None:
+    from decnet.asn import enrich_ip
+
+    _seed_fixture(tmp_path)
+    assert enrich_ip("192.168.1.1") == (None, None, None)
+
+
+def test_enrich_ip_unannounced_returns_none(tmp_path: Path) -> None:
+    from decnet.asn import enrich_ip
+
+    _seed_fixture(tmp_path)
+    # 9.0.0.0 isn't in our fixture range — no BGP announcement we know of.
+    assert enrich_ip("9.0.0.0") == (None, None, None)