Skip to content

Commit e87eb83

Browse files
authored
refactor(protocols): every versioned family base dispatches on read, make and from_data (#2639)
1 parent b731a7b commit e87eb83

24 files changed

Lines changed: 1997 additions & 73 deletions

‎docs/source/contributing/conventions/protocol-family-grouping.rst‎

Lines changed: 66 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -96,13 +96,72 @@ that member alone, so no registry binds :class:`~pcapkit.protocols.internet.ip.I
9696
the registry only; parsing or building through a base directly is the rule below.
9797

9898
**A versioned family's base dispatches on both paths** (:issue:`2524`). Parsing
99-
octets through it, constructing it from fields and its ``from_data`` give the member
100-
the octets, fields or data model describe, never an instance of the base. In
101-
:class:`~pcapkit.protocols.application.http.HTTP`,
102-
:meth:`~pcapkit.protocols.application.http.HTTP._dispatch_version` picks the member
103-
from the octets, for a payload a transport port binds to HTTP as well, and
104-
:meth:`~pcapkit.protocols.application.http.HTTP._dispatch_fields` from the fields.
105-
The other versioned families are tracked on :issue:`2574`.
99+
octets through it, constructing it from fields and its ``from_data`` give a member,
100+
never an instance of the base, and a subclass of the base is constructed as itself.
101+
102+
**The member is the one the** ``version`` **keyword names, or else the one the octets
103+
or the data model carry, and never one a field picks.** ``version`` names the member
104+
on either path, unchecked against the octets it is given; where their format carries
105+
a version, the member's own parser refuses another's. Without it, octets give the
106+
member the version they carry, where the format has one, and ``from_data`` reads the
107+
data model's class or its ``version``, as the table below gives. No field picks a
108+
member, not even a field only one member takes, and no member is a default: fields
109+
without ``version`` raise :exc:`~pcapkit.utilities.exceptions.ProtocolError`, and a
110+
field the member does not take fails that member's own keyword check. Ruled on
111+
:issue:`2574`. A class built directly takes ``version`` as well, which must then be
112+
its own version: a member's, or, for a subclass outside the members, the one an IGMP
113+
class states in its ``version``, which a subclass of the other bases does not have.
114+
While parsing, the keyword is handed on unread, since an IP layer passes its own
115+
version under that name to the layer it carries.
116+
117+
.. list-table::
118+
:header-rows: 1
119+
:widths: 13 15 42 30
120+
121+
* - Base
122+
- ``version``
123+
- Octets without ``version``
124+
- ``from_data``
125+
* - :class:`~pcapkit.protocols.internet.igmp.IGMP`
126+
- ``1``, ``2``, ``3``
127+
- :meth:`~pcapkit.protocols.internet.igmp.IGMP._dispatch`: type, max response
128+
time and length, placed by
129+
:meth:`~pcapkit.protocols.internet.igmp.IGMP._classify`
130+
- ``version``, which each IGMP data model carries though no octet does,
131+
ruled on :issue:`2574`
132+
* - :class:`~pcapkit.protocols.internet.ip.IP`
133+
- ``4``, ``6``
134+
- the Version nibble
135+
- ``version``
136+
* - :class:`~pcapkit.protocols.internet.icmp.ICMP`
137+
- ``4``, ``6``
138+
- refused, below
139+
- the data model; a :obj:`dict` is refused
140+
* - :class:`~pcapkit.protocols.link.l2tp.L2TP`
141+
- ``2``
142+
- the version nibble
143+
- ``version``
144+
* - :class:`~pcapkit.protocols.link.linux_sll.LinuxSLL`
145+
- ``1``, ``2``
146+
- refused, below
147+
- the data model; a :obj:`dict` is refused
148+
149+
:class:`~pcapkit.protocols.application.http.HTTP` dispatches otherwise. Its octets
150+
go to :meth:`~pcapkit.protocols.application.http.HTTP._dispatch_version`, which reads
151+
the connection preface, a start line or a frame header, for a payload a transport
152+
port binds to HTTP as well. Without ``version``, its
153+
:meth:`~pcapkit.protocols.application.http.HTTP._dispatch_fields` picks by each
154+
member's own fields and builds ``HTTPv1`` from none, and its ``from_data`` reads the
155+
data model, or a :obj:`dict` by its ``receipt`` or ``sid``.
156+
157+
**Octets that carry no version are refused through the base without** ``version``
158+
(:issue:`2574`). An ICMP message and a Linux cooked-capture header have no version
159+
field: the enclosing layer names it, by IP protocol number 1 or 58 and by link type
160+
113 or 276, and those registries bind the members. So ``ICMP(...)`` and
161+
``LinuxSLL(...)`` on octets raise :exc:`~pcapkit.utilities.exceptions.ProtocolError`
162+
rather than guess, as does their ``from_data`` on a :obj:`dict`, whose keys pick no
163+
member. A version a family has no member for, such as L2TP's ``1`` (L2F) and ``3``,
164+
raises the same way.
106165

107166
**Octets neither version takes**, a frameless HTTP/2 connection preface among them,
108167
are :class:`~pcapkit.protocols.misc.raw.Raw` with no ``error`` on the transport path,

‎docs/source/pcapkit/protocols/internet/icmp.rst‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,23 @@ ICMP - Internet Control Message Protocol
88
which is a base class for Internet Control Message
99
Protocol (ICMP) protocol family [*]_, e.g.
1010
:class:`~pcapkit.protocols.internet.icmpv4.ICMPv4` and
11-
:class:`~pcapkit.protocols.internet.icmpv6.ICMPv6`.
11+
:class:`~pcapkit.protocols.internet.icmpv6.ICMPv6`. Constructing the base gives the
12+
one its ``version`` keyword names, from octets or from fields, and is refused
13+
without it, since an ICMP message carries no version of its own. Its
14+
:meth:`~pcapkit.protocols.internet.icmp.ICMP.from_data` gives the one whose data
15+
model it is handed (:issue:`2574`).
1216

1317
.. autoclass:: pcapkit.protocols.internet.icmp.ICMP
1418
:no-members:
1519
:show-inheritance:
1620

1721
.. automethod:: id
22+
.. automethod:: from_data
23+
24+
.. automethod:: __init__
25+
.. automethod:: __new__
26+
27+
.. automethod:: _member_of_version
1828

1929
.. rubric:: Footnotes
2030

‎docs/source/pcapkit/protocols/internet/igmp.rst‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,13 @@ data model as-is; IGMPv3's wire format differs materially by message, so
1515
instead -- see :doc:`igmpv3`.
1616
:attr:`~pcapkit.protocols.internet.igmp.IGMP.alias` names the protocol each
1717
message is read as: ``'IGMP'`` for IGMPv1, the name :rfc:`1112` gives it, and
18-
``'IGMPv2'`` or ``'IGMPv3'`` for the others.
18+
``'IGMPv2'`` or ``'IGMPv3'`` for the others. Constructing the base gives the
19+
version class its ``version`` keyword names; without it, octets give the class
20+
the message classifies as, and fields are refused. Its
21+
:meth:`~pcapkit.protocols.internet.igmp.IGMP.from_data` gives the class the
22+
``version`` of its data names: every IGMP data model carries one, ``1``, ``2`` or
23+
``3``, set by the class that read or built the message and on no octet, so an
24+
IGMPv1 and an IGMPv2 message read alike apart from it (:issue:`2574`).
1925

2026
The structure is keyed as for IGMPv1; an IGMPv2 message's keys start ``igmpv2``
2127
instead:
@@ -42,11 +48,16 @@ Octets Bits Name Description
4248

4349
.. automethod:: read
4450
.. automethod:: make
51+
.. automethod:: from_data
4552

4653
.. automethod:: __index__
54+
.. automethod:: __init__
55+
.. automethod:: __new__
4756

48-
.. automethod:: _classify
4957
.. automethod:: _make_data
58+
.. automethod:: _classify
59+
.. automethod:: _dispatch
60+
.. automethod:: _member_of_version
5061

5162
Header Schemas
5263
--------------

‎docs/source/pcapkit/protocols/internet/ip.rst‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,23 @@ IP - Internet Protocol
88
which is a base class for Internet Protocol (IP)
99
protocol family [*]_, e.g.
1010
:class:`~pcapkit.protocols.internet.ipv4.IPv4` and
11-
:class:`~pcapkit.protocols.internet.ipv6.IPv6`.
11+
:class:`~pcapkit.protocols.internet.ipv6.IPv6`. Constructing the base gives the one
12+
its ``version`` keyword names; without it, octets give the one their Version field
13+
names, and fields are refused. Its
14+
:meth:`~pcapkit.protocols.internet.ip.IP.from_data` reads the ``version`` of its
15+
data (:issue:`2574`).
1216

1317
.. autoclass:: pcapkit.protocols.internet.ip.IP
1418
:no-members:
1519
:show-inheritance:
1620

1721
.. automethod:: id
22+
.. automethod:: from_data
23+
24+
.. automethod:: __init__
25+
.. automethod:: __new__
26+
27+
.. automethod:: _member_of_version
1828

1929
.. rubric:: Footnotes
2030

‎docs/source/pcapkit/protocols/internet/ipv4.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ Octets Bits Name Description
4848

4949
.. automethod:: read
5050
.. automethod:: make
51+
.. automethod:: unpack
5152

5253
.. automethod:: _make_data
5354

‎docs/source/pcapkit/protocols/internet/ipv6.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ Octets Bits Name Description
3737

3838
.. automethod:: read
3939
.. automethod:: make
40+
.. automethod:: unpack
4041

4142
.. automethod:: _make_data
4243

‎docs/source/pcapkit/protocols/link/l2tp.rst‎

Lines changed: 19 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,12 @@ version's layout for every version.
3333
.. autoproperty:: info_name
3434

3535
.. automethod:: id
36+
.. automethod:: from_data
3637

3738
.. automethod:: __index__
39+
.. automethod:: __new__
40+
41+
.. automethod:: _member_of_version
3842

3943
Versions Not Implemented
4044
------------------------
@@ -60,15 +64,21 @@ since callers take element zero as canonical.
6064
Version Dispatch
6165
----------------
6266

63-
Nothing dispatches on the version nibble, because L2TPv2 is the only version
64-
implemented. Another would follow the precedent of
65-
:class:`~pcapkit.protocols.application.http.HTTP`, which reads a version and
66-
delegates to a per-version class. L2TP is the easier case:
67-
:meth:`HTTP._guess_version <pcapkit.protocols.application.http.HTTP._guess_version>`
68-
has to *infer* the version -- recognising the HTTP/2 preface or an HTTP/1 start
69-
line, else trial-parsing each candidate -- because HTTP's wire format carries no
70-
version field, whereas L2TP states its version explicitly in those four bits. A
71-
deterministic switch on ``Ver`` is enough, and no new registry is needed.
67+
Constructing the base gives the member its ``version`` field names, from octets or
68+
from fields; without it, octets give the one their version nibble names, and fields
69+
are refused, since no field picks a member (:issue:`2574`).
70+
:meth:`~pcapkit.protocols.link.l2tp.L2TP._member_of_version` maps ``2`` to
71+
:class:`~pcapkit.protocols.link.l2tpv2.L2TPv2` and refuses any other version, for
72+
that field, for the nibble and for the data
73+
:meth:`~pcapkit.protocols.link.l2tp.L2TP.from_data` is handed. UDP port 1701 binds
74+
L2TPv2 itself, the only member. The switch is where a further member goes, and
75+
binding the port to the base through a hook making the same switch, as
76+
:meth:`IGMP._dispatch <pcapkit.protocols.internet.igmp.IGMP._dispatch>` does for
77+
IP protocol 2, needs no new registry. L2TP is the easier case beside
78+
:class:`~pcapkit.protocols.application.http.HTTP`, whose
79+
:meth:`~pcapkit.protocols.application.http.HTTP._guess_version` has to *infer*
80+
the version, because HTTP's wire format carries no version field, whereas L2TP
81+
states its version explicitly in those four bits.
7282

7383
.. rubric:: Footnotes
7484

‎docs/source/pcapkit/protocols/link/linux_sll.rst‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,16 +19,25 @@ Linux "cooked" capture encapsulation family:
1919

2020
The versions differ in field order and width, so each parses its own header.
2121
The base holds what they share: the next-layer dispatch, and link-layer address
22-
validation. It has no registry index, so its ``__index__`` raises.
22+
validation. It has no registry index, so its ``__index__`` raises. Constructing
23+
the base gives the version its ``version`` keyword names, from octets or from
24+
fields, and is refused without it, since the link type rather than the header
25+
names the version. Its
26+
:meth:`~pcapkit.protocols.link.linux_sll.LinuxSLL.from_data` gives the version
27+
whose data model it is handed (:issue:`2574`).
2328

2429
.. autoclass:: pcapkit.protocols.link.linux_sll.LinuxSLL
2530
:no-members:
2631
:show-inheritance:
2732

2833
.. automethod:: id
2934
.. automethod:: register
35+
.. automethod:: from_data
3036
.. automethod:: __index__
37+
.. automethod:: __init__
38+
.. automethod:: __new__
3139
.. automethod:: _import_next_layer
40+
.. automethod:: _member_of_version
3241

3342
.. autoattribute:: __proto__
3443
:no-value:

‎pcapkit/protocols/data/internet/igmp.py‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@
99
if TYPE_CHECKING:
1010
from ipaddress import IPv4Address
1111

12+
from typing_extensions import Literal
13+
1214
from pcapkit.const.igmp.type import Type as Enum_Type
1315

1416
__all__ = ['IGMP']
@@ -27,6 +29,13 @@ class IGMP(Protocol):
2729
2830
"""
2931

32+
#: Version of IGMP the message was read as, ``1`` or ``2``: the
33+
#: :attr:`~pcapkit.protocols.internet.igmp.IGMP.version` of the class that
34+
#: read or built it. It is on no octet, since the versions share this
35+
#: layout, and :meth:`IGMP.from_data
36+
#: <pcapkit.protocols.internet.igmp.IGMP.from_data>` dispatches on it
37+
#: (:issue:`2574`).
38+
version: 'Literal[1, 2]'
3039
#: Message type.
3140
type: 'Enum_Type'
3241
#: Max response time, in units of 1/10 second. Meaningful only for a
@@ -41,5 +50,5 @@ class IGMP(Protocol):
4150
group: 'IPv4Address'
4251

4352
if TYPE_CHECKING:
44-
def __init__(self, type: 'Enum_Type', max_resp_time: 'int', checksum: 'bytes', # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin
45-
group: 'IPv4Address') -> 'None': ...
53+
def __init__(self, version: 'Literal[1, 2]', type: 'Enum_Type', max_resp_time: 'int', # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin
54+
checksum: 'bytes', group: 'IPv4Address') -> 'None': ...

‎pcapkit/protocols/data/internet/igmpv3.py‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@
1010
if TYPE_CHECKING:
1111
from ipaddress import IPv4Address
1212

13+
from typing_extensions import Literal
14+
1315
from pcapkit.const.igmp.record_type import RecordType as Enum_RecordType
1416
from pcapkit.const.igmp.type import Type as Enum_Type
1517

@@ -27,6 +29,11 @@ class IGMPv3(Protocol):
2729
2830
"""
2931

32+
#: Version of IGMP, always ``3``. It is on no octet: it names the class
33+
#: that read or built the message, as on the IGMPv1/v2 data model, and
34+
#: :meth:`IGMP.from_data <pcapkit.protocols.internet.igmp.IGMP.from_data>`
35+
#: dispatches on it (:issue:`2574`).
36+
version: 'Literal[3]'
3037
#: Message type.
3138
type: 'Enum_Type'
3239
#: Header length, in octets. IGMP has no header field of its own that
@@ -79,7 +86,7 @@ class Query(IGMPv3):
7986
sources: 'tuple[IPv4Address, ...]'
8087

8188
if TYPE_CHECKING:
82-
def __init__(self, type: 'Enum_Type', length: 'int', max_resp_code: 'int',
89+
def __init__(self, version: 'Literal[3]', type: 'Enum_Type', length: 'int', max_resp_code: 'int',
8390
max_resp_time: 'int', checksum: 'bytes', group: 'IPv4Address',
8491
resv: 'int', s_flag: 'bool', qrv: 'int', qqic: 'int', qqi: 'int',
8592
sources: 'tuple[IPv4Address, ...]') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin,line-too-long
@@ -128,6 +135,7 @@ class Report(IGMPv3):
128135
records: 'tuple[GroupRecord, ...]'
129136

130137
if TYPE_CHECKING:
131-
def __init__(self, type: 'Enum_Type', length: 'int', reserved_1: 'int', checksum: 'bytes',
138+
def __init__(self, version: 'Literal[3]', type: 'Enum_Type', length: 'int', reserved_1: 'int',
139+
checksum: 'bytes',
132140
reserved_2: 'bytes', num_group_records: 'int',
133141
records: 'tuple[GroupRecord, ...]') -> 'None': ... # pylint: disable=unused-argument,super-init-not-called,multiple-statements,redefined-builtin

0 commit comments

Comments
 (0)