netprotocols 2.0.0__tar.gz → 2.2.0__tar.gz

{netprotocols-2.0.0 → netprotocols-2.2.0}/.github/workflows/ci.yml

@@ -50,6 +50,29 @@ jobs:
       - run: uv build
       - run: uv run --isolated --no-project --with dist/*.whl python -c "import netprotocols; print(netprotocols.__version__)"
 
+  # Proves the README's browser/WASM claim (#99) against the real
+  # thing, not a simulation of it: boots an actual Pyodide runtime
+  # (scripts/pyodide/run_in_pyodide.mjs, via Node — no browser needed,
+  # same WebAssembly build either way) and decodes the whole
+  # real-capture corpus with the wheel this job just built. See
+  # scripts/pyodide/check_in_pyodide.py for what it checks and why.
+  pyodide:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv build
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - run: npm ci
+        working-directory: scripts/pyodide
+      - run: >-
+          node scripts/pyodide/run_in_pyodide.mjs
+          "$GITHUB_WORKSPACE" scripts/pyodide/check_in_pyodide.py
+
   # Blocking, at 15% below the committed baseline. The threshold has
   # runner data behind it: this job's first run measured 3.7% away from
   # a baseline recorded on entirely different hardware, and run-to-run

netprotocols-2.2.0/.github/workflows/fuzz.yml

@@ -0,0 +1,64 @@
+name: Nightly fuzz
+
+# Separate from ci.yml on purpose: ci.yml is reused via workflow_call
+# by release.yml specifically so the release gate and the PR gate never
+# drift apart (see the comment at the top of ci.yml). Folding a
+# schedule trigger into it would fire that whole ladder on a cron too,
+# not just this exploratory job.
+on:
+  schedule:
+    # Arbitrary; 03:00 UTC lands after most contributors' working day
+    # across common timezones, clear of any push/PR traffic.
+    - cron: "0 3 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  # tests/test_fuzz.py's own "netprotocols" profile is deliberately
+  # derandomize=True at 200 examples, so CI has run the *same* 200
+  # inputs on every push since it was written. This job runs the whole
+  # suite under the "nightly" profile instead (10,000 examples, a real
+  # random seed each time — see tests/test_fuzz.py's module docstring),
+  # so it explores new ground every run rather than replaying the same
+  # counterexample search forever. Pinned to Python 3.12 only, unlike
+  # the "test" job's full matrix: this is an exploratory job, not a
+  # compatibility gate, and 3x the interpreters would 3x its cost for
+  # no extra coverage of what it is actually looking for.
+  fuzz:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      # Keyed by run id with a prefix restore-key: a fixed key would
+      # restore forever but (actions/cache never overwrites an existing
+      # key) never actually save a new one, so nothing would
+      # accumulate. This restores the most recent run's cache and saves
+      # today's as a new entry, so Hypothesis's example database grows
+      # night over night instead of starting cold every time.
+      - name: Restore accumulated Hypothesis examples
+        uses: actions/cache@v4
+        with:
+          path: .hypothesis
+          key: hypothesis-nightly-${{ github.run_id }}
+          restore-keys: |
+            hypothesis-nightly-
+      - name: Run the full suite under the nightly fuzz profile
+        env:
+          HYPOTHESIS_PROFILE: nightly
+        run: uv run --frozen pytest
+      # A failed scheduled run already notifies repo watchers by
+      # default (GitHub's standard behavior) — that red run *is* the
+      # report; nothing here files an issue on top of it. This just
+      # makes the minimal counterexample recoverable without needing
+      # repo write access to re-run the job locally.
+      - name: Upload the failing example database
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: hypothesis-nightly-failure-${{ github.run_id }}
+          path: .hypothesis
+          retention-days: 30

{netprotocols-2.0.0 → netprotocols-2.2.0}/.gitignore

@@ -150,3 +150,8 @@ amass.log
 
 # Written by the benchmark CI step (scripts/benchmark.py output)
 benchmark.out
+
+# npm dependency (the pyodide package itself) for scripts/pyodide/ —
+# CI installs it fresh from package-lock.json, same as any other
+# lockfile-pinned dependency.
+scripts/pyodide/node_modules/

{netprotocols-2.0.0 → netprotocols-2.2.0}/ARCHITECTURE.md

@@ -81,8 +81,20 @@ match ip:
    declaration order — `Ethernet.__match_args__ ==
    ('dst', 'src', 'ethertype')` — so a *positional* class pattern
    (`case Ethernet(dst, src, ethertype)`) works with no extra code. An
-   ordinary class has to declare `__match_args__` by hand to get that;
-   this library never does.
+   ordinary class has to declare `__match_args__` by hand to get that.
+   Most headers here never do either — but a few of the widest ones
+   are a deliberate exception: `IPv4`, `TCP` and `DHCP` run to 14, 11
+   and 15 fields respectively, so their full auto-generated tuple is
+   unusable positionally (nobody writes, or gets right, a
+   fourteen-slot pattern). Those three hand-declare a short
+   `__match_args__` instead — `IPv4.__match_args__ ==
+   ('src', 'dst', 'protocol')` — the two or three fields someone
+   drafting a positional pattern actually reaches for. The override is
+   documented at each class and pinned by
+   `tests/test_pattern_matching.py`, so it cannot drift the way an
+   *accidental* override would; keyword patterns
+   (`case IPv4(protocol=6)`) are unaffected by any of this and stay
+   the documented default (#94).
 2. **Every field with a fixed vocabulary of wire values is an
    `IntEnum`**, defined in [`_enums.py`](src/netprotocols/_enums.py),
    and `IntEnum` subclasses `int`. A *value* pattern therefore matches
@@ -107,11 +119,16 @@ there.)
 **Keeping this working is a contributor obligation, not a given.**
 Field declaration order is part of a class's public API — reordering
 fields changes what a positional pattern binds to, silently, for
-anyone matching by position. And a field carrying a closed set of wire
-values should stay an `IntEnum` sourced from `_enums.py` rather than
-degrade to a bare `int`; the moment it does, `case Header(field=SomeEnum.X)`
-stops matching and fails silently (the pattern falls through to the
-next `case`, it does not raise) rather than loudly.
+anyone matching by position. (The curated three are the exception:
+`IPv4`/`TCP`/`DHCP`'s hand-declared `__match_args__` is independent of
+field order, so reordering *their* fields cannot break positional
+matching — but adding or renaming one of the fields the curated tuple
+names does need the tuple, and the test pinning it, updated by hand.)
+And a field carrying a closed set of wire values should stay an
+`IntEnum` sourced from `_enums.py` rather than degrade to a bare
+`int`; the moment it does, `case Header(field=SomeEnum.X)` stops
+matching and fails silently (the pattern falls through to the next
+`case`, it does not raise) rather than loudly.
 
 ## The decode contract
 
@@ -387,6 +404,8 @@ src/netprotocols/
 ├── packet.py       Packet composition, with_checksums(), flow_key()
 ├── checksum.py     RFC 1071: internet_checksum, compute, verify
 ├── flow.py         FlowKey, flow_key(): canonical bidirectional keys
+├── pcap.py         read_captures()/read_pcap()/read_pcapng(): classic
+│                   pcap and pcapng readers, from bytes not filenames
 ├── layer2/         ethernet.py, arp.py, vlan.py (802.1Q / 802.1ad)
 ├── layer3/         ip.py (IPv4 + IPv6), icmp.py (ICMPv4 + ICMPv6),
 │                   igmp.py, gre.py,

{netprotocols-2.0.0 → netprotocols-2.2.0}/CHANGELOG.md

@@ -5,6 +5,214 @@ 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).
 
+## [2.2.0] - 2026-09-04
+
+### Added
+- **Typed accessors for every enum-backed field.** `_enums.py` defines
+  `EtherType`, `IPProtocol`, `ARPOperation` and `ARPHardwareType`, but
+  until now no decoded field exposed them — only the `*_name` display
+  strings, and the enums themselves were used only for dispatch. Every
+  field with a fixed wire vocabulary now has an `*_enum` companion
+  alongside the existing `int` field and its `*_name` string, mirroring
+  the `src`/`src_address` precedent 1.3.0 established for IP addresses:
+  `Ethernet.ethertype_enum`, `VLAN.ethertype_enum`, `GRE.protocol_enum`,
+  `IPv4.protocol_enum`, `IPv6.next_header_enum` (and the three IPv6
+  extension headers that share the field: `IPv6HopByHopOptions`,
+  `IPv6DestinationOptions`, `IPv6Routing`, `IPv6Fragment`),
+  `ARP.oper_enum`, `ARP.ptype_enum`, `ARP.htype_name`/`ARP.htype_enum`
+  (new — `ARPHardwareType` was exported but referenced nowhere), and
+  `DHCP.htype_name`/`DHCP.htype_enum`. Each returns `None` — never
+  raises — for a wire value this library does not enumerate, so
+  `bytes(decode(x)) == x` is unaffected for unrecognized values; the
+  raw `int` field stays canonical and round-trips regardless (#95).
+- **IPv4, TCP and DHCP curate a short `__match_args__` by hand.** Their
+  full auto-generated positional form runs to 11-15 fields — unusable
+  positionally, since nobody writes, or gets right, a fourteen-slot
+  pattern. `IPv4.__match_args__ == ('src', 'dst', 'protocol')`,
+  `TCP.__match_args__ == ('src_port', 'dst_port', 'flags')`,
+  `DHCP.__match_args__ == ('op', 'chaddr', 'yiaddr')` — the two or
+  three fields someone drafting `case IPv4(...)` actually reaches for.
+  Every other header (including the still-wide `IPv6`, at 8 fields)
+  keeps the plain auto-generated tuple, and keyword patterns
+  (`case IPv4(protocol=6)`) are unaffected either way and stay the
+  documented default. `__match_args__` is part of the public API once
+  documented, so the chosen order is pinned by
+  `tests/test_pattern_matching.py` rather than left free to drift.
+  ARCHITECTURE.md and `docs/CLAIMS.md` are updated to describe this as
+  a deliberate, tested exception rather than the "this library never
+  hand-declares `__match_args__`" absolute they stated before (#94).
+- **DNS resource records expose typed RDATA, and every question, not
+  just the first.** `DNSResourceRecord.rdata_text` decoded A/AAAA/MX/
+  SOA/etc. into a display string only; a new `rdata_value` field adds
+  the typed decoding alongside it (`rdata_text` is unchanged) —
+  `ipaddress.IPv4Address`/`IPv6Address` for A/AAAA, the decompressed
+  target `str` for NS/CNAME/PTR, a new `MXRecord(preference, exchange)`
+  for MX, a new `SOARecord(mname, rname, serial, refresh, retry,
+  expire, minimum)` for SOA, `list[str]` of character-strings for TXT,
+  and `None` — never raises — for the types this library does not
+  decode. Computed eagerly at parse time, like `rdata_text` always has
+  been: a name inside RDATA (a CNAME's target, for instance) can use
+  DNS compression against the *whole* message, so decoding it needs
+  the same message-wide context `rdata_text` already required, which a
+  property computed lazily from `rdata` alone could not resolve.
+  Separately, `DNS.questions` adds a `tuple[DNSQuestion, ...]` walking
+  every entry of the question section — `question_name`/`question_type`
+  /`question_class` exposed only the first and are unchanged (#96).
+- **A typed `DHCPOption`, alongside `DHCP.option_map`.** `option_map`
+  was the only accessor in the library returning a bare
+  `dict[int, bytes]` rather than typed objects; it is unchanged (still
+  returns exactly what it always did). A new `parsed_options` property
+  wraps the same, already RFC-3396-concatenated, mapping into a
+  `tuple[DHCPOption, ...]`, mirroring `TCPOption`/`IPv4Option`: `code`,
+  `data`, `code_name`, and a decoded `.value` for the option codes this
+  library understands — a single `ipaddress.IPv4Address` for Subnet
+  Mask (1)/Requested IP Address (50)/Server Identifier (54), a tuple of
+  one or more for Router (3)/Domain Name Server (6) (RFC 2132 permits
+  repeating either), the integer seconds for IP Address Lease Time
+  (51), the raw byte for Message Type (53). `None` — never raises —
+  for codes this library does not decode and malformed option data
+  (#96).
+- **`IPv4Option.value` decodes Record Route, Timestamp and Router
+  Alert.** `IPv4Option` had `kind_name` and no `.value` — the three
+  common kinds (RFC 791 §3.1, RFC 2113) were named but their contents
+  left raw, unlike `TCPOption`, which already decodes its values.
+  Record Route (7) decodes to a `tuple[ipaddress.IPv4Address, ...]` of
+  the addresses recorded so far — the option's own pointer byte says
+  how many of the address slots are actually filled, not the option's
+  total length. Timestamp (68) decodes to `tuple[int, ...]` of plain
+  millisecond timestamps when its flag selects that shape, or
+  `tuple[tuple[ipaddress.IPv4Address, int], ...]` of (address,
+  timestamp) pairs when the flag says each entry carries one — the
+  overflow counter and pointer are not decoded, read `data` raw for
+  those. Router Alert (148) decodes to the 2-byte value as `int`.
+  `None` — never raises — for every other kind and for malformed data
+  on one of these three (a bad pointer, an unrecognized Timestamp
+  flag, a short buffer) (#96).
+- **`IPv6Routing.segments` and `IPv6Option.value` for Router Alert /
+  Jumbo Payload.** `IPv6Routing.data` was entirely unparsed — no
+  segment-list extraction for any routing type. RH0 (`routing_type`
+  ``0``, deprecated by RFC 5095 but still seen — RFC 2460 §4.4) and
+  Mobile IPv6 (``2``, RFC 6275 §6.4) both store a 4-byte reserved field
+  followed by one IPv6 address per segment; `segments` decodes that
+  into a `tuple[ipaddress.IPv6Address, ...]`. RPL Source Routing (``3``,
+  RFC 6554) is deliberately **not** decoded: RFC 6554 §3 elides a
+  shared prefix from each intermediate address relative to the
+  enclosing packet's *destination* address, context this
+  one-extension-header accessor does not have — `data` stays available
+  raw. `None` for every other routing type and for malformed address
+  data. Separately, `IPv6Option.value` (Hop-by-Hop / Destination
+  Options TLVs) now decodes Router Alert (5, RFC 2711 §2.1) and Jumbo
+  Payload (194, RFC 2675 §2) into typed `int`s, the last of #96's four
+  pieces (`IPv6Option` "likewise decode[d] no values"); `None` for
+  every other type and malformed data, same contract throughout this
+  tier (#96).
+- **CI proves the library runs under a real Pyodide (WebAssembly)
+  runtime**, not just that the modules `scapy`/`dpkt` need are
+  individually blocked. A new `pyodide` job (`.github/workflows/ci.yml`)
+  boots actual Pyodide under Node via `scripts/pyodide/run_in_pyodide.mjs`,
+  installs the wheel this job just built, and decodes the entire
+  real-capture fixture corpus with it — see
+  `scripts/pyodide/check_in_pyodide.py`. That surfaced a genuine bug
+  along the way: `IPv6.decode()`/`bytes(IPv6(...))` used
+  `socket.inet_ntop`/`inet_pton(AF_INET6, ...)`, and Pyodide's CPython
+  build has `AF_INET6` sockets disabled, so every IPv6 frame failed to
+  decode there. `_base.py`'s `ipv6_to_bytes`/`bytes_to_ipv6` are now a
+  pure-Python implementation (`ipaddress` for parsing; a hand-rolled
+  RFC 5952 canonicalizer, differentially verified against glibc's
+  `inet_ntop` across 500,000+ random addresses plus both of its
+  dotted-quad special cases, for formatting — `str(ipaddress.IPv6Address)`
+  was tried first and rejected: it disagrees with glibc on IPv4-mapped
+  addresses, and disagrees with *itself* between Python 3.11 and 3.12).
+  IPv4 addressing is unaffected; behavior for every existing platform
+  is unchanged, exception type included (#99).
+- **Nightly fuzzing with a moving seed.** `tests/test_fuzz.py`'s
+  `"netprotocols"` Hypothesis profile is deterministic on purpose (200
+  examples, `derandomize=True`) so a pull request is reproducible — but
+  that also means every build since it was written has run the *same*
+  200 inputs. A new `"nightly"` profile (10,000 examples, a real random
+  seed each run) runs the whole suite on a new schedule,
+  `.github/workflows/fuzz.yml` (03:00 UTC daily, plus manual dispatch),
+  kept out of `ci.yml` deliberately — `ci.yml` is reused by
+  `release.yml` via `workflow_call`, and a `schedule:` trigger there
+  would fire the whole PR/release gate on a cron, not just this
+  exploratory job. `.hypothesis/`'s example database accumulates
+  across nightly runs via `actions/cache` (keyed by run id with a
+  prefix restore-key, since a fixed key would restore forever but
+  never actually save a new entry) and uploads as a workflow artifact
+  on failure, so a counterexample is recoverable without repo write
+  access; a failed scheduled run's own red build is the notification
+  (GitHub already does this by default), so nothing here files an
+  issue on top of it. Reproduce locally:
+  `HYPOTHESIS_PROFILE=nightly uv run pytest`. Also adds a targeted
+  strategy building well-formed TCP SYN options (MSS, window scale,
+  SACK-Permitted, SACK, timestamps) — the real-capture corpus never
+  caught a SYN, so unlike NOP/Timestamps these otherwise depend on
+  `max_examples` alone stumbling into a well-formed TLV by chance
+  (#98).
+- **A pcap/pcapng reader that takes bytes, not filenames.** New
+  `netprotocols.pcap`: `read_captures(buffer)` auto-detects classic
+  pcap vs. pcapng from its magic number and yields `CapturedFrame`
+  (`timestamp` in nanoseconds since the Unix epoch, normalized from
+  whatever resolution the source recorded, `data` the frame's raw
+  bytes); `read_pcap()`/`read_pcapng()` are the same for a caller who
+  already knows the format. pcapng support covers exactly the block
+  types frames can come from — Section Header, Interface Description
+  (read only for its `if_tsresol` option), Enhanced Packet, and Simple
+  Packet (which the format gives no timestamp at all, hence `0`);
+  every other block type is skipped wholesale. A malformed or
+  truncated capture raises the new `MalformedCaptureError`
+  (`ProtocolError` family, no `lax` mode — a corrupt *container* is a
+  different failure shape than a malformed header inside one already-
+  extracted frame). Format detection is eager; producing frames is
+  lazy (a generator), so a bad record downstream doesn't invalidate
+  what already iterated cleanly, and a huge capture is never forced
+  into a list of frames nobody asked for.
+
+  `tests/conftest.py` drops the private classic-pcap reader every test
+  file reached for — `pcap_frames()` is now a thin adapter over the
+  shipped `read_pcap()`, and `~10` test files were migrated onto it (a
+  real migration, not a rename: `tests/test_pcap.py` keeps its own
+  independent reference reader, deliberately never importing the
+  module it is cross-checking, the same "standalone, so a shared bug
+  can't cancel itself out" precedent as `scripts/benchmark.py` and
+  `scripts/check_fixtures.py`).
+
+  One design idea was tried and reverted on measurement: slicing each
+  frame lazily out of a `memoryview` over the whole buffer, to keep
+  large captures zero-copy. Measured across synthetic captures up to
+  ~140MB, it was 0.91x-0.98x — never faster, sometimes slower — because
+  a real capture is many *small* frames, and a `memoryview` slice's own
+  overhead is paid per frame; #88's identical finding for a single
+  frame generalizes rather than being contradicted. `docs/CLAIMS.md`
+  5.8 is corrected accordingly — it previously forward-referenced this
+  issue with an unverified "1.8x" figure (#100).
+
+### Documentation
+- **The comparative-claims embargo is lifted (#107, #124).** `docs/CLAIMS.md`
+  1.7 gained a per-project table auditing ten comparable Python packet
+  libraries' CI configurations (dpkt, scapy, pypacker, construct,
+  pcapkit, dnspython, pyshark, nfstream, stackforge, PyTCP-net_proto)
+  for an actual performance-regression gate — cited file:line or
+  workflow, dated 2026-09-04; none of the ten gate on one, so the
+  comparative form of 1.7's claim is now stated with that evidence
+  (#124). Every section that previously carried a
+  `COMPARATIVE — HELD` banner is re-measured against the current tree
+  and published: decode throughput (1.1, 1.2), encoding throughput
+  (1.3), import time (1.4), wheel size (1.5), decode depth (1.6), the
+  `mypy --strict` comparison (2.1), `match`/`case` exclusivity (2.2),
+  the five-property combination (2.3), Pyodide/browser support (3.1),
+  and the permissive-licence wedge (4.1). One finding moved against
+  this project rather than for it and is reported as such: three tiers
+  of added surface since Tier 1 (#87's dispatch rewrite, #88's chain
+  walker, #91's structured errors chief among them) reversed decode
+  throughput from 1.16× faster than dpkt back to roughly 11% slower —
+  still within the 15% band claim 1.2 names, just no longer ahead.
+  Two new reproduction scripts back claims that previously had none:
+  `scripts/benchmark_encode.py` (1.3) and `scripts/benchmark_import.py`
+  (1.4). `README.md` gains a "Why NETProtocols" section drawing the
+  now-published claims into the project's front door, in the tone
+  `docs/CLAIMS.md` 4.2 sets for writing about competitors.
+
 ## [2.0.0] - 2026-09-04
 
 ### Development

{netprotocols-2.0.0 → netprotocols-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: netprotocols
-Version: 2.0.0
+Version: 2.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
@@ -72,6 +72,80 @@ pip install netprotocols
 
 Requires Python 3.12+. Fully typed (`py.typed`, mypy strict).
 
+## Why NETProtocols
+
+Measured against `dpkt 1.9.8` and `scapy 2.7.0` on a 97-frame corpus of
+real captured traffic (CPython 3.12.3, x86-64 Linux; re-measured
+2026-09-04 — see [docs/CLAIMS.md](docs/CLAIMS.md) for every number
+below, its reproduction command, and its caveats):
+
+- **Within 15% of dpkt on decode, 5.6× faster than scapy** —
+  `uv run --group bench python scripts/benchmark.py --compare`. dpkt is
+  the faster of the two comparators on this corpus; the gap moves both
+  ways as this library and dpkt each change, and this file's job is to
+  say so honestly rather than only when it's flattering.
+- **Decodes further into the stack than dpkt on 27 of 97 corpus
+  frames** — DNS and DHCP payloads that dpkt leaves as raw bytes,
+  netprotocols continues decoding. A throughput number means little
+  without knowing how much work it bought.
+- **4.5× faster than dpkt at re-encoding** (`bytes(header)`,
+  `scripts/benchmark_encode.py`) — the other half of "codec" that
+  nobody else benchmarks.
+- **Imports in 54 ms; `scapy.all` takes 458+ ms** (`scripts/benchmark_import.py`),
+  and never touches the host doing it — importing scapy populates live
+  interface and routing tables as a side effect of the import
+  statement.
+- **An 85.6 KB wheel against scapy's 2.47 MB** — about 30× smaller.
+- **Regression-gated in CI, which — as far as we could establish by
+  auditing ten comparable Python packet libraries' CI configurations
+  (dpkt, scapy, pypacker, construct, pcapkit, dnspython, pyshark,
+  nfstream, stackforge, PyTCP-net_proto; full citations in
+  [docs/CLAIMS.md §1.7](docs/CLAIMS.md)) — none of them do.** Two of
+  the ten ship real benchmark code that simply never runs in CI
+  (construct disables it explicitly; stackforge's Criterion benches are
+  never invoked); the rest have no performance benchmark at all.
+- **Typed where the alternatives are not.** `mypy --strict` over the
+  whole of `src/`, enforced in CI. scapy ships `py.typed` but enables
+  strict checking on 107 of its files, 2 of the 121 under
+  `scapy/layers/` — the dissectors most code touches stay `Any`. dpkt
+  ships no `py.typed` at all, and no third-party stub package exists
+  for it.
+- **The only MIT-licensed, strictly-typed, zero-dependency packet codec
+  still under active maintenance.** scapy is GPL-2.0; pypacker is
+  GPLv2; the newer entrants `stackforge` and `PyTCP-net_proto` are both
+  GPL-3.0. The other permissive option, dpkt (BSD), last released
+  2022-08-18 and last committed 2024-05-05, still targets Python 2.7
+  and 3.5–3.9, and remains marked Beta after twelve years.
+- **Runs where scapy cannot — including in the browser.** Verified
+  under a real Pyodide runtime in CI: scapy fails to import at all
+  under Pyodide (`from fcntl import ioctl` is unconditional in
+  `scapy/arch/`), where netprotocols, dpkt and pypacker all import
+  cleanly.
+- **The only one of these libraries a `match`/`case` statement
+  dissects out of the box.** dpkt builds `__slots__` from a metaclass
+  and generates no `__match_args__`; scapy routes fields through
+  `__getattr__`; construct returns dicts. None gives you a pattern to
+  match against.
+
+None of this makes scapy less than an extraordinary piece of software —
+it crafts, sends, sniffs and fuzzes across thousands of protocols, and
+this library does none of that. The comparison above is scoped to what
+both are: a codec that turns bytes into typed objects and back.
+
+One `mypy --strict` run says more than the bullets above:
+
+```
+# scapy 2.7.0 — a field name that does not exist
+p.ThisFieldDoesNotExist   → Any     (no error)
+
+# dpkt 1.9.8 — the whole module
+import dpkt.ethernet      → error: missing library stubs or py.typed
+
+# netprotocols — a typo in a real field name
+ip.proto                  → error: "IPv4" has no attribute
+                              "proto"; maybe "protocol"?
+```
+
 ## Protocol coverage
 
 | Layer | Protocol | Class | Notes |
@@ -185,6 +259,29 @@ to read `stopped_by`. Outside this one RFC-mandated case, a *complete*
 frame that fails to decode is still a bug to raise on — `lax=True`
 elsewhere is a capture tool's choice, not a default.
 
+## Reading captures
+
+`read_captures()` takes the bytes of a capture file — not a path — and
+auto-detects classic pcap vs. pcapng from its magic number:
+
+```python
+from netprotocols import decode_frame, read_captures
+
+data = open("traffic.pcap", "rb").read()  # or however you got the bytes
+for timestamp, frame in read_captures(data):
+    packet = decode_frame(frame, lax=True)
+    ...
+```
+
+Each `CapturedFrame` is `(timestamp, data)` — `timestamp` normalized to
+nanoseconds since the Unix epoch regardless of the source format's own
+resolution (classic pcap's microseconds or nanoseconds; pcapng's
+per-interface `if_tsresol`). `read_pcap()`/`read_pcapng()` are the same
+thing for a caller who already knows the format and wants to skip
+detection. A malformed or truncated capture raises
+`MalformedCaptureError`, the same `ProtocolError` family every other
+exception in this library belongs to.
+
 ## Flow keys
 
 `Packet.flow_key()` (or the free function, `netprotocols.flow_key()`,
@@ -212,6 +309,20 @@ named value against the plain `int` the wire actually carries. See
 [ARCHITECTURE.md](ARCHITECTURE.md#structural-pattern-matching) for why
 both of those hold and how to keep them holding.
 
+`IPv4`, `TCP` and `DHCP` are wide enough (11-15 fields) that their
+full auto-generated positional form is unusable, so those three
+additionally curate a short `__match_args__` by hand — the fields
+someone matching by position actually reaches for:
+
+```python
+match ip:
+    case IPv4(src, dst, IPProtocol.TCP):
+        print(f"TCP: {src} -> {dst}")
+```
+
+Keyword patterns (`case IPv4(protocol=IPProtocol.TCP)`) work on every
+field regardless, curated or not, and stay the documented default.
+
 ```python
 from netprotocols import IPv4, IPProtocol, TCP
 
@@ -294,24 +405,29 @@ monitor built on it (formerly Packet-Sniffer).
 
 ## Roadmap
 
-Planned work lives in the issue tracker rather than being restated
-here, so this section cannot drift out of date the way a copied list
-does. The current plan is
-[#107](https://github.com/EONRaider/NETProtocols/issues/107) — five
-tiers, each mapped to a release:
+The post-1.3.0 roadmap,
+[#107](https://github.com/EONRaider/NETProtocols/issues/107), is
+complete — five tiers plus a competitor CI audit
+([#124](https://github.com/EONRaider/NETProtocols/issues/124)) and the
+comparative-claims embargo lift that closed it out:
 
 | Version | Theme |
 |---|---|
 | [1.3.1](https://github.com/EONRaider/NETProtocols/issues/102) | Hygiene |
 | [1.4.0](https://github.com/EONRaider/NETProtocols/issues/103) | Decode performance |
-| [2.0.0](https://github.com/EONRaider/NETProtocols/issues/104) | A public protocol registry, a shipped chain walker, flow keys |
+| [2.0.0](https://github.com/EONRaider/NETProtocols/issues/104) | A public protocol registry, a shipped chain walker, flow keys — **released** |
 | [2.1.0](https://github.com/EONRaider/NETProtocols/issues/105) | Typed accessors and pattern-matching ergonomics |
 | [2.2.0](https://github.com/EONRaider/NETProtocols/issues/106) | Universal round-trip properties, nightly fuzzing, a pcap reader |
 
-The previous wave — TCP and IPv4 option parsing, ICMP message bodies,
-NDP, IPv6 extension-header TLV options, the GRE checksum arm, a
-DNS-over-TCP corpus fixture and `ipaddress` accessors — shipped in
-1.3.0; see [CHANGELOG.md](CHANGELOG.md).
+Everything through 2.2.0 has landed on `master`; per the roadmap's own
+release policy, only 2.0.0 was an actual PyPI release, and the
+comparative claims above draw on the finished tree. New planned work
+will open fresh issues rather than restating a list here, so this
+section stays accurate without upkeep. The wave before this one — TCP
+and IPv4 option parsing, ICMP message bodies, NDP, IPv6
+extension-header TLV options, the GRE checksum arm, a DNS-over-TCP
+corpus fixture and `ipaddress` accessors — shipped in 1.3.0; see
+[CHANGELOG.md](CHANGELOG.md).
 
 ## Contributing