Skip to content

docs(protocols): repair the protocol pages and cut their restatement (#719) #1044

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JarryShaw merged 2 commits into from
Oct 5, 2026
Merged

docs(protocols): repair the protocol pages and cut their restatement (#719) #1044

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4352cce
docs(protocols): repair the protocol pages and cut their restatement …
JarryShaw Oct 5, 2026
af35550
docs(protocols): name the HTTP/1 start-line check in the L2TP page (#…
JarryShaw Oct 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 22 additions & 20 deletions docs/source/pcapkit/protocols/application/ngap.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,22 +25,24 @@ Decoding therefore needs the optional |pycrate|_ dependency
(``pip install pypcapkit[NGAP]``). :mod:`pcapkit` imports and works without
it; an NGAP payload simply degrades to the opaque payload path, exactly as an
unregistered PPID would, because
:meth:`SCTP._import_next_layer <pcapkit.protocols.transport.sctp.SCTP._import_next_layer>`
is wrapped in :func:`~pcapkit.utilities.decorators.beholder` and falls back to
:meth:`~pcapkit.protocols.protocol.Protocol._import_next_layer`, which
:class:`~pcapkit.protocols.transport.sctp.SCTP` inherits, is wrapped in
:func:`~pcapkit.utilities.decorators.beholder` and falls back to
:class:`~pcapkit.protocols.misc.raw.Raw`.

Why |pycrate|_ rather than a PER codec of our own
-------------------------------------------------
Decoder Dependency
------------------

Two things make it the cheaper answer. |pycrate|_ **ships NGAP already
compiled**, at ``pycrate_asn1dir/NGAP.py``, so the 3GPP ASN.1 source does not
have to be vendored here and tracked across releases; and it is **pure
Python**, with no compiled extension to build on any platform. Decoding costs
0.15 ms per PDU, the same order as :mod:`pcapkit`'s own per-packet cost, so
the generic strategy below is not paying for the convenience.
|pycrate|_ is used rather than a PER codec of our own, for two reasons. It
**ships NGAP already compiled**, at ``pycrate_asn1dir/NGAP.py``, so the 3GPP
ASN.1 source does not have to be vendored here and tracked across releases; and
it is **pure Python**, with no compiled extension to build on any platform.
Decoding costs 0.15 ms per PDU, the same order as :mod:`pcapkit`'s own
per-packet cost, so the generic strategy below is not paying for the
convenience.

Generic conversion, not 81 hand-written procedures
--------------------------------------------------
Generic Conversion
------------------

The decoded value tree is mapped into :class:`~pcapkit.corekit.infoclass.Info`
objects **structurally**, by ASN.1 shape rather than by procedure:
Expand All @@ -65,22 +67,22 @@ kind, procedure code, criticality, message type name and the IE list -- are
surfaced as first-class fields on
:class:`~pcapkit.protocols.data.application.ngap.NGAP` regardless.

Known limitations
Known Limitations
-----------------

* **PPID 66 payloads are not decoded.** ``NGAP_over_DTLS_over_SCTP`` wraps the
``NGAP-PDU`` in a DTLS record, and :mod:`pcapkit` implements no DTLS, so the
bytes reaching :meth:`NGAP.read` are not an APER encoding. The PPID is
registered so that it is *named* rather than anonymous; the payload itself
degrades to :class:`~pcapkit.protocols.misc.raw.Raw`.
* **The specification version is |pycrate|_'s, not this package's.** The IE and
procedure enumerations were generated from ``NGAP_Constants`` of |pycrate|_
0.8.1 (Release-18-era: 81 procedure codes, 438 protocol IE IDs, highest 443).
A |pycrate|_ that carries a newer NGAP will decode IEs that
* **The specification version is that of the installed decoder, not this
package's.** The IE and procedure enumerations were generated from
``NGAP_Constants`` of |pycrate|_ 0.8.1 (Release-18-era: 81 procedure codes,
438 protocol IE IDs, highest 443). A |pycrate|_ that carries a newer NGAP will decode IEs that
:class:`~pcapkit.protocols.application.ngap.ProcedureCode` and
:class:`~pcapkit.protocols.application.ngap.ProtocolIE` do not name; both
extend themselves at lookup time rather than failing, so such a value is
reported as ``Unassigned_<n>``.
:class:`~pcapkit.protocols.application.ngap.ProtocolIE` do not name. Such a
value resolves to a non-registering member called ``Unassigned`` rather than
failing or adding a member to either enumeration.
* **NGAP over a fragmented SCTP association is not reassembled.** A DATA chunk
is decoded on its own, so an ``NGAP-PDU`` split across chunks by SCTP
fragmentation fails to decode rather than being reassembled first.
Expand Down
14 changes: 7 additions & 7 deletions docs/source/pcapkit/protocols/application/ospf.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,19 +16,19 @@ as below:
====== ===== ================== ===============================
0 0 ``ospf.version`` Version Number
------ ----- ------------------ -------------------------------
0 0 ``ospf.type`` Type
1 8 ``ospf.type`` Type
------ ----- ------------------ -------------------------------
0 1 ``ospf.len`` Packet Length (header included)
2 16 ``ospf.len`` Packet Length (header included)
------ ----- ------------------ -------------------------------
0 2 ``ospf.router_id`` Router ID
4 32 ``ospf.router_id`` Router ID
------ ----- ------------------ -------------------------------
0 4 ``ospf.area_id`` Area ID
8 64 ``ospf.area_id`` Area ID
------ ----- ------------------ -------------------------------
0 6 ``ospf.chksum`` Checksum
12 96 ``ospf.chksum`` Checksum
------ ----- ------------------ -------------------------------
0 7 ``ospf.autype`` Authentication Type
14 112 ``ospf.autype`` Authentication Type
------ ----- ------------------ -------------------------------
1 8 ``ospf.auth`` Authentication
16 128 ``ospf.auth`` Authentication
====== ===== ================== ===============================

.. raw:: html
Expand Down
26 changes: 12 additions & 14 deletions docs/source/pcapkit/protocols/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,7 @@ Protocol Family
.. module:: pcapkit.protocols.data
.. module:: pcapkit.protocols.schema

:mod:`pcapkit.protocols` is collection of all protocol families,
with detailed implementation and methods.
:mod:`pcapkit.protocols` is the collection of all protocol families.

.. toctree::
:maxdepth: 2
Expand All @@ -18,10 +17,9 @@ with detailed implementation and methods.
application/index
misc/index

All protocol classes are implemented as :class:`~pcapkit.protocols.protocol.ProtocolBase`
subclasses, which are responsible for processing extracted binary packet data
and/or construct protocol packet from given information. Below is a brief
diagram of the class hierarchy of :mod:`pcapkit.protocols`:
All protocol classes are :class:`~pcapkit.protocols.protocol.ProtocolBase`
subclasses, which parse extracted binary packet data and/or construct a packet
from given information. The class hierarchy of :mod:`pcapkit.protocols`:

.. mermaid::

Expand Down Expand Up @@ -106,7 +104,7 @@ diagram of the class hierarchy of :mod:`pcapkit.protocols`:
click C "/pcapkit/protocols/protocol.html#pcapkit.protocols.protocol.Protocol"
click D "/ext.html#what-s-in-for-protocols"

click Link "/pcapkit/protocols/link/link.html#pcapkit.protocols.link.Link"
click Link "/pcapkit/protocols/link/link.html#pcapkit.protocols.link.link.Link"
click Ethernet "/pcapkit/protocols/link/ethernet.html#pcapkit.protocols.link.ethernet.Ethernet"
click L2TP "/pcapkit/protocols/link/l2tp.html#pcapkit.protocols.link.l2tp.L2TP"
click L2TPv2 "/pcapkit/protocols/link/l2tpv2.html#pcapkit.protocols.link.l2tpv2.L2TPv2"
Expand All @@ -119,27 +117,27 @@ diagram of the class hierarchy of :mod:`pcapkit.protocols`:
click RARP "/pcapkit/protocols/application/rarp.html#pcapkit.protocols.application.rarp.RARP"
click DRARP "/pcapkit/protocols/application/rarp.html#pcapkit.protocols.application.rarp.DRARP"

click Internet "/pcapkit/protocols/internet/internet.html#pcapkit.protocols.internet.Internet"
click Internet "/pcapkit/protocols/internet/internet.html#pcapkit.protocols.internet.internet.Internet"
click AH "/pcapkit/protocols/internet/ah.html#pcapkit.protocols.internet.ah.AH"
click ESP "/pcapkit/protocols/internet/esp.html#pcapkit.protocols.internet.esp.ESP"
click HIP "/pcapkit/protocols/internet/hip.html#pcapkit.protocols.internet.hip.HIP"
click HOPOPT "/pcapkit/protocols/internet/hopopt.html#pcapkit.protocols.internet.hopopt.HOPOPT"
click IP "/pcapkit/protocols/internet/ip.html#pcapkit.protocols.internet.ip.IP"
click IPsec "/pcapkit/protocols/internet/ipsec.html#pcapkit.protocols.internet.ipsec.IPsec"
click IPv4 "/pcapkit/protocols/internet/ipv4.html#pcapkit.protocols.internet.ip.ipv4.IPv4"
click IPv6 "/pcapkit/protocols/internet/ipv6.html#pcapkit.protocols.internet.ip.ipv6.IPv6"
click IPv4 "/pcapkit/protocols/internet/ipv4.html#pcapkit.protocols.internet.ipv4.IPv4"
click IPv6 "/pcapkit/protocols/internet/ipv6.html#pcapkit.protocols.internet.ipv6.IPv6"
click IPv6-Frag "/pcapkit/protocols/internet/ipv6_frag.html#pcapkit.protocols.internet.ipv6_frag.IPv6_Frag"
click IPv6-Opts "/pcapkit/protocols/internet/ipv6_opts.html#pcapkit.protocols.internet.ipv6_opts.IPv6_Opts"
click IPv6-Route "/pcapkit/protocols/internet/ipv6_route.html#pcapkit.protocols.internet.ipv6_route.IPv6_Route"
click IPX "/pcapkit/protocols/internet/ipx.html#pcapkit.protocols.internet.ipx.IPX"
click MH "/pcapkit/protocols/internet/mh.html#pcapkit.protocols.internet.mh.MH"

click Transport "/pcapkit/protocols/transport/transport.html#pcapkit.protocols.transport.Transport"
click TCP "/pcapkit/protocols/transport/tcp.html#pcapkit.protocols.internet.tcp.TCP"
click UDP "/pcapkit/protocols/transport/udp.html#pcapkit.protocols.internet.udp.UDP"
click Transport "/pcapkit/protocols/transport/transport.html#pcapkit.protocols.transport.transport.Transport"
click TCP "/pcapkit/protocols/transport/tcp.html#pcapkit.protocols.transport.tcp.TCP"
click UDP "/pcapkit/protocols/transport/udp.html#pcapkit.protocols.transport.udp.UDP"
click SCTP "/pcapkit/protocols/transport/sctp.html#pcapkit.protocols.transport.sctp.SCTP"

click Application "/pcapkit/protocols/application/application.html#pcapkit.protocols.application.Application"
click Application "/pcapkit/protocols/application/application.html#pcapkit.protocols.application.application.Application"
click HTTP "/pcapkit/protocols/application/http.html#pcapkit.protocols.application.http.HTTP"
click h1 "/pcapkit/protocols/application/httpv1.html#pcapkit.protocols.application.httpv1.HTTP"
click h2 "/pcapkit/protocols/application/httpv2.html#pcapkit.protocols.application.httpv2.HTTP"
Expand Down
8 changes: 4 additions & 4 deletions docs/source/pcapkit/protocols/internet/ah.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ AH - Authentication Header
.. module:: pcapkit.protocols.internet.ah

:mod:`pcapkit.protocols.internet.ah` contains
:class:`~pcapkit.protocols.internet.AH` only,
:class:`~pcapkit.protocols.internet.ah.AH` only,
which implements extractor for Authentication
Header (AH) [*]_, whose structure is described
as below:
Expand All @@ -15,9 +15,9 @@ Octets Bits Name Description
0 0 ``ah.next`` Next Header
1 8 ``ah.length`` Payload Length
2 16 Reserved (must be zero)
4 32 ``sah.spi`` Security Parameters Index (SPI)
8 64 ``sah.seq`` Sequence Number Field
12 96 ``sah.icv`` Integrity Check Value (ICV)
4 32 ``ah.spi`` Security Parameters Index (SPI)
8 64 ``ah.seq`` Sequence Number Field
12 96 ``ah.icv`` Integrity Check Value (ICV)
======= ========= ======================= ===================================

.. autoclass:: pcapkit.protocols.internet.ah.AH
Expand Down
8 changes: 2 additions & 6 deletions docs/source/pcapkit/protocols/internet/esp.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -120,12 +120,8 @@ registered**: 3DES, AES-CTR, the AES-CCM and Camellia families,
ChaCha20-Poly1305, the implicit IV variants of :rfc:`8750`, the :rfc:`9227`
MGM suites, and the transforms long since deprecated.

The enumerations themselves are generated into :mod:`pcapkit.const.esp` and
re-exported here for convenience:
:class:`Cipher <pcapkit.const.esp.cipher.Cipher>` is
:class:`pcapkit.const.esp.cipher.Cipher` and :class:`Integrity
<pcapkit.const.esp.integrity.Integrity>` is
:class:`pcapkit.const.esp.integrity.Integrity`.
Both enumerations are generated into :mod:`pcapkit.const.esp` and re-exported
from this module.

Both enumerations additionally carry each transform's prefix-stripped spelling
as an alias, since that is how ESP and :rfc:`8221` name the algorithms, so
Expand Down
36 changes: 18 additions & 18 deletions docs/source/pcapkit/protocols/internet/ipv4.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,25 +12,25 @@ as below:
======= ========= ====================== =============================================
Octets Bits Name Description
======= ========= ====================== =============================================
0 0 ``ip.version`` Version (``4``)
0 4 ``ip.hdr_len`` Internal Header Length (IHL)
1 8 ``ip.tos.pre`` Precedence
1 11 ``ip.tos.del`` Delay
1 12 ``ip.tos.thr`` Throughput
1 13 ``ip.tos.rel`` Reliability
1 14 ``ip.tos.ecn`` Explicit Congestion Notification (ECN)
2 16 ``ip.len`` Total Length
4 32 ``ip.id`` Identification
0 0 ``ipv4.version`` Version (``4``)
0 4 ``ipv4.hdr_len`` Internet Header Length (IHL)
1 8 ``ipv4.tos.pre`` Precedence
1 11 ``ipv4.tos.del`` Delay
1 12 ``ipv4.tos.thr`` Throughput
1 13 ``ipv4.tos.rel`` Reliability
1 14 ``ipv4.tos.ecn`` Explicit Congestion Notification (ECN)
2 16 ``ipv4.len`` Total Length
4 32 ``ipv4.id`` Identification
6 48 Reserved Bit (must be ``\x00``)
6 49 ``ip.flags.df`` Don't Fragment (DF)
6 50 ``ip.flags.mf`` More Fragments (MF)
6 51 ``ip.offset`` Fragment Offset
8 64 ``ip.ttl`` Time To Live (TTL)
9 72 ``ip.protocol`` Protocol (Transport Layer)
10 80 ``ip.checksum`` Header Checksum
12 96 ``ip.src`` Source IP Address
16 128 ``ip.dst`` Destination IP Address
20 160 ``ip.options`` IP Options (if IHL > ``5``)
6 49 ``ipv4.flags.df`` Don't Fragment (DF)
6 50 ``ipv4.flags.mf`` More Fragments (MF)
6 51 ``ipv4.offset`` Fragment Offset
8 64 ``ipv4.ttl`` Time To Live (TTL)
9 72 ``ipv4.protocol`` Protocol (Transport Layer)
10 80 ``ipv4.checksum`` Header Checksum
12 96 ``ipv4.src`` Source IP Address
16 128 ``ipv4.dst`` Destination IP Address
20 160 ``ipv4.options`` IP Options (if IHL > ``5``)
======= ========= ====================== =============================================

.. autoclass:: pcapkit.protocols.internet.ipv4.IPv4
Expand Down
16 changes: 8 additions & 8 deletions docs/source/pcapkit/protocols/internet/ipv6.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,14 @@ as below:
======= ========= ===================== =======================================
Octets Bits Name Description
======= ========= ===================== =======================================
0 0 ``ip.version`` Version (``6``)
0 4 ``ip.class`` Traffic Class
1 12 ``ip.label`` Flow Label
4 32 ``ip.payload`` Payload Length (header excludes)
6 48 ``ip.next`` Next Header
7 56 ``ip.limit`` Hop Limit
8 64 ``ip.src`` Source Address
24 192 ``ip.dst`` Destination Address
0 0 ``ipv6.version`` Version (``6``)
0 4 ``ipv6.class`` Traffic Class
1 12 ``ipv6.label`` Flow Label
4 32 ``ipv6.payload`` Payload Length (header excludes)
6 48 ``ipv6.next`` Next Header
7 56 ``ipv6.limit`` Hop Limit
8 64 ``ipv6.src`` Source Address
24 192 ``ipv6.dst`` Destination Address
======= ========= ===================== =======================================

.. autoclass:: pcapkit.protocols.internet.ipv6.IPv6
Expand Down
31 changes: 15 additions & 16 deletions docs/source/pcapkit/protocols/internet/ipv6_ext.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,18 +5,17 @@ IPv6_Ext - IPv6 Extension Header

:mod:`pcapkit.protocols.internet.ipv6_ext` contains
:class:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext`
only, which serves two roles at once: it is the
shared **base class** of all eight IPv6 extension headers this package
implements -- supplying them the ``extension``-mode contract, i.e. the
guards that make :attr:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext.payload`,
only, which serves two roles at once. It is the shared **base class** of all
eight IPv6 extension headers this package implements, supplying the
``extension``-mode contract: the guards that make
:attr:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext.payload`,
:attr:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext.protocol` and
:attr:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext.protochain`
unavailable on a header parsed as part of an IPv6 chain -- and it
implements a **generic** extractor for IPv6 extension
headers [*]_, standing in for one whenever the header's own dedicated
parser is unavailable or has failed. :rfc:`6564#section-4` guarantees,
with an RFC 2119 **MUST**, that any IPv6 extension header defined
since April 2012 carries the same first two octets:
unavailable on a header parsed as part of an IPv6 chain. It also implements a
**generic** extractor for IPv6 extension headers [*]_, standing in whenever a
header's own dedicated parser is unavailable or has failed. :rfc:`6564#section-4`
requires, with an RFC 2119 **MUST**, that any IPv6 extension header defined since
April 2012 carry the same first two octets:

======= ========= ===================== =====================================
Octets Bits Name Description
Expand All @@ -27,12 +26,12 @@ Octets Bits Name Description
2 16 ``payload`` Header-specific content
======= ========= ===================== =====================================

so those two octets are parseable without knowing anything else about
the header. See the module docstring below for the closed exception
table (``IPv6-Frag`` and ``AH`` each use their own length rule; ``ESP``
has a dedicated parser whose own info reports no next header rather than
lacking one, and ``253`` and ``254`` have no dedicated parser at all --
none of the three ever reaches this class), the two ways this class is
so those two octets are parseable without knowing anything else about the
header. The module docstring in :file:`pcapkit/protocols/internet/ipv6_ext.py`
holds the closed exception table (``IPv6-Frag`` and ``AH`` each use their own
length rule; ``ESP`` has a dedicated parser whose own info reports no next header
rather than lacking one, and ``253`` and ``254`` have no dedicated parser at all,
so none of the three ever reaches this class), the two ways this class is
dispatched to, and why an overrun stops the walk instead of clipping it.

.. autoclass:: pcapkit.protocols.internet.ipv6_ext.IPv6_Ext
Expand Down
6 changes: 3 additions & 3 deletions docs/source/pcapkit/protocols/internet/ipv6_opts.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,9 @@ as below:
======= ========= =================== =================================
Octets Bits Name Description
======= ========= =================== =================================
0 0 ``opt.next`` Next Header
1 8 ``opt.length`` Header Extensive Length
2 16 ``opt.options`` Options
0 0 ``opts.next`` Next Header
1 8 ``opts.length`` Header Extensive Length
2 16 ``opts.options`` Options
======= ========= =================== =================================

.. autoclass:: pcapkit.protocols.internet.ipv6_opts.IPv6_Opts
Expand Down
Loading
Loading