Files

T

Beyhan Oğur d5f52cc3d3 first commit

2026-09-03 04:45:36 +03:00

25 KiB

Raw Permalink Blame History

Packet Logger

**Referenced Files in This Document** - [PacketFilter.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilter.cs) - [PacketFilterCondition.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilterCondition.cs) - [PacketFilterConditions.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilterConditions.cs) - [PacketFilterInfo.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilterInfo.cs) - [PacketWaitEntry.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketWaitEntry.cs) - [PacketWaitEntries.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketWaitEntries.cs) - [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs) - [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs) - [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs) - [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs) - [PacketHandler.cs](file://ClassicAssist.Shared/UO/Network/PacketHandler.cs) - [BasePacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/BasePacket.cs) - [PacketDirection.cs](file://ClassicAssist.Shared/UO/Data/PacketDirection.cs) - [HexDumpControl.axaml.cs](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml.cs) - [HexDumpControl.axaml](file://ClassicAssist.Avalonia/Controls/HexDumpControl.axaml) - [PacketEntryBinaryValueConverter.cs](file://ClassicAssist.Avalonia/Misc/PacketEntryBinaryValueConverter.cs) - [PacketEntryTextValueConverter.cs](file://ClassicAssist.Shared/UI/Misc/PacketEntryTextValueConverter.cs) - [ReplayPacketLog.cs](file://ClassicAssist.Tests/ReplayPacketLog.cs)

Introduction
Project Structure
Core Components
Architecture Overview
Detailed Component Analysis
Dependency Analysis
Performance Considerations
Troubleshooting Guide
Conclusion
Appendices

Introduction

This document explains the Packet Logger tooling within ClassicAssist.Avalonia, focusing on network traffic capture, filtering, and replay capabilities for Ultima Online (UO) protocol packets. It covers how to configure filters by packet type, direction, and content patterns; inspect binary payloads using the hex dump control; synchronize tests with the packet wait system; and integrate logging into development workflows. Guidance is provided for performance considerations and best practices when debugging network interactions.

Project Structure

The Packet Logger spans shared networking logic and Avalonia UI components:

Shared networking layer defines packet types, handlers, filter conditions, and synchronization primitives.
Avalonia UI provides a Hex Dump control and value converters for displaying packet data.
Tests include a replay utility that demonstrates capturing and re-sending sessions.

graph TB
subgraph "Shared Networking"
PF["PacketFilter<br/>PacketFilterCondition<br/>PacketFilterConditions<br/>PacketFilterInfo"]
PW["PacketWaitEntry<br/>PacketWaitEntries"]
PH["PacketHandler"]
IPH["IncomingPacketHandlers"]
OPH["OutgoingPacketHandlers"]
IPF["IncomingPacketFilters"]
OPF["OutgoingPacketFilters"]
BP["BasePacket"]
PD["PacketDirection"]
end
subgraph "Avalonia UI"
HD["HexDumpControl"]
PBV["PacketEntryBinaryValueConverter"]
PTB["PacketEntryTextValueConverter"]
end
subgraph "Tests"
RPL["ReplayPacketLog"]
end
PH --> IPH
PH --> OPH
PH --> IPF
PH --> OPF
IPF --> PF
OPF --> PF
PF --> PD
PF --> BP
PW --> PF
HD --> PBV
HD --> PTB
RPL --> PH

Diagram sources

Section sources

Core Components

Packet filtering engine: Defines filter conditions, composite filters, and metadata used to match incoming/outgoing packets.
Packet handlers: Central dispatcher that routes packets through filters and invokes registered handlers.
Packet wait system: Synchronization primitives to wait for specific packets or sequences during tests.
Hex dump control: Avalonia control for visual inspection of raw packet bytes.
Replay utility: Test helper to record and re-send captured sessions.

Key responsibilities:

Capture: Intercept UO packets at send/receive boundaries.
Filter: Match packets by type, direction, and payload patterns.
Inspect: Display raw bytes and decoded text via UI controls.
Wait: Block until expected packets arrive for deterministic testing.
Replay: Re-execute recorded sessions to reproduce issues.

Section sources

Architecture Overview

The packet pipeline integrates filtering and dispatch around a central handler. Filters can be applied per direction (incoming/outgoing), and the wait system coordinates test flows. The UI exposes a hex dump view for binary inspection.

sequenceDiagram
participant App as "Application"
participant Net as "PacketHandler"
participant IF as "IncomingPacketFilters"
participant OF as "OutgoingPacketFilters"
participant IH as "IncomingPacketHandlers"
participant OH as "OutgoingPacketHandlers"
participant UI as "HexDumpControl"
App->>Net : "Send/Receive Packet"
alt Incoming
Net->>IF : "Evaluate filters"
IF-->>Net : "Matched?"
Net->>IH : "Invoke handler if matched"
IH-->>UI : "Expose payload for inspection"
else Outgoing
Net->>OF : "Evaluate filters"
OF-->>Net : "Matched?"
Net->>OH : "Invoke handler if matched"
OH-->>UI : "Expose payload for inspection"
end

Diagram sources

Detailed Component Analysis

Filtering System

The filtering subsystem supports matching packets by type, direction, and content patterns. Conditions are composed to build complex rules.

classDiagram
class PacketFilter {
+evaluate(packet) bool
}
class PacketFilterCondition {
+match(packet) bool
}
class PacketFilterConditions {
+and(...)
+or(...)
+not(...)
}
class PacketFilterInfo {
+description string
+enabled bool
}
class BasePacket {
+type int
+data byte[]
}
class PacketDirection {
<<enum>>
}
PacketFilter --> PacketFilterCondition : "uses"
PacketFilter --> PacketFilterInfo : "metadata"
PacketFilterCondition --> BasePacket : "inspects"
PacketFilterCondition --> PacketDirection : "checks"

Configuration guidance:

Direction: Use direction-aware filters to limit scope to incoming or outgoing traffic.
Type: Narrow by packet type to reduce noise.
Content: Apply pattern-based conditions on payload bytes or decoded fields.
Composition: Combine multiple conditions with logical operators to refine matches.

Best practices:

Prefer specific type checks before broad content scans.
Cache expensive computations inside conditions when possible.
Keep filter descriptions meaningful for UI display and debugging.

Diagram sources

Section sources

Packet Handlers and Dispatch

The central handler orchestrates filter evaluation and invokes registered handlers for incoming and outgoing packets.

flowchart TD
Start(["Packet arrives"]) --> CheckDir{"Direction?"}
CheckDir --> |Incoming| EvalIn["Evaluate IncomingPacketFilters"]
CheckDir --> |Outgoing| EvalOut["Evaluate OutgoingPacketFilters"]
EvalIn --> InMatch{"Any match?"}
EvalOut --> OutMatch{"Any match?"}
InMatch --> |Yes| CallIn["Call IncomingPacketHandlers"]
InMatch --> |No| SkipIn["Skip"]
OutMatch --> |Yes| CallOut["Call OutgoingPacketHandlers"]
OutMatch --> |No| SkipOut["Skip"]
CallIn --> End(["Done"])
CallOut --> End
SkipIn --> End
SkipOut --> End

Operational notes:

Register handlers for specific packet types to process relevant events.
Ensure filters are efficient to avoid blocking the network thread.
Separate concerns: filters decide whether to pass; handlers perform actions.

Diagram sources

Section sources

Packet Wait System

The wait system enables synchronization for tests and automation scenarios by waiting for specific packets or sequences.

sequenceDiagram
participant Test as "Test Code"
participant Wait as "PacketWaitEntries"
participant Entry as "PacketWaitEntry"
participant Net as "PacketHandler"
Test->>Wait : "Register wait condition"
Wait->>Entry : "Create entry with predicate"
Test->>Net : "Perform action that triggers packet"
Net->>Wait : "Notify matching packets"
Wait->>Entry : "Resolve when predicate matches"
Entry-->>Test : "Signal completion"

Usage tips:

Define precise predicates to avoid false positives.
Set timeouts to prevent indefinite waits.
Clear entries after use to free resources.

Diagram sources

Section sources

Hex Dump Control and Binary Inspection

The Avalonia Hex Dump control renders raw packet bytes for analysis. Value converters bridge packet data to UI-friendly formats.

classDiagram
class HexDumpControl {
+Render(bytes) void
}
class PacketEntryBinaryValueConverter {
+Convert(value) string
}
class PacketEntryTextValueConverter {
+Convert(value) string
}
HexDumpControl --> PacketEntryBinaryValueConverter : "uses"
HexDumpControl --> PacketEntryTextValueConverter : "uses"

Inspection workflow:

Select a packet entry to view its raw bytes.
Use the hex view to locate offsets and values.
Switch to text view for readable strings where applicable.

Diagram sources

Section sources

Replay Functionality

The replay utility demonstrates recording and re-sending captured sessions, useful for reproducing issues and validating fixes.

sequenceDiagram
participant Recorder as "Recorder"
participant Store as "Capture Store"
participant Replayer as "ReplayPacketLog"
participant Net as "PacketHandler"
Recorder->>Store : "Record packets"
Replayer->>Store : "Load session"
Replayer->>Net : "Re-send recorded packets"
Net-->>Replayer : "Dispatch to handlers"

Guidance:

Record minimal necessary traffic to reduce file size.
Normalize timestamps or add delays to mimic real timing.
Validate server responses after replay to ensure correctness.

Diagram sources

Section sources

Dependency Analysis

The following diagram highlights key dependencies among filtering, dispatch, and UI components.

graph LR
PF["PacketFilter"] --> PFC["PacketFilterCondition"]
PF --> PFI["PacketFilterInfo"]
PFC --> BP["BasePacket"]
PFC --> PD["PacketDirection"]
PH["PacketHandler"] --> IPF["IncomingPacketFilters"]
PH --> OPF["OutgoingPacketFilters"]
PH --> IPH["IncomingPacketHandlers"]
PH --> OPH["OutgoingPacketHandlers"]
HD["HexDumpControl"] --> PBV["PacketEntryBinaryValueConverter"]
HD --> PTB["PacketEntryTextValueConverter"]
RPL["ReplayPacketLog"] --> PH

Diagram sources

Section sources

Performance Considerations

Filter specificity: Narrow filters by packet type and direction to minimize payload scanning.
Avoid heavy work in hot paths: Defer expensive operations off the network thread.
Limit UI updates: Batch or throttle UI rendering when logging large volumes.
Manage memory: Reuse buffers and clear references to avoid retention.
Timeouts: Always set reasonable timeouts for wait entries to prevent hangs.
Logging volume: Enable detailed logging only when needed; disable otherwise.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common issues and resolutions:

No packets captured: Verify handlers are registered and filters are enabled.
False positives: Tighten filter predicates and validate direction/type checks.
Slow performance: Profile filter conditions and reduce payload inspections.
Stalled tests: Ensure wait entries have timeouts and are cleared after completion.
UI freezes: Offload conversions and avoid frequent UI updates from network threads.

Section sources

Conclusion

The Packet Logger integrates robust filtering, dispatch, synchronization, and inspection tools tailored for UO protocol debugging. By configuring precise filters, leveraging the hex dump control, and using the wait system for deterministic tests, developers can efficiently diagnose network behavior and reproduce issues with replay utilities. Adhering to performance best practices ensures smooth operation even under high traffic loads.

[No sources needed since this section summarizes without analyzing specific files]

Appendices

Example Workflows

Capturing and analyzing UO protocol packets:
- Enable logging for incoming/outgoing directions.
- Add filters by packet type and narrow by content patterns.
- Inspect payloads using the hex dump control and text converter.
Creating custom filters:
- Implement a condition that inspects BasePacket fields and direction.
- Compose with other conditions using logical operators.
- Attach descriptive metadata for UI visibility.
Replaying captured sessions:
- Record a session with minimal necessary packets.
- Load the session via the replay utility.
- Re-send packets and validate server responses.

[No sources needed since this section provides conceptual guidance]

25 KiB Raw Permalink Blame History

Packet Logger

Table of Contents

Introduction

Project Structure

Core Components

Architecture Overview

Detailed Component Analysis

Filtering System

Packet Handlers and Dispatch

Packet Wait System

Hex Dump Control and Binary Inspection

Replay Functionality

Dependency Analysis

Performance Considerations

Troubleshooting Guide

Conclusion

Appendices

Example Workflows

25 KiB

Raw Permalink Blame History