Skip to content

Commit e4584a4

Browse files
JarryShawJarryShaw
committed
feat(internet): add IGMPv1/IGMPv2 with one shared read path (#2439)
- pcapkit/protocols/internet/igmp.py: IGMP, registered at TransType.IGMP, reads both versions itself. _classify decides the version; one error path refuses other types and non-8-octet Queries (RFC 9776 s7.1), so IPv4 falls back to Raw. alias is dynamic, set from the parsed version. - igmpv1.py / igmpv2.py: IGMP pinned to one version via _pinned; read, make and data mapping are inherited, not duplicated. - Schema, data model, IANA Type registry, docs and tests added.
1 parent b6efe66 commit e4584a4

39 files changed

Lines changed: 1497 additions & 31 deletions

‎docs/source/contributing/pep.rst‎

Lines changed: 17 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ one. Grouped by each TCP/IP layer and ordered by protocol name alphabetically,
4141
the ones outstanding are,
4242

4343
* Link Layer: DSL, EAPOL, FDDI, ISDN, LINUX_SLL, LINUX_SLL2, NDP, PPP
44-
* Internet Layer: ECN, ICMP, ICMPv6, IGMP, Shim6
44+
* Internet Layer: ECN, ICMP, ICMPv6, Shim6
4545
* Transport Layer: DCCP, RSVP
4646
* Application Layer: BGP, DHCP, DHCPv6, DNS, IMAP, LDAP, MQTT, NNTP,
4747
NTP, ONC/RPC, POP, QUIC, RIP, RTP, SIP, SMTP, SNMP, SSH, Telnet,
@@ -362,8 +362,8 @@ Follow-ups to the bindings above:
362362
port number. That depends on the proxy identifying the version positively
363363
instead of guessing, since a guess path is wrong on non-HTTP input.
364364

365-
Beyond those, the gaps most likely to be met in a real capture are ICMP (1),
366-
ICMPv6 (58) and IGMP (2) on the internet layer, each of which has a stub;
365+
Beyond those, the gaps most likely to be met in a real capture are ICMP (1)
366+
and ICMPv6 (58) on the internet layer, each of which has a stub;
367367
and ``LINUX_SLL`` and ``LINUX_SLL2`` at the link layer, which every
368368
``tcpdump -i any`` capture uses and which have no stub.
369369

@@ -1085,11 +1085,16 @@ Steps`_ above.
10851085

10861086
**Wave 2 — the protocol pairs that want a shared abstract base**, per `More
10871087
Protocols, More!!!`_ above: **ICMP with ICMPv6**, **TLS/SSL with DTLS**, and
1088-
``LINUX_SLL`` with ``LINUX_SLL2``, plus **IGMP** on its own. These are grouped
1089-
because the shared-base question is the design work and doing either half of a
1090-
pair alone would answer it twice. ``LINUX_SLL`` matters out of proportion to its
1091-
size: every ``tcpdump -i any`` capture uses it, and neither variant has even a
1092-
stub.
1088+
``LINUX_SLL`` with ``LINUX_SLL2``. These are grouped because the shared-base
1089+
question is the design work and doing either half of a pair alone would
1090+
answer it twice. ``LINUX_SLL`` matters out of proportion to its size: every
1091+
``tcpdump -i any`` capture uses it, and neither variant has even a stub.
1092+
1093+
**IGMP v1/v2 — done within wave 2** (:issue:`2439`).
1094+
:class:`~pcapkit.protocols.internet.igmp.IGMP` reads both versions through one
1095+
path, with ``alias`` naming the version; the versioned classes are that class
1096+
pinned to one version.
1097+
:rfc:`3376` IGMPv3 is :issue:`2448`.
10931098

10941099
**Done within wave 2 — TLS/SSL with DTLS.** The `DTLS`_ section above lists
10951100
what is decoded (the shared :class:`~pcapkit.protocols.application.ssl.SSL`
@@ -1122,9 +1127,10 @@ above, which describes the payloads in question and why a registry of their own
11221127
is wanted instead of
11231128
:meth:`~pcapkit.protocols.protocol.Protocol._decode_next_layer`. It is
11241129
sequenced *after* wave 2 rather than by preference: the multicast options embed
1125-
:rfc:`3810` MLD, which rides in **ICMPv6**, and :rfc:`3376` **IGMP** records —
1126-
both wave 2 deliverables. Landing the registry first would give a dispatch table
1127-
with nothing but :class:`~pcapkit.protocols.misc.raw.Raw` to register. The
1130+
:rfc:`3810` MLD, which rides in **ICMPv6**, and :rfc:`3376` **IGMPv3** group
1131+
records — ICMPv6 a wave 2 deliverable, IGMPv3 :issue:`2448`. Landing the
1132+
registry first would give a dispatch table with nothing but
1133+
:class:`~pcapkit.protocols.misc.raw.Raw` to register. The
11281134
counter-argument is real though, and worth weighing rather than dismissing: changing the
11291135
parsed shape from :obj:`bytes` to :class:`~pcapkit.protocols.misc.raw.Raw` is the
11301136
disruptive half, since it changes what existing captures dump to, so there is a case for

‎docs/source/ext.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,12 @@ The protocol classes :mod:`pcapkit` ships:
6565
| | :class:`pcapkit.protocols.internet.ipx.IPX` |
6666
+ +----------------+-----------------------+-------------------------------------------------------------+
6767
| | :class:`pcapkit.protocols.internet.hip.HIP` |
68+
+ +----------------+-----------------------+-------------------------------------------------------------+
69+
| | | :class:`pcapkit.protocols.internet.igmp.IGMP` |
70+
+ + +-----------------------+-------------------------------------------------------------+
71+
| | IGMP Family | :class:`pcapkit.protocols.internet.igmpv1.IGMP` |
72+
+ + +-----------------------+-------------------------------------------------------------+
73+
| | | :class:`pcapkit.protocols.internet.igmpv2.IGMP` |
6874
+------------------------------------------------------------------+----------------+-----------------------+-------------------------------------------------------------+
6975
| Transport Layer | :class:`pcapkit.protocols.transport.tcp.TCP` |
7076
+ (:class:`~pcapkit.protocols.transport.transport.Transport` +----------------+-----------------------+-------------------------------------------------------------+

‎docs/source/pcapkit/const/igmp.rst‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
====================================================================
2+
:class:`~pcapkit.protocols.internet.igmp.IGMP` Constant Enumerations
3+
====================================================================
4+
5+
.. module:: pcapkit.const.igmp
6+
7+
This module contains all constant enumerations of
8+
:class:`~pcapkit.protocols.internet.igmp.IGMP` implementations. Available
9+
enumerations include:
10+
11+
.. list-table::
12+
13+
* - :class:`IGMP_Type <pcapkit.const.igmp.type.Type>`
14+
- IGMP Type Numbers [*]_
15+
16+
IGMP Type Numbers
17+
=================
18+
19+
.. module:: pcapkit.const.igmp.type
20+
21+
This module contains the constant enumeration for **IGMP Type Numbers**,
22+
which is automatically generated from :class:`pcapkit.vendor.igmp.type.Type`.
23+
24+
.. autoclass:: pcapkit.const.igmp.type.Type
25+
:members:
26+
:undoc-members:
27+
:show-inheritance:
28+
29+
.. rubric:: Footnotes
30+
31+
.. [*] https://www.iana.org/assignments/igmp-type-numbers/igmp-type-numbers.xhtml

‎docs/source/pcapkit/const/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,7 @@ Internet Layer
8080

8181
esp
8282
hip
83+
igmp
8384
ipv4
8485
ipv6
8586
ipx

‎docs/source/pcapkit/protocols/index.rst‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@ from given information. The class hierarchy of :mod:`pcapkit.protocols`:
7979
end
8080

8181
subgraph internet [Internet Layer]
82-
Internet --> IPX & IP & IPsec & IPv6_Ext
82+
Internet --> IPX & IP & IPsec & IPv6_Ext & IGMP
8383

8484
subgraph ip [IP Family]
8585
IP --> IPv4 & IPv6
@@ -92,6 +92,10 @@ from given information. The class hierarchy of :mod:`pcapkit.protocols`:
9292
subgraph ipv6ext [IPv6 Extension Header]
9393
IPv6_Ext --> IPv6-Frag & IPv6-Opts & IPv6-Route & HOPOPT & MH & HIP
9494
end
95+
96+
subgraph igmp [IGMP Family]
97+
IGMP --> IGMPv1 & IGMPv2
98+
end
9599
end
96100

97101
subgraph transport [Transport Layer]
@@ -128,6 +132,9 @@ from given information. The class hierarchy of :mod:`pcapkit.protocols`:
128132
click AH "internet/ah.html#pcapkit.protocols.internet.ah.AH"
129133
click ESP "internet/esp.html#pcapkit.protocols.internet.esp.ESP"
130134
click HIP "internet/hip.html#pcapkit.protocols.internet.hip.HIP"
135+
click IGMP "internet/igmp.html#pcapkit.protocols.internet.igmp.IGMP"
136+
click IGMPv1 "internet/igmpv1.html#pcapkit.protocols.internet.igmpv1.IGMP"
137+
click IGMPv2 "internet/igmpv2.html#pcapkit.protocols.internet.igmpv2.IGMP"
131138
click HOPOPT "internet/hopopt.html#pcapkit.protocols.internet.hopopt.HOPOPT"
132139
click IP "internet/ip.html#pcapkit.protocols.internet.ip.IP"
133140
click IPsec "internet/ipsec.html#pcapkit.protocols.internet.ipsec.IPsec"

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

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
IGMP - Internet Group Management Protocol
2+
==========================================
3+
4+
.. module:: pcapkit.protocols.internet.igmp
5+
6+
:mod:`pcapkit.protocols.internet.igmp` contains
7+
:class:`~pcapkit.protocols.internet.igmp.IGMP`, the entry point and shared
8+
parser of the Internet Group Management Protocol (IGMP) [*]_ family. IGMPv1
9+
and IGMPv2 share the 8-octet structure below, and :attr:`alias` names the
10+
version of each message; :class:`IGMPv1 <pcapkit.protocols.internet.igmpv1.IGMP>`
11+
and :class:`IGMPv2 <pcapkit.protocols.internet.igmpv2.IGMP>` pin this class to
12+
one version.
13+
14+
======= ========= ========================= ===================================
15+
Octets Bits Name Description
16+
======= ========= ========================= ===================================
17+
0 0 ``igmp.type`` Type
18+
1 8 ``igmp.max_resp_time`` Max Response Time
19+
2 16 ``igmp.checksum`` Checksum
20+
4 32 ``igmp.group`` Group Address
21+
======= ========= ========================= ===================================
22+
23+
.. autoclass:: pcapkit.protocols.internet.igmp.IGMP
24+
:no-members:
25+
:show-inheritance:
26+
27+
.. autoproperty:: name
28+
.. autoproperty:: alias
29+
.. autoproperty:: length
30+
31+
.. automethod:: id
32+
33+
.. automethod:: read
34+
.. automethod:: make
35+
36+
.. automethod:: _classify
37+
38+
.. automethod:: _make_data
39+
40+
.. automethod:: __index__
41+
42+
Header Schemas
43+
--------------
44+
45+
.. module:: pcapkit.protocols.schema.internet.igmp
46+
47+
.. autoclass:: pcapkit.protocols.schema.internet.igmp.IGMP
48+
:members:
49+
:show-inheritance:
50+
51+
Data Models
52+
-----------
53+
54+
.. module:: pcapkit.protocols.data.internet.igmp
55+
56+
.. autoclass:: pcapkit.protocols.data.internet.igmp.IGMP
57+
:members:
58+
:show-inheritance:
59+
60+
.. rubric:: Footnotes
61+
62+
.. [*] https://en.wikipedia.org/wiki/Internet_Group_Management_Protocol

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

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
IGMPv1 - Internet Group Management Protocol version 1
2+
=============================================================
3+
4+
.. module:: pcapkit.protocols.internet.igmpv1
5+
6+
:mod:`pcapkit.protocols.internet.igmpv1` contains
7+
:class:`~pcapkit.protocols.internet.igmpv1.IGMP`, which implements an
8+
extractor for Internet Group Management Protocol version 1 (IGMPv1)
9+
[:rfc:`1112`]. It shares its header schema and data model with
10+
:class:`IGMPv2 <pcapkit.protocols.internet.igmpv2.IGMP>` -- see
11+
:mod:`~pcapkit.protocols.internet.igmp` for both.
12+
13+
.. autoclass:: pcapkit.protocols.internet.igmpv1.IGMP
14+
:no-members:
15+
:show-inheritance:
16+
17+
.. autoproperty:: alias
18+
19+
.. automethod:: id
20+
21+
.. automethod:: read

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

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
IGMPv2 - Internet Group Management Protocol version 2
2+
=============================================================
3+
4+
.. module:: pcapkit.protocols.internet.igmpv2
5+
6+
:mod:`pcapkit.protocols.internet.igmpv2` contains
7+
:class:`~pcapkit.protocols.internet.igmpv2.IGMP`, which implements an
8+
extractor for Internet Group Management Protocol version 2 (IGMPv2)
9+
[:rfc:`2236`]. It shares its header schema and data model with
10+
:class:`IGMPv1 <pcapkit.protocols.internet.igmpv1.IGMP>` -- see
11+
:mod:`~pcapkit.protocols.internet.igmp` for both.
12+
13+
.. autoclass:: pcapkit.protocols.internet.igmpv2.IGMP
14+
:no-members:
15+
:show-inheritance:
16+
17+
.. autoproperty:: alias
18+
19+
.. automethod:: id
20+
21+
.. automethod:: read

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

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,11 +26,14 @@ internet layer, with detailed implementation and methods.
2626
ah
2727
esp
2828
hip
29+
igmp
30+
igmpv1
31+
igmpv2
2932
ipx
3033

3134
.. todo::
3235

33-
Implement ECN, ICMP, ICMPv6, IGMP, Shim6.
36+
Implement ECN, ICMP, ICMPv6, Shim6.
3437

3538
Protocol Registry
3639
-----------------

‎docs/source/pcapkit/vendor/igmp.rst‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
==============================================================
2+
:class:`~pcapkit.protocols.internet.igmp.IGMP` Vendor Crawlers
3+
==============================================================
4+
5+
.. module:: pcapkit.vendor.igmp
6+
7+
This module contains all vendor crawlers of
8+
:class:`~pcapkit.protocols.internet.igmp.IGMP` implementations. Available
9+
vendor crawlers include:
10+
11+
.. list-table::
12+
13+
* - :class:`IGMP_Type <pcapkit.vendor.igmp.type.Type>`
14+
- IGMP Type Numbers [*]_
15+
16+
IGMP Type Numbers
17+
=================
18+
19+
.. module:: pcapkit.vendor.igmp.type
20+
21+
This module contains the vendor crawler for **IGMP Type Numbers**,
22+
which is automatically generating :class:`pcapkit.const.igmp.type.Type`.
23+
24+
.. autoclass:: pcapkit.vendor.igmp.type.Type
25+
:members: FLAG, LINK
26+
:show-inheritance:
27+
28+
.. rubric:: Footnotes
29+
30+
.. [*] https://www.iana.org/assignments/igmp-type-numbers/igmp-type-numbers.xhtml

0 commit comments

Comments
 (0)