netprotocols 1.2.0__tar.gz → 2.0.0__tar.gz

netprotocols-2.0.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,60 @@
+name: Bug report
+description: A protocol decodes, encodes, or chains incorrectly, or raises the wrong error.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the report. netprotocols decodes real traffic, so the most
+        useful reports come with the actual bytes that trigger the problem.
+        Please search [existing issues](https://github.com/EONRaider/NETProtocols/issues)
+        first.
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: >-
+        netprotocols version
+        (`python -c "import netprotocols; print(netprotocols.__version__)"`)
+        and your Python version.
+      placeholder: "netprotocols 1.2.0, Python 3.12.3"
+    validations:
+      required: true
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What did you decode or build, and what went wrong?
+      placeholder: "IPv4.decode(...) returned X, but the header on the wire says Y."
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Reproduction
+      description: >-
+        A minimal snippet. Include the raw bytes as a hex string so it runs
+        standalone — that is by far the fastest path to a fix. Rendered as
+        Python; no backticks needed.
+      render: python
+      placeholder: |
+        from netprotocols import Ethernet
+
+        frame = bytes.fromhex("ffffffffffff0007...")
+        print(Ethernet.decode(frame))
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What should have happened instead?
+    validations:
+      required: true
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Checklist
+      options:
+        - label: I included the raw bytes (or a pcap) needed to reproduce this.
+        - label: I searched existing issues for a duplicate.

netprotocols-2.0.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,10 @@
+# Freeform issues stay enabled (the roadmap and design discussions don't
+# fit a form); the templates just make the common cases structured.
+blank_issues_enabled: true
+contact_links:
+  - name: Contributing guide
+    url: https://github.com/EONRaider/NETProtocols/blob/master/CONTRIBUTING.md
+    about: Dev setup, the QA ladder, and how to add a protocol.
+  - name: Protocol roadmap
+    url: https://github.com/EONRaider/NETProtocols/issues/22
+    about: Planned protocols and their ordering — check before requesting one.

netprotocols-2.0.0/.github/ISSUE_TEMPLATE/protocol_request.yml

@@ -0,0 +1,66 @@
+name: Protocol request
+description: Request support for a protocol netprotocols does not decode yet.
+labels: ["enhancement", "roadmap"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        The roadmap ([#22](https://github.com/EONRaider/NETProtocols/issues/22))
+        tracks planned protocols and their ordering — check it and existing
+        issues first. Adding a protocol follows the cookbook in
+        [ARCHITECTURE.md](https://github.com/EONRaider/NETProtocols/blob/master/ARCHITECTURE.md);
+        contributions are welcome.
+  - type: input
+    id: protocol
+    attributes:
+      label: Protocol
+      placeholder: "e.g. DHCP, GRE, 802.1X"
+    validations:
+      required: true
+  - type: input
+    id: spec
+    attributes:
+      label: Specification
+      description: The RFC or standard number(s) that define the header.
+      placeholder: "RFC 2131"
+    validations:
+      required: true
+  - type: dropdown
+    id: layer
+    attributes:
+      label: Layer
+      description: Roughly where it sits in the stack.
+      options:
+        - Link (2)
+        - Network (3)
+        - Transport (4)
+        - Application (7)
+        - Other / not sure
+    validations:
+      required: true
+  - type: textarea
+    id: dispatch
+    attributes:
+      label: How it is reached
+      description: >-
+        What carries it — which lower layer, and which dispatch value
+        (EtherType, IP protocol number, or port)?
+      placeholder: "Behind UDP on ports 67/68."
+    validations:
+      required: false
+  - type: textarea
+    id: sample
+    attributes:
+      label: Sample traffic
+      description: >-
+        A pcap or a hex dump of a real frame makes this far easier to
+        implement and test — the fixture corpus is captured from real traffic.
+    validations:
+      required: false
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Checklist
+      options:
+        - label: I checked the roadmap (#22) and existing issues.
+        - label: I can provide a real capture (pcap or hex) of this protocol.

netprotocols-2.0.0/.github/pull_request_template.md

@@ -0,0 +1,40 @@
+<!--
+Thanks for contributing to netprotocols! Fill in the sections below and
+delete this comment. CONTRIBUTING.md has the full workflow; the short
+version is: keep the QA ladder green and update the docs your change
+touches. Relative links below resolve from the repo root once this
+becomes the PR description.
+-->
+
+## Summary
+
+<!-- What does this change do, and why? Link any related issue, e.g. "Closes #22". -->
+
+## What's included
+
+<!-- The concrete changes, one bullet each: new/edited modules, tests, docs. -->
+
+-
+
+## Verification
+
+<!-- Paste the QA-ladder output, or tick the boxes. All four gates run in CI. -->
+
+- [ ] `uv run ruff check` and `uv run ruff format --check` are clean
+- [ ] `uv run mypy` is clean (strict)
+- [ ] `uv run pytest` passes locally (CI runs it on Python 3.12 / 3.13 / 3.14)
+- [ ] `CHANGELOG.md` has an entry under `## [Unreleased]`
+
+### New protocol or dispatch change — also:
+
+<!-- Delete this block if it doesn't apply. See ARCHITECTURE.md's cookbook. -->
+
+- [ ] Followed the add-a-protocol cookbook in [ARCHITECTURE.md](ARCHITECTURE.md) and the decode contract in `src/netprotocols/_base.py`
+- [ ] New `EtherType` / `IPProtocol` numbers carry display names in lockstep (a completeness test enforces it)
+- [ ] Registered the class in the fuzz suite (`tests/test_fuzz.py::ALL_PROTOCOLS`)
+- [ ] Added a fixture and updated [tests/fixtures/MANIFEST.md](tests/fixtures/MANIFEST.md) — a real capture where possible (see CONTRIBUTING.md for the capture scripts)
+- [ ] Updated the README coverage table and the ARCHITECTURE.md chain diagram
+
+## Notes
+
+<!-- Anything reviewers should know: trade-offs, follow-ups, companion PRs. Optional. -->

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.2.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