first commit

2026-09-03 04:45:36 +03:00
commit d5f52cc3d3
1038 changed files with 169579 additions and 0 deletions
@@ -0,0 +1,31 @@
+---
+kind: error_handling
+name: Exception-based Errors with Sentry Reporting and UI Abstraction
+category: error_handling
+scope:
+    - '**'
+source_files:
+    - ClassicAssist.Shared/Engine.cs
+    - ClassicAssist.Shared/Misc/MessageBoxProvider.cs
+    - ClassicAssist/UI/Misc/WPFMessageBoxProvider.cs
+---
+
+ClassicAssist uses a conventional .NET exception-driven error model rather than a dedicated error-type system. There are no custom *Exception classes defined in the codebase; errors propagate as standard CLR exceptions (InvalidOperationException, ArgumentOutOfRangeException, NotImplementedException) or third-party types such as RateLimitExceededException.
+
+Core propagation and reporting:
+- The shared Engine class wraps packet-processing queues (ProcessIncomingQueue, ProcessOutgoingQueue) in try/catch blocks that swallow exceptions and forward them to Sentry via SentrySdk.WithScope(...).CaptureException(e), attaching contextual extras (packet bytes, player state, world counts). This is the central unhandled-error sink for network I/O.
+- Extension initialization (InitializeExtensions) catches any exception during plugin IExtension.Initialize() calls and logs them to Console.WriteLine, preventing one broken extension from crashing the host.
+- SendPacketToClient explicitly catches ThreadInterruptedException to tolerate macro interruption while waiting on locks.
+
+UI error presentation:
+- User-facing dialogs go through an abstraction: IMessageBoxProvider (defined in ClassicAssist.Shared/Misc/MessageBoxProvider.cs) with platform-specific implementations WPFMessageBoxProvider and AvaloniaMessageBoxProvider. The shared Engine.MessageBoxProvider static property is injected at startup so core logic stays UI-agnostic.
+- Many UI components catch Exception broadly and either log or ignore it (e.g., HexDumpControl.xaml.cs, MacroBrowserViewModel.cs), relying on Sentry for diagnostics rather than returning typed results.
+
+Validation and early failures:
+- Public APIs guard preconditions by throwing InvalidOperationException / ArgumentOutOfRangeException (e.g., Engine.SendPacketToServer(BasePacket) checks direction, Utility.GetEnumValueByName throws when parsing fails). These are developer-facing contract violations, not runtime-recoverable conditions.
+
+Conventions developers should follow:
+1. Use standard CLR exceptions for invalid arguments or invariant violations; do not define new *Exception subclasses unless you need extra payload.
+2. Wrap long-running or cross-thread work (packet queues, async operations) in try/catch and report via SentrySdk.CaptureException; never let exceptions bubble out of engine callbacks.
+3. Surface user-visible problems through Engine.MessageBoxProvider.Show(...), using the shared MessageBoxImage.Error|Warning|Information enum — keep UI framework details out of shared code.
+4. Catch only specific recoverable exceptions (e.g., ThreadInterruptedException) and rethrow or log everything else.