Improve gateway reliability and dashboard docs

src/MxGateway.Worker/MxAccess/IWorkerRuntimeSession.cs

@@ -1,4 +1,5 @@
 using System;
+using System.Collections.Generic;
 using System.Threading;
 using System.Threading.Tasks;
 using MxGateway.Contracts.Proto;
@@ -17,6 +18,12 @@ public interface IWorkerRuntimeSession : IDisposable
 
     WorkerRuntimeHeartbeatSnapshot CaptureHeartbeat();
 
+    IReadOnlyList<WorkerEvent> DrainEvents(uint maxEvents);
+
+    WorkerFault? DrainFault();
+
+    bool CancelCommand(string correlationId);
+
     void RequestShutdown();
 
     Task<MxAccessShutdownResult> ShutdownGracefullyAsync(

src/MxGateway.Worker/MxAccess/MxAccessEventQueue.cs

@@ -14,6 +14,7 @@ public sealed class MxAccessEventQueue
     private readonly object syncRoot = new();
     private ulong lastEventSequence;
     private WorkerFault? fault;
+    private bool faultDrained;
 
     public MxAccessEventQueue()
         : this(DefaultCapacity)
@@ -163,6 +164,20 @@ public sealed class MxAccessEventQueue
         }
     }
 
+    public WorkerFault? DrainFault()
+    {
+        lock (syncRoot)
+        {
+            if (fault is null || faultDrained)
+            {
+                return null;
+            }
+
+            faultDrained = true;
+            return fault.Clone();
+        }
+    }
+
     private WorkerFault CreateOverflowFault()
     {
         string message = $"MXAccess outbound event queue reached capacity {capacity}.";

src/MxGateway.Worker/MxAccess/MxAccessSession.cs

@@ -79,7 +79,14 @@ public sealed class MxAccessSession : IDisposable
         }
         catch (Exception exception)
         {
-            eventSink.Detach();
+            try
+            {
+                eventSink.Detach();
+            }
+            catch
+            {
+                // Preserve the creation failure while still releasing the COM object below.
+            }
 
             if (mxAccessComObject is not null && Marshal.IsComObject(mxAccessComObject))
             {
@@ -535,13 +542,15 @@ public sealed class MxAccessSession : IDisposable
 
     private void DisposeCore(ICollection<MxAccessShutdownFailure>? failures)
     {
+        Exception? detachException = null;
         try
         {
             eventSink.Detach();
         }
-        catch (Exception exception) when (failures is not null)
+        catch (Exception exception)
         {
-            failures.Add(new MxAccessShutdownFailure(
+            detachException = exception;
+            failures?.Add(new MxAccessShutdownFailure(
                 "DetachEvents",
                 serverHandle: null,
                 itemHandle: null,
@@ -565,6 +574,10 @@ public sealed class MxAccessSession : IDisposable
         }
 
         disposed = true;
+        if (detachException is not null && failures is null)
+        {
+            throw detachException;
+        }
     }
 
     private void ThrowIfDisposed()

src/MxGateway.Worker/MxAccess/MxAccessStaSession.cs

@@ -127,6 +127,16 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
         return eventQueue.Drain(maxEvents);
     }
 
+    public WorkerFault? DrainFault()
+    {
+        return eventQueue.DrainFault();
+    }
+
+    public bool CancelCommand(string correlationId)
+    {
+        return commandDispatcher?.CancelQueuedCommand(correlationId) ?? false;
+    }
+
     public Task<IReadOnlyList<RegisteredServerHandle>> GetRegisteredServerHandlesAsync(
         CancellationToken cancellationToken = default)
     {
@@ -207,7 +217,14 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
                 throw new TimeoutException($"MXAccess graceful shutdown exceeded {timeout}.");
             }
 
-            result = await cleanupTask.ConfigureAwait(false);
+            try
+            {
+                result = await cleanupTask.ConfigureAwait(false);
+            }
+            catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested)
+            {
+                throw new TimeoutException($"MXAccess graceful shutdown exceeded {timeout}.");
+            }
         }
 
         TimeSpan remaining = timeout - stopwatch.Elapsed;
@@ -232,7 +249,17 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
 
         if (session is not null)
         {
-            staRuntime.InvokeAsync(() => session.Dispose()).GetAwaiter().GetResult();
+            try
+            {
+                staRuntime.InvokeAsync(() => session.Dispose())
+                    .Wait(TimeSpan.FromSeconds(2));
+            }
+            catch (AggregateException)
+            {
+            }
+            catch (ObjectDisposedException)
+            {
+            }
         }
 
         staRuntime.Dispose();