Skip to content

Commit 759766b

Browse files
committed
docs(contributing): measure reassembly-integration compliance against IP/TCP/DTLS
1 parent 09126cd commit 759766b

1 file changed

Lines changed: 32 additions & 6 deletions

File tree

‎docs/source/contributing/conventions/reassembly-integration.rst‎

Lines changed: 32 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -22,10 +22,36 @@ The Rule
2222
message, accept overlaps -- the engine does the same and adds no timeout, cap or
2323
ordering rule the RFC does not call for.
2424

25-
.. note::
25+
Compliance, Measured
26+
~~~~~~~~~~~~~~~~~~~~~
2627

27-
This page records the ruling as given. Whether the existing :class:`IP
28-
<pcapkit.foundation.reassembly.ip.IP>` and :class:`TCP
29-
<pcapkit.foundation.reassembly.tcp.TCP>` engines already follow points 2 and 3, and
30-
what the DTLS engine (:mod:`pcapkit.foundation.reassembly.dtls`) needs to catch up,
31-
is a separate compliance question, tracked apart from this page.
28+
**Point 1 is an existing, enforced precedent.** Neither
29+
:class:`~pcapkit.protocols.internet.ipv4.IPv4` nor
30+
:class:`~pcapkit.protocols.internet.ipv6.IPv6` nor
31+
:class:`~pcapkit.protocols.transport.tcp.TCP` imports or calls into
32+
:mod:`pcapkit.foundation.reassembly` at all. The real path is
33+
:mod:`pcapkit.foundation.engines` calling a ``pcapkit.toolkit.<engine>`` extraction
34+
function on an already-parsed frame, feeding the result to the reassembly instance the
35+
:class:`~pcapkit.foundation.extraction.Extractor` holds.
36+
37+
**Points 2 and 3 describe infrastructure that does not exist yet, for any engine.**
38+
No single :mod:`pcapkit.toolkit` helper enumerates which output engines support a given
39+
reassembly engine -- support is established ad hoc, per engine backend, in three
40+
different shapes (define the extraction functions; define them raising
41+
:exc:`~pcapkit.utilities.exceptions.UnsupportedCall`; or disable reassembly at the
42+
engine level, as :mod:`pcapkit.foundation.engines.pyshark` does). No
43+
:mod:`pcapkit.foundation.analysis` module exists; what parses a reassembled outcome
44+
today is the pre-existing, general-purpose
45+
:meth:`Protocol.analyze <pcapkit.protocols.protocol.Protocol.analyze>` dispatcher,
46+
reused via :class:`~pcapkit.foundation.reassembly.data.data.Deferred`, not a method
47+
written for reassembly specifically. So points 2 and 3 are a forward-looking ask, not
48+
yet a pattern any engine follows.
49+
50+
**The DTLS reassembly work on** :pr:`2451` **violates point 1.**
51+
:class:`~pcapkit.protocols.application.dtls.DTLS` imports
52+
:class:`~pcapkit.foundation.reassembly.dtls.DTLS` directly and calls it from
53+
:meth:`DTLS.read`, which no other protocol class does. Its own module docstring notes
54+
the further divergence from the IP/TCP shape: it is "not toolkit-fed", reports its
55+
reassembled body eagerly instead of through a :class:`Deferred
56+
<pcapkit.foundation.reassembly.data.data.Deferred>`, and sets no
57+
``__protocol_type__``.

0 commit comments

Comments
 (0)