bdo-toolkit 1.0.0__py3-none-any.whl

bdo_toolkit/diagnostics.py

@@ -0,0 +1,51 @@
+"""Out-of-band protocol compatibility diagnostics."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class DecoderDiagnostic:
+    """One deduplicated decoder-compatibility warning.
+
+    Diagnostics are deliberately not :class:`BDOEvent` objects and therefore
+    bypass event filters. A storage-ID-filtered production app can learn that
+    its profile stopped resolving destinations even when no matching event can
+    be delivered.
+    """
+
+    code: str
+    message: str
+    severity: str = "warning"
+    subsystem: str = "storage"
+    opcode: Optional[int] = None
+    requested_storage_ids: tuple[int, ...] = ()
+
+    def to_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class DecoderHealth:
+    """Snapshot of storage-decoder compatibility, separate from packet loss."""
+
+    storage_status: str = "not_observed"
+    storage_messages_observed: int = 0
+    storage_messages_decoded: int = 0
+    storage_records_decoded: int = 0
+    storage_destination_failures: int = 0
+    storage_geometry_failures: int = 0
+    diagnostics_emitted: int = 0
+
+    @property
+    def storage_is_compatible(self) -> Optional[bool]:
+        if self.storage_status == "not_observed":
+            return None
+        return self.storage_status == "compatible"
+
+    def to_dict(self) -> dict[str, object]:
+        output = asdict(self)
+        output["storage_is_compatible"] = self.storage_is_compatible
+        return output

bdo_toolkit/events.py

@@ -0,0 +1,214 @@
+"""Stable event objects emitted by the toolkit.
+
+The packet protocol is still moving, so these models intentionally keep an
+``extra`` mapping for newly discovered fields that should not require a schema
+break on day one.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import datetime as dt
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import Any, Mapping, Optional
+
+
+def _freeze_value(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return MappingProxyType(
+            {key: _freeze_value(item) for key, item in value.items()}
+        )
+    if isinstance(value, (list, tuple)):
+        return tuple(_freeze_value(item) for item in value)
+    if isinstance(value, (set, frozenset)):
+        return frozenset(_freeze_value(item) for item in value)
+    return value
+
+
+def _thaw_value(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return {key: _thaw_value(item) for key, item in value.items()}
+    if isinstance(value, tuple):
+        return [_thaw_value(item) for item in value]
+    if isinstance(value, frozenset):
+        return [_thaw_value(item) for item in value]
+    return value
+
+
+def _hashable_value(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return frozenset(
+            (key, _hashable_value(item)) for key, item in value.items()
+        )
+    if isinstance(value, (tuple, list)):
+        return tuple(_hashable_value(item) for item in value)
+    if isinstance(value, (set, frozenset)):
+        return frozenset(_hashable_value(item) for item in value)
+    return value
+
+
+@dataclass(frozen=True)
+class Flow:
+    """Network flow for a server-to-client packet stream."""
+
+    source_ip: str
+    source_port: int
+    destination_ip: str
+    destination_port: int
+
+    def __str__(self) -> str:
+        return (
+            f"{self.source_ip}:{self.source_port} -> "
+            f"{self.destination_ip}:{self.destination_port}"
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        return dataclasses.asdict(self)
+
+
+@dataclass(frozen=True)
+class BDOEvent:
+    """One decoded gameplay-relevant packet event."""
+
+    event_type: str
+    timestamp: float
+    flow: Flow
+    item_id: int
+    quantity: int
+    # Known semantic origin, producing system, or event context. Storage
+    # endpoint identity belongs exclusively to storage_id/name fields.
+    source: Optional[str] = None
+    raw_context: Optional[str] = None
+    opcode: Optional[int] = None
+    message_length: Optional[int] = None
+    base_item_id: Optional[int] = None
+    enhancement_level: Optional[int] = None
+    enhancement: Optional[str] = None
+    inventory_slot: Optional[int] = None
+    item_instance: Optional[str] = None
+    # Opaque per-record instance observed to remain identical while matching
+    # item/quantity records entered different town storages. It is not the
+    # destination identity; ``storage_id`` carries that key.
+    storage_instance: Optional[str] = None
+    record_index: Optional[int] = None
+    record_count: Optional[int] = None
+    record_offset: Optional[int] = None
+    confidence: Optional[str] = None
+    extra: Mapping[str, Any] = field(default_factory=dict)
+    storage_id: Optional[int] = None
+    storage_name: Optional[str] = None
+    storage_name_confidence: Optional[str] = None
+    # Internal TCP connection-lifetime identity. This must not affect the
+    # public event schema, equality, or hashing; stateful classifiers use it to
+    # keep reconnects that reuse one four-tuple isolated.
+    _flow_generation: int = field(
+        default=0,
+        kw_only=True,
+        repr=False,
+        compare=False,
+        hash=False,
+    )
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "extra", _freeze_value(self.extra))
+
+    @property
+    def timestamp_text(self) -> str:
+        return dt.datetime.fromtimestamp(self.timestamp).strftime("%H:%M:%S.%f")[:-3]
+
+    @property
+    def timestamp_iso(self) -> str:
+        """Deterministic UTC ISO-8601 timestamp for serialization."""
+        return (
+            dt.datetime.fromtimestamp(self.timestamp, tz=dt.timezone.utc)
+            .isoformat(timespec="milliseconds")
+            .replace("+00:00", "Z")
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        output: dict[str, Any] = {
+            "event_type": self.event_type,
+            "timestamp": self.timestamp,
+            "timestamp_iso": self.timestamp_iso,
+            "flow": self.flow.to_dict(),
+            "item_id": self.item_id,
+            "quantity": self.quantity,
+        }
+        optional = {
+            "source": self.source,
+            "raw_context": self.raw_context,
+            "opcode": f"0x{self.opcode:04X}" if self.opcode is not None else None,
+            "message_length": self.message_length,
+            "base_item_id": self.base_item_id,
+            "enhancement_level": self.enhancement_level,
+            "enhancement": self.enhancement,
+            "inventory_slot": (
+                f"0x{self.inventory_slot:02x}"
+                if self.inventory_slot is not None
+                else None
+            ),
+            "item_instance": self.item_instance,
+            "storage_instance": self.storage_instance,
+            "storage_id": self.storage_id,
+            "storage_name": self.storage_name,
+            "storage_name_confidence": self.storage_name_confidence,
+            "record_index": self.record_index,
+            "record_count": self.record_count,
+            "record_offset": self.record_offset,
+            "confidence": self.confidence,
+        }
+        for key, value in optional.items():
+            if value is not None:
+                output[key] = value
+        if self.extra:
+            output["extra"] = _thaw_value(self.extra)
+        return output
+
+    def __hash__(self) -> int:
+        values = tuple(
+            getattr(self, field_info.name)
+            for field_info in dataclasses.fields(self)
+            if field_info.name != "extra"
+            and field_info.compare
+            and field_info.hash is not False
+        )
+        return hash((values, _hashable_value(self.extra)))
+
+    def format_human(self) -> str:
+        parts = [f"[{self.timestamp_text}]", self.event_type.upper()]
+        is_storage = self.event_type in {
+            "storage_delta",
+            "storage_snapshot",
+            "storage_record",
+        }
+        if self.source is not None:
+            parts.append(f"source={self.source!r}")
+        if is_storage:
+            if self.storage_name is not None:
+                parts.append(f"destination={self.storage_name!r}")
+            elif self.storage_id is not None:
+                parts.append(
+                    f"destination='UNKNOWN_STORAGE(0x{self.storage_id:08x})'"
+                )
+        parts.extend((f"item_id={self.item_id}", f"quantity={self.quantity}"))
+        if self.base_item_id is not None:
+            parts.append(f"base_item_id={self.base_item_id}")
+        if self.enhancement_level is not None:
+            parts.append(f"enhancement_level={self.enhancement_level}")
+        if self.enhancement is not None:
+            parts.append(f"enhancement={self.enhancement}")
+        if self.record_index is not None and self.record_count is not None:
+            parts.append(f"record_index={self.record_index}/{self.record_count}")
+        if self.item_instance is not None:
+            parts.append(f"item_instance={self.item_instance}")
+        if self.storage_instance is not None:
+            parts.append(f"storage_instance={self.storage_instance}")
+        if self.storage_id is not None:
+            parts.append(f"storage_id=0x{self.storage_id:08x}")
+        if self.storage_name_confidence is not None:
+            parts.append(
+                f"storage_name_confidence={self.storage_name_confidence}"
+            )
+        return " ".join(parts)
+

bdo_toolkit/filters.py

@@ -0,0 +1,105 @@
+"""Composable event filters for app-facing streams."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable, Optional, TypeVar
+
+from .events import BDOEvent
+
+
+T = TypeVar("T")
+
+
+_ACTIVITY_EVENT_TYPES = frozenset(
+    {"loot_preview", "item_received", "storage_delta"}
+)
+_SNAPSHOT_RECORD_EVENT_TYPES = frozenset(
+    {"inventory_snapshot", "storage_snapshot"}
+)
+
+
+def _freeze(values: Optional[Iterable[T]]) -> Optional[frozenset[T]]:
+    if values is None:
+        return None
+    if isinstance(values, (str, bytes)):
+        raise TypeError("filter values must be an iterable of values, not a string")
+    return frozenset(values)
+
+
+@dataclass(frozen=True, init=False)
+class EventFilter:
+    """Filter completed events before yielding them to an application.
+
+    Constructing ``EventFilter()`` directly remains an unconstrained filter.
+    The named presets make common delivery policies explicit without changing
+    the meaning of any caller-supplied filter.
+    """
+
+    event_types: Optional[frozenset[str]] = None
+    # Exact semantic origin, producing-system, or event-context labels.
+    sources: Optional[frozenset[str]] = None
+    # Authoritative numeric storage destination identities.
+    storage_ids: Optional[frozenset[int]] = None
+    item_ids: Optional[frozenset[int]] = None
+
+    def __init__(
+        self,
+        *,
+        event_types: Optional[Iterable[str]] = None,
+        sources: Optional[Iterable[str]] = None,
+        storage_ids: Optional[Iterable[int]] = None,
+        item_ids: Optional[Iterable[int]] = None,
+    ) -> None:
+        # Normalize at the public constructor boundary so callers can use
+        # ordinary sets/lists while the frozen object remains truly immutable.
+        object.__setattr__(self, "event_types", _freeze(event_types))
+        object.__setattr__(self, "sources", _freeze(sources))
+        object.__setattr__(self, "storage_ids", _freeze(storage_ids))
+        object.__setattr__(self, "item_ids", _freeze(item_ids))
+
+    @classmethod
+    def from_values(
+        cls,
+        *,
+        event_types: Optional[Iterable[str]] = None,
+        sources: Optional[Iterable[str]] = None,
+        storage_ids: Optional[Iterable[int]] = None,
+        item_ids: Optional[Iterable[int]] = None,
+    ) -> "EventFilter":
+        return cls(
+            event_types=event_types,
+            sources=sources,
+            storage_ids=storage_ids,
+            item_ids=item_ids,
+        )
+
+    @classmethod
+    def activity(cls) -> "EventFilter":
+        """Ordinary live events, excluding hydration and neutral diagnostics."""
+
+        return cls(event_types=_ACTIVITY_EVENT_TYPES)
+
+    @classmethod
+    def snapshot_records(cls) -> "EventFilter":
+        """Per-record inventory and storage character-load hydration."""
+
+        return cls(event_types=_SNAPSHOT_RECORD_EVENT_TYPES)
+
+    @classmethod
+    def all(cls) -> "EventFilter":
+        """Every completed decoded event, equivalent to ``EventFilter()``."""
+
+        return cls()
+
+    def allows(self, event: BDOEvent) -> bool:
+        if self.event_types is not None and event.event_type not in self.event_types:
+            return False
+        if self.sources is not None and event.source not in self.sources:
+            return False
+        if self.storage_ids is not None and event.storage_id not in self.storage_ids:
+            return False
+        if self.item_ids is not None and event.item_id not in self.item_ids:
+            return False
+        return True
+

bdo_toolkit/item_state.py

@@ -0,0 +1,48 @@
+"""Canonical experimental facade for aggregate inventory and storage state.
+
+The implementation remains in :mod:`bdo_toolkit.character_state` so existing
+imports continue to work.  These aliases provide item-domain naming without a
+wholesale move or package-root stability promise.
+"""
+
+from __future__ import annotations
+
+from .character_state import (
+    CharacterLoadSession,
+    CharacterStateSnapshot as ItemStateSnapshot,
+    InventoryContainerSummary,
+    InventoryHydrationDiagnostics,
+    InventorySnapshotSummary,
+    ItemStateCaptureLimitError,
+    ItemStateCaptureLimits,
+    ItemStateCoverage,
+    ItemStateDiagnostics,
+    ItemStateProvenance,
+    SnapshotItem,
+    StorageContents,
+    StorageDestinationDiagnostics,
+    StorageHydrationDiagnostics,
+    StorageSnapshotSummary,
+    analyze_character_load_pcap as analyze_item_state_pcap,
+    format_character_state as format_item_state,
+)
+
+__all__ = [
+    "CharacterLoadSession",
+    "InventoryContainerSummary",
+    "InventoryHydrationDiagnostics",
+    "InventorySnapshotSummary",
+    "ItemStateCaptureLimitError",
+    "ItemStateCaptureLimits",
+    "ItemStateCoverage",
+    "ItemStateDiagnostics",
+    "ItemStateProvenance",
+    "ItemStateSnapshot",
+    "SnapshotItem",
+    "StorageContents",
+    "StorageDestinationDiagnostics",
+    "StorageHydrationDiagnostics",
+    "StorageSnapshotSummary",
+    "analyze_item_state_pcap",
+    "format_item_state",
+]