Skip to content

Commit f17c77f

Browse files
authored
test(generators): HTTP/2 sample frames are all written on stream 0 (#1161)
1 parent 5b09a9e commit f17c77f

2 files changed

Lines changed: 153 additions & 3 deletions

File tree

‎examples/generators/options.py‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1120,15 +1120,28 @@ def _httpv2_overrides() -> 'dict[Any, dict[str, Any]]':
11201120
# ``settings=None``, the default, matches none of the accepted forms.
11211121
Enum_Frame.SETTINGS: {'settings': [(Enum_Setting.HEADER_TABLE_SIZE, 4096)]},
11221122
Enum_Frame.GOAWAY: {'debug_data': b'\xde\xad'},
1123+
# A server-initiated stream is even and non-zero (RFC 9113 Section 5.1.1).
1124+
Enum_Frame.PUSH_PROMISE: {'promised_sid': 2},
11231125
}
11241126

11251127

1128+
#: HTTP/2 frame types that apply to the connection as a whole and so are sent
1129+
#: on stream 0 (RFC 9113 Sections 6.5, 6.7 and 6.8). Every other frame type is
1130+
#: sent on :data:`HTTPV2_STREAM`.
1131+
HTTPV2_CONNECTION_FRAMES = (4, 6, 7) # SETTINGS, PING, GOAWAY
1132+
1133+
#: Stream identifier of every stream-level HTTP/2 frame: the first
1134+
#: client-initiated stream (RFC 9113 Section 5.1.1). ``DATA``, ``HEADERS``,
1135+
#: ``PRIORITY``, ``RST_STREAM``, ``PUSH_PROMISE`` and ``CONTINUATION`` are a
1136+
#: connection error on stream 0, and ``WINDOW_UPDATE`` may use either.
1137+
HTTPV2_STREAM = 1
1138+
1139+
11261140
def _httpv2_build(code: 'Any', kwargs: 'dict[str, Any]') -> 'Any':
11271141
from pcapkit.protocols.application.httpv2 import HTTP
11281142

1129-
# SETTINGS and PING both reject a non-zero stream identifier, so every
1130-
# frame uses stream 0 rather than each one picking its own.
1131-
return HTTP(type=code, sid=0, frame=dict(kwargs))
1143+
sid = 0 if int(code) in HTTPV2_CONNECTION_FRAMES else HTTPV2_STREAM
1144+
return HTTP(type=code, sid=sid, frame=dict(kwargs))
11321145

11331146

