netprotocols 1.3.0__tar.gz → 2.0.0__tar.gz

netprotocols-2.0.0/.github/workflows/ci.yml

@@ -0,0 +1,91 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+  # Callable so the release workflow can run this exact ladder against a
+  # tagged commit before publishing (see release.yml). Keeping one
+  # definition means the release gate cannot drift from the PR gate.
+  workflow_call:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv run ruff check
+      - run: uv run ruff format --check
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv run mypy
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv run --frozen pytest --cov=netprotocols --cov-report=term
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - run: uv run --isolated --no-project --with dist/*.whl python -c "import netprotocols; print(netprotocols.__version__)"
+
+  # 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
+  # spread on one machine is ~2%. 15% is therefore roughly four times
+  # the noise it has to tolerate, which leaves real regressions (Tier 1
+  # moved this number by 30-90% a step) nowhere to hide.
+  #
+  # A failure re-measures once before failing, because a shared runner
+  # can lose a slice of CPU to a neighbour: a genuine regression fails
+  # both attempts, a noisy one usually does not.
+  #
+  # Pinned to the baseline's interpreter on purpose: normalization
+  # cancels how fast the machine is, not which CPython it runs (see the
+  # module docstring in scripts/benchmark.py). If a change is a
+  # deliberate trade, re-record with --update-baseline and say why.
+  benchmark:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - name: Corpus decode throughput
+        shell: bash
+        run: |
+          # Keep the benchmark's own exit status: piping the whole thing
+          # into tee would report tee's, and wrapping it in a { } group
+          # would report the trailing echo's -- either way the gate
+          # would pass while the check failed.
+          status=0
+          uv run --frozen --group bench python scripts/benchmark.py \
+            --check --threshold 15 --compare >benchmark.out 2>&1 || status=$?
+          {
+            echo '```'
+            cat benchmark.out
+            echo '```'
+          } >>"$GITHUB_STEP_SUMMARY"
+          cat benchmark.out
+          exit "$status"

netprotocols-2.0.0/.github/workflows/release.yml

@@ -0,0 +1,61 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  # Run the full QA ladder against the tagged commit before anything is
+  # uploaded. This is not redundant with the CI workflow's own triggers:
+  # those fire on pushes and pull requests targeting master, and a tag
+  # push matches neither, so without this job a release ran no checks at
+  # all. A tag can also point at a commit that never landed on master.
+  # A published version can only be yanked, never replaced.
+  ci:
+    uses: ./.github/workflows/ci.yml
+
+  publish:
+    needs: ci
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      # The QA ladder cannot catch a mistagged release: every check
+      # passes because the code is fine and only the tag is wrong. Read
+      # the version back out of the artifact that is about to be
+      # uploaded, rather than re-parsing pyproject.toml, so this
+      # compares against what PyPI will actually receive.
+      - name: Verify the tag matches the version being published
+        run: |
+          set -euo pipefail
+          # Only the "v*" trigger keeps a bare "1.3.0" tag from reaching
+          # this step, where it would compare equal and pass. Check the
+          # prefix here too, so the contract survives a wider trigger.
+          case "${GITHUB_REF_NAME}" in
+            v*) tag="${GITHUB_REF_NAME#v}" ;;
+            *)
+              echo "::error::Tag ${GITHUB_REF_NAME} does not start with 'v'."
+              echo "Release tags must be of the form v<version>." >&2
+              exit 1
+              ;;
+          esac
+          built=$(uv run --isolated --no-project --with dist/*.whl \
+            python -c \
+            "from importlib.metadata import version; print(version('netprotocols'))")
+          if [ "$tag" != "$built" ]; then
+            echo "::error::Tag ${GITHUB_REF_NAME} would publish version ${built}."
+            echo "The tag and the packaged version must agree." >&2
+            echo "Either retag as v${built}, or set the version in" >&2
+            echo "pyproject.toml (and __version__) to ${tag} and retag." >&2
+            exit 1
+          fi
+          echo "Tag ${GITHUB_REF_NAME} matches packaged version ${built}."
+      - run: uv publish --trusted-publishing always

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

@@ -147,3 +147,6 @@ amass.log
 
 # Application-specific
 .logs/tests/fixtures/staging/
+
+# Written by the benchmark CI step (scripts/benchmark.py output)
+benchmark.out

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

@@ -61,6 +61,58 @@ Three design choices worth knowing:
   version = ver_ihl >> 4
   ```
 
+## Structural pattern matching
+
+Every decoded header works with `match`/`case` today, and nothing in
+`src/` was written to make that true — it falls out of the two design
+choices above, for reasons worth being precise about:
+
+```python
+match eth:
+    case Ethernet(ethertype=EtherType.IPV4):
+        ...
+
+match ip:
+    case IPv4(protocol=IPProtocol.TCP, ttl=t) if t > 32:
+        ...
+```
+
+1. **`@dataclass` auto-generates `__match_args__`** from the field
+   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.
+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
+   the plain integer the wire actually carries —
+   `case Ethernet(ethertype=EtherType.IPV4)` matches an instance whose
+   `ethertype` field holds the `int` `0x0800` — with no cast, no
+   adapter, and no separate "typed" view to keep in sync with the raw
+   field.
+
+Keyword class patterns (`ClassName(field=pattern)`) work on *any*
+object exposing that attribute; `__match_args__` is only needed for
+the positional form. What a frozen dataclass adds is that the
+attribute is guaranteed to exist exactly as declared, with no
+proxying: a class pattern here either matches a real field or fails
+outright — a mistyped field name in a keyword pattern silently never
+matches rather than raising, on any object, dataclass or not, so this
+buys reliability rather than a new failure mode, not immunity from
+that one. (How this compares to other Python packet libraries is
+tracked in `docs/CLAIMS.md`, not stated here — see the embargo notes
+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.
+
 ## The decode contract
 
 `decode(data)` is the heart of the library, and every protocol obeys
@@ -90,12 +142,43 @@ Errors form a small typed hierarchy rooted at `ProtocolError`:
 ```
 ProtocolError
 ├── TruncatedHeaderError     buffer shorter than the header claims
-└── InvalidFieldError        field value violates the protocol's rules
-    ├── InvalidMACAddressError
-    ├── InvalidIPv4AddressError
-    └── InvalidManufacturerCodeError
+├── InvalidFieldError        field value violates the protocol's rules
+│   ├── InvalidMACAddressError
+│   ├── InvalidIPv4AddressError
+│   └── InvalidManufacturerCodeError
+└── MaxDepthExceededError    a frame's chain exceeded decode_frame's max_depth
+```
+
+**Every raise carries structured context, not just a message.** A
+formatted string is easy for a human to read and impossible for a
+fuzzer, conformance suite, or validation tool to act on without
+regexing it — so every raise site in `src/` attaches `protocol` (the
+class that raised) and, where meaningful, `field` (the attribute at
+fault), `offset`, and `expected`/`actual`:
+
+```python
+try:
+    packet = decode_frame(frame)
+except ProtocolError as e:
+    print(e.protocol, e.field, e.offset, e.frame_offset, e.expected, e.actual)
 ```
 
+`offset` is relative to whatever buffer the error was found in: the
+`data` argument of a `decode()` call when `field` is `None` or names a
+fixed-header value, or the attribute `field` names when it's a raw
+`bytes` field parsed on demand (`options`, `body`, `sections`) — a TCP
+option error's `offset` is relative to `header.options`, not to the
+frame. `decode_frame` is the only code holding the cursor needed to
+rebase a layer's own offset to the whole frame, so it does — the
+result lands in `frame_offset`, left `None` by a bare
+`SomeClass.decode()` call with no frame to rebase against. A
+`__post_init__` validation error (values, not bytes) leaves `offset`
+`None` too; there is nothing to be positioned in.
+
+All five fields default to `None` and adding them never changes a
+message string — every existing `str(err)` and `match=` assertion
+holds unchanged.
+
 ## Walking a frame: the next_protocol() chain
 
 A captured frame is a chain of headers, each one naming what it
@@ -154,44 +237,114 @@ Ethernet, IP protocol numbers out of IPv4/IPv6 — and they live in
 space is shared (1 is ICMPv4, 58 is ICMPv6, 6 is TCP, 17 is UDP — no
 collisions).
 
-A complete frame walk is a five-line loop:
+A complete frame walk is a five-line loop — which is exactly why it
+ships as [`decode_frame()`](src/netprotocols/walk.py) rather than as
+something every caller retypes:
+
+```python
+packet = decode_frame(frame)          # Packet(Ethernet(...), IPv4(...), TCP(...))
+```
+
+Underneath it is the loop the two answers imply:
 
 ```python
-layers, cursor, protocol = [], 0, Ethernet
+layers, cursor, protocol = [], 0, start
 while protocol is not None:
     header = protocol.decode(frame[cursor:])
     layers.append(header)
     cursor += header.header_len
-    protocol = header.next_protocol()
+    protocol = header.next_protocol(registry)
 ```
 
-**Why the deferred imports?** `Ethernet.next_protocol()` must name
-`ARP`, `IPv4`, and `IPv6` — but `arp.py` also imports from the
-Ethernet side of the world (EtherType names). Importing layer modules
-from each other at module level would create cycles, so two rules keep
-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.
+The shipped version adds what a copy-pasted loop never has: a bounded
+depth (`max_depth`, so a crafted frame cannot make the walk grind), an
+explicit `start=` layer for buffers that begin mid-stack, a `lax=True`
+mode that reports partial success on `packet.stopped_by` instead of
+raising, and the `registry`/`decode_as` hook above. The walk slices
+whatever it is handed and never converts: `bytes` stays fastest for one
+frame, a `memoryview` over a big capture buffer stays zero-copy.
+Wrapping each frame in a `memoryview` internally measured *slower*
+(0.95x on the corpus), so the walker does not.
+
+**Where do those arrows live?** Not in the protocol classes. Every
+one of them is a row in a dispatch table owned by
+[`registry.py`](src/netprotocols/registry.py), and `next_protocol()`
+is a single `dict.get` against one of five tables named after the wire
+field they dispatch on:
+
+| Table | Dispatches on | Read by |
+|---|---|---|
+| `ethertype` | Ethernet II EtherType | `Ethernet`, `VLAN`, `GRE` |
+| `ip.proto` | IPv4 `protocol` | `IPv4` |
+| `ip.proto.v6` | IPv6 `next_header` | `IPv6`, extension headers |
+| `udp.port` | UDP well-known port | `UDP` |
+| `tcp.port` | TCP well-known port | `TCP` |
+
+`ip.proto.v6` **inherits** `ip.proto`: the two share a number space
+but not a table, because the four extension headers must be reachable
+only inside an IPv6 chain. Registering in `ip.proto` reaches both;
+registering in `ip.proto.v6` reaches the v6 chain alone. Inheritance
+is resolved when you register, not when you look up, so the gating
+costs nothing on the hot path — an IPv4 packet with `protocol=0`
+cannot conjure a Hop-by-Hop layer because the table it reads has no
+entry for `0`.
+
+**Extending the walk without forking.** The tables are public. A
+protocol this library does not implement — MPLS, VXLAN, a proprietary
+telemetry header — is one registration away from participating in
+frame walks like any built-in:
+
+```python
+from netprotocols import Protocol
+from netprotocols.registry import register
+
+@register("ethertype", 0x8847)
+class MPLS(Protocol):
+    ...
+```
+
+Registrations land in the process-wide `DEFAULT` registry. When they
+must not — you are embedding this library, or isolating a test — build
+your own with `Registry.from_defaults()` and hand it to the caller
+that walks frames. Registering over an existing entry raises
+`RegistryConflictError` unless you pass `override=True`, so two
+packages claiming the same port cannot silently resolve by import
+order; re-registering the *same* class to the same key is a no-op,
+because a decorator re-runs whenever its module does.
+
+**Why is the built-in map in its own module?** `Ethernet` must name
+`ARP`, `IPv4`, and `IPv6` — but `arp.py` imports from the Ethernet
+side of the world (EtherType names). Importing layer modules from each
+other at module level would create cycles, so the built-in
+registrations live together in
+[`_defaults.py`](src/netprotocols/_defaults.py), whose imports sit
+inside `install()` and run once from `__init__.py` after every
+protocol class exists. Shared enums stay in the dependency-free
+`_enums.py`. The layer modules bind their table at import and never
+import each other's classes at all.
 
 ## 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.
+The `ethertype` and `ip.proto` tables dispatch on a single
+authoritative field: it exists to say what follows. The two port
+tables break that model, and differ in kind rather than just in name.
+A port is a *guess* — any service may run on any port, and the
+discriminator is split across the source and destination ports.
+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). DNS on UDP 53 and DHCP on 67/68 decode as a
+fourth layer; on TCP, port 53 names `DNSOverTCP`, a shim that consumes
+the 2-byte length prefix (RFC 1035 §4.2.2) and chains onward, so the
+walk stays uniform.
 
 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.
+a mis-dispatch degrades to a diagnosed frame, never to garbage. This
+is why the port tables can be opened to third parties as safely as the
+authoritative ones: a wrong registration costs a diagnosed frame, not
+a wrong answer.
 
 ## The encode side, and the round-trip guarantee
 
@@ -225,24 +378,28 @@ headers and `bytes(packet)` joins them, ready for a raw socket.
 
 ```
 src/netprotocols/
-├── __init__.py     public API re-exports, __version__
+├── __init__.py     public API re-exports, __version__, registry install
 ├── _base.py        Protocol ABC, decode contract, address helpers
 ├── _enums.py       EtherType, IPProtocol, ARPOperation (imports nothing)
-├── packet.py       Packet composition, with_checksums()
+├── registry.py     public dispatch tables: register(), Registry
+├── walk.py         decode_frame(): the shipped chain walker
+├── _defaults.py    the built-in decoder map, installed at import
+├── packet.py       Packet composition, with_checksums(), flow_key()
 ├── checksum.py     RFC 1071: internet_checksum, compute, verify
-├── layer2/         ethernet.py, arp.py
+├── flow.py         FlowKey, flow_key(): canonical bidirectional keys
+├── layer2/         ethernet.py, arp.py, vlan.py (802.1Q / 802.1ad)
 ├── layer3/         ip.py (IPv4 + IPv6), icmp.py (ICMPv4 + ICMPv6),
-│                   igmp.py,
+│                   igmp.py, gre.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
+├── layer4/         tcp.py, udp.py, _ports.py (port-table dispatch)
+├── layer7/         dns.py, dhcp.py
 └── utils/          validators (mac.py, ipv4.py), exceptions.py
 tests/              one file per protocol + test_contract.py
                     (truncation, lying lengths, chain walks),
                     test_corpus.py (invariants over the real-capture
-                    corpus in tests/fixtures/, 93 frames across 16
-                    scenarios — see its MANIFEST.md), test_checksum.py
+                    corpus in tests/fixtures/ — see its MANIFEST.md for
+                    the frame and scenario counts), test_checksum.py
                     (corpus checksums recompute to wire values), and
                     test_fuzz.py (hypothesis properties: decode never
                     raises outside ProtocolError)
@@ -273,14 +430,15 @@ the same:
    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` — 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`.)
+4. **Wire the chain.** Register the class against the value that
+   names it, in the table that carries that value — `register("udp.port",
+   53, DNS)`. Nothing in the layer below changes. If you are adding a
+   protocol *to this library* rather than to your own program, add the
+   wire value to `_enums.py` too (display name in lockstep — a test
+   enforces it) and put the registration in `_defaults.py` alongside
+   the rest. Numbers valid only inside an IPv6 chain go in
+   `ip.proto.v6` rather than `ip.proto`, which is the whole of the
+   gating.
 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
@@ -290,6 +448,10 @@ the same:
    trips, truncated input, and (if variable-length) an options case
    and a lying-length case. Export the class from `__init__.py`.
 
+Steps 1–3, 5 and 6 are the same whether the protocol ships here or in
+your own package; only step 4 differs, and only in *where* the
+registration lives.
+
 If you follow the six steps, your protocol automatically composes with
 `Packet`, participates in frame walks, and inherits the library's
 error behavior — that's the whole point of the shared contract.