Add XML documentation across gateway, worker, and .NET client

src/MxGateway.Server/Grpc/EventStreamService.cs

@@ -16,6 +16,12 @@ public sealed class EventStreamService(
     GatewayMetrics metrics,
     ILogger<EventStreamService> logger) : IEventStreamService
 {
+    /// <summary>
+    /// Streams events from a session to the client asynchronously.
+    /// </summary>
+    /// <param name="request">Stream events request.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Async enumerable of MX events.</returns>
     public async IAsyncEnumerable<MxEvent> StreamEventsAsync(
         StreamEventsRequest request,
         [EnumeratorCancellation] CancellationToken cancellationToken)

src/MxGateway.Server/Grpc/GalaxyProtoMapper.cs

@@ -10,6 +10,9 @@ namespace MxGateway.Server.Grpc;
 /// </summary>
 public static class GalaxyProtoMapper
 {
+    /// <summary>Maps Galaxy hierarchy and attribute rows to Galaxy object protos.</summary>
+    /// <param name="hierarchy">Hierarchy rows from Galaxy Repository.</param>
+    /// <param name="attributes">Attribute rows from Galaxy Repository.</param>
     public static IEnumerable<GalaxyObject> MapHierarchy(
         IReadOnlyList<GalaxyHierarchyRow> hierarchy,
         IReadOnlyList<GalaxyAttributeRow> attributes)
@@ -24,6 +27,9 @@ public static class GalaxyProtoMapper
         }
     }
 
+    /// <summary>Maps a Galaxy hierarchy row to a Galaxy object proto.</summary>
+    /// <param name="row">Hierarchy row from Galaxy Repository.</param>
+    /// <param name="attributesByGobjectId">Attributes indexed by gobject ID.</param>
     public static GalaxyObject MapObject(
         GalaxyHierarchyRow row,
         IReadOnlyDictionary<int, List<GalaxyAttributeRow>> attributesByGobjectId)
@@ -52,6 +58,8 @@ public static class GalaxyProtoMapper
         return obj;
     }
 
+    /// <summary>Maps a Galaxy attribute row to a Galaxy attribute proto.</summary>
+    /// <param name="row">Attribute row from Galaxy Repository.</param>
     public static GalaxyAttribute MapAttribute(GalaxyAttributeRow row) => new()
     {
         AttributeName = row.AttributeName,

src/MxGateway.Server/Grpc/GalaxyRepositoryGrpcService.cs

@@ -22,6 +22,7 @@ public sealed class GalaxyRepositoryGrpcService(
 {
     private static readonly TimeSpan FirstLoadWaitBudget = TimeSpan.FromSeconds(5);
 
+    /// <inheritdoc />
     public override async Task<TestConnectionReply> TestConnection(
         TestConnectionRequest request,
         ServerCallContext context)
@@ -30,6 +31,7 @@ public sealed class GalaxyRepositoryGrpcService(
         return new TestConnectionReply { Ok = ok };
     }
 
+    /// <inheritdoc />
     public override async Task<GetLastDeployTimeReply> GetLastDeployTime(
         GetLastDeployTimeRequest request,
         ServerCallContext context)
@@ -52,6 +54,7 @@ public sealed class GalaxyRepositoryGrpcService(
         return reply;
     }
 
+    /// <inheritdoc />
     public override async Task<DiscoverHierarchyReply> DiscoverHierarchy(
         DiscoverHierarchyRequest request,
         ServerCallContext context)
@@ -71,6 +74,7 @@ public sealed class GalaxyRepositoryGrpcService(
         return entry.Reply;
     }
 
+    /// <inheritdoc />
     public override async Task WatchDeployEvents(
         WatchDeployEventsRequest request,
         IServerStreamWriter<DeployEvent> responseStream,

src/MxGateway.Server/Grpc/IEventStreamService.cs

@@ -2,8 +2,16 @@ using MxGateway.Contracts.Proto;
 
 namespace MxGateway.Server.Grpc;
 
+/// <summary>
+/// Streams MXAccess events to gRPC clients.
+/// </summary>
 public interface IEventStreamService
 {
+    /// <summary>
+    /// Streams events for the specified session to the caller.
+    /// </summary>
+    /// <param name="request">Request payload.</param>
+    /// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
     IAsyncEnumerable<MxEvent> StreamEventsAsync(
         StreamEventsRequest request,
         CancellationToken cancellationToken);

src/MxGateway.Server/Grpc/MxAccessGatewayService.cs

@@ -9,6 +9,7 @@ using MxGateway.Server.Workers;
 
 namespace MxGateway.Server.Grpc;
 
+/// <summary>gRPC service implementation for MXAccess Gateway operations.</summary>
 public sealed class MxAccessGatewayService(
     ISessionManager sessionManager,
     IGatewayRequestIdentityAccessor identityAccessor,
@@ -18,6 +19,7 @@ public sealed class MxAccessGatewayService(
     GatewayMetrics metrics,
     ILogger<MxAccessGatewayService> logger) : MxAccessGateway.MxAccessGatewayBase
 {
+    /// <inheritdoc />
     public override async Task<OpenSessionReply> OpenSession(
         OpenSessionRequest request,
         ServerCallContext context)
@@ -56,6 +58,7 @@ public sealed class MxAccessGatewayService(
         }
     }
 
+    /// <inheritdoc />
     public override async Task<CloseSessionReply> CloseSession(
         CloseSessionRequest request,
         ServerCallContext context)
@@ -80,6 +83,7 @@ public sealed class MxAccessGatewayService(
         }
     }
 
+    /// <inheritdoc />
     public override async Task<MxCommandReply> Invoke(
         MxCommandRequest request,
         ServerCallContext context)
@@ -100,6 +104,7 @@ public sealed class MxAccessGatewayService(
         }
     }
 
+    /// <inheritdoc />
     public override async Task StreamEvents(
         StreamEventsRequest request,
         IServerStreamWriter<MxEvent> responseStream,

src/MxGateway.Server/Grpc/MxAccessGrpcMapper.cs

@@ -3,15 +3,26 @@ using MxGateway.Contracts.Proto;
 
 namespace MxGateway.Server.Grpc;
 
+/// <summary>
+/// Maps between worker IPC types and gRPC contract types.
+/// </summary>
 public sealed class MxAccessGrpcMapper
 {
     private readonly TimeProvider _timeProvider;
 
+    /// <summary>
+    /// Initializes the mapper with an optional time provider.
+    /// </summary>
+    /// <param name="timeProvider">Time provider for timestamps; defaults to system time if null.</param>
     public MxAccessGrpcMapper(TimeProvider? timeProvider = null)
     {
         _timeProvider = timeProvider ?? TimeProvider.System;
     }
 
+    /// <summary>
+    /// Maps a gRPC MX command request to a worker command.
+    /// </summary>
+    /// <param name="request">Request payload.</param>
     public WorkerCommand MapCommand(MxCommandRequest request)
     {
         ArgumentNullException.ThrowIfNull(request);
@@ -24,6 +35,10 @@ public sealed class MxAccessGrpcMapper
         };
     }
 
+    /// <summary>
+    /// Maps a worker command reply to a gRPC MX command reply.
+    /// </summary>
+    /// <param name="reply">Worker command reply.</param>
     public MxCommandReply MapCommandReply(WorkerCommandReply reply)
     {
         ArgumentNullException.ThrowIfNull(reply);
@@ -39,6 +54,10 @@ public sealed class MxAccessGrpcMapper
         return reply.Reply.Clone();
     }
 
+    /// <summary>
+    /// Maps a worker event to a gRPC MX event.
+    /// </summary>
+    /// <param name="workerEvent">Worker event to map.</param>
     public MxEvent MapEvent(WorkerEvent workerEvent)
     {
         ArgumentNullException.ThrowIfNull(workerEvent);
@@ -50,6 +69,10 @@ public sealed class MxAccessGrpcMapper
         };
     }
 
+    /// <summary>
+    /// Creates an OK protocol status.
+    /// </summary>
+    /// <param name="message">Status message.</param>
     public static ProtocolStatus Ok(string message = "OK")
     {
         return new ProtocolStatus
@@ -59,6 +82,10 @@ public sealed class MxAccessGrpcMapper
         };
     }
 
+    /// <summary>
+    /// Creates an InvalidRequest protocol status.
+    /// </summary>
+    /// <param name="message">Status message.</param>
     public static ProtocolStatus InvalidRequest(string message)
     {
         return new ProtocolStatus
@@ -68,6 +95,10 @@ public sealed class MxAccessGrpcMapper
         };
     }
 
+    /// <summary>
+    /// Creates a SessionNotFound protocol status.
+    /// </summary>
+    /// <param name="message">Status message.</param>
     public static ProtocolStatus SessionNotFound(string message)
     {
         return new ProtocolStatus
@@ -77,6 +108,10 @@ public sealed class MxAccessGrpcMapper
         };
     }
 
+    /// <summary>
+    /// Creates a SessionNotReady protocol status.
+    /// </summary>
+    /// <param name="message">Status message.</param>
     public static ProtocolStatus SessionNotReady(string message)
     {
         return new ProtocolStatus
@@ -86,6 +121,10 @@ public sealed class MxAccessGrpcMapper
         };
     }
 
+    /// <summary>
+    /// Creates a WorkerUnavailable protocol status.
+    /// </summary>
+    /// <param name="message">Status message.</param>
     public static ProtocolStatus WorkerUnavailable(string message)
     {
         return new ProtocolStatus
@@ -95,6 +134,10 @@ public sealed class MxAccessGrpcMapper
         };
     }
 
+    /// <summary>
+    /// Creates a Timeout protocol status.
+    /// </summary>
+    /// <param name="message">Status message.</param>
     public static ProtocolStatus Timeout(string message)
     {
         return new ProtocolStatus
@@ -104,6 +147,10 @@ public sealed class MxAccessGrpcMapper
         };
     }
 
+    /// <summary>
+    /// Creates a Canceled protocol status.
+    /// </summary>
+    /// <param name="message">Status message.</param>
     public static ProtocolStatus Canceled(string message)
     {
         return new ProtocolStatus
@@ -113,6 +160,10 @@ public sealed class MxAccessGrpcMapper
         };
     }
 
+    /// <summary>
+    /// Creates a ProtocolViolation protocol status.
+    /// </summary>
+    /// <param name="message">Status message.</param>
     public static ProtocolStatus ProtocolViolation(string message)
     {
         return new ProtocolStatus

src/MxGateway.Server/Grpc/MxAccessGrpcRequestValidator.cs

@@ -5,6 +5,8 @@ namespace MxGateway.Server.Grpc;
 
 public sealed class MxAccessGrpcRequestValidator
 {
+    /// <summary>Validates an open session request.</summary>
+    /// <param name="request">The request to validate.</param>
     public void ValidateOpenSession(OpenSessionRequest request)
     {
         ArgumentNullException.ThrowIfNull(request);
@@ -15,18 +17,24 @@ public sealed class MxAccessGrpcRequestValidator
         }
     }
 
+    /// <summary>Validates a close session request.</summary>
+    /// <param name="request">The request to validate.</param>
     public void ValidateCloseSession(CloseSessionRequest request)
     {
         ArgumentNullException.ThrowIfNull(request);
         RequireSessionId(request.SessionId);
     }
 
+    /// <summary>Validates a stream events request.</summary>
+    /// <param name="request">The request to validate.</param>
     public void ValidateStreamEvents(StreamEventsRequest request)
     {
         ArgumentNullException.ThrowIfNull(request);
         RequireSessionId(request.SessionId);
     }
 
+    /// <summary>Validates an invoke request with command payload.</summary>
+    /// <param name="request">The request to validate.</param>
     public void ValidateInvoke(MxCommandRequest request)
     {
         ArgumentNullException.ThrowIfNull(request);