bdo-toolkit 1.0.0__py3-none-any.whl

bdo_toolkit/solare/_result.py

@@ -0,0 +1,441 @@
+"""Turn opcode-agnostic structural discovery into immutable public models."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Optional
+
+from bdo_toolkit._protocol import BDOFrame
+
+from ._constants import class_name
+from ._detail_learning import learn_unknown_solare_details
+from ._details import (
+    _overall_layout_for,
+    _rich_layout_for,
+    decode_solare_details,
+    decode_solare_overall_details,
+)
+from ._discovery import (
+    DiscoveredSolareFamily,
+    SolareDiscoveryResult,
+    discover_solare,
+    family_frames,
+)
+from ._validation import validate_retain_raw_extensions
+from .models import (
+    SolareCaptureHealth,
+    SolareCaptureResult,
+    SolareClass,
+    SolareDetectionStatus,
+    SolareEvidence,
+    SolareFamilyLayout,
+    SolareLeaderboardSnapshot,
+    SolareOverallEntry,
+    SolarePlayer,
+    solare_snapshot_id,
+)
+
+
+def _family_layout(
+    family: Optional[DiscoveredSolareFamily],
+    *,
+    detail_layout_id: Optional[str] = None,
+) -> Optional[SolareFamilyLayout]:
+    if family is None:
+        return None
+    return SolareFamilyLayout(
+        role=family.role,
+        opcode=family.opcode,
+        message_length=family.frame_length,
+        message_count=family.frame_count,
+        record_stride=family.record_stride,
+        name_offset=family.name_offset,
+        rank_offset=family.rank_offset,
+        class_offset=family.class_offset,
+        detail_layout_id=detail_layout_id,
+    )
+
+
+def _ranking_players(rich: DiscoveredSolareFamily) -> tuple[SolarePlayer, ...]:
+    players = (
+        SolarePlayer(
+            name=name,
+            global_rank=rank,
+            primary_class=SolareClass(code=class_code, name=class_name(class_code)),
+        )
+        for name, rank, class_code in zip(
+            rich.names,
+            rich.ranks,
+            rich.class_codes,
+        )
+    )
+    return tuple(sorted(players, key=lambda player: player.global_rank))
+
+
+def _overall_entries(
+    overall: DiscoveredSolareFamily,
+) -> tuple[SolareOverallEntry, ...]:
+    return tuple(
+        SolareOverallEntry(
+            name=name,
+            global_rank=rank,
+        )
+        for name, rank in zip(overall.names, overall.ranks)
+    )
+
+
+def _details_match_discovery(
+    players: tuple[SolarePlayer, ...],
+    rich: DiscoveredSolareFamily,
+) -> bool:
+    discovered = tuple(
+        sorted(
+            zip(rich.ranks, rich.names, rich.class_codes),
+            key=lambda row: row[0],
+        )
+    )
+    decoded = tuple(
+        (player.global_rank, player.name, player.primary_class.code)
+        for player in sorted(players, key=lambda player: player.global_rank)
+    )
+    return decoded == discovered
+
+
+def _overall_details_match_discovery(
+    entries: tuple[SolareOverallEntry, ...],
+    overall: DiscoveredSolareFamily,
+) -> bool:
+    discovered = tuple(
+        sorted(
+            zip(overall.ranks, overall.names),
+            key=lambda row: row[0],
+        )
+    )
+    decoded = tuple(
+        (entry.global_rank, entry.name)
+        for entry in sorted(entries, key=lambda entry: entry.global_rank)
+    )
+    return decoded == discovered
+
+
+def _message_for_status(status: SolareDetectionStatus) -> str:
+    messages = {
+        SolareDetectionStatus.COMPLETE: (
+            "structurally confirmed Solare leaderboard without a known opcode"
+        ),
+        SolareDetectionStatus.DETECTED_INCOMPLETE: (
+            "leaderboard traffic was recognized, but the complete snapshot "
+            "was not captured"
+        ),
+        SolareDetectionStatus.RICH_CANDIDATE: (
+            "a complete class-balanced ranked table was found, but the "
+            "independent overall top-100 cross-check was not captured"
+        ),
+        SolareDetectionStatus.RANKED_PARTIAL: (
+            "ranked leaderboard structure was found, but the class-balanced "
+            "table and overall cross-check were incomplete"
+        ),
+        SolareDetectionStatus.MENU_CONTEXT: (
+            "Solare menu/history-like traffic was found, not a leaderboard"
+        ),
+        SolareDetectionStatus.INCONCLUSIVE: (
+            "no complete structural Solare signature was found"
+        ),
+        SolareDetectionStatus.NO_TRAFFIC: (
+            "no inbound payload from the selected game-server ports was found"
+        ),
+    }
+    return messages[status]
+
+
+def _resource_loss_summary(health: SolareCaptureHealth) -> Optional[str]:
+    """Describe bounded live-pipeline losses that invalidate acquisition.
+
+    This deliberately covers only losses introduced by the toolkit's bounded
+    packet/reassembly pipeline.  Pcap drops and TCP gaps keep their broader
+    capture-integrity wording below.
+    """
+
+    losses: list[str] = []
+    if health.packet_queue_overflows:
+        count = health.packet_queue_overflows
+        losses.append(
+            "packet queue overflow discarded "
+            f"{count} captured packet{'s' if count != 1 else ''} before decoding"
+        )
+    if health.flow_state_evictions:
+        count = health.flow_state_evictions
+        losses.append(
+            "forced flow-state eviction removed "
+            f"{count} active TCP reassembly state{'s' if count != 1 else ''}"
+        )
+    if not losses:
+        return None
+    if len(losses) == 1:
+        return losses[0]
+    return f"{losses[0]} and {losses[1]}"
+
+
+def _capture_loss_summary(health: SolareCaptureHealth) -> Optional[str]:
+    """Name every observed acquisition loss, including pre-confirmation gaps."""
+
+    losses: list[str] = []
+    resource_loss = _resource_loss_summary(health)
+    if resource_loss is not None:
+        losses.append(resource_loss)
+    if health.tcp_gap_resets:
+        count = health.tcp_gap_resets
+        losses.append(
+            "TCP reassembly reset "
+            f"{count} time{'s' if count != 1 else ''} after an unresolved "
+            "sequence gap"
+        )
+    if health.pcap_dropped not in (None, 0):
+        backend_drop_count = health.pcap_dropped
+        assert backend_drop_count is not None
+        losses.append(
+            "the capture backend reported "
+            f"{backend_drop_count} dropped "
+            f"packet{'s' if backend_drop_count != 1 else ''}"
+        )
+    if health.pcap_interface_dropped not in (None, 0):
+        interface_drop_count = health.pcap_interface_dropped
+        assert interface_drop_count is not None
+        losses.append(
+            "the capture interface reported "
+            f"{interface_drop_count} dropped "
+            f"packet{'s' if interface_drop_count != 1 else ''}"
+        )
+    if not losses:
+        return None
+    if len(losses) == 1:
+        return losses[0]
+    return "; ".join(losses[:-1]) + f"; and {losses[-1]}"
+
+
+def _noncomplete_message(
+    status: SolareDetectionStatus,
+    health: SolareCaptureHealth,
+    *,
+    integrity_rejected: bool,
+) -> str:
+    capture_loss = _capture_loss_summary(health)
+    if capture_loss is not None:
+        retry = (
+            "Retry after reducing capture load"
+            if _resource_loss_summary(health) is not None
+            else "Retry with a fresh capture"
+        )
+        if integrity_rejected:
+            return (
+                "the structural tables matched, but acquisition integrity was "
+                f"lost because {capture_loss}; snapshot publication was "
+                f"withheld. {retry}"
+            )
+        return (
+            f"{_message_for_status(status)}; acquisition integrity was lost "
+            f"because {capture_loss}. {retry}"
+        )
+
+    if integrity_rejected:
+        return (
+            "the structural tables matched, but capture gaps or reported "
+            "packet drops made acquisition integrity uncertain; snapshot "
+            "publication was withheld"
+        )
+
+    message = _message_for_status(status)
+    if health.candidate_history_rolled_over and health.capture_is_clean:
+        return (
+            f"{message}; the bounded candidate history rolled over after older "
+            "frames were evaluated and discarded. Retry while opening the "
+            "leaderboard promptly"
+        )
+    return message
+
+
+def _evidence(
+    discovery: SolareDiscoveryResult,
+    health: SolareCaptureHealth,
+    *,
+    class_detail_layout_id: Optional[str] = None,
+    overall_detail_layout_id: Optional[str] = None,
+) -> SolareEvidence:
+    ranked = discovery.ranked_candidate
+    overall = discovery.overall or discovery.partial_overall
+    rich = discovery.rich
+    return SolareEvidence(
+        scanned_messages=discovery.scanned_frames,
+        candidate_families=discovery.candidate_families,
+        ranked_players=ranked.record_count if ranked is not None else 0,
+        class_group_counts=rich.class_counts if rich is not None else (),
+        overall_players=overall.record_count if overall is not None else 0,
+        exact_cross_check=discovery.exact_cross_check,
+        rich_layout=_family_layout(
+            rich,
+            detail_layout_id=class_detail_layout_id,
+        ),
+        overall_layout=_family_layout(
+            overall,
+            detail_layout_id=overall_detail_layout_id,
+        ),
+        health=health,
+    )
+
+
+def build_solare_result(
+    frames: Iterable[BDOFrame],
+    health: SolareCaptureHealth,
+    *,
+    retain_raw_extensions: bool = False,
+    _discovery: Optional[SolareDiscoveryResult] = None,
+) -> SolareCaptureResult:
+    """Classify collected generic frames and construct a fail-closed result.
+
+    A snapshot is returned only after the rich 620-player class table and an
+    independent complete overall top 100 agree on every shared rank and name.
+    Deeper detail decoding is optional: an unfamiliar geometry may use bounded
+    ephemeral inference after confirmation, while every unsupported or
+    ambiguous capability is still omitted from the ranking snapshot.
+    """
+
+    retain_raw_extensions = validate_retain_raw_extensions(
+        retain_raw_extensions
+    )
+    frame_tuple = tuple(frames)
+    discovery = _discovery or discover_solare(frame_tuple)
+    integrity_rejected = discovery.confirmed and not health.capture_is_clean
+    if not frame_tuple and health.payload_segments == 0:
+        status = SolareDetectionStatus.NO_TRAFFIC
+    elif integrity_rejected:
+        status = SolareDetectionStatus.DETECTED_INCOMPLETE
+    else:
+        status = SolareDetectionStatus(discovery.status)
+
+    if status is not SolareDetectionStatus.COMPLETE:
+        evidence = _evidence(discovery, health)
+        message = _noncomplete_message(
+            status,
+            health,
+            integrity_rejected=integrity_rejected,
+        )
+        return SolareCaptureResult(
+            status=status,
+            evidence=evidence,
+            message=message,
+        )
+
+    rich = discovery.rich
+    overall = discovery.overall
+    assert rich is not None
+    assert overall is not None
+
+    players = _ranking_players(rich)
+    overall_entries = _overall_entries(overall)
+    class_table_capabilities = {"rankings"}
+    overall_capabilities = {"rankings"}
+    class_detail_layout_id: Optional[str] = None
+    overall_detail_layout_id: Optional[str] = None
+    rich_frames = family_frames(frame_tuple, rich)
+    overall_frames = family_frames(frame_tuple, overall)
+    class_details = decode_solare_details(
+        rich_frames,
+        rich,
+        retain_raw_extensions=retain_raw_extensions,
+    )
+    overall_details = decode_solare_overall_details(
+        overall_frames,
+        overall,
+        retain_raw_extensions=retain_raw_extensions,
+    )
+    learn_rich = _rich_layout_for(rich) is None
+    learn_overall = _overall_layout_for(overall) is None
+    if learn_rich or learn_overall:
+        known_rich_elos: Optional[dict[str, int]] = None
+        if (
+            not learn_rich
+            and class_details is not None
+            and "elo" in class_details.capabilities
+            and all(player.elo is not None for player in class_details.players)
+        ):
+            known_rich_elos = {
+                player.name: player.elo
+                for player in class_details.players
+                if player.elo is not None
+            }
+        known_overall_elos: Optional[dict[str, int]] = None
+        if (
+            not learn_overall
+            and overall_details is not None
+            and "elo" in overall_details.capabilities
+            and all(entry.elo is not None for entry in overall_details.entries)
+        ):
+            known_overall_elos = {
+                entry.name: entry.elo
+                for entry in overall_details.entries
+                if entry.elo is not None
+            }
+        learned_class, learned_overall = learn_unknown_solare_details(
+            rich_frames,
+            rich,
+            overall_frames,
+            overall,
+            learn_rich=learn_rich,
+            learn_overall=learn_overall,
+            retain_raw_extensions=retain_raw_extensions,
+            known_rich_elos=known_rich_elos,
+            known_overall_elos=known_overall_elos,
+        )
+        if class_details is None and learn_rich:
+            class_details = learned_class
+        if overall_details is None and learn_overall:
+            overall_details = learned_overall
+
+    if class_details is not None and _details_match_discovery(
+        class_details.players,
+        rich,
+    ):
+        players = tuple(
+            sorted(class_details.players, key=lambda player: player.global_rank)
+        )
+        class_detail_layout_id = class_details.layout_id
+        class_table_capabilities.update(class_details.capabilities)
+
+    if overall_details is not None and _overall_details_match_discovery(
+        overall_details.entries,
+        overall,
+    ):
+        overall_entries = tuple(
+            sorted(
+                overall_details.entries,
+                key=lambda entry: entry.global_rank,
+            )
+        )
+        overall_detail_layout_id = overall_details.layout_id
+        overall_capabilities.update(overall_details.capabilities)
+
+    evidence = _evidence(
+        discovery,
+        health,
+        class_detail_layout_id=class_detail_layout_id,
+        overall_detail_layout_id=overall_detail_layout_id,
+    )
+    snapshot = SolareLeaderboardSnapshot(
+        snapshot_id=solare_snapshot_id(
+            players,
+            overall_top_100=overall_entries,
+        ),
+        observed_at=max(
+            frame.context.timestamp for frame in (*rich_frames, *overall_frames)
+        ),
+        players=players,
+        overall_top_100=overall_entries,
+        class_table_capabilities=frozenset(class_table_capabilities),
+        overall_capabilities=frozenset(overall_capabilities),
+    )
+    return SolareCaptureResult(
+        status=status,
+        evidence=evidence,
+        snapshot=snapshot,
+        message=_message_for_status(status),
+    )

bdo_toolkit/solare/_scanner.py

@@ -0,0 +1,203 @@
+"""Midstream-safe generic BDO framing used by Solare structural discovery."""
+
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+from bdo_toolkit._protocol import BDOFrame, PacketContext
+
+from ._constants import (
+    BDO_HEADER_SIZE,
+    BDO_MAX_FRAME_SIZE,
+    DISCOVERY_MAX_FRAME_LENGTH,
+    DISCOVERY_MIN_FRAME_LENGTH,
+    DISCOVERY_SYNC_BUFFER_LIMIT,
+    DISCOVERY_SYNC_HEADERS,
+)
+
+
+def _u16le(data: bytes | bytearray, offset: int) -> int:
+    return int.from_bytes(data[offset : offset + 2], "little")
+
+
+class SolareDiscoveryStreamScanner:
+    """Emit generic frames without trusting a known Solare opcode.
+
+    Live capture can attach in the middle of an application message. The
+    scanner therefore requires either two equal large-family headers or three
+    consecutive generic flag-zero headers before it declares synchronization.
+    """
+
+    def __init__(
+        self,
+        callback: Callable[[BDOFrame], None],
+        reset_callback: Optional[Callable[[], None]] = None,
+    ) -> None:
+        self._callback = callback
+        self._reset_callback = reset_callback
+        self._buffer = bytearray()
+        self._buffer_start_sequence: Optional[int] = None
+        self._locked = False
+        self._frame_index = 0
+
+    def reset(self) -> None:
+        self._buffer.clear()
+        self._buffer_start_sequence = None
+        self._locked = False
+        if self._reset_callback is not None:
+            self._reset_callback()
+
+    def can_anchor_at_start(self, data: bytes) -> bool:
+        """Return whether byte zero already satisfies the discovery sync proof."""
+
+        def header_length(offset: int) -> Optional[int]:
+            if offset + BDO_HEADER_SIZE > len(data):
+                return None
+            message_length = _u16le(data, offset)
+            if not BDO_HEADER_SIZE <= message_length <= BDO_MAX_FRAME_SIZE:
+                return -1
+            if data[offset + 2] != 0:
+                return -1
+            return message_length
+
+        position = 0
+        generic_chain = True
+        for index in range(DISCOVERY_SYNC_HEADERS):
+            message_length = header_length(position)
+            if message_length is None or message_length < BDO_HEADER_SIZE:
+                generic_chain = False
+                break
+            if index != DISCOVERY_SYNC_HEADERS - 1:
+                if position + message_length > len(data):
+                    generic_chain = False
+                    break
+                position += message_length
+        if generic_chain:
+            return True
+
+        first_length = header_length(0)
+        if first_length is None or not (
+            DISCOVERY_MIN_FRAME_LENGTH
+            <= first_length
+            <= DISCOVERY_MAX_FRAME_LENGTH
+        ):
+            return False
+        second_offset = first_length
+        return (
+            header_length(second_offset) == first_length
+            and second_offset + BDO_HEADER_SIZE <= len(data)
+            and _u16le(data, 3) == _u16le(data, second_offset + 3)
+        )
+
+    def feed(self, data: bytes, context: PacketContext) -> None:
+        if not data:
+            return
+        if not self._buffer:
+            self._buffer_start_sequence = context.stream_start
+        self._buffer.extend(data)
+        self._scan(context)
+
+    def scan_standalone(self, data: bytes, context: PacketContext) -> None:
+        # FlowManager invokes this for overlap/retransmission bytes already
+        # represented in the primary stream. Ignoring them prevents duplicate
+        # discovery frames.
+        return
+
+    def _discard_prefix(self, byte_count: int) -> None:
+        if byte_count <= 0:
+            return
+        del self._buffer[:byte_count]
+        if self._buffer_start_sequence is not None:
+            self._buffer_start_sequence += byte_count
+        if not self._buffer:
+            self._buffer_start_sequence = None
+
+    def _header_length(self, offset: int) -> Optional[int]:
+        if offset + BDO_HEADER_SIZE > len(self._buffer):
+            return None
+        message_length = _u16le(self._buffer, offset)
+        if not BDO_HEADER_SIZE <= message_length <= BDO_MAX_FRAME_SIZE:
+            return -1
+        if self._buffer[offset + 2] != 0:
+            return -1
+        return message_length
+
+    def _has_sync_chain(self, offset: int) -> Optional[bool]:
+        position = offset
+        for index in range(DISCOVERY_SYNC_HEADERS):
+            message_length = self._header_length(position)
+            if message_length is None:
+                return None
+            if message_length < BDO_HEADER_SIZE:
+                return False
+            if index == DISCOVERY_SYNC_HEADERS - 1:
+                return True
+            if position + message_length > len(self._buffer):
+                return None
+            position += message_length
+        return True
+
+    def _find_sync_offset(self) -> Optional[int]:
+        final_offset = len(self._buffer) - BDO_HEADER_SIZE
+        for offset in range(max(0, final_offset + 1)):
+            if self._has_sync_chain(offset) is True:
+                return offset
+        return None
+
+    def _find_repeated_large_family_offset(self) -> Optional[int]:
+        final_offset = len(self._buffer) - BDO_HEADER_SIZE
+        for offset in range(max(0, final_offset + 1)):
+            message_length = self._header_length(offset)
+            if message_length is None or not (
+                DISCOVERY_MIN_FRAME_LENGTH
+                <= message_length
+                <= DISCOVERY_MAX_FRAME_LENGTH
+            ):
+                continue
+            next_offset = offset + message_length
+            next_length = self._header_length(next_offset)
+            if next_length != message_length:
+                continue
+            if _u16le(self._buffer, offset + 3) != _u16le(
+                self._buffer, next_offset + 3
+            ):
+                continue
+            return offset
+        return None
+
+    def _scan(self, context: PacketContext) -> None:
+        while True:
+            if not self._locked:
+                sync_offset = self._find_repeated_large_family_offset()
+                if sync_offset is None:
+                    sync_offset = self._find_sync_offset()
+                if sync_offset is None:
+                    if len(self._buffer) > DISCOVERY_SYNC_BUFFER_LIMIT:
+                        self._discard_prefix(
+                            len(self._buffer) - DISCOVERY_SYNC_BUFFER_LIMIT
+                        )
+                    return
+                if sync_offset:
+                    self._discard_prefix(sync_offset)
+                self._locked = True
+
+            message_length = self._header_length(0)
+            if message_length is None:
+                return
+            if message_length < BDO_HEADER_SIZE:
+                self._locked = False
+                self._discard_prefix(1)
+                continue
+            if message_length > len(self._buffer):
+                return
+
+            message = bytes(self._buffer[:message_length])
+            frame = BDOFrame(
+                index=self._frame_index,
+                message=message,
+                context=context,
+                stream_sequence=self._buffer_start_sequence,
+            )
+            self._frame_index += 1
+            self._callback(frame)
+            self._discard_prefix(message_length)

bdo_toolkit/solare/_validation.py

@@ -0,0 +1,11 @@
+"""Shared validation for public Arena of Solare acquisition options."""
+
+from __future__ import annotations
+
+
+def validate_retain_raw_extensions(value: object) -> bool:
+    """Return a validated raw-retention flag with one consistent contract."""
+
+    if not isinstance(value, bool):
+        raise TypeError("retain_raw_extensions must be a boolean")
+    return value