bdo-toolkit 1.0.1__tar.gz → 1.0.3__tar.gz

{bdo_toolkit-1.0.1/src/bdo_toolkit.egg-info → bdo_toolkit-1.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bdo-toolkit
-Version: 1.0.1
+Version: 1.0.3
 Summary: Passive, read-only BDO packet parsing toolkit for app developers.
 Author: bdo-toolkit contributors
 License-Expression: MIT
@@ -28,6 +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)
+[![PyPI version](https://img.shields.io/pypi/v/bdo-toolkit?style=flat-square&label=version)](https://pypi.org/project/bdo-toolkit/)
 [![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)
@@ -48,11 +49,21 @@ traffic into structured, application-ready data.
 
 ## Capabilities
 
-| In-game task | Python result | Status | Guide |
+bdo-toolkit exposes three passive workflows. Each can observe live traffic or
+replay a saved PCAP or PCAPNG file.
+
+| Capability | What it provides | Guide | Status |
 | --- | --- | --- | --- |
-| Watch supported item changes such as loot, gathering, and storage activity | A continuing stream of typed `BDOEvent` objects | Stable | [Item events](https://ychwu.github.io/bdo-toolkit/#item-overview) |
-| Log in or switch characters | One observational `ItemStateSnapshot` of inventory, known balances, and town storage | Beta | [Inventory & town storage](https://ychwu.github.io/bdo-toolkit/#item-state-overview) |
-| Load the Arena of Solare Leaderboard | One `SolareCaptureResult`; a complete result contains a leaderboard snapshot | Beta | [Arena of Solare](https://ychwu.github.io/bdo-toolkit/#solare-overview) |
+| Item activity | A continuing stream of typed `BDOEvent` objects for supported loot, gathering, inventory, and storage changes | [Item events](https://ychwu.github.io/bdo-toolkit/#item-overview) | Stable |
+| Inventory and town storage | A finite `ItemStateSnapshot` assembled from character-load traffic, with inventory, known balances, and observed town storage | [Inventory & town storage](https://ychwu.github.io/bdo-toolkit/#item-state-overview) | Beta |
+| Arena of Solare leaderboards | A finite `SolareCaptureResult` containing overall rankings, class tables, and player statistics when the capture is complete | [Arena of Solare](https://ychwu.github.io/bdo-toolkit/#solare-overview) | Beta |
+
+These workflows include synchronous and
+[asyncio](https://ychwu.github.io/bdo-toolkit/#asyncio) sessions, capture and
+decoder health diagnostics, console and JSONL event writers, and a
+[command-line interface](https://ychwu.github.io/bdo-toolkit/#cli). Exact
+signatures, fields, lifecycle behavior, and failure contracts are in the
+[API index](https://ychwu.github.io/bdo-toolkit/#api-index).
 
 Testing and validation cover **NA/EU only**. Compatibility with other regional
 services is unknown.
@@ -98,46 +109,12 @@ installed with the Python wheel.
 See the [Examples index](https://ychwu.github.io/bdo-toolkit/#item-examples)
 for every script, its prerequisites, and the guide that explains it.
 
-## Documentation
-
-The documentation separates task-focused guides from the symbol-first API
-reference. Exact signatures, fields, lifecycle behavior, and failure contracts
-live there rather than in this README.
-
-| Goal | Start here |
-| --- | --- |
-| Understand the package | [Overview](https://ychwu.github.io/bdo-toolkit/#overview) |
-| Build with live item events | [Item events](https://ychwu.github.io/bdo-toolkit/#item-overview) |
-| Query character inventory and town storage | [Inventory & town storage](https://ychwu.github.io/bdo-toolkit/#item-state-overview) |
-| Rebuild item decoding after a patch | [Calibration](https://ychwu.github.io/bdo-toolkit/#calibration-workflow) |
-| Capture and query an Arena of Solare leaderboard | [Arena of Solare](https://ychwu.github.io/bdo-toolkit/#solare-overview) |
-| Integrate with an asyncio application | [Asyncio integration](https://ychwu.github.io/bdo-toolkit/#asyncio) |
-| Look up a class, function, or model | [API index](https://ychwu.github.io/bdo-toolkit/#api-index) |
-| Use the terminal interface | [Command line](https://ychwu.github.io/bdo-toolkit/#cli) |
-| Diagnose a problem | [Troubleshooting](https://ychwu.github.io/bdo-toolkit/#errors) |
-| Review data handling and project boundaries | [Safety & privacy](https://ychwu.github.io/bdo-toolkit/#stability) |
-
 ## Support
 
 For questions, contact me on Discord: `._.__.__._._.__._____.__._.___.`
 
 For bugs and feature requests, [open a GitHub issue](https://github.com/ychwu/bdo-toolkit/issues).
 
-## Development
-
-```powershell
-git clone https://github.com/ychwu/bdo-toolkit.git
-cd bdo-toolkit
-python -m pip install -e ".[dev]"
-python -m pytest -q -W error
-python -m mypy src/bdo_toolkit
-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.14. Tests that require private
-game-session captures skip when those local fixtures are absent.
-
 ## License
 
 bdo-toolkit is available under the

{bdo_toolkit-1.0.1 → bdo_toolkit-1.0.3}/README.md

@@ -1,6 +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)
+[![PyPI version](https://img.shields.io/pypi/v/bdo-toolkit?style=flat-square&label=version)](https://pypi.org/project/bdo-toolkit/)
 [![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)
@@ -21,11 +22,21 @@ traffic into structured, application-ready data.
 
 ## Capabilities
 
-| In-game task | Python result | Status | Guide |
+bdo-toolkit exposes three passive workflows. Each can observe live traffic or
+replay a saved PCAP or PCAPNG file.
+
+| Capability | What it provides | Guide | Status |
 | --- | --- | --- | --- |
-| Watch supported item changes such as loot, gathering, and storage activity | A continuing stream of typed `BDOEvent` objects | Stable | [Item events](https://ychwu.github.io/bdo-toolkit/#item-overview) |
-| Log in or switch characters | One observational `ItemStateSnapshot` of inventory, known balances, and town storage | Beta | [Inventory & town storage](https://ychwu.github.io/bdo-toolkit/#item-state-overview) |
-| Load the Arena of Solare Leaderboard | One `SolareCaptureResult`; a complete result contains a leaderboard snapshot | Beta | [Arena of Solare](https://ychwu.github.io/bdo-toolkit/#solare-overview) |
+| Item activity | A continuing stream of typed `BDOEvent` objects for supported loot, gathering, inventory, and storage changes | [Item events](https://ychwu.github.io/bdo-toolkit/#item-overview) | Stable |
+| Inventory and town storage | A finite `ItemStateSnapshot` assembled from character-load traffic, with inventory, known balances, and observed town storage | [Inventory & town storage](https://ychwu.github.io/bdo-toolkit/#item-state-overview) | Beta |
+| Arena of Solare leaderboards | A finite `SolareCaptureResult` containing overall rankings, class tables, and player statistics when the capture is complete | [Arena of Solare](https://ychwu.github.io/bdo-toolkit/#solare-overview) | Beta |
+
+These workflows include synchronous and
+[asyncio](https://ychwu.github.io/bdo-toolkit/#asyncio) sessions, capture and
+decoder health diagnostics, console and JSONL event writers, and a
+[command-line interface](https://ychwu.github.io/bdo-toolkit/#cli). Exact
+signatures, fields, lifecycle behavior, and failure contracts are in the
+[API index](https://ychwu.github.io/bdo-toolkit/#api-index).
 
 Testing and validation cover **NA/EU only**. Compatibility with other regional
 services is unknown.
@@ -71,46 +82,12 @@ installed with the Python wheel.
 See the [Examples index](https://ychwu.github.io/bdo-toolkit/#item-examples)
 for every script, its prerequisites, and the guide that explains it.
 
-## Documentation
-
-The documentation separates task-focused guides from the symbol-first API
-reference. Exact signatures, fields, lifecycle behavior, and failure contracts
-live there rather than in this README.
-
-| Goal | Start here |
-| --- | --- |
-| Understand the package | [Overview](https://ychwu.github.io/bdo-toolkit/#overview) |
-| Build with live item events | [Item events](https://ychwu.github.io/bdo-toolkit/#item-overview) |
-| Query character inventory and town storage | [Inventory & town storage](https://ychwu.github.io/bdo-toolkit/#item-state-overview) |
-| Rebuild item decoding after a patch | [Calibration](https://ychwu.github.io/bdo-toolkit/#calibration-workflow) |
-| Capture and query an Arena of Solare leaderboard | [Arena of Solare](https://ychwu.github.io/bdo-toolkit/#solare-overview) |
-| Integrate with an asyncio application | [Asyncio integration](https://ychwu.github.io/bdo-toolkit/#asyncio) |
-| Look up a class, function, or model | [API index](https://ychwu.github.io/bdo-toolkit/#api-index) |
-| Use the terminal interface | [Command line](https://ychwu.github.io/bdo-toolkit/#cli) |
-| Diagnose a problem | [Troubleshooting](https://ychwu.github.io/bdo-toolkit/#errors) |
-| Review data handling and project boundaries | [Safety & privacy](https://ychwu.github.io/bdo-toolkit/#stability) |
-
 ## Support
 
 For questions, contact me on Discord: `._.__.__._._.__._____.__._.___.`
 
 For bugs and feature requests, [open a GitHub issue](https://github.com/ychwu/bdo-toolkit/issues).
 
-## Development
-
-```powershell
-git clone https://github.com/ychwu/bdo-toolkit.git
-cd bdo-toolkit
-python -m pip install -e ".[dev]"
-python -m pytest -q -W error
-python -m mypy src/bdo_toolkit
-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.14. Tests that require private
-game-session captures skip when those local fixtures are absent.
-
 ## License
 
 bdo-toolkit is available under the

{bdo_toolkit-1.0.1 → bdo_toolkit-1.0.3}/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),