diff --git a/examples/generators/options.py b/examples/generators/options.py index 48480ee408..f19ae91beb 100644 --- a/examples/generators/options.py +++ b/examples/generators/options.py @@ -1120,15 +1120,28 @@ def _httpv2_overrides() -> 'dict[Any, dict[str, Any]]': # ``settings=None``, the default, matches none of the accepted forms. Enum_Frame.SETTINGS: {'settings': [(Enum_Setting.HEADER_TABLE_SIZE, 4096)]}, Enum_Frame.GOAWAY: {'debug_data': b'\xde\xad'}, + # A server-initiated stream is even and non-zero (RFC 9113 Section 5.1.1). + Enum_Frame.PUSH_PROMISE: {'promised_sid': 2}, } +#: HTTP/2 frame types that apply to the connection as a whole and so are sent +#: on stream 0 (RFC 9113 Sections 6.5, 6.7 and 6.8). Every other frame type is +#: sent on :data:`HTTPV2_STREAM`. +HTTPV2_CONNECTION_FRAMES = (4, 6, 7) # SETTINGS, PING, GOAWAY + +#: Stream identifier of every stream-level HTTP/2 frame: the first +#: client-initiated stream (RFC 9113 Section 5.1.1). ``DATA``, ``HEADERS``, +#: ``PRIORITY``, ``RST_STREAM``, ``PUSH_PROMISE`` and ``CONTINUATION`` are a +#: connection error on stream 0, and ``WINDOW_UPDATE`` may use either. +HTTPV2_STREAM = 1 + + def _httpv2_build(code: 'Any', kwargs: 'dict[str, Any]') -> 'Any': from pcapkit.protocols.application.httpv2 import HTTP - # SETTINGS and PING both reject a non-zero stream identifier, so every - # frame uses stream 0 rather than each one picking its own. - return HTTP(type=code, sid=0, frame=dict(kwargs)) + sid = 0 if int(code) in HTTPV2_CONNECTION_FRAMES else HTTPV2_STREAM + return HTTP(type=code, sid=sid, frame=dict(kwargs)) def _httpv2_parse(octets: 'bytes') -> 'Any': diff --git a/tests/protocols/test_option_generator_httpv2_stream_unit.py b/tests/protocols/test_option_generator_httpv2_stream_unit.py new file mode 100644 index 0000000000..07cdbbf44c --- /dev/null +++ b/tests/protocols/test_option_generator_httpv2_stream_unit.py @@ -0,0 +1,137 @@ +# -*- coding: utf-8 -*- +"""The generator's HTTP/2 frames decode as HTTP/2. C.f. #1156. + +:file:`examples/captures/options-transport.pcap` carries one TCP segment to port +80 per HTTP/2 frame type, built by ``_httpv2_build`` in +:file:`examples/generators/options.py`. That function put every frame on stream +0. :rfc:`9113#section-6` makes ``DATA``, ``HEADERS``, ``PRIORITY``, +``RST_STREAM``, ``PUSH_PROMISE`` and ``CONTINUATION`` on stream 0 a connection +error, and since #1153 :meth:`HTTP._guess_version +` declines a frame no +conforming sender writes, so six of the ten segments decoded as ``TCP:Raw``. +:mod:`tests.protocols.test_option_coverage_runtime` checks only the +``Ethernet:IPv4`` prefix, so nothing noticed. + +:data:`EXPECTED_STREAM` spells each type's stream out rather than reading it from +the generator, so a wrong generator constant fails here as ``0 != 1``. + +This module is unit tier: it builds its segments in memory from the generator's +own cases and reads no capture, so it runs on a fresh checkout. + +""" + +from __future__ import annotations + +import importlib.util +import sys +import types +import unittest +import warnings + +from tests._support import time_limit +from tests._tiers import ROOT + +RUNTIME_DEPS = ('tbtrim', 'aenum', 'chardet', 'dictdumper') +HAS_RUNTIME = all(importlib.util.find_spec(name) is not None for name in RUNTIME_DEPS) + +#: A 20-octet TCP header, data offset 5, ACK set, from port 50000 to port 80 -- +#: the ports ``_frame`` gives the ``tcp`` envelope. +_TCP_TO_80 = bytes.fromhex('c350005000000001000000015010ffff00000000') + +#: Frame type -> whether :rfc:`9113#section-6` puts it on a non-zero stream +#: (``True``) or on stream 0 (``False``). ``WINDOW_UPDATE`` may use either; the +#: generator puts it on a stream. +EXPECTED_STREAM = { + 0x0: True, # DATA (Section 6.1) + 0x1: True, # HEADERS (Section 6.2) + 0x2: True, # PRIORITY (Section 6.3) + 0x3: True, # RST_STREAM (Section 6.4) + 0x4: False, # SETTINGS (Section 6.5) + 0x5: True, # PUSH_PROMISE (Section 6.6) + 0x6: False, # PING (Section 6.7) + 0x7: False, # GOAWAY (Section 6.8) + 0x8: True, # WINDOW_UPDATE (Section 6.9) + 0x9: True, # CONTINUATION (Section 6.10) +} + + +def _load_generator() -> 'types.ModuleType': + """Load :file:`examples/generators/options.py` by path, under a name of its own. + + Returns: + The generator module. + + Raises: + RuntimeError: If the module cannot be found or loaded. + + """ + path = ROOT / 'examples' / 'generators' / 'options.py' + spec = importlib.util.spec_from_file_location( + 'pcapkit_samples_options_httpv2_stream', path) + if spec is None or spec.loader is None: # pragma: no cover + raise RuntimeError(f'cannot load the option generator from {path}') + + module = importlib.util.module_from_spec(spec) + sys.modules[spec.name] = module + spec.loader.exec_module(module) + return module + + +@unittest.skipUnless(HAS_RUNTIME, 'runtime dependencies not installed') +class HTTPv2GeneratedFrameTests(unittest.TestCase): + """Each ``httpv2-frame`` case, as the capture carries it.""" + + @classmethod + def setUpClass(cls) -> None: + options = _load_generator() + family = options.FAMILY_MAP['httpv2-frame'] + with warnings.catch_warnings(): + warnings.simplefilter('ignore') + cls.frames = {int(outcome.case.code): outcome + for outcome in options.outcomes((family,))} + + def test_every_frame_type_is_generated(self) -> None: + """The ten :rfc:`9113` frame types are the ten cases, all capturable.""" + self.assertEqual(sorted(self.frames), sorted(EXPECTED_STREAM)) + for code, outcome in self.frames.items(): + with self.subTest(type=code): + self.assertEqual(outcome.status, 'OK', outcome.detail) + + def test_each_frame_is_on_a_stream_its_type_allows(self) -> None: + """Octets 5-8 are non-zero exactly where :data:`EXPECTED_STREAM` says.""" + for code, outcome in self.frames.items(): + with self.subTest(type=code): + sid = int.from_bytes(outcome.octets[5:9], 'big') & 0x7FFFFFFF + self.assertEqual(sid != 0, EXPECTED_STREAM[code], f'stream {sid}') + + def test_push_promise_promises_a_server_initiated_stream(self) -> None: + """The promised stream is even and non-zero (:rfc:`9113#section-5.1.1`).""" + octets = self.frames[0x5].octets + promised = int.from_bytes(octets[9:13], 'big') & 0x7FFFFFFF + self.assertTrue(promised and promised % 2 == 0, f'promised stream {promised}') + + def test_each_length_counts_the_payload_only(self) -> None: + """The 24-bit Length excludes the 9-octet header (:rfc:`9113#section-4.1`).""" + for code, outcome in self.frames.items(): + with self.subTest(type=code): + length = int.from_bytes(outcome.octets[:3], 'big') + self.assertEqual(length, len(outcome.octets) - 9) + + def test_each_frame_decodes_as_http2_over_tcp(self) -> None: + """A port-80 segment carrying the frame decodes ``TCP:HTTP/2``, not ``TCP:Raw``.""" + from pcapkit.protocols.transport.tcp import TCP + + for code, outcome in self.frames.items(): + with self.subTest(type=code): + raw = _TCP_TO_80 + outcome.octets + with warnings.catch_warnings(): + # An in-memory segment carries no checksum; the chain is + # what is under test. + warnings.simplefilter('ignore') + with time_limit(): + proto = TCP(raw, len(raw)) + self.assertEqual(str(proto.protochain), 'TCP:HTTP/2') + + +if __name__ == '__main__': + unittest.main()