netprotocols 1.1.0__tar.gz → 1.2.0__tar.gz

{netprotocols-1.1.0 → netprotocols-1.2.0}/ARCHITECTURE.md

@@ -158,6 +158,26 @@ the graph acyclic: shared registries live in the dependency-free
 `_enums.py`, and `next_protocol()` mappings import their target
 classes *inside the function body*, at call time.
 
+## Port-based dispatch is best-effort
+
+The EtherType and IP-protocol registries dispatch on a single
+authoritative field. Application protocols break that model: they are
+identified by *port*, which is a heuristic — any service may run on any
+port, and the discriminator is split across the source and destination
+ports. `UDP.next_protocol()` therefore consults a well-known-port
+registry (`netprotocols.layer4._ports`), checking the destination port
+first (a request targets the server's port) and then the source port
+(a response comes from it). `DNS` is the first such protocol; a DNS
+message on UDP port 53 now decodes as a fourth layer.
+
+Because the guess can be wrong, the application class validates
+strictly on decode: a non-DNS datagram that happens to use port 53
+raises a `ProtocolError`, which the ordinary decode-error path absorbs
+(the chain keeps the layers it did decode and records the failure). So
+a mis-dispatch degrades to a diagnosed frame, never to garbage. Only
+UDP is wired this way for now — DNS over TCP carries a 2-byte length
+prefix (RFC 1035 §4.2.2) that needs separate handling.
+
 ## The encode side, and the round-trip guarantee
 
 Every class also works in reverse. Constructors take the friendly
@@ -174,10 +194,14 @@ Protocol.decode(bytes(header)) == header        # object → wire → object
 bytes(Protocol.decode(raw)) == raw[:header_len] # wire → object → wire
 ```
 
-One deliberate exception: **checksums are carried verbatim**. The
-library neither computes nor verifies them (yet — it's on the
-roadmap), which is exactly what you want when faithfully re-encoding
-captured traffic.
+One deliberate boundary: **decode and encode carry checksums
+verbatim** — exactly what you want when faithfully re-encoding
+captured traffic. Computing and verifying them is explicit, via
+`netprotocols.checksum`: `compute()`/`verify()` handle the IPv4 header
+checksum, ICMPv4, and TCP/UDP/ICMPv6 with their IPv4/IPv6
+pseudo-headers, and `Packet.with_checksums(payload)` fills a whole
+stack before sending. (The RFC 768 subtlety lives where it belongs:
+the `0x0000 → 0xFFFF` substitution applies to UDP alone.)
 
 `Packet` is the thin composition layer: it holds an ordered tuple of
 headers and `bytes(packet)` joins them, ready for a raw socket.
@@ -189,13 +213,24 @@ src/netprotocols/
 ├── __init__.py     public API re-exports, __version__
 ├── _base.py        Protocol ABC, decode contract, address helpers
 ├── _enums.py       EtherType, IPProtocol, ARPOperation (imports nothing)
-├── packet.py       Packet composition
+├── packet.py       Packet composition, with_checksums()
+├── checksum.py     RFC 1071: internet_checksum, compute, verify
 ├── layer2/         ethernet.py, arp.py
-├── layer3/         ip.py (IPv4 + IPv6), icmp.py (ICMPv4 + ICMPv6)
-├── layer4/         tcp.py, udp.py
+├── layer3/         ip.py (IPv4 + IPv6), icmp.py (ICMPv4 + ICMPv6),
+│                   igmp.py,
+│                   ipv6_ext.py (Hop-by-Hop, Routing, Fragment,
+│                   Destination Options)
+├── layer4/         tcp.py, udp.py, _ports.py (well-known-port registry)
+├── layer7/         dns.py
 └── utils/          validators (mac.py, ipv4.py), exceptions.py
 tests/              one file per protocol + test_contract.py
-                    (truncation, lying lengths, chain walks)
+                    (truncation, lying lengths, chain walks),
+                    test_corpus.py (invariants over the real-capture
+                    corpus in tests/fixtures/, 65 frames across 12
+                    scenarios — see its MANIFEST.md), test_checksum.py
+                    (corpus checksums recompute to wire values), and
+                    test_fuzz.py (hypothesis properties: decode never
+                    raises outside ProtocolError)
 ```
 
 Tooling: [uv](https://docs.astral.sh/uv/) manages the environment
@@ -217,12 +252,20 @@ the same:
    (raise `TruncatedHeaderError` when the buffer can't satisfy it) and
    materialize the variable part as `bytes`.
 3. **Implement `__bytes__()`.** Pack the same fields back; the
-   round-trip tests will hold you honest.
+   round-trip tests will hold you honest. When a payload is
+   self-referential — DNS names compress by pointing at earlier bytes,
+   so re-encoding a parsed record cannot reproduce the original — keep
+   that region as raw `bytes` and parse it through read-only accessors
+   that never re-encode. `bytes(decode(x)) == x` then holds by
+   construction (see `layer7/dns.py`).
 4. **Wire the chain.** The layer below decides when your class is
    next. For DNS that means UDP would implement `next_protocol()`
    consulting the ports. (For a new EtherType or IP protocol number,
-   add the value to `_enums.py` and one mapping entry in
-   `ethernet.py`/`ip.py`, using a deferred import.)
+   add the value to `_enums.py` — display name in lockstep, a test
+   enforces it — and one mapping entry in `ethernet.py`/`ip.py`, using
+   a deferred import. Numbers valid only inside an IPv6 chain follow
+   the extension headers' example: `_ip_protocol_class` hands them out
+   only when `ipv6=True`.)
 5. **Add display properties** for anything a human would want rendered
    (`flags_str`-style names, hex strings). Degrade gracefully on
    unknown values — return `"unknown (47)"`, never raise from a

{netprotocols-1.1.0 → netprotocols-1.2.0}/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2026-08-30
+
+### Added
+- **IGMP** (`netprotocols.IGMP`, RFC 1112/2236/3376) — IPv4 multicast
+  group management, dispatched from IPv4 protocol 2. The common
+  four-byte header (type, max-response code, checksum) is decoded; the
+  `group_address` accessor reads the group for the message types that
+  carry one, and `netprotocols.checksum` gains an IGMP arm. v3
+  group-record parsing is a roadmap follow-up.
+- **DNS** (`netprotocols.DNS`, RFC 1035) — the first application-layer
+  protocol. The 12-byte header and flag bits are decoded; the four
+  message sections are kept raw with on-demand, read-only accessors
+  (`question_name`, `question_type`, `question_class`) that decompress
+  names safely (bounded pointer-following; malformed or looping names
+  raise `InvalidFieldError`, never hang). Round-trip stays byte-exact.
+- **Port-based dispatch** on UDP: `UDP.next_protocol()` reaches an
+  application protocol by well-known port (`netprotocols.layer4._ports`,
+  `{53: DNS}` for now), checked destination-then-source. Documented as
+  best-effort — a mis-dispatch degrades to the malformed-frame path.
+
 ## [1.1.0] - 2026-08-29
 
 ### Added

{netprotocols-1.1.0 → netprotocols-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: netprotocols
-Version: 1.1.0
+Version: 1.2.0
 Summary: Low-level implementations of common networking protocols
 Project-URL: Homepage, https://github.com/EONRaider/NETProtocols
 Project-URL: Repository, https://github.com/EONRaider/NETProtocols
@@ -74,8 +74,10 @@ Requires Python 3.12+. Fully typed (`py.typed`, mypy strict).
 | 3 | IPv6 Destination Options | `IPv6DestinationOptions` | RFC 8200 §4.6 |
 | 3 | ICMPv4 | `ICMPv4` | RFC 792, 8-byte header |
 | 3 | ICMPv6 | `ICMPv6` | RFC 4443, 8-byte header |
+| 3 | IGMP | `IGMP` | RFC 1112/2236/3376, IPv4 multicast management |
 | 4 | TCP | `TCP` | RFC 9293, data-offset/options aware |
 | 4 | UDP | `UDP` | RFC 768 |
+| 7 | DNS | `DNS` | RFC 1035, over UDP; header + on-demand name decompression |
 
 ## Decoding a captured frame
 
@@ -150,18 +152,26 @@ byte layout maps onto a dataclass, the decode contract, the
 `next_protocol()` chain, and a cookbook for adding a new protocol.
 
 This library is the engine behind
-[Packet-Sniffer](https://github.com/EONRaider/Packet-Sniffer), a
-network traffic monitor built on it.
+[RootWire](https://github.com/EONRaider/RootWire), a network traffic
+monitor built on it (formerly Packet-Sniffer).
 
 ## Roadmap
 
-- 802.1Q VLAN tags, DNS, DHCP, IGMP, GRE.
+- More protocols: 802.1Q VLAN tags, DHCP, GRE (DNS and IGMP shipped in 1.2).
+- Full DNS resource-record parsing (the header and question are decoded today; answer/authority/additional sections are kept raw).
+- IGMPv3 group-record parsing (the common header is decoded today; v3 report records are kept raw in the body).
+- Optional richer address accessors (`ipaddress` / EUI objects
+  alongside the `str` fields).
+- TLV parsing inside IPv6 extension-header options.
 
 ## Contributing
 
 Development uses [uv](https://docs.astral.sh/uv/): `uv sync`, then
 `uv run pytest`, `uv run mypy`, and `uv run ruff check` — all three are
-enforced by CI on Python 3.12–3.14. Start with
+enforced by CI on Python 3.12–3.14. The test suite is anchored by a
+65-frame corpus of real captured traffic
+([tests/fixtures/MANIFEST.md](tests/fixtures/MANIFEST.md)) plus
+property-based fuzzing of the decode path. Start with
 [ARCHITECTURE.md](ARCHITECTURE.md).
 
 ## License

{netprotocols-1.1.0 → netprotocols-1.2.0}/README.md

@@ -49,8 +49,10 @@ Requires Python 3.12+. Fully typed (`py.typed`, mypy strict).
 | 3 | IPv6 Destination Options | `IPv6DestinationOptions` | RFC 8200 §4.6 |
 | 3 | ICMPv4 | `ICMPv4` | RFC 792, 8-byte header |
 | 3 | ICMPv6 | `ICMPv6` | RFC 4443, 8-byte header |
+| 3 | IGMP | `IGMP` | RFC 1112/2236/3376, IPv4 multicast management |
 | 4 | TCP | `TCP` | RFC 9293, data-offset/options aware |
 | 4 | UDP | `UDP` | RFC 768 |
+| 7 | DNS | `DNS` | RFC 1035, over UDP; header + on-demand name decompression |
 
 ## Decoding a captured frame
 
@@ -125,18 +127,26 @@ byte layout maps onto a dataclass, the decode contract, the
 `next_protocol()` chain, and a cookbook for adding a new protocol.
 
 This library is the engine behind
-[Packet-Sniffer](https://github.com/EONRaider/Packet-Sniffer), a
-network traffic monitor built on it.
+[RootWire](https://github.com/EONRaider/RootWire), a network traffic
+monitor built on it (formerly Packet-Sniffer).
 
 ## Roadmap
 
-- 802.1Q VLAN tags, DNS, DHCP, IGMP, GRE.
+- More protocols: 802.1Q VLAN tags, DHCP, GRE (DNS and IGMP shipped in 1.2).
+- Full DNS resource-record parsing (the header and question are decoded today; answer/authority/additional sections are kept raw).
+- IGMPv3 group-record parsing (the common header is decoded today; v3 report records are kept raw in the body).
+- Optional richer address accessors (`ipaddress` / EUI objects
+  alongside the `str` fields).
+- TLV parsing inside IPv6 extension-header options.
 
 ## Contributing
 
 Development uses [uv](https://docs.astral.sh/uv/): `uv sync`, then
 `uv run pytest`, `uv run mypy`, and `uv run ruff check` — all three are
-enforced by CI on Python 3.12–3.14. Start with
+enforced by CI on Python 3.12–3.14. The test suite is anchored by a
+65-frame corpus of real captured traffic
+([tests/fixtures/MANIFEST.md](tests/fixtures/MANIFEST.md)) plus
+property-based fuzzing of the decode path. Start with
 [ARCHITECTURE.md](ARCHITECTURE.md).
 
 ## License

{netprotocols-1.1.0 → netprotocols-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "netprotocols"
-version = "1.1.0"
+version = "1.2.0"
 description = "Low-level implementations of common networking protocols"
 readme = "README.md"
 license = "MIT"

netprotocols-1.2.0/scripts/capture_fixtures_igmp.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Capture an IGMP fixture for the corpus (plan item I-2).
+#
+#     sudo scripts/capture_fixtures_igmp.sh
+#
+# IGMP is IPv4 multicast group management — it never appeared in the
+# original corpus (which provoked IPv6 MLD, not IPv4 IGMP). Joining an
+# IPv4 multicast group makes the kernel emit a membership report
+# (IGMPv2 type 0x16 or IGMPv3 type 0x22, depending on the host's
+# configured version); a querier on the LAN may also produce a
+# membership query (type 0x11). This captures `ip proto 2` on the
+# default interface while joining a group, then validates.
+
+set -euo pipefail
+
+if [[ $EUID -ne 0 ]]; then
+    echo "This script needs root for tcpdump (or run it via sudo)." >&2
+    exit 1
+fi
+
+command -v tcpdump >/dev/null || { echo "tcpdump is required." >&2; exit 1; }
+
+OUT="tests/fixtures/staging"
+mkdir -p "$OUT"
+IFACE=$(ip route show default | awk '/default/ {print $5; exit}')
+[[ -n $IFACE ]] || { echo "No default interface found." >&2; exit 1; }
+echo "[*] Default interface: $IFACE"
+
+join_group() {
+    python3 - "$IFACE" <<'PY' || true
+import socket, struct, sys, time
+group = "239.255.42.99"  # an administratively-scoped group (RFC 2365)
+sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+mreq = socket.inet_aton(group) + socket.inet_aton("0.0.0.0")
+sock.setsockopt(socket.IPPROTO_IP, socket.IP_ADD_MEMBERSHIP, mreq)
+time.sleep(3)  # report is emitted on join; hold briefly
+sock.setsockopt(socket.IPPROTO_IP, socket.IP_DROP_MEMBERSHIP, mreq)
+sys.stderr.write(f"joined and left {group} on {sys.argv[1]}\n")
+PY
+}
+
+echo "[>] igmp (join 239.255.42.99 to provoke a membership report)"
+tcpdump -i "$IFACE" -c 4 -w "$OUT/igmp.pcap" --immediate-mode -q \
+    ip proto 2 >/dev/null 2>&1 &
+pid=$!
+sleep 1
+join_group
+for _ in $(seq 15); do kill -0 $pid 2>/dev/null || break; sleep 1; done
+kill $pid 2>/dev/null || true
+wait $pid 2>/dev/null || true
+
+echo
+echo "[*] Validating..."
+CHECKER_PY=$(command -v python3)
+if [[ -n ${SUDO_USER:-} ]]; then
+    chown -R "$SUDO_USER" "$OUT"
+    sudo -u "$SUDO_USER" "$CHECKER_PY" scripts/check_fixtures.py "$OUT"
+else
+    "$CHECKER_PY" scripts/check_fixtures.py "$OUT"
+fi
+
+echo
+echo "[i] If no frames were captured, your host may emit IGMPv3 only when"
+echo "    a querier is present, or multicast may be disabled on $IFACE."
+echo "    The igmp.pcap in staging (if non-empty and OK above) is ready to"
+echo "    fold into the corpus."

{netprotocols-1.1.0 → netprotocols-1.2.0}/scripts/check_fixtures.py

@@ -98,6 +98,14 @@ def check_frame(frame: bytes, stats: Counter) -> list[str]:
                 != struct.unpack_from("!H", upper, 2)[0]
             ):
                 failures.append("icmpv4-checksum")
+        elif proto == 2 and upper_len >= 8:
+            stats["igmp"] += 1
+            # IGMP: whole message, checksum at bytes 2-3, no pseudo-header.
+            if (
+                internet_checksum(upper[:2] + b"\x00\x00" + upper[4:])
+                != struct.unpack_from("!H", upper, 2)[0]
+            ):
+                failures.append("igmp-checksum")
         elif proto == 6 and upper_len >= 20:
             stats["tcp"] += 1
             zeroed = upper[:16] + b"\x00\x00" + upper[18:]

{netprotocols-1.1.0 → netprotocols-1.2.0}/src/netprotocols/__init__.py

@@ -16,6 +16,7 @@ from netprotocols.checksum import compute, internet_checksum, verify
 from netprotocols.layer2.arp import ARP
 from netprotocols.layer2.ethernet import Ethernet
 from netprotocols.layer3.icmp import ICMPv4, ICMPv6
+from netprotocols.layer3.igmp import IGMP
 from netprotocols.layer3.ip import IPv4, IPv6
 from netprotocols.layer3.ipv6_ext import (
     IPv6DestinationOptions,
@@ -25,6 +26,7 @@ from netprotocols.layer3.ipv6_ext import (
 )
 from netprotocols.layer4.tcp import TCP
 from netprotocols.layer4.udp import UDP
+from netprotocols.layer7.dns import DNS
 from netprotocols.packet import Packet
 from netprotocols.utils.exceptions import (
     InvalidFieldError,
@@ -37,10 +39,12 @@ from netprotocols.utils.exceptions import (
 from netprotocols.utils.ipv4 import validate_ipv4_addr
 from netprotocols.utils.mac import random_mac, validate_mac_addr
 
-__version__ = "1.1.0"
+__version__ = "1.2.0"
 
 __all__ = [
     "ARP",
+    "DNS",
+    "IGMP",
     "TCP",
     "UDP",
     "ARPHardwareType",

{netprotocols-1.1.0 → netprotocols-1.2.0}/src/netprotocols/checksum.py

@@ -24,6 +24,7 @@ from netprotocols._base import (
 )
 from netprotocols._enums import IPProtocol
 from netprotocols.layer3.icmp import ICMPv4, ICMPv6
+from netprotocols.layer3.igmp import IGMP
 from netprotocols.layer3.ip import IPv4, IPv6
 from netprotocols.layer4.tcp import TCP
 from netprotocols.layer4.udp import UDP
@@ -109,6 +110,10 @@ def compute(
         return internet_checksum(_zeroed(bytes(layer), 10))
     if isinstance(layer, ICMPv4):
         return internet_checksum(_zeroed(bytes(layer), 2) + payload)
+    if isinstance(layer, IGMP):
+        # Whole message, checksum field (bytes 2-3) zeroed, no
+        # pseudo-header; the body is already part of bytes(layer).
+        return internet_checksum(_zeroed(bytes(layer), 2))
     if isinstance(layer, ICMPv6):
         enclosing = _require_ip(layer, ip)
         segment = _zeroed(bytes(layer), 2) + payload

{netprotocols-1.1.0 → netprotocols-1.2.0}/src/netprotocols/layer3/__init__.py

@@ -1,4 +1,5 @@
 from netprotocols.layer3.icmp import ICMPv4, ICMPv6
+from netprotocols.layer3.igmp import IGMP
 from netprotocols.layer3.ip import IPv4, IPv6
 from netprotocols.layer3.ipv6_ext import (
     IPv6DestinationOptions,
@@ -8,6 +9,7 @@ from netprotocols.layer3.ipv6_ext import (
 )
 
 __all__ = [
+    "IGMP",
     "ICMPv4",
     "ICMPv6",
     "IPv4",

netprotocols-1.2.0/src/netprotocols/layer3/igmp.py

@@ -0,0 +1,95 @@
+"""IGMP header — IPv4 multicast group management (RFC 1112/2236/3376).
+
+IGMP rides directly on IPv4 (protocol 2) and never encapsulates another
+protocol. The message types do not share one fixed layout — a v3
+membership report replaces the group-address field with a record count
+— so only the common first four bytes (type, max-response code,
+checksum) are modelled as fields; the remainder is kept as raw
+``body``. The ``group_address`` accessor reads bytes 4-7 as an IPv4
+address for the message types that carry one there, and returns
+``None`` otherwise. Parsing the v3 group-record array is a roadmap
+follow-up.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from struct import Struct
+from typing import ClassVar, Self
+
+from netprotocols._base import Protocol, bytes_to_ipv4
+
+__all__ = ["IGMP"]
+
+#: Message types whose bytes 4-7 hold a group address (RFC 2236 §2;
+#: RFC 3376 §4.1 for the v3 query). The v3 report (0x22) does not.
+_GROUP_ADDRESS_TYPES = frozenset({0x11, 0x12, 0x16, 0x17})
+
+
+@dataclass(frozen=True, slots=True)
+class IGMP(Protocol):
+    """An IGMP message.
+
+    :param type: Message type — ``0x11`` query, ``0x12`` v1 report,
+        ``0x16`` v2 report, ``0x17`` leave group, ``0x22`` v3 report.
+    :param max_resp_code: Maximum response code (queries; 0 in reports).
+    :param checksum: Checksum over the whole IGMP message, carried
+        verbatim (compute/verify via :mod:`netprotocols.checksum`).
+    :param body: The message-type-specific remainder (group address, or
+        a v3 record count and group records), kept raw.
+    """
+
+    type: int
+    max_resp_code: int
+    checksum: int
+    body: bytes = b""
+
+    _struct: ClassVar[Struct] = Struct("!BBH")
+
+    type_names: ClassVar[dict[int, str]] = {
+        0x11: "Membership Query",
+        0x12: "IGMPv1 Membership Report",
+        0x16: "IGMPv2 Membership Report",
+        0x17: "Leave Group",
+        0x22: "IGMPv3 Membership Report",
+    }
+
+    @classmethod
+    def decode(cls, data: bytes | memoryview) -> Self:
+        type_, max_resp_code, checksum = cls._unpack_fixed(data)
+        return cls(
+            type=type_,
+            max_resp_code=max_resp_code,
+            checksum=checksum,
+            body=bytes(data[cls._struct.size :]),
+        )
+
+    def __bytes__(self) -> bytes:
+        return (
+            self._struct.pack(self.type, self.max_resp_code, self.checksum)
+            + self.body
+        )
+
+    @property
+    def header_len(self) -> int:
+        # IGMP is the whole IP payload: consume it all (terminal).
+        return self._struct.size + len(self.body)
+
+    @property
+    def type_name(self) -> str:
+        """Display name of the message type, e.g. ``"Membership Query"``."""
+        return self.type_names.get(self.type, f"unknown ({self.type:#04x})")
+
+    @property
+    def group_address(self) -> str | None:
+        """The multicast group in dotted-decimal, for the message types
+        that carry it in bytes 4-7 (query, v1/v2 report, leave); ``None``
+        for the v3 report, which uses that space for a record count."""
+        if self.type in _GROUP_ADDRESS_TYPES and len(self.body) >= 4:
+            return bytes_to_ipv4(self.body[:4])
+        return None
+
+    @property
+    def checksum_hex_str(self) -> str:
+        """The checksum as a hexadecimal string, e.g. ``"0x0b3a"``."""
+        return f"{self.checksum:#06x}"

{netprotocols-1.1.0 → netprotocols-1.2.0}/src/netprotocols/layer3/ip.py

@@ -47,6 +47,7 @@ def _ip_protocol_class(number: int, *, ipv6: bool) -> type[Protocol] | None:
     decode a Hop-by-Hop layer.
     """
     from netprotocols.layer3.icmp import ICMPv4, ICMPv6
+    from netprotocols.layer3.igmp import IGMP
     from netprotocols.layer3.ipv6_ext import (
         IPv6DestinationOptions,
         IPv6Fragment,
@@ -61,6 +62,7 @@ def _ip_protocol_class(number: int, *, ipv6: bool) -> type[Protocol] | None:
     mapping: dict[int, type[Protocol]] = {
         IPProtocol.HOPOPT: IPv6HopByHopOptions,
         IPProtocol.ICMP: ICMPv4,
+        IPProtocol.IGMP: IGMP,
         IPProtocol.IPV6_ROUTE: IPv6Routing,
         IPProtocol.IPV6_FRAG: IPv6Fragment,
         IPProtocol.IPV6_ICMP: ICMPv6,

netprotocols-1.2.0/src/netprotocols/layer4/_ports.py

@@ -0,0 +1,34 @@
+"""Port-based application-protocol dispatch for the transport layer.
+
+Unlike the EtherType and IP-protocol registries — where a single
+authoritative field names what follows — application protocols are
+identified by *port*, which is a heuristic: any service may run on any
+port, and the discriminator is split across two fields (source and
+destination). Dispatch therefore checks the destination port first (a
+request targets the server's well-known port) and then the source port
+(a response comes from it), and the resulting class is expected to
+validate strictly on decode so that a wrong guess degrades to the
+library's ordinary malformed-frame path rather than yielding garbage.
+
+Only UDP is wired this round. TCP application protocols (DNS over TCP
+carries a 2-byte length prefix, RFC 1035 §4.2.2) need their own
+handling and are left for later.
+"""
+
+from __future__ import annotations
+
+from netprotocols._base import Protocol
+
+__all__ = ["udp_app_class"]
+
+
+def udp_app_class(src_port: int, dst_port: int) -> type[Protocol] | None:
+    """The class that decodes a UDP payload, chosen by well-known port.
+
+    Returns ``None`` when neither port names a known application
+    protocol — the common case, where the chain ends at UDP.
+    """
+    from netprotocols.layer7.dns import DNS
+
+    registry: dict[int, type[Protocol]] = {53: DNS}
+    return registry.get(dst_port) or registry.get(src_port)

{netprotocols-1.1.0 → netprotocols-1.2.0}/src/netprotocols/layer4/udp.py

@@ -44,6 +44,15 @@ class UDP(Protocol):
             self.src_port, self.dst_port, self.length, self.checksum
         )
 
+    def next_protocol(self) -> type[Protocol] | None:
+        """The application protocol carried by this datagram, chosen by
+        well-known port (best-effort — see
+        :mod:`netprotocols.layer4._ports`); ``None`` when neither port
+        is recognized."""
+        from netprotocols.layer4._ports import udp_app_class
+
+        return udp_app_class(self.src_port, self.dst_port)
+
     @property
     def checksum_hex_str(self) -> str:
         """The checksum as a hexadecimal string, e.g. ``"0x1c2a"``."""

netprotocols-1.2.0/src/netprotocols/layer7/__init__.py

@@ -0,0 +1,3 @@
+from netprotocols.layer7.dns import DNS
+
+__all__ = ["DNS"]