bdo-toolkit 1.0.0__tar.gz → 1.0.2__tar.gz

{bdo_toolkit-1.0.0/src/bdo_toolkit.egg-info → bdo_toolkit-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bdo-toolkit
-Version: 1.0.0
+Version: 1.0.2
 Summary: Passive, read-only BDO packet parsing toolkit for app developers.
 Author: bdo-toolkit contributors
 License-Expression: MIT
@@ -12,9 +12,10 @@ Keywords: bdo,packets,parse,pcap,passive
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Typing :: Typed
-Requires-Python: >=3.10
+Requires-Python: >=3.14
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: scapy>=2.5
@@ -27,7 +28,7 @@ Dynamic: license-file
 # bdo-toolkit
 
 [![CI](https://img.shields.io/github/actions/workflow/status/ychwu/bdo-toolkit/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/ychwu/bdo-toolkit/actions/workflows/ci.yml)
-[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://github.com/ychwu/bdo-toolkit/blob/main/pyproject.toml)
+[![Python 3.14+](https://img.shields.io/badge/python-3.14%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://github.com/ychwu/bdo-toolkit/blob/main/pyproject.toml)
 ![Tested on NA/EU](https://img.shields.io/badge/tested-NA%2FEU-5b61a8?style=flat-square)
 [![Package: Stable](https://img.shields.io/badge/package-stable-2f855a?style=flat-square)](https://ychwu.github.io/bdo-toolkit/#stability)
 [![License: MIT](https://img.shields.io/badge/license-MIT-2f855a?style=flat-square)](https://github.com/ychwu/bdo-toolkit/blob/main/LICENSE)
@@ -62,7 +63,7 @@ services is unknown.
 python -m pip install bdo-toolkit
 ```
 
-Python 3.10 or newer is required. Before live capture, complete
+Python 3.14 or newer is required. Before live capture, complete
 [Installation & setup](https://ychwu.github.io/bdo-toolkit/#capture-foundation),
 including Npcap on Windows and permission to capture on the selected interface.
 Offline PCAP and PCAPNG replay does not require Npcap.
@@ -134,7 +135,7 @@ python -m pip wheel . --no-deps --wheel-dir dist
 ```
 
 CI runs tests, type checking, wheel construction, and a CLI smoke test on
-Ubuntu and Windows with Python 3.10 and 3.14. Tests that require private
+Ubuntu and Windows with Python 3.14. Tests that require private
 game-session captures skip when those local fixtures are absent.
 
 ## License

{bdo_toolkit-1.0.0 → bdo_toolkit-1.0.2}/README.md

@@ -1,7 +1,7 @@
 # bdo-toolkit
 
 [![CI](https://img.shields.io/github/actions/workflow/status/ychwu/bdo-toolkit/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/ychwu/bdo-toolkit/actions/workflows/ci.yml)
-[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://github.com/ychwu/bdo-toolkit/blob/main/pyproject.toml)
+[![Python 3.14+](https://img.shields.io/badge/python-3.14%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://github.com/ychwu/bdo-toolkit/blob/main/pyproject.toml)
 ![Tested on NA/EU](https://img.shields.io/badge/tested-NA%2FEU-5b61a8?style=flat-square)
 [![Package: Stable](https://img.shields.io/badge/package-stable-2f855a?style=flat-square)](https://ychwu.github.io/bdo-toolkit/#stability)
 [![License: MIT](https://img.shields.io/badge/license-MIT-2f855a?style=flat-square)](https://github.com/ychwu/bdo-toolkit/blob/main/LICENSE)
@@ -36,7 +36,7 @@ services is unknown.
 python -m pip install bdo-toolkit
 ```
 
-Python 3.10 or newer is required. Before live capture, complete
+Python 3.14 or newer is required. Before live capture, complete
 [Installation & setup](https://ychwu.github.io/bdo-toolkit/#capture-foundation),
 including Npcap on Windows and permission to capture on the selected interface.
 Offline PCAP and PCAPNG replay does not require Npcap.
@@ -108,7 +108,7 @@ python -m pip wheel . --no-deps --wheel-dir dist
 ```
 
 CI runs tests, type checking, wheel construction, and a CLI smoke test on
-Ubuntu and Windows with Python 3.10 and 3.14. Tests that require private
+Ubuntu and Windows with Python 3.14. Tests that require private
 game-session captures skip when those local fixtures are absent.
 
 ## License

{bdo_toolkit-1.0.0 → bdo_toolkit-1.0.2}/pyproject.toml

@@ -7,7 +7,7 @@ name = "bdo-toolkit"
 dynamic = ["version"]
 description = "Passive, read-only BDO packet parsing toolkit for app developers."
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.14"
 dependencies = [
   "scapy>=2.5",
 ]
@@ -21,6 +21,7 @@ classifiers = [
   "Development Status :: 5 - Production/Stable",
   "Operating System :: OS Independent",
   "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.14",
   "Programming Language :: Python :: 3 :: Only",
   "Typing :: Typed",
 ]
@@ -47,6 +48,9 @@ where = ["src"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 
+[tool.mypy]
+python_version = "3.14"
+
 [tool.setuptools.package-data]
 bdo_toolkit = ["py.typed"]
 

{bdo_toolkit-1.0.0 → bdo_toolkit-1.0.2}/src/bdo_toolkit/_async_sessions.py

@@ -14,7 +14,7 @@ from concurrent.futures import ThreadPoolExecutor
 from functools import partial
 from pathlib import Path
 from types import TracebackType
-from typing import AsyncIterator, Callable, Optional, TypeVar
+from typing import AsyncIterator, Callable, Optional
 
 from ._capture_runtime import CaptureEndpoint, _attach_cleanup_owner
 from ._capture_options import LiveCaptureOptions, PacketCaptureOptions
@@ -33,10 +33,7 @@ from .origin_learning import CompanionObservation
 from .profiles import OpcodeProfile
 
 
-T = TypeVar("T")
-
-
-async def _wait_ignoring_cancellation(future: asyncio.Future[T]) -> T:
+async def _wait_ignoring_cancellation[T](future: asyncio.Future[T]) -> T:
     """Wait for an already-started operation, even after caller cancellation."""
 
     while not future.done():
@@ -51,14 +48,14 @@ async def _wait_ignoring_cancellation(future: asyncio.Future[T]) -> T:
     return future.result()
 
 
-async def _await_preserving_future(future: asyncio.Future[T]) -> T:
+async def _await_preserving_future[T](future: asyncio.Future[T]) -> T:
     """Await without cancelling or wrapping the submitted worker future."""
 
     await asyncio.wait((future,))
     return future.result()
 
 
-def _thread_task(function: Callable[[], T]) -> asyncio.Task[T]:
+def _thread_task[T](function: Callable[[], T]) -> asyncio.Task[T]:
     return asyncio.create_task(asyncio.to_thread(function))
 
 
@@ -143,7 +140,7 @@ class AsyncLiveCaptureSession:
 
         self._session.raise_if_failed()
 
-    def _submit(self, function: Callable[[], T]) -> asyncio.Future[T]:
+    def _submit[T](self, function: Callable[[], T]) -> asyncio.Future[T]:
         if self._executor_closed:
             raise RuntimeError("async live capture session is already closed")
         loop = asyncio.get_running_loop()
@@ -380,11 +377,10 @@ class AsyncLiveCaptureSession:
                     self,
                     context="async live item capture context",
                 )
-            if hasattr(exc_value, "add_note"):
-                exc_value.add_note(
-                    "async live item capture context cleanup also failed: "
-                    f"{cleanup_error!r}"
-                )
+            exc_value.add_note(
+                "async live item capture context cleanup also failed: "
+                f"{cleanup_error!r}"
+            )
 
 
 class AsyncCalibrationSession:
@@ -644,8 +640,7 @@ class AsyncCalibrationSession:
                     self,
                     context="async live calibration context",
                 )
-            if hasattr(exc_value, "add_note"):
-                exc_value.add_note(
-                    "async live calibration context cleanup also failed: "
-                    f"{cleanup_error!r}"
-                )
+            exc_value.add_note(
+                "async live calibration context cleanup also failed: "
+                f"{cleanup_error!r}"
+            )

{bdo_toolkit-1.0.0 → bdo_toolkit-1.0.2}/src/bdo_toolkit/_capture_backend.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Iterable, Iterator, Optional, Protocol
+from typing import Any, Iterable, Iterator, Optional, Protocol
 
 
 class SegmentConsumer(Protocol):
@@ -93,21 +93,138 @@ def validate_server_ports(ports: Iterable[int]) -> tuple[int, ...]:
     return tuple(normalized)
 
 
+def _required_header_integer(value: Any, field_name: str) -> int:
+    """Return one decoded header field or reject an incomplete dissection."""
+    if value is None:
+        raise ValueError(f"IPv4/TCP {field_name} is unavailable")
+    try:
+        return int(value)
+    except (TypeError, ValueError, OverflowError) as exc:
+        raise ValueError(f"IPv4/TCP {field_name} is invalid: {value!r}") from exc
+
+
+def _validate_unfragmented_ipv4_tcp(ip: Any) -> None:
+    """Reject IP states that cannot be handed to TCP reassembly safely."""
+    version = _required_header_integer(getattr(ip, "version", None), "version")
+    if version != 4:
+        raise ValueError(f"expected IPv4 version 4, got {version}")
+
+    fragment_offset = _required_header_integer(
+        getattr(ip, "frag", None),
+        "fragment offset",
+    )
+    flags = _required_header_integer(getattr(ip, "flags", None), "flags")
+    if fragment_offset != 0 or flags & 0x01:
+        raise ValueError(
+            "fragmented IPv4/TCP packets are unsupported; "
+            "TCP reassembly requires a complete IP datagram"
+        )
+
+
+def _captured_ipv4_length(ip: Any) -> int:
+    """Return captured bytes without reserializing ordinary Scapy packets."""
+    original = getattr(ip, "original", None)
+    if isinstance(original, (bytes, bytearray, memoryview)) and original:
+        return len(original)
+    return len(bytes(ip))
+
+
+def _extract_ipv4_tcp_payload(ip: Any, tcp: Any) -> bytes:
+    """Return only application bytes declared by complete IPv4/TCP headers.
+
+    Scapy exposes link-layer padding through ``tcp.payload`` even though those
+    bytes lie beyond the IPv4 total length. The wire header lengths are the
+    authority at this boundary so padding can never advance TCP sequence state.
+    """
+    total_length = _required_header_integer(
+        getattr(ip, "len", None),
+        "total length",
+    )
+    ip_header_words = _required_header_integer(
+        getattr(ip, "ihl", None),
+        "header length",
+    )
+    tcp_header_words = _required_header_integer(
+        getattr(tcp, "dataofs", None),
+        "TCP header length",
+    )
+
+    if not 5 <= ip_header_words <= 15:
+        raise ValueError(
+            f"invalid IPv4 header length: {ip_header_words} 32-bit words"
+        )
+    if not 5 <= tcp_header_words <= 15:
+        raise ValueError(
+            f"invalid TCP header length: {tcp_header_words} 32-bit words"
+        )
+    if not 0 <= total_length <= 0xFFFF:
+        raise ValueError(f"invalid IPv4 total length: {total_length}")
+
+    captured_length = _captured_ipv4_length(ip)
+    if captured_length < total_length:
+        raise ValueError(
+            "truncated IPv4 packet: "
+            f"header declares {total_length} bytes, capture has {captured_length}"
+        )
+
+    header_length = (ip_header_words + tcp_header_words) * 4
+    if total_length < header_length:
+        raise ValueError(
+            "invalid IPv4/TCP header lengths: "
+            f"total length {total_length} is smaller than {header_length}"
+        )
+
+    declared_length = total_length - header_length
+    available = bytes(getattr(tcp, "payload", b""))
+    if len(available) < declared_length:
+        raise ValueError(
+            "truncated IPv4/TCP payload: "
+            f"header declares {declared_length} bytes, capture has {len(available)}"
+        )
+    return available[:declared_length]
+
+
+def _consumer_server_ports(engine: SegmentConsumer) -> Optional[frozenset[int]]:
+    """Read the validated port set exposed by each built-in consumer."""
+    ports = getattr(engine, "server_ports", None)
+    if ports is None:
+        # Solare's internal collector predates the shared ``server_ports`` name.
+        ports = getattr(engine, "ports", None)
+    if ports is None:
+        return None
+    return frozenset(ports)
+
+
 def make_packet_handler(engine: SegmentConsumer):
     IP, TCP, _, _, _ = import_scapy()
+    server_ports = _consumer_server_ports(engine)
 
     def handle(packet) -> None:
-        if IP not in packet or TCP not in packet:
+        if IP not in packet:
             return
 
         ip = packet[IP]
+        protocol = _required_header_integer(getattr(ip, "proto", None), "protocol")
+        if protocol != 6:
+            return
+
+        if TCP not in packet:
+            # Non-initial fragments and severely truncated headers have no
+            # source port, so they cannot be attributed to a selected flow.
+            return
+
         tcp = packet[TCP]
-        payload = bytes(tcp.payload)
+        source_port = int(tcp.sport)
+        if server_ports is not None and source_port not in server_ports:
+            return
+
+        _validate_unfragmented_ipv4_tcp(ip)
+        payload = _extract_ipv4_tcp_payload(ip, tcp)
         flags = int(tcp.flags)
 
         engine.process_tcp_segment(
             source_ip=str(ip.src),
-            source_port=int(tcp.sport),
+            source_port=source_port,
             destination_ip=str(ip.dst),
             destination_port=int(tcp.dport),
             sequence=int(tcp.seq),

{bdo_toolkit-1.0.0 → bdo_toolkit-1.0.2}/src/bdo_toolkit/_capture_runtime.py

@@ -64,18 +64,17 @@ def _attach_cleanup_owner(
         # Built-in and ordinary application exceptions expose __dict__. Keep
         # the original failure identity even for an exotic immutable subtype.
         pass
-    if hasattr(error, "add_note"):
-        if attached:
-            error.add_note(
-                f"{context} cleanup is incomplete; retry stop() on "
-                "exception.cleanup_owner"
-            )
-        else:
-            error.add_note(
-                f"{context} cleanup is incomplete; this exception subtype "
-                "cannot expose cleanup_owner, so retain and stop the original "
-                "session object"
-            )
+    if attached:
+        error.add_note(
+            f"{context} cleanup is incomplete; retry stop() on "
+            "exception.cleanup_owner"
+        )
+    else:
+        error.add_note(
+            f"{context} cleanup is incomplete; this exception subtype "
+            "cannot expose cleanup_owner, so retain and stop the original "
+            "session object"
+        )
 
 
 @dataclass(frozen=True)
@@ -456,11 +455,10 @@ class LivePacketCapture:
                     # Startup remains the primary failure, but incomplete
                     # cleanup must be explicit in its traceback and remains
                     # retryable through stop().
-                    if hasattr(exc, "add_note"):
-                        exc.add_note(
-                            "live capture startup cleanup also failed: "
-                            f"{cleanup_error!r}"
-                        )
+                    exc.add_note(
+                        "live capture startup cleanup also failed: "
+                        f"{cleanup_error!r}"
+                    )
                 if not self._cleanup_incomplete:
                     self._capture = None
                     self._capture_socket = None