11341147
def _httpv2_parse(octets: 'bytes') -> 'Any':
Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# -*- coding: utf-8 -*-
2+
"""The generator's HTTP/2 frames decode as HTTP/2. C.f. #1156.
3+
4+
:file:`examples/captures/options-transport.pcap` carries one TCP segment to port
5+
80 per HTTP/2 frame type, built by ``_httpv2_build`` in
6+
:file:`examples/generators/options.py`. That function put every frame on stream
7+
0. :rfc:`9113#section-6` makes ``DATA``, ``HEADERS``, ``PRIORITY``,
8+
``RST_STREAM``, ``PUSH_PROMISE`` and ``CONTINUATION`` on stream 0 a connection
9+
error, and since #1153 :meth:`HTTP._guess_version
10+
<pcapkit.protocols.application.http.HTTP._guess_version>` declines a frame no
11+
conforming sender writes, so six of the ten segments decoded as ``TCP:Raw``.
12+
:mod:`tests.protocols.test_option_coverage_runtime` checks only the
13+
``Ethernet:IPv4`` prefix, so nothing noticed.
14+
15+
:data:`EXPECTED_STREAM` spells each type's stream out rather than reading it from
16+
the generator, so a wrong generator constant fails here as ``0 != 1``.
17+
18+
This module is unit tier: it builds its segments in memory from the generator's
19+
own cases and reads no capture, so it runs on a fresh checkout.
20+
21+
"""
22+
23+
from __future__ import annotations
24+
25+
import importlib.util
26+
import sys
27+
import types
28+
import unittest
29+
import warnings
30+
31+
from tests._support import time_limit
32+
from tests._tiers import ROOT
33+
34+
RUNTIME_DEPS = ('tbtrim', 'aenum', 'chardet', 'dictdumper')
35+
HAS_RUNTIME = all(importlib.util.find_spec(name) is not None for name in RUNTIME_DEPS)
36+
37+
#: A 20-octet TCP header, data offset 5, ACK set, from port 50000 to port 80 --
38+
#: the ports ``_frame`` gives the ``tcp`` envelope.
39+
_TCP_TO_80 = bytes.fromhex('c350005000000001000000015010ffff00000000')
40+
41+
#: Frame type -> whether :rfc:`9113#section-6` puts it on a non-zero stream
42+
#: (``True``) or on stream 0 (``False``). ``WINDOW_UPDATE`` may use either; the
43+
#: generator puts it on a stream.
44+
EXPECTED_STREAM = {
45+
0x0: True, # DATA (Section 6.1)
46+
0x1: True, # HEADERS (Section 6.2)
47+
0x2: True, # PRIORITY (Section 6.3)
48+
0x3: True, # RST_STREAM (Section 6.4)
49+
0x4: False, # SETTINGS (Section 6.5)
50+
0x5: True, # PUSH_PROMISE (Section 6.6)
51+
0x6: False, # PING (Section 6.7)
52+
0x7: False, # GOAWAY (Section 6.8)
53+
0x8: True, # WINDOW_UPDATE (Section 6.9)
54+
0x9: True, # CONTINUATION (Section 6.10)
55+
}
56+
57+
58+
def _load_generator() -> 'types.ModuleType':
59+
"""Load :file:`examples/generators/options.py` by path, under a name of its own.
60+
61+
Returns:
62+
The generator module.
63+
64+
Raises:
65+
RuntimeError: If the module cannot be found or loaded.
66+
67+
"""
68+
path = ROOT / 'examples' / 'generators' / 'options.py'
69+
spec = importlib.util.spec_from_file_location(
70+
'pcapkit_samples_options_httpv2_stream', path)
71+
if spec is None or spec.loader is None: # pragma: no cover
72+
raise RuntimeError(f'cannot load the option generator from {path}')
73+
74+
module = importlib.util.module_from_spec(spec)
75+
sys.modules[spec.name] = module
76+
spec.loader.exec_module(module)
77+
return module
78+
79+
80+
@unittest.skipUnless(HAS_RUNTIME, 'runtime dependencies not installed')
81+
class HTTPv2GeneratedFrameTests(unittest.TestCase):
82+
"""Each ``httpv2-frame`` case, as the capture carries it."""
83+
84+
@classmethod
85+
def setUpClass(cls) -> None:
86+
options = _load_generator()
87+
family = options.FAMILY_MAP['httpv2-frame']
88+
with warnings.catch_warnings():
89+
warnings.simplefilter('ignore')
90+
cls.frames = {int(outcome.case.code): outcome
91+
for outcome in options.outcomes((family,))}
92+
93+
def test_every_frame_type_is_generated(self) -> None:
94+
"""The ten :rfc:`9113` frame types are the ten cases, all capturable."""
95+
self.assertEqual(sorted(self.frames), sorted(EXPECTED_STREAM))
96+
for code, outcome in self.frames.items():
97+
with self.subTest(type=code):
98+
self.assertEqual(outcome.status, 'OK', outcome.detail)
99+
100+
def test_each_frame_is_on_a_stream_its_type_allows(self) -> None:
101+
"""Octets 5-8 are non-zero exactly where :data:`EXPECTED_STREAM` says."""
102+
for code, outcome in self.frames.items():
103+
with self.subTest(type=code):
104+
sid = int.from_bytes(outcome.octets[5:9], 'big') & 0x7FFFFFFF
105+
self.assertEqual(sid != 0, EXPECTED_STREAM[code], f'stream {sid}')
106+
107+
def test_push_promise_promises_a_server_initiated_stream(self) -> None:
108+
"""The promised stream is even and non-zero (:rfc:`9113#section-5.1.1`)."""
109+
octets = self.frames[0x5].octets
110+
promised = int.from_bytes(octets[9:13], 'big') & 0x7FFFFFFF
111+
self.assertTrue(promised and promised % 2 == 0, f'promised stream {promised}')
112+
113+
def test_each_length_counts_the_payload_only(self) -> None:
114+
"""The 24-bit Length excludes the 9-octet header (:rfc:`9113#section-4.1`)."""
115+
for code, outcome in self.frames.items():
116+
with self.subTest(type=code):
117+
length = int.from_bytes(outcome.octets[:3], 'big')
118+
self.assertEqual(length, len(outcome.octets) - 9)
119+
120+
def test_each_frame_decodes_as_http2_over_tcp(self) -> None:
121+
"""A port-80 segment carrying the frame decodes ``TCP:HTTP/2``, not ``TCP:Raw``."""
122+
from pcapkit.protocols.transport.tcp import TCP
123+
124+
for code, outcome in self.frames.items():
125+
with self.subTest(type=code):
126+
raw = _TCP_TO_80 + outcome.octets
127+
with warnings.catch_warnings():
128+
# An in-memory segment carries no checksum; the chain is
129+
# what is under test.
130+
warnings.simplefilter('ignore')
131+
with time_limit():
132+
proto = TCP(raw, len(raw))
133+
self.assertEqual(str(proto.protochain), 'TCP:HTTP/2')
134+
135+
136+
if __name__ == '__main__':
137+
unittest.main()

0 commit comments

Comments
 (0)