Skip to content

refactor(analysis): DTLS's foundation analysis wraps a DTLS protocol method - #2634

Merged
JarryShaw merged 1 commit into
mainfrom
refactor/2622-dtls-analysis
Nov 2, 2026
Merged

JarryShaw merged 1 commit into
mainfrom
refactor/2622-dtls-analysis

Conversation

@JarryShaw

Copy link
Copy Markdown
Owner

What is the purpose of your pull request?

  • refactor — changes neither behaviour nor performance

Description of your pull request and other information

As the owner ruled on #2622, pcapkit.foundation.analysis is a public layer over protocol methods and holds no parsing of its own. DTLS now matches IP and TCP:

  • The rebuild-and-fallback logic in foundation.analysis.dtls._read_handshake moves into the classmethod DTLS.analyze_handshake.
  • dtls_handshake and the reassembly Deferred both call that classmethod, the Deferred through the engine's __protocol_type__.
  • The convention is written onto reassembly-integration.rst as "Parse Ownership". A new guard fails on any import of pcapkit.foundation under pcapkit/protocols/ outside TYPE_CHECKING, except registry.protocols.

Output is unchanged: 68 test-vector datagrams, 40 synthetic vectors and every sample capture match, including pickle round trips. One fix comes with the move. On main, an undecodable handshake body logged CRITICAL and replaced sys.excepthook/threading.excepthook. It is now a quiet refusal, per #2588's rule.

A custom engine's __protocol_type__ now decides the DTLS parse, as it does for IP and TCP, and must define analyze_handshake. foundation.analysis is in no release. A Sonnet cross-review reproduced the differential and the guard mutations; its fixes are folded in.

Closes #2622

…2622)

- DTLS.analyze_handshake(header, body), after read_handshake, takes over
  the analysis module's private decoder: rebuild the message unfragmented,
  read it, keep a body that does not decode raw. That refusal is quiet
  (CaughtByCaller), where it logged at CRITICAL and installed the hooks.
- dtls_handshake calls it, and the reassembly Deferred binds
  __protocol_type__'s, as IP and TCP do; one without it fails on completion.
- reassembly-integration.rst records the ruling; protocol-family-grouping.rst
  counts the explicit CaughtByCaller under #2588's rule.
- Tests pin the delegation, a subclass override, pickling, the quiet
  fallback, and that protocols import only registry.protocols from foundation.

Closes #2622.
@JarryShaw JarryShaw added this to the PyPCAPKit v1.6 milestone Nov 2, 2026
@JarryShaw JarryShaw added refactor Restructuring for its own sake — neither a fix nor a new capability (refactor: prefix) review: good-to-go Cross-review at the current head says ready; CI state is separate labels Nov 2, 2026
@JarryShaw

Copy link
Copy Markdown
Owner Author

GOOD TO GO at e05e7a447, from a Sonnet cross-review.

  • Behaviour. It reproduced the DTLS differential (72 datagrams, 0 mismatches) and confirmed pickle round trips.
  • Quiet-refusal fix. On main, a malformed handshake body logs CRITICAL and installs excepthooks. Here it logs nothing and installs no hooks.
  • Import guard. Seven injection forms each failed the guard.
  • Review fixes folded in:
    • the heading is now "Parse Ownership";
    • the module docstring is fixed;
    • the guard exempts only registry.protocols;
    • the __protocol_type__ requirement is documented;
    • Handled Refusals names the explicit-CaughtByCaller case.
  • Rebase. It is rebased past feat(application): dissect RFC 9146 connection-ID DTLS records #2631 with a mechanical import merge; the patch-id outside dtls.py is unchanged.

@JarryShaw
JarryShaw merged commit 4665f45 into main Nov 2, 2026
59 of 61 checks passed
@github-project-automation github-project-automation Bot moved this to Done in PyPCAPKit Nov 2, 2026
@JarryShaw
JarryShaw deleted the refactor/2622-dtls-analysis branch November 2, 2026 05:44
@JarryShaw JarryShaw removed the review: good-to-go Cross-review at the current head says ready; CI state is separate label Nov 2, 2026
JarryShaw added a commit that referenced this pull request Nov 2, 2026
…types and the registry split into 1.6.0 (#2449)

- Breaking: Quick-Start values their fields cannot carry raise, reversing
  1.5.0's round-down of a TCP rate under 80 kbps (#2630).
- Folded into unreleased entries: tls12_cid records and DTLSContext
  (#2631), LinkType 105 and 127 in Frame and PCAP-NG (#2632), and
  DTLS.analyze_handshake behind dtls_handshake and packet (#2634).
- Changed: foundation.registry.protocols split into per-layer submodules
  (#2635); 1.6.0's register_* roles and 1.5.0's three register_protocol*
  roles point at their submodules, 1.5.0's text unchanged.
- The conventions entry records the per-layer wrapper placement (#2635)
  and parse ownership (#2634). No entry for #2629, which changes no
  released behaviour.
- CHANGELOG.md regenerated; util/changelog_md.py --check passes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

refactor Restructuring for its own sake — neither a fix nor a new capability (refactor: prefix)

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

refactor(analysis): DTLS's foundation analysis wraps a DTLS protocol method, and the analysis convention is written down

1 participant