Skip to content

Commit e252db9

Browse files
authored
docs(tcp): name what the MPTCP and option makers raise; give Quick-Start rate its unit (#2235) (#2247)
TCP._make_mptcp_join raises ProtocolError on a flags combination that is none of SYN, SYN/ACK and ACK, and TCP._make_tcp_options passes on what its option makers raise, yet neither had a Raises section. Add one to each: ProtocolError for both, plus ProtocolNotImplemented for a named MPTCP subtype or alternate checksum algorithm not in its namespace. The TCP Quick-Start Response req_rate and the IPv4, HOPOPT and IPv6-Opts Quick-Start rate fields hold an int since #2167 but gave no unit. State that they are in kbps, 40 * 2 ** N or 0 for N = 0 (RFC 4782 Section 3.1), and add a versionchanged 1.5.0 for the float to int change, matching the FastOpenCookie note from the same fix. Docstring and #: comments only; the AST guard passes, so there is no fail-without-fix test.
1 parent 55bbbb4 commit e252db9

5 files changed

Lines changed: 52 additions & 8 deletions

File tree

‎pcapkit/protocols/data/internet/hopopt.py‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -210,11 +210,19 @@ def __init__(self, type: 'Enum_Option', action: 'int', change: 'bool', length: '
210210

211211

212212
class QuickStartOption(Option):
213-
"""Data model for HOPOPT Quick Start option."""
213+
"""Data model for HOPOPT Quick Start option.
214+
215+
.. versionchanged:: 1.5.0
216+
217+
``rate`` is an :obj:`int` rather than a :obj:`float` (:issue:`2167`).
218+
219+
"""
214220

215221
#: QS function.
216222
func: 'QSFunction'
217-
#: Rate request/report.
223+
#: Rate request/report, in kbps: ``40 * 2 ** N`` for the Rate Request or
224+
#: Rate Report field ``N``, or ``0`` if ``N`` is ``0`` (:rfc:`4782`
225+
#: Section 3.1).
218226
rate: 'int'
219227

220228

‎pcapkit/protocols/data/internet/ipv4.py‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -409,11 +409,19 @@ def __init__(self, code: 'OptionNumber', length: 'int', type: 'OptionType', aler
409409

410410

411411
class QSOption(Option):
412-
"""Data model for IPv4 Quick Start (``QS``) option."""
412+
"""Data model for IPv4 Quick Start (``QS``) option.
413+
414+
.. versionchanged:: 1.5.0
415+
416+
``rate`` is an :obj:`int` rather than a :obj:`float` (:issue:`2167`).
417+
418+
"""
413419

414420
#: QS function.
415421
func: 'QSFunction'
416-
#: Rate request/report.
422+
#: Rate request/report, in kbps: ``40 * 2 ** N`` for the Rate Request or
423+
#: Rate Report field ``N``, or ``0`` if ``N`` is ``0`` (:rfc:`4782`
424+
#: Section 3.1).
417425
rate: 'int'
418426

419427

‎pcapkit/protocols/data/internet/ipv6_opts.py‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -219,11 +219,19 @@ def __init__(self, type: 'Enum_Option', action: 'int', change: 'bool', length: '
219219

220220

221221
class QuickStartOption(Option):
222-
"""Data model for IPv6-Opts Quick Start option."""
222+
"""Data model for IPv6-Opts Quick Start option.
223+
224+
.. versionchanged:: 1.5.0
225+
226+
``rate`` is an :obj:`int` rather than a :obj:`float` (:issue:`2167`).
227+
228+
"""
223229

224230
#: QS function.
225231
func: 'QSFunction'
226-
#: Rate request/report.
232+
#: Rate request/report, in kbps: ``40 * 2 ** N`` for the Rate Request or
233+
#: Rate Report field ``N``, or ``0`` if ``N`` is ``0`` (:rfc:`4782`
234+
#: Section 3.1).
227235
rate: 'int'
228236

229237

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

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -341,9 +341,17 @@ def __init__(self, kind: 'OptionNumber', length: 'int', digest: 'bytes') -> 'Non
341341

342342
@info_final
343343
class QuickStartResponse(Option):
344-
"""Data model for TCP quick start response option."""
344+
"""Data model for TCP quick start response option.
345345
346-
#: Rate request.
346+
.. versionchanged:: 1.5.0
347+
348+
``req_rate`` is an :obj:`int` rather than a :obj:`float`
349+
(:issue:`2167`).
350+
351+
"""
352+
353+
#: Rate request, in kbps: ``40 * 2 ** N`` for the Rate Request field
354+
#: ``N``, or ``0`` if ``N`` is ``0`` (:rfc:`4782` Section 3.1).
347355
req_rate: 'int'
348356
#: TTL difference.
349357
ttl_diff: 'int'

‎pcapkit/protocols/transport/tcp.py‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2156,6 +2156,14 @@ def _make_tcp_options(self, options: 'list[Schema_Option | tuple[Enum_Option, di
21562156
Returns:
21572157
Tuple of options and total length of options.
21582158
2159+
Raises:
2160+
ProtocolError: If an option maker rejects its option, e.g. a user
2161+
timeout too large for 15 bits of minutes, or an MPTCP option
2162+
whose fields, or the segment's flags, it cannot encode.
2163+
ProtocolNotImplemented: If an option argument given by name, an
2164+
MPTCP ``subtype`` or an alternate checksum ``algorithm``, is
2165+
not in its namespace and has no default.
2166+
21592167
Note:
21602168
The options are emitted in the given order, ``NOP`` and ``EOOL``
21612169
included, so that a parsed option list re-emits the same octets.
@@ -2975,6 +2983,10 @@ def _make_mptcp_join(self, subtype: 'Enum_MPTCPOption', opt: 'Optional[Data_MPTC
29752983
Returns:
29762984
Constructed option schema.
29772985
2986+
Raises:
2987+
ProtocolError: If the segment's flags are none of SYN, SYN/ACK and
2988+
ACK.
2989+
29782990
"""
29792991
if Enum_Flags.SYN in self._flags and Enum_Flags.ACK not in self._flags: # MP_JOIN-SYN
29802992
return self._make_join_syn(subtype, opt, **kwargs) # type: ignore[arg-type]

0 commit comments

Comments
 (0)