feat(internet): add IGMPv1/IGMPv2 as concrete classes over an abstract base

docs/source/contributing/pep.rst

@@ -41,7 +41,7 @@ one. Grouped by each TCP/IP layer and ordered by protocol name alphabetically,
 the ones outstanding are,
 
 * Link Layer: DSL, EAPOL, FDDI, ISDN, NDP, PPP
-* Internet Layer: ECN, ICMP, ICMPv6, IGMP, Shim6
+* Internet Layer: ECN, ICMP, ICMPv6, Shim6
 * Transport Layer: DCCP, RSVP
 * Application Layer: BGP, DHCP, DHCPv6, DNS, IMAP, LDAP, MQTT, NNTP,
   NTP, ONC/RPC, POP, QUIC, RIP, RTP, SIP, SMTP, SNMP, SSH, Telnet,
@@ -361,8 +361,8 @@ Follow-ups to the bindings above:
   port number. That depends on the proxy identifying the version positively
   instead of guessing, since a guess path is wrong on non-HTTP input.
 
-Beyond those, the gaps most likely to be met in a real capture are ICMP (1),
-ICMPv6 (58) and IGMP (2) on the internet layer, each of which has a stub.
+Beyond those, the gaps most likely to be met in a real capture are ICMP (1)
+and ICMPv6 (58) on the internet layer, each of which has a stub.
 
 PCAPNG Support
 --------------
@@ -1087,6 +1087,12 @@ question is the design work and doing either half of a pair alone would answer i
 twice. **DCCP** is the transport-layer implementation, tracked by :issue:`2489`, and
 blocked on :issue:`2479` for its pseudo-header checksum.
 
+**IGMP v1/v2 — done within wave 2** (:issue:`2439`).
+The versioned classes :class:`IGMPv1 <pcapkit.protocols.internet.igmpv1.IGMP>` and
+:class:`IGMPv2 <pcapkit.protocols.internet.igmpv2.IGMP>` share one read path on the
+abstract :class:`~pcapkit.protocols.internet.igmp.IGMP` base.
+:rfc:`3376` IGMPv3 is :issue:`2448`.
+
 **Done within wave 2 — TLS/SSL with DTLS.** The `DTLS`_ section above lists
 what is decoded (the shared :class:`~pcapkit.protocols.application.ssl.SSL`
 base, TLS, DTLS, and handshake message framing) and what is not (DTLS
@@ -1125,9 +1131,10 @@ above, which describes the payloads in question and why a registry of their own
 is wanted instead of
 :meth:`~pcapkit.protocols.protocol.Protocol._decode_next_layer`. It is
 sequenced *after* wave 2 rather than by preference: the multicast options embed
-:rfc:`3810` MLD, which rides in **ICMPv6**, and :rfc:`3376` **IGMP** records —
-both wave 2 deliverables. Landing the registry first would give a dispatch table
-with nothing but :class:`~pcapkit.protocols.misc.raw.Raw` to register. The
+:rfc:`3810` MLD, which rides in **ICMPv6**, and :rfc:`3376` **IGMPv3** group
+records — ICMPv6 a wave 2 deliverable, IGMPv3 :issue:`2448`. Landing the
+registry first would give a dispatch table with nothing but
+:class:`~pcapkit.protocols.misc.raw.Raw` to register. The
 counter-argument is real though, and worth weighing rather than dismissing: changing the
 parsed shape from :obj:`bytes` to :class:`~pcapkit.protocols.misc.raw.Raw` is the
 disruptive half, since it changes what existing captures dump to, so there is a case for

docs/source/ext.rst

@@ -71,6 +71,12 @@ The protocol classes :mod:`pcapkit` ships:
 |                                                                  | :class:`pcapkit.protocols.internet.ipx.IPX`                                                          |
 +                                                                  +----------------+-----------------------+-------------------------------------------------------------+
 |                                                                  | :class:`pcapkit.protocols.internet.hip.HIP`                                                          |
++                                                                  +----------------+-----------------------+-------------------------------------------------------------+
+|                                                                  |                | :class:`pcapkit.protocols.internet.igmp.IGMP`                                       |
++                                                                  +                +-----------------------+-------------------------------------------------------------+
+|                                                                  | IGMP Family    | :class:`pcapkit.protocols.internet.igmpv1.IGMP`                                     |
++                                                                  +                +-----------------------+-------------------------------------------------------------+
+|                                                                  |                | :class:`pcapkit.protocols.internet.igmpv2.IGMP`                                     |
 +------------------------------------------------------------------+----------------+-----------------------+-------------------------------------------------------------+
 | Transport Layer                                                  | :class:`pcapkit.protocols.transport.tcp.TCP`                                                         |
 + (:class:`~pcapkit.protocols.transport.transport.Transport`       +----------------+-----------------------+-------------------------------------------------------------+

docs/source/pcapkit/const/igmp.rst

@@ -0,0 +1,31 @@
+====================================================================
+:class:`~pcapkit.protocols.internet.igmp.IGMP` Constant Enumerations
+====================================================================
+
+.. module:: pcapkit.const.igmp
+
+This module contains all constant enumerations of
+:class:`~pcapkit.protocols.internet.igmp.IGMP` implementations. Available
+enumerations include:
+
+.. list-table::
+
+   * - :class:`IGMP_Type <pcapkit.const.igmp.type.Type>`
+     - IGMP Type Numbers [*]_
+
+IGMP Type Numbers
+=================
+
+.. module:: pcapkit.const.igmp.type
+
+This module contains the constant enumeration for **IGMP Type Numbers**,
+which is automatically generated from :class:`pcapkit.vendor.igmp.type.Type`.
+
+.. autoclass:: pcapkit.const.igmp.type.Type
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. rubric:: Footnotes
+
+.. [*] https://www.iana.org/assignments/igmp-type-numbers/igmp-type-numbers.xhtml

docs/source/pcapkit/const/index.rst

@@ -80,6 +80,7 @@ Internet Layer
 
    esp
    hip
+   igmp
    ipv4
    ipv6
    ipx

docs/source/pcapkit/protocols/index.rst

@@ -83,7 +83,7 @@ from given information. The class hierarchy of :mod:`pcapkit.protocols`:
        end
 
        subgraph internet [Internet Layer]
-           Internet --> IPX & IP & IPsec & IPv6_Ext
+           Internet --> IPX & IP & IPsec & IPv6_Ext & IGMP
 
            subgraph ip [IP Family]
                IP --> IPv4 & IPv6
@@ -96,6 +96,10 @@ from given information. The class hierarchy of :mod:`pcapkit.protocols`:
            subgraph ipv6ext [IPv6 Extension Header]
                IPv6_Ext --> IPv6-Frag & IPv6-Opts & IPv6-Route & HOPOPT & MH & HIP
            end
+
+           subgraph igmp [IGMP Family]
+               IGMP --> IGMPv1 & IGMPv2
+           end
        end
 
        subgraph transport [Transport Layer]
@@ -135,6 +139,9 @@ from given information. The class hierarchy of :mod:`pcapkit.protocols`:
        click AH "internet/ah.html#pcapkit.protocols.internet.ah.AH"
        click ESP "internet/esp.html#pcapkit.protocols.internet.esp.ESP"
        click HIP "internet/hip.html#pcapkit.protocols.internet.hip.HIP"
+       click IGMP "internet/igmp.html#pcapkit.protocols.internet.igmp.IGMP"
+       click IGMPv1 "internet/igmpv1.html#pcapkit.protocols.internet.igmpv1.IGMP"
+       click IGMPv2 "internet/igmpv2.html#pcapkit.protocols.internet.igmpv2.IGMP"
        click HOPOPT "internet/hopopt.html#pcapkit.protocols.internet.hopopt.HOPOPT"
        click IP "internet/ip.html#pcapkit.protocols.internet.ip.IP"
        click IPsec "internet/ipsec.html#pcapkit.protocols.internet.ipsec.IPsec"

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

@@ -0,0 +1,59 @@
+IGMP - Internet Group Management Protocol
+==========================================
+
+.. module:: pcapkit.protocols.internet.igmp
+
+:mod:`pcapkit.protocols.internet.igmp` contains
+:class:`~pcapkit.protocols.internet.igmp.IGMP`, the abstract base of the
+Internet Group Management Protocol (IGMP) [*]_ versions 1 and 2. Both share
+the 8-octet structure below. :class:`IGMPv1 <pcapkit.protocols.internet.igmpv1.IGMP>`
+and :class:`IGMPv2 <pcapkit.protocols.internet.igmpv2.IGMP>` set :attr:`version`,
+and :attr:`alias` names the version of each message.
+
+======= ========= ========================= ===================================
+Octets      Bits        Name                    Description
+======= ========= ========================= ===================================
+  0           0   ``igmp.type``             Type
+  1           8   ``igmp.max_resp_time``    Max Response Time
+  2          16   ``igmp.checksum``         Checksum
+  4          32   ``igmp.group``            Group Address
+======= ========= ========================= ===================================
+
+.. autoclass:: pcapkit.protocols.internet.igmp.IGMP
+   :no-members:
+   :show-inheritance:
+
+   .. autoproperty:: name
+   .. autoproperty:: version
+   .. autoproperty:: alias
+   .. autoproperty:: length
+
+   .. automethod:: read
+   .. automethod:: make
+
+   .. automethod:: __index__
+
+   .. automethod:: _classify
+   .. automethod:: _make_data
+
+Header Schemas
+--------------
+
+.. module:: pcapkit.protocols.schema.internet.igmp
+
+.. autoclass:: pcapkit.protocols.schema.internet.igmp.IGMP
+   :members:
+   :show-inheritance:
+
+Data Models
+-----------
+
+.. module:: pcapkit.protocols.data.internet.igmp
+
+.. autoclass:: pcapkit.protocols.data.internet.igmp.IGMP
+   :members:
+   :show-inheritance:
+
+.. rubric:: Footnotes
+
+.. [*] https://en.wikipedia.org/wiki/Internet_Group_Management_Protocol

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

@@ -0,0 +1,22 @@
+IGMPv1 - Internet Group Management Protocol version 1
+=============================================================
+
+.. module:: pcapkit.protocols.internet.igmpv1
+
+:mod:`pcapkit.protocols.internet.igmpv1` contains
+:class:`~pcapkit.protocols.internet.igmpv1.IGMP`, which implements an
+extractor for Internet Group Management Protocol version 1 (IGMPv1)
+[:rfc:`1112`]. It shares its header schema and data model with
+:class:`IGMPv2 <pcapkit.protocols.internet.igmpv2.IGMP>` -- see
+:mod:`~pcapkit.protocols.internet.igmp` for both.
+
+.. autoclass:: pcapkit.protocols.internet.igmpv1.IGMP
+   :no-members:
+   :show-inheritance:
+
+   .. autoproperty:: version
+   .. autoproperty:: alias
+
+   .. automethod:: id
+
+   .. automethod:: read

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

@@ -0,0 +1,22 @@
+IGMPv2 - Internet Group Management Protocol version 2
+=============================================================
+
+.. module:: pcapkit.protocols.internet.igmpv2
+
+:mod:`pcapkit.protocols.internet.igmpv2` contains
+:class:`~pcapkit.protocols.internet.igmpv2.IGMP`, which implements an
+extractor for Internet Group Management Protocol version 2 (IGMPv2)
+[:rfc:`2236`]. It shares its header schema and data model with
+:class:`IGMPv1 <pcapkit.protocols.internet.igmpv1.IGMP>` -- see
+:mod:`~pcapkit.protocols.internet.igmp` for both.
+
+.. autoclass:: pcapkit.protocols.internet.igmpv2.IGMP
+   :no-members:
+   :show-inheritance:
+
+   .. autoproperty:: version
+   .. autoproperty:: alias
+
+   .. automethod:: id
+
+   .. automethod:: read

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

@@ -26,11 +26,14 @@ internet layer, with detailed implementation and methods.
    ah
    esp
    hip
+   igmp
+   igmpv1
+   igmpv2
    ipx
 
 .. todo::
 
-   Implement ECN, ICMP, ICMPv6, IGMP, Shim6.
+   Implement ECN, ICMP, ICMPv6, Shim6.
 
 Protocol Registry
 -----------------

docs/source/pcapkit/vendor/igmp.rst

@@ -0,0 +1,30 @@
+==============================================================
+:class:`~pcapkit.protocols.internet.igmp.IGMP` Vendor Crawlers
+==============================================================
+
+.. module:: pcapkit.vendor.igmp
+
+This module contains all vendor crawlers of
+:class:`~pcapkit.protocols.internet.igmp.IGMP` implementations. Available
+vendor crawlers include:
+
+.. list-table::
+
+   * - :class:`IGMP_Type <pcapkit.vendor.igmp.type.Type>`
+     - IGMP Type Numbers [*]_
+
+IGMP Type Numbers
+=================
+
+.. module:: pcapkit.vendor.igmp.type
+
+This module contains the vendor crawler for **IGMP Type Numbers**,
+which is automatically generating :class:`pcapkit.const.igmp.type.Type`.
+
+.. autoclass:: pcapkit.vendor.igmp.type.Type
+   :members: FLAG, LINK
+   :show-inheritance:
+
+.. rubric:: Footnotes
+
+.. [*] https://www.iana.org/assignments/igmp-type-numbers/igmp-type-numbers.xhtml

docs/source/pcapkit/vendor/index.rst

@@ -55,6 +55,7 @@ Internet Layer
 
    esp
    hip
+   igmp
    ipv4
    ipv6
    ipx

examples/generators/dispatch.py

@@ -71,6 +71,7 @@
 """
 from __future__ import annotations
 
+import inspect
 import os
 import pathlib
 import struct
@@ -341,8 +342,10 @@ def _link_build(code: 'int') -> 'Any':
 # Internet -- TransType.
 ###############################################################################
 
-#: Codes dispatched over an IPv4 outer header.
-_INTERNET_OVER_IPV4 = frozenset({4, 6, 17, 50, 51, 89, 111, 132})
+#: Codes dispatched over an IPv4 outer header. IGMP (2) is canonically
+#: IPv4-only -- multicast's IPv6 equivalent is MLD, which rides in ICMPv6
+#: rather than as its own IP protocol number (#2439).
+_INTERNET_OVER_IPV4 = frozenset({2, 4, 6, 17, 50, 51, 89, 111, 132})
 
 
 def _internet_registry() -> 'Any':
@@ -380,6 +383,14 @@ def _internet_payload(code: 'int') -> 'bytes':
         from pcapkit.protocols.internet.ah import AH
         return bytes(AH(next=TransType.TCP, spi=0x1234, seq=1, icv=b'\x00' * 12,
                         payload=_tcp(9999)))
+    if code == TransType.IGMP:
+        from pcapkit.const.igmp.type import Type
+        from pcapkit.protocols.internet.igmpv2 import IGMP
+
+        # A General Query: an IGMPv1/v2 message is the 8-octet header and
+        # nothing else, so there is no further payload to wrap. A nonzero
+        # max_resp_time makes it IGMPv2, the class IGMP dispatches it to.
+        return bytes(IGMP(type=Type.IGMP_Membership_Query, max_resp_time=100, group='0.0.0.0'))
     if code == TransType.IPv6_NoNxt:
         # The registered target for this code *is* Raw -- there is no
         # dissector to hand it, "no next header" is the whole point -- so any
@@ -674,6 +685,7 @@ def _link_enum() -> 'Any':
     'internet/IPv6_Frag': ('pcapkit.protocols.internet.ipv6_frag', 'IPv6_Frag'),
     'internet/ESP': ('pcapkit.protocols.internet.esp', 'ESP'),
     'internet/AH': ('pcapkit.protocols.internet.ah', 'AH'),
+    'internet/IGMP': ('pcapkit.protocols.internet.igmp', 'IGMP'),
     'internet/IPv6_NoNxt': ('pcapkit.protocols.misc.raw', 'Raw'),
     'internet/IPv6_Opts': ('pcapkit.protocols.internet.ipv6_opts', 'IPv6_Opts'),
     'internet/IPX_in_IP': ('pcapkit.protocols.internet.ipx', 'IPX'),
@@ -908,7 +920,11 @@ def probe(case: 'Case') -> 'Outcome':
     # protochain`` on the string alone, even though no AH instance exists
     # anywhere in the chain. ``.protocols`` holds the actual ``type(instance)``
     # for each layer, which that substitution cannot spoof.
-    reached = case.target in frame.protochain.protocols
+    # An abstract target is a dispatcher: the chain holds the concrete class it
+    # picked, so a subclass of it counts as reaching it (IGMP -> IGMPv1/IGMPv2).
+    reached = any(klass is case.target
+                  or (inspect.isabstract(case.target) and issubclass(klass, case.target))
+                  for klass in frame.protochain.protocols)
     error = '' if reached else _find_error(frame.info.to_dict())
     return Outcome(case, chain, reached, '', error)
 

pcapkit/__init__.py

@@ -114,7 +114,8 @@
     'ARP', 'C_Tag', 'Ethernet', 'InARP', 'L2TP',            # Link Layer
     'L2TPv2', 'LinuxSLL', 'LinuxSLL1', 'LinuxSLL2', 'Loopback', 'S_Tag', 'VLAN',
 
-    'AH', 'ESP', 'IP', 'IPsec', 'IPv4', 'IPv6', 'IPX',      # Internet Layer
+    'AH', 'ESP', 'IGMP', 'IGMPv1', 'IGMPv2',                # Internet Layer
+    'IP', 'IPsec', 'IPv4', 'IPv6', 'IPX',
     'HIP', 'HOPOPT', 'IPv6_Frag', 'IPv6_Ext', 'IPv6_Opts', 'IPv6_Route', 'MH',
                                                             # IPv6 Extension Header
 

pcapkit/all.py

@@ -121,7 +121,8 @@
     'Raw',                                                  # Raw Packet
     'ARP', 'C_Tag', 'Ethernet', 'InARP', 'L2TP', 'L2TPv2', 'LinuxSLL', 'LinuxSLL1',
     'LinuxSLL2', 'Loopback', 'S_Tag', 'VLAN',               # Link Layer
-    'AH', 'ESP', 'IP', 'IPsec', 'IPv4', 'IPv6', 'IPX',      # Internet Layer
+    'AH', 'ESP', 'IGMP', 'IGMPv1', 'IGMPv2',                # Internet Layer
+    'IP', 'IPsec', 'IPv4', 'IPv6', 'IPX',
     'HIP', 'HOPOPT', 'IPv6_Ext', 'IPv6_Frag', 'IPv6_Opts', 'IPv6_Route', 'MH',
                                                             # IPv6 Extension Header
     'TCP', 'UDP', 'SCTP',                                   # Transport Layer

pcapkit/const/__init__.py

@@ -20,6 +20,7 @@
 from pcapkit.const.ftp import *
 from pcapkit.const.hip import *
 from pcapkit.const.http import *
+from pcapkit.const.igmp import *
 from pcapkit.const.ipv4 import *
 from pcapkit.const.ipv6 import *
 from pcapkit.const.ipx import *
@@ -48,6 +49,8 @@
     'HIP_Suite', 'HIP_Transport', 'HIP_EdDSACurve',
     # HTTP
     'HTTP_ErrorCode', 'HTTP_Frame', 'HTTP_Method', 'HTTP_Setting', 'HTTP_Status',
+    # IGMP
+    'IGMP_Type',
     # IPv4
     'IPv4_ClassificationLevel', 'IPv4_OptionClass', 'IPv4_OptionNumber', 'IPv4_ProtectionAuthority',
     'IPv4_QSFunction', 'IPv4_RouterAlert', 'IPv4_ToSDelay', 'IPv4_ToSECN', 'IPv4_ToSPrecedence',