Skip to content

Commit c8f49a3

Browse files
committed
docs(protocols): sweep link and transport prose (#1103)
Version directives, all 1.5.0 and naming the issue: - versionchanged on ARP, InARP, L2TP, VLAN, TCP and UDP. - versionadded on L2TPv2, C_Tag, S_Tag and SCTP. Accuracy: - Header tables use the data-model keys: ethernet.*, tcp.options, l2tp.version, and the tcp.flags.reserved row on the TCP page. - _read_mode_poc names the POC-permitted option; SACK typo fixed. - Timed wording dropped: "currently" (7), "as before" (2). Rendered output: - Dead cross-references now resolve: Protocol.* for ProtocolBase.*, Protocol.info, apptype.apptype.AppType, VLAN's C_Tag/S_Tag links. - Stray quote removed from the FastOpenCookie docstring. - TCP, SCTP, Link and Transport pages document the referenced helpers, schemas and hooks they were missing. Refs #1103
1 parent f4ed067 commit c8f49a3

20 files changed

Lines changed: 163 additions & 50 deletions

File tree

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,9 @@ which is a base class for link layer protocols, e.g. :class:`~pcapkit.protocols.
1515
.. autoproperty:: layer
1616

1717
.. automethod:: register
18+
.. automethod:: from_data
19+
20+
.. automethod:: __post_init__
1821

1922
.. autoattribute:: __layer__
2023
.. autoattribute:: __proto__

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

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -320,6 +320,10 @@ Header Schemas
320320
:members:
321321
:show-inheritance:
322322

323+
.. autoclass:: pcapkit.protocols.schema.transport.sctp.ChunkListField
324+
:members:
325+
:show-inheritance:
326+
323327
Type Stubs
324328
~~~~~~~~~~
325329

@@ -335,7 +339,10 @@ Auxiliary Functions
335339
~~~~~~~~~~~~~~~~~~~
336340

337341
.. autofunction:: pcapkit.protocols.schema.transport.sctp.padding_length
342+
.. autofunction:: pcapkit.protocols.schema.transport.sctp.pre_pack_padding
343+
.. autofunction:: pcapkit.protocols.schema.transport.sctp.bounded
338344
.. autofunction:: pcapkit.protocols.schema.transport.sctp.nested_length
345+
.. autofunction:: pcapkit.protocols.schema.transport.sctp.whole_chunks_length
339346

340347
Data Models
341348
-----------

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

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Octets Bits Name Description
1717
4 32 ``tcp.seq`` Sequence Number
1818
8 64 ``tcp.ack`` Acknowledgement Number (if ACK set)
1919
12 96 ``tcp.hdr_len`` Data Offset
20-
12 100 Reserved (must be ``\x00``)
20+
12 100 ``tcp.flags.reserved`` Reserved (must be ``\x00``)
2121
12 103 ``tcp.flags.ns`` ECN Concealment Protection (NS)
2222
13 104 ``tcp.flags.cwr`` Congestion Window Reduced (CWR)
2323
13 105 ``tcp.flags.ece`` ECN-Echo (ECE)
@@ -187,6 +187,10 @@ Header Schemas
187187
:members:
188188
:show-inheritance:
189189

190+
.. autoclass:: pcapkit.protocols.schema.transport.tcp.SACKBlock
191+
:members:
192+
:show-inheritance:
193+
190194
.. autoclass:: pcapkit.protocols.schema.transport.tcp.Echo
191195
:members:
192196
:show-inheritance:
@@ -251,6 +255,10 @@ Header Schemas
251255
:members:
252256
:show-inheritance:
253257

258+
.. autoclass:: pcapkit.protocols.schema.transport.tcp._MPTCP
259+
:members:
260+
:show-inheritance:
261+
254262
.. autoclass:: pcapkit.protocols.schema.transport.tcp.MPTCP
255263
:members:
256264
:show-inheritance:
@@ -372,6 +380,7 @@ Auxiliary Functions
372380

373381
.. autofunction:: pcapkit.protocols.schema.transport.tcp.mptcp_data_selector
374382
.. autofunction:: pcapkit.protocols.schema.transport.tcp.mptcp_add_address_selector
383+
.. autofunction:: pcapkit.protocols.schema.transport.tcp.mptcp_dss_checksum
375384
.. autofunction:: pcapkit.protocols.schema.transport.tcp.mptcp_dss_ack_selector
376385
.. autofunction:: pcapkit.protocols.schema.transport.tcp.mptcp_dss_dsn_selector
377386

@@ -420,6 +429,10 @@ Data Models
420429
:members:
421430
:show-inheritance:
422431

432+
.. autoclass:: pcapkit.protocols.data.transport.tcp.SACKBlock
433+
:members:
434+
:show-inheritance:
435+
423436
.. autoclass:: pcapkit.protocols.data.transport.tcp.Echo
424437
:members:
425438
:show-inheritance:
@@ -496,6 +509,10 @@ Data Models
496509
:members:
497510
:show-inheritance:
498511

512+
.. autoclass:: pcapkit.protocols.data.transport.tcp.MPTCPCapableFlag
513+
:members:
514+
:show-inheritance:
515+
499516
.. autoclass:: pcapkit.protocols.data.transport.tcp.MPTCPJoin
500517
:members:
501518
:show-inheritance:

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,9 @@ which is a base class for transport layer protocols, eg.
1818

1919
.. automethod:: register
2020
.. automethod:: analyze
21+
.. automethod:: from_data
22+
23+
.. automethod:: __post_init__
2124

2225
.. automethod:: _make_port
2326
.. automethod:: _decode_next_layer

‎pcapkit/protocols/link/arp.py‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,15 @@ class ARP(Link[Data_ARP, Schema_ARP],
8585
- Dynamic Reverse Address Resolution Protocol (:class:`~pcapkit.protocols.application.rarp.DRARP`) [:rfc:`1931`]
8686
- Inverse Address Resolution Protocol (:class:`~pcapkit.protocols.link.arp.InARP`) [:rfc:`2390`]
8787
88+
.. versionchanged:: 1.5.0
89+
90+
:meth:`make` refuses a :obj:`bool` protocol address (:issue:`540`), packs
91+
a non-IP protocol address from its *hex* text rather than as ASCII, and
92+
checks every address against ``hlen`` and ``plen`` (:issue:`1139`). An
93+
Ethernet ``hlen`` other than 6 rebuilds (:issue:`1205`), and
94+
:meth:`read` takes an IPv4 or IPv6 protocol address only when both
95+
``ptype`` and the address length agree (:issue:`1206`).
96+
8897
"""
8998
#: Name of corresponding protocol.
9099
_name: 'Literal["Address Resolution Protocol", "Inverse Address Resolution Protocol", "Reverse Address Resolution Protocol", "Dynamic Reverse Address Resolution Protocol"]' # pylint: disable=line-too-long
@@ -484,7 +493,14 @@ def _make_proto_resolve(self, addr: 'IPv4Address | IPv6Address | str | bytes', p
484493

485494

486495
class InARP(ARP, schema=Schema_ARP, data=Data_ARP):
487-
"""This class implements Inverse Address Resolution Protocol."""
496+
"""This class implements Inverse Address Resolution Protocol.
497+
498+
.. versionchanged:: 1.5.0
499+
500+
Parses with the ARP schema rather than falling back to the raw one
501+
(:issue:`1204`).
502+
503+
"""
488504

489505
##########################################################################
490506
# Methods.

‎pcapkit/protocols/link/c_tag.py‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,13 @@
4444
# the base class's pair. c.f. :class:`~pcapkit.protocols.application.rarp.RARP`, which
4545
# restates them for the same reason.
4646
class C_Tag(VLAN, schema=Schema_VLAN, data=Data_VLAN):
47-
"""This class implements 802.1Q Customer VLAN Tag Type."""
47+
"""This class implements 802.1Q Customer VLAN Tag Type.
48+
49+
.. versionadded:: 1.5.0
50+
51+
Takes over the customer tag from :class:`~pcapkit.protocols.link.vlan.VLAN`.
52+
53+
"""
4854

4955
##########################################################################
5056
# Properties.
@@ -65,7 +71,7 @@ def alias(self) -> 'Literal["802.1Q"]':
6571
#: class-name default -- a rename must not silently move the output key.
6672
@property
6773
def info_name(self) -> 'Literal["c_tag"]':
68-
"""Key name of the :attr:`info` dict."""
74+
"""Key name of the :attr:`~pcapkit.protocols.protocol.Protocol.info` dict."""
6975
return 'c_tag'
7076

7177
##########################################################################

‎pcapkit/protocols/link/ethernet.py‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -12,15 +12,15 @@
1212
1313
.. table::
1414
15-
====== ===== ============ =========================
16-
Octets Bits Name Description
17-
====== ===== ============ =========================
18-
0 0 ``eth.dst`` Destination MAC Address
19-
------ ----- ------------ -------------------------
20-
6 48 ``eth.src`` Source MAC Address
21-
------ ----- ------------ -------------------------
22-
12 96 ``eth.type`` Protocol (Internet Layer)
23-
====== ===== ============ =========================
15+
====== ===== ================= =========================
16+
Octets Bits Name Description
17+
====== ===== ================= =========================
18+
0 0 ``ethernet.dst`` Destination MAC Address
19+
------ ----- ----------------- -------------------------
20+
6 48 ``ethernet.src`` Source MAC Address
21+
------ ----- ----------------- -------------------------
22+
12 96 ``ethernet.type`` Protocol (Internet Layer)
23+
====== ===== ================= =========================
2424
2525
.. [*] https://en.wikipedia.org/wiki/Ethernet
2626

‎pcapkit/protocols/link/l2tp.py‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,11 @@ class L2TP(Link[_PT, _ST], Generic[_PT, _ST]): # pylint: disable=abstract-metho
120120
defined here, so the class cannot be instantiated. Bind a version, never this
121121
class.
122122
123+
.. versionchanged:: 1.5.0
124+
125+
Became an abstract base for the family; its version-2 parsing moved to
126+
:class:`~pcapkit.protocols.link.l2tpv2.L2TPv2`.
127+
123128
"""
124129

125130
##########################################################################
@@ -134,7 +139,7 @@ class L2TP(Link[_PT, _ST], Generic[_PT, _ST]): # pylint: disable=abstract-metho
134139
#: every consumer would have to know the version to find the data.
135140
@property
136141
def info_name(self) -> 'Literal["l2tp"]':
137-
"""Key name of the :attr:`info` dict."""
142+
"""Key name of the :attr:`~pcapkit.protocols.protocol.Protocol.info` dict."""
138143
return 'l2tp'
139144

140145
##########################################################################

‎pcapkit/protocols/link/l2tpv2.py‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@
3333
------- ----- --------------------- ------------------------------------------
3434
1 8 Reserved (must be zero ``x00``)
3535
------- ----- --------------------- ------------------------------------------
36-
1 12 ``l2tp.ver`` Version (``2``)
36+
1 12 ``l2tp.version`` Version (``2``)
3737
------- ----- --------------------- ------------------------------------------
3838
2 16 ``l2tp.length`` Length (optional by ``len``)
3939
------- ----- --------------------- ------------------------------------------
@@ -93,6 +93,12 @@ class L2TPv2(L2TP[Data_L2TP, Schema_L2TP],
9393
(:rfc:`3931` §4.1.2 shares the port) degrades to
9494
:class:`~pcapkit.protocols.misc.raw.Raw` instead of being reported as v2.
9595
96+
.. versionadded:: 1.5.0
97+
98+
Takes over the version-2 parsing that
99+
:class:`~pcapkit.protocols.link.l2tp.L2TP` carried, and refuses a version
100+
nibble other than ``2`` (:issue:`548`).
101+
96102
Note:
97103
IANA protocol number 115 (``L2TP``) is deliberately left unbound. It
98104
references :rfc:`3931`, i.e. **L2TPv3**, whose session and control

‎pcapkit/protocols/link/link.py‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -135,7 +135,7 @@ def register(cls, code: 'Enum_EtherType', protocol: 'ModuleDescriptor[ProtocolBa
135135
replacement so a caller can tell *what* was lost. Fires only
136136
when the incumbent differs from the replacement -- see
137137
:meth:`ProtocolBase.register
138-
<pcapkit.protocols.protocol.ProtocolBase.register>` for the
138+
<pcapkit.protocols.protocol.Protocol.register>` for the
139139
guard this shares with ``register_protocol``, and for the
140140
shipped descriptor a restore puts back (:issue:`1504`).
141141
@@ -156,7 +156,7 @@ def from_data(cls, data: '_PT | dict[str, Any]', **kwargs: 'Any') -> 'Self':
156156
Args:
157157
data: Protocol data.
158158
**kwargs: Construction keywords, as for :meth:`ProtocolBase.from_data
159-
<pcapkit.protocols.protocol.ProtocolBase.from_data>`.
159+
<pcapkit.protocols.protocol.Protocol.from_data>`.
160160
161161
Returns:
162162
Protocol instance, cut back to what was captured when the header
@@ -179,9 +179,9 @@ def __post_init__(self, file: 'Optional[IO[bytes] | bytes]' = None,
179179
**kwargs: Arbitrary keyword arguments.
180180
181181
Notes:
182-
A header the data ends inside keeps that in its :attr:`info`, so
183-
that :meth:`from_data` rebuilds only what was captured
184-
(:issue:`1458`).
182+
A header the data ends inside keeps that in its
183+
:attr:`~pcapkit.protocols.protocol.Protocol.info`, so that
184+
:meth:`from_data` rebuilds only what was captured (:issue:`1458`).
185185
186186
"""
187187
super().__post_init__(file, length, **kwargs) # type: ignore[arg-type]

0 commit comments

Comments
 (0)