|
| 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