Skip to content

Commit de22a52

Browse files
authored
docs(protocols): third whole-repo pass over link and transport (#1103) (#1833)
Counts: - reword the SCTP PPID and error-cause notes, the register_apptype note, the HTTP port comments, the L2TP dispatch prose, the MPTCP subtype comment and the nested_length docstring without counting Accuracy: - L2TP no longer says only one version exists: L2TPv3 and L2F exist, unimplemented - TCP Flags.urg is the flag, not the pointer; the option-list and unassigned-option docstrings say what they do; selectors document their FieldError - the L2TPv2 note points at the module page, not a missing measurement Directives: - versionchanged 1.5.0 on TCP.make and UDP.make for out-of-range ports (#758), and on UDP.make for total_length preceding payload (#1155) Rendering: - single-paragraph Returns on the MPTCP selectors, so no empty paragraph - autodoc no longer reads #: comments' leading phrases as types - drop the duplicate Flags stub on tcp.rst and repeated notes on l2tpv2.rst and s_tag.rst; move the L2TP class above its narrative - document the ARP schema fields and l2tp_payload_length Grammar: e.g./etc., register Warns and notes, reserved rows, __init__. Refs #1103
1 parent bd1d3cd commit de22a52

20 files changed

Lines changed: 142 additions & 122 deletions

File tree

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

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,16 @@ versions do not share one. Only the first 16-bit word, with a version nibble at
2626
bits 12-15, is common to all of them; a base that parsed further would assume one
2727
version's layout for every version.
2828

29+
.. autoclass:: pcapkit.protocols.link.l2tp.L2TP
30+
:no-members:
31+
:show-inheritance:
32+
33+
.. autoproperty:: info_name
34+
35+
.. automethod:: id
36+
37+
.. automethod:: __index__
38+
2939
Versions Not Implemented
3040
------------------------
3141

@@ -51,8 +61,8 @@ since callers take element zero as canonical.
5161
Version Dispatch
5262
----------------
5363

54-
Nothing dispatches on the version nibble, because only one version exists. A
55-
second would follow the precedent of
64+
Nothing dispatches on the version nibble, because L2TPv2 is the only version
65+
implemented. Another would follow the precedent of
5666
:class:`~pcapkit.protocols.application.http.HTTP`, which reads a version and
5767
delegates to a per-version class. L2TP is the easier case:
5868
:meth:`HTTP._guess_version <pcapkit.protocols.application.http.HTTP._guess_version>`
@@ -61,16 +71,6 @@ line, else trial-parsing each candidate -- because HTTP's wire format carries no
6171
version field, whereas L2TP states its version explicitly in those four bits. A
6272
deterministic switch on ``Ver`` is enough, and no new registry is needed.
6373

64-
.. autoclass:: pcapkit.protocols.link.l2tp.L2TP
65-
:no-members:
66-
:show-inheritance:
67-
68-
.. autoproperty:: info_name
69-
70-
.. automethod:: id
71-
72-
.. automethod:: __index__
73-
7474
.. rubric:: Footnotes
7575

7676
.. [*] https://en.wikipedia.org/wiki/Layer_2_Tunneling_Protocol

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

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -22,17 +22,17 @@ reading ``2``. It is dispatched from
2222
------- ----- --------------------- ------------------------------------------
2323
0 1 ``l2tp.flags.len`` Length
2424
------- ----- --------------------- ------------------------------------------
25-
0 2 Reserved (must be zero ``x00``)
25+
0 2 Reserved (must be zero)
2626
------- ----- --------------------- ------------------------------------------
2727
0 4 ``l2tp.flags.seq`` Sequence
2828
------- ----- --------------------- ------------------------------------------
29-
0 5 Reserved (must be zero ``x00``)
29+
0 5 Reserved (must be zero)
3030
------- ----- --------------------- ------------------------------------------
3131
0 6 ``l2tp.flags.offset`` Offset
3232
------- ----- --------------------- ------------------------------------------
3333
0 7 ``l2tp.flags.prio`` Priority
3434
------- ----- --------------------- ------------------------------------------
35-
1 8 Reserved (must be zero ``x00``)
35+
1 8 Reserved (must be zero)
3636
------- ----- --------------------- ------------------------------------------
3737
1 12 ``l2tp.version`` Version (``2``)
3838
------- ----- --------------------- ------------------------------------------
@@ -57,11 +57,6 @@ reading ``2``. It is dispatched from
5757
whichever version was on the wire. The version is reported by
5858
:attr:`~pcapkit.protocols.link.l2tpv2.L2TPv2.alias` instead.
5959

60-
IANA protocol number 115 (``L2TP``) is deliberately left unbound: it
61-
references :rfc:`3931`, i.e. **L2TPv3**, whose headers have a different shape,
62-
so the binding waits on an ``L2TPv3`` class rather than this one. See
63-
:mod:`pcapkit.protocols.link.l2tp`.
64-
6560
.. autoclass:: pcapkit.protocols.link.l2tpv2.L2TPv2
6661
:no-members:
6762
:show-inheritance:
@@ -96,6 +91,11 @@ Type Stubs
9691
:members:
9792
:show-inheritance:
9893

94+
Auxiliary Functions
95+
~~~~~~~~~~~~~~~~~~~
96+
97+
.. autofunction:: pcapkit.protocols.schema.link.l2tp.l2tp_payload_length
98+
9999
Data Models
100100
-----------
101101

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@ Link Layer Base Protocol
55

66
:mod:`pcapkit.protocols.link.link` contains :class:`~pcapkit.protocols.link.link.Link`,
77
which is a base class for link layer protocols, e.g. :class:`~pcapkit.protocols.link.arp.ARP`/InARP,
8-
:class:`~pcapkit.protocols.link.ethernet.Ethernet`, :class:`~pcapkit.protocols.link.l2tp.L2TP`,
9-
:class:`~pcapkit.protocols.link.vlan.VLAN` and etc.
8+
:class:`~pcapkit.protocols.link.ethernet.Ethernet`, :class:`~pcapkit.protocols.link.l2tp.L2TP`
9+
and :class:`~pcapkit.protocols.link.vlan.VLAN`.
1010

1111
.. autoclass:: pcapkit.protocols.link.link.Link
1212
:no-members:

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

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,6 @@ It has a module of its own, apart from
1919
*different* registry indices, ``0x88A8`` against ``0x8100``; see
2020
:mod:`pcapkit.protocols.link.vlan` for the rule.
2121

22-
.. note::
23-
24-
802.1ad is part of IEEE 802.1Q-2011. The ``802.1ad`` name is kept because it
25-
is what the provider-bridging tag is universally called.
26-
2722
.. autoclass:: pcapkit.protocols.link.s_tag.S_Tag
2823
:no-members:
2924
:show-inheritance:

‎docs/source/pcapkit/protocols/transport/tcp.rst‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -318,11 +318,6 @@ Type Stubs
318318
:members:
319319
:show-inheritance:
320320

321-
.. autoclass:: pcapkit.protocols.schema.transport.tcp.Flags
322-
:no-index:
323-
:members:
324-
:show-inheritance:
325-
326321
.. autoclass:: pcapkit.protocols.schema.transport.tcp.POCProfile
327322
:members:
328323
:show-inheritance:

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ Transport Layer Base Protocol
55

66
:mod:`pcapkit.protocols.transport.transport` contains
77
:class:`~pcapkit.protocols.transport.transport.Transport`,
8-
which is a base class for transport layer protocols, eg.
8+
which is a base class for transport layer protocols, e.g.
99
:class:`~pcapkit.protocols.transport.tcp.TCP`,
1010
:class:`~pcapkit.protocols.transport.udp.UDP` and
1111
:class:`~pcapkit.protocols.transport.sctp.SCTP`.

‎pcapkit/protocols/data/transport/tcp.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -364,7 +364,7 @@ class UserTimeout(Option):
364364

365365
#: User timeout.
366366
timeout: 'timedelta'
367-
#: Granularity (``G``): the timeout is in minutes if set, in seconds if not.
367+
#: Granularity (``G``). The timeout is in minutes if set, in seconds if not.
368368
granularity: 'bool'
369369

370370
if TYPE_CHECKING:
@@ -427,8 +427,8 @@ class MPTCPCapableFlag(Data):
427427
deny_join: 'bool'
428428
#: Reserved flags (``D`` to ``G``).
429429
reserved: 'int'
430-
#: HMAC algorithm flag (``H``): HMAC-SHA1 under version 0 (:rfc:`6824`),
431-
#: HMAC-SHA256 under version 1 (:rfc:`8684`).
430+
#: HMAC algorithm flag (``H``), selecting HMAC-SHA1 under version 0
431+
#: (:rfc:`6824`) and HMAC-SHA256 under version 1 (:rfc:`8684`).
432432
hsa: 'bool'
433433

434434
if TYPE_CHECKING:

‎pcapkit/protocols/link/__init__.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@
55
66
.. module:: pcapkit.protocols.link
77
8-
:mod:`pcapkit.protocols.link` is collection of all protocols in
9-
link layer, with detailed implementation and methods.
8+
:mod:`pcapkit.protocols.link` is a collection of all protocols in
9+
the link layer, with detailed implementation and methods.
1010
1111
"""
1212
# TODO: Implements DSL, EAPOL, FDDI, ISDN, NDP, PPP.

‎pcapkit/protocols/link/l2tp.py‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -68,15 +68,16 @@
6868
Selecting a Version
6969
-------------------
7070
71-
Nothing *dispatches* on the version nibble, because only one version exists
72-
-- but :meth:`L2TPv2.read <pcapkit.protocols.link.l2tpv2.L2TPv2.read>` does
73-
**check** it, and refuses anything other than ``2``. That is the half of the
74-
mechanism which is useful with one version implemented: it keeps v3 traffic on
75-
port 1701 (:rfc:`3931` §4.1.2 shares the port, so this is ordinary capture
71+
Nothing *dispatches* on the version nibble, because L2TPv2 is the only version
72+
implemented -- but
73+
:meth:`L2TPv2.read <pcapkit.protocols.link.l2tpv2.L2TPv2.read>` does **check**
74+
it, and refuses anything other than ``2``. That is the half of the mechanism
75+
which is useful with no other version implemented: it keeps v3 traffic on port
76+
1701 (:rfc:`3931` §4.1.2 shares the port, so this is ordinary capture
7677
traffic rather than a corner case) from being reported as v2 with a tunnel and
7778
session ID read out of v3's Control Connection ID.
7879
79-
When a second version lands, the remaining half -- delegation rather than refusal
80+
When another version lands, the remaining half -- delegation rather than refusal
8081
-- already has a precedent in
8182
:class:`~pcapkit.protocols.application.http.HTTP`, which reads a version and
8283
delegates to a per-version class. L2TP is the easier case: HTTP has to

‎pcapkit/protocols/link/l2tpv2.py‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -21,17 +21,17 @@
2121
------- ----- --------------------- ------------------------------------------
2222
0 1 ``l2tp.flags.len`` Length
2323
------- ----- --------------------- ------------------------------------------
24-
0 2 Reserved (must be zero ``x00``)
24+
0 2 Reserved (must be zero)
2525
------- ----- --------------------- ------------------------------------------
2626
0 4 ``l2tp.flags.seq`` Sequence
2727
------- ----- --------------------- ------------------------------------------
28-
0 5 Reserved (must be zero ``x00``)
28+
0 5 Reserved (must be zero)
2929
------- ----- --------------------- ------------------------------------------
3030
0 6 ``l2tp.flags.offset`` Offset
3131
------- ----- --------------------- ------------------------------------------
3232
0 7 ``l2tp.flags.prio`` Priority
3333
------- ----- --------------------- ------------------------------------------
34-
1 8 Reserved (must be zero ``x00``)
34+
1 8 Reserved (must be zero)
3535
------- ----- --------------------- ------------------------------------------
3636
1 12 ``l2tp.version`` Version (``2``)
3737
------- ----- --------------------- ------------------------------------------
@@ -106,8 +106,8 @@ class L2TPv2(L2TP[Data_L2TP, Schema_L2TP],
106106
``L2TPv3`` class rather than on this one. Binding *this* class there does
107107
not work (:issue:`548`): over IP the v3 session header carries no
108108
version nibble at all, so this class cannot recognise that the datagram
109-
is not its own. See
110-
:class:`~pcapkit.protocols.link.l2tp.L2TP` for the measurement.
109+
is not its own. See :mod:`pcapkit.protocols.link.l2tp` for the
110+
versions not implemented.
111111
112112
The class subclasses :class:`~pcapkit.protocols.link.link.Link` and so
113113
reports ``layer == 'Link'`` even though it is carried inside UDP: a

0 commit comments

Comments
 (0)