netprotocols 0.8.0__tar.gz → 1.0.1__tar.gz

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

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+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__)"

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

@@ -0,0 +1,18 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    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
+      - run: uv publish --trusted-publishing always

netprotocols-1.0.1/.gitignore

@@ -0,0 +1,149 @@
+### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# Pycharm
+.idea/
+
+# OWASP Amass
+amass.txt
+amass.log
+
+# Application-specific
+.logs/tests/fixtures/staging/

netprotocols-1.0.1/ARCHITECTURE.md

@@ -0,0 +1,222 @@
+# How NETProtocols works
+
+This is a guided tour of the library's inner workings, written for
+anyone who wants to contribute a protocol, fix a bug, or simply
+understand how raw bytes become Python objects and back. No prior
+experience with packet dissection is assumed — only curiosity and a
+little Python.
+
+## A header is just bytes at fixed positions
+
+Here are the first 14 bytes of a real captured frame — an Ethernet II
+header announcing an ARP packet:
+
+```
+ff ff ff ff ff ff   00 07 0d af f4 54   08 06
+└───────────────┘   └───────────────┘   └───┘
+ destination MAC       source MAC     EtherType
+   (broadcast)                        0x0806 = ARP
+```
+
+Every protocol header works like this: a sequence of fields, each at a
+known offset with a known width, in network byte order (big-endian).
+Parsing one is nothing more than slicing the right bytes and
+interpreting them as integers or addresses.
+
+## From bytes to a dataclass
+
+Each protocol is a **frozen, slotted dataclass** whose fields mirror
+the wire format, plus a class-level `struct.Struct` describing the
+fixed portion's layout. For the header above:
+
+```python
+@dataclass(frozen=True, slots=True)
+class Ethernet(Protocol):
+    dst: str        # "ff:ff:ff:ff:ff:ff"
+    src: str        # "00:07:0d:af:f4:54"
+    ethertype: int  # 0x0806
+
+    _struct: ClassVar[Struct] = Struct("!6s6sH")
+```
+
+The format string `"!6s6sH"` reads: network byte order (`!`), two
+6-byte strings (the MACs), one unsigned 16-bit integer (the
+EtherType). The `Struct` is compiled once at class definition time —
+decoding a million frames reuses the same compiled object.
+
+Three design choices worth knowing:
+
+- **Frozen + slots**: instances are immutable (safe to share, hash,
+  and compare) and carry no `__dict__` (cheap to allocate by the
+  million during live capture).
+- **Friendly field types**: addresses are stored as their canonical
+  strings, everything else as `int`, options as `bytes`. What you see
+  in a `repr()` is what you work with.
+- **Bitfields are explicit**: where the wire packs several fields into
+  one integer (IPv4's version/IHL byte, TCP's offset/flags word), the
+  decode method splits them with shifts and masks you can read:
+
+  ```python
+  ihl = ver_ihl & 0x0F
+  version = ver_ihl >> 4
+  ```
+
+## The decode contract
+
+`decode(data)` is the heart of the library, and every protocol obeys
+the same three rules (spelled out in [`_base.py`](src/netprotocols/_base.py)):
+
+1. **It receives the entire remaining buffer** — everything from the
+   start of its header to the end of the captured frame — and parses
+   the fixed portion with `_struct.unpack_from`. A buffer too short
+   for the fixed portion raises `TruncatedHeaderError`.
+2. **Variable-length headers finish the job themselves.** IPv4 reads
+   its IHL and TCP reads its data offset, sanity-checks it (5–15, and
+   the declared bytes must exist in the buffer — a header that *lies*
+   about its length raises `TruncatedHeaderError`), then slices its
+   `options` as materialized `bytes`.
+3. **Trailing bytes are fine.** Whatever follows the header belongs to
+   the next layer. After decoding, `instance.header_len` says exactly
+   how many bytes this header consumed — a *property*, so IPv4 answers
+   `ihl * 4` and TCP answers `data_offset * 4`.
+
+Decoding accepts `bytes` or `memoryview`. Views are a decode-time
+transient only: every stored field is a scalar or materialized
+`bytes`, so no decoded object ever aliases the buffer it came from.
+You can safely reuse or mutate capture buffers.
+
+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
+```
+
+## Walking a frame: the next_protocol() chain
+
+A captured frame is a chain of headers, each one naming what it
+carries. In this library that fact is typed: every decoded header
+answers `next_protocol()` with the *class* that decodes its payload,
+or `None` when the chain ends (nothing encapsulated, or a protocol
+this library doesn't implement yet).
+
+```mermaid
+flowchart LR
+  E[Ethernet] -->|0x0806| A[ARP]
+  E -->|0x0800| I4[IPv4]
+  E -->|0x86DD| I6[IPv6]
+  I4 -->|1| IC4[ICMPv4]
+  I4 -->|6| T[TCP]
+  I4 -->|17| U[UDP]
+  I6 -->|58| IC6[ICMPv6]
+  I6 -->|6| T
+  I6 -->|17| U
+```
+
+The numbers on the arrows are the wire values — EtherTypes out of
+Ethernet, IP protocol numbers out of IPv4/IPv6 — and they live in
+[`_enums.py`](src/netprotocols/_enums.py) as `EtherType` and
+`IPProtocol`. IPv4 and IPv6 share one registry because the number
+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:
+
+```python
+layers, cursor, protocol = [], 0, Ethernet
+while protocol is not None:
+    header = protocol.decode(frame[cursor:])
+    layers.append(header)
+    cursor += header.header_len
+    protocol = header.next_protocol()
+```
+
+**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 encode side, and the round-trip guarantee
+
+Every class also works in reverse. Constructors take the friendly
+forms (string addresses, integer fields), validate them in
+`__post_init__` (address formats; and IHL/data-offset must agree with
+`len(options)` — you cannot construct a self-contradictory header),
+and `bytes()` re-emits the exact on-wire form.
+
+The test suite enforces the round trip in both directions for every
+protocol:
+
+```python
+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.
+
+`Packet` is the thin composition layer: it holds an ordered tuple of
+headers and `bytes(packet)` joins them, ready for a raw socket.
+
+## Layout map
+
+```
+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
+├── layer2/         ethernet.py, arp.py
+├── layer3/         ip.py (IPv4 + IPv6), icmp.py (ICMPv4 + ICMPv6)
+├── layer4/         tcp.py, udp.py
+└── utils/          validators (mac.py, ipv4.py), exceptions.py
+tests/              one file per protocol + test_contract.py
+                    (truncation, lying lengths, chain walks)
+```
+
+Tooling: [uv](https://docs.astral.sh/uv/) manages the environment
+(`uv sync`); `uv run pytest`, `uv run mypy` (strict), and
+`uv run ruff check` are the three gates CI enforces on Python
+3.12–3.14.
+
+## Cookbook: adding a protocol
+
+Say you want to add DNS (sitting behind UDP). The pattern is always
+the same:
+
+1. **Model the fixed header.** Create `layer7/dns.py` with a frozen,
+   slotted dataclass: one field per header field, a `_struct` for the
+   fixed portion (`"!HHHHHH"` for DNS: id, flags, and four counts).
+2. **Implement `decode()`.** Call `cls._unpack_fixed(data)`, split any
+   bitfields explicitly, and construct the instance. If the header is
+   variable-length, validate the declared length against `len(data)`
+   (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.
+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.)
+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
+   display helper.
+6. **Test with real bytes.** Capture or craft a real header, add it as
+   a fixture, and cover: a decode with asserted fields, both round
+   trips, truncated input, and (if variable-length) an options case
+   and a lying-length case. Export the class from `__init__.py`.
+
+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.

netprotocols-1.0.1/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+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.0.1] - 2026-08-29
+
+### Fixed
+- `IPv4.next_protocol()` chained non-first fragments
+  (`fragment_offset > 0`) into garbage upper-layer decodes — a slice
+  from the middle of a fragmented payload has no header at its start.
+  Discovered by the new real-capture fixture corpus on live fragmented
+  traffic; the chain now ends at the IPv4 layer for those frames, as it
+  already did for unknown protocols.
+
+### Added (development)
+- A real-capture fixture corpus under `tests/fixtures/` (56 frames,
+  10 scenarios, every checksum internally verified — see its
+  MANIFEST.md) with corpus-wide invariant tests, plus the capture and
+  validation scripts under `scripts/`.
+
+## [1.0.0] - 2026-08-21
+
+Complete rewrite. The public API is new; see the README and
+ARCHITECTURE.md for the current usage.
+
+### Changed
+- The parsing core moved from `ctypes.BigEndianStructure` subclasses to
+  frozen, slotted dataclasses parsed with `struct.Struct`. Decoded and
+  constructed instances are now identical in type and compare equal
+  field-by-field.
+- `next_protocol()` (returning the class that decodes the payload, or
+  `None`) replaces the stringly-typed `encapsulated_proto` chain.
+  Protocol number registries are exposed as `EtherType`, `IPProtocol`,
+  and `ARPOperation` enums.
+- `header_len` is now an instance property: IPv4 honors IHL and TCP
+  honors the data offset, and both expose their raw `options` bytes.
+- Field names modernized (`ethertype`, `src_port`, `total_length`,
+  `checksum`, ...); display helpers are properties such as
+  `protocol_name`, `flags_str`, and `checksum_hex_str`.
+- Packaging moved to PEP 621 (`hatchling` + `uv`), src layout, Python
+  3.12+, MIT license, `py.typed` (mypy strict clean).
+- Validators are plain functions (`validate_mac_addr`,
+  `validate_ipv4_addr`) raising exceptions rooted at `ProtocolError`.
+
+### Fixed
+- `TCP.header_len` was hardcoded to 32 bytes; the base header is 20 and
+  the real length follows the data offset.
+- Decoding ignored IPv4 IHL and TCP data offset, so headers carrying
+  options were mis-sliced.
+- Serialization returned a zeroed buffer (`Protocol.__str__`);
+  `bytes(header)` now re-emits the exact on-wire form, options included.
+- `Packet` rejected instances of indirect `Protocol` subclasses
+  (e.g. `IPv4`, `ICMPv4`) due to validation against direct subclasses
+  only; membership is now checked with `isinstance`.
+- Malformed input (truncated buffers, lying IHL/data-offset values) now
+  raises typed exceptions (`TruncatedHeaderError`, `InvalidFieldError`)
+  instead of arbitrary `ValueError`/`struct.error` leaks.
+
+### Removed
+- The `Validator` descriptor infrastructure (it stored state on the
+  descriptor itself — class-shared — and was never wired into any
+  protocol class).
+- Poetry manifests and the `setup.py`-era metadata.
+
+## [0.8.0] - 2022-08-19
+
+Last release of the ctypes-based implementation, published to PyPI in
+2022. The repository had drifted behind the published releases; the
+0.8.0 sources were recovered from the PyPI sdist and committed (tagged
+`v0.8.0`) before the 1.0.0 rewrite. Releases 0.4.4 through 0.8.0 exist
+on PyPI only; their individual histories were not preserved.

netprotocols-1.0.1/LICENSE

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

netprotocols-1.0.1/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.5
+Name: netprotocols
+Version: 1.0.1
+Summary: Low-level implementations of common networking protocols
+Project-URL: Homepage, https://github.com/EONRaider/NETProtocols
+Project-URL: Repository, https://github.com/EONRaider/NETProtocols
+Project-URL: Changelog, https://github.com/EONRaider/NETProtocols/blob/master/CHANGELOG.md
+Author-email: EONRaider <livewire_voodoo@protonmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: arp,ethernet,icmp,ip,networking,packet,protocols,tcp,udp
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Networking
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# NETProtocols
+
+[![CI](https://github.com/EONRaider/NETProtocols/actions/workflows/ci.yml/badge.svg)](https://github.com/EONRaider/NETProtocols/actions/workflows/ci.yml)
+![Python Version](https://img.shields.io/badge/python-3.12%2B-blue?logo=python)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+![Typed](https://img.shields.io/badge/typing-strict-informational)
+
+Low-level implementations of common networking protocols, in pure
+Python with zero dependencies.
+
+Decode raw header bytes into typed, immutable protocol objects — or
+build those objects from field values and serialize them back to their
+exact on-wire form. Every header is a frozen dataclass whose fields
+mirror the wire format, so decoded traffic is introspectable,
+comparable, and round-trippable.
+
+```pycon
+>>> from netprotocols import Ethernet
+>>> eth = Ethernet.decode(frame)
+>>> eth
+Ethernet(dst='ff:ff:ff:ff:ff:ff', src='00:07:0d:af:f4:54', ethertype=2054)
+>>> eth.ethertype_name
+'ARP'
+>>> eth.next_protocol()
+<class 'netprotocols.layer2.arp.ARP'>
+>>> bytes(eth) == frame[:eth.header_len]
+True
+```
+
+## Installation
+
+```
+pip install netprotocols
+```
+
+Requires Python 3.12+. Fully typed (`py.typed`, mypy strict).
+
+## Protocol coverage
+
+| Layer | Protocol | Class | Notes |
+|---|---|---|---|
+| 2 | Ethernet II | `Ethernet` | IEEE 802.3 |
+| 2 | ARP | `ARP` | RFC 826, IPv4-over-Ethernet binding |
+| 3 | IPv4 | `IPv4` | RFC 791, IHL/options aware |
+| 3 | IPv6 | `IPv6` | RFC 8200, fixed header |
+| 3 | ICMPv4 | `ICMPv4` | RFC 792, 8-byte header |
+| 3 | ICMPv6 | `ICMPv6` | RFC 4443, 8-byte header |
+| 4 | TCP | `TCP` | RFC 9293, data-offset/options aware |
+| 4 | UDP | `UDP` | RFC 768 |
+
+## Decoding a captured frame
+
+Each class decodes its own header from the start of a buffer and
+tolerates trailing bytes, so you can walk a whole frame with two pieces
+of information every header provides: `header_len` (how many bytes it
+consumed) and `next_protocol()` (which class decodes what follows).
+
+```python
+from netprotocols import Ethernet
+
+def decode_frame(frame: bytes) -> list:
+    layers, cursor, protocol = [], 0, Ethernet
+    while protocol is not None:
+        header = protocol.decode(frame[cursor:])
+        layers.append(header)
+        cursor += header.header_len
+        protocol = header.next_protocol()
+    return layers  # e.g. [Ethernet(...), IPv4(...), TCP(...)]
+```
+
+Malformed input raises exceptions rooted at a single base class:
+
+```python
+from netprotocols import ProtocolError, TruncatedHeaderError, InvalidFieldError
+
+try:
+    layers = decode_frame(frame)
+except TruncatedHeaderError:   # buffer shorter than the header claims
+    ...
+except InvalidFieldError:      # nonsense field values (IHL < 5, bad address)
+    ...
+except ProtocolError:          # catches every library error
+    ...
+```
+
+## Building and serializing headers
+
+Constructors take friendly values (string MAC/IP addresses, integer
+fields) and validate them; `bytes()` emits the exact on-wire form.
+`Packet` concatenates a stack of layers:
+
+```python
+from netprotocols import ARP, Ethernet, Packet, random_mac
+
+sha = random_mac()
+frame = Packet(
+    Ethernet(dst="ff:ff:ff:ff:ff:ff", src=sha, ethertype=0x0806),
+    ARP(htype=1, ptype=0x0800, hlen=6, plen=4, oper=1,
+        sha=sha, spa="192.168.1.96",
+        tha="00:00:00:00:00:00", tpa="192.168.1.254"),
+)
+raw = bytes(frame)  # ready for a raw socket
+```
+
+Checksums are carried verbatim in both directions: the library neither
+computes nor verifies them (planned — see the roadmap).
+
+## Display helpers
+
+Every class exposes human-readable properties next to the raw fields:
+`Ethernet.ethertype_name`, `IPv4.protocol_name`, `IPv4.flags_name`,
+`TCP.flags_str` (`"SYN ACK"`), `ARP.oper_name`, `ICMPv4.type_name`,
+and hexadecimal renderings such as `checksum_hex_str`. Unknown values
+degrade gracefully (`"0x88cc"`, `"unknown (47)"`) instead of raising.
+
+## How it works
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for a guided tour: how a header
+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.
+
+## Roadmap
+
+- IPv6 extension headers (hop-by-hop, routing, fragment, destination
+  options) — today the decode chain ends at `IPv6` for traffic behind
+  them (e.g. MLD).
+- 802.1Q VLAN tags, DNS, DHCP, IGMP, GRE.
+- Checksum computation on encode and verification flags on decode.
+- Fuzzing of the decode path.
+
+## 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
+[ARCHITECTURE.md](ARCHITECTURE.md).
+
+## License
+
+[MIT](LICENSE)