Issue #14: implement event streaming and backpressure

src/MxGateway.Server/Sessions/GatewaySession.cs

@@ -13,6 +13,7 @@ public sealed class GatewaySession
     private DateTimeOffset _lastClientActivityAt;
     private DateTimeOffset? _leaseExpiresAt;
     private bool _closeStarted;
+    private int _activeEventSubscriberCount;
 
     public GatewaySession(
         string sessionId,
@@ -131,6 +132,17 @@ public sealed class GatewaySession
         }
     }
 
+    public int ActiveEventSubscriberCount
+    {
+        get
+        {
+            lock (_syncRoot)
+            {
+                return _activeEventSubscriberCount;
+            }
+        }
+    }
+
     public void AttachWorkerClient(IWorkerClient workerClient)
     {
         ArgumentNullException.ThrowIfNull(workerClient);
@@ -202,6 +214,29 @@ public sealed class GatewaySession
         }
     }
 
+    public IDisposable AttachEventSubscriber(bool allowMultipleSubscribers)
+    {
+        lock (_syncRoot)
+        {
+            if (_state != SessionState.Ready || _workerClient?.State != WorkerClientState.Ready)
+            {
+                throw new SessionManagerException(
+                    SessionManagerErrorCode.SessionNotReady,
+                    $"Session {SessionId} is not ready for event streaming. Current state is {_state}.");
+            }
+
+            if (!allowMultipleSubscribers && _activeEventSubscriberCount > 0)
+            {
+                throw new SessionManagerException(
+                    SessionManagerErrorCode.EventSubscriberAlreadyActive,
+                    $"Session {SessionId} already has an active event stream subscriber.");
+            }
+
+            _activeEventSubscriberCount++;
+            return new EventSubscriberLease(this);
+        }
+    }
+
     public async Task<WorkerCommandReply> InvokeAsync(
         WorkerCommand command,
         CancellationToken cancellationToken)
@@ -287,4 +322,31 @@ public sealed class GatewaySession
             return _workerClient;
         }
     }
+
+    private void DetachEventSubscriber()
+    {
+        lock (_syncRoot)
+        {
+            if (_activeEventSubscriberCount > 0)
+            {
+                _activeEventSubscriberCount--;
+            }
+        }
+    }
+
+    private sealed class EventSubscriberLease(GatewaySession session) : IDisposable
+    {
+        private bool _disposed;
+
+        public void Dispose()
+        {
+            if (_disposed)
+            {
+                return;
+            }
+
+            session.DetachEventSubscriber();
+            _disposed = true;
+        }
+    }
 }