Improve gateway reliability and dashboard docs

clients/dotnet/MxGateway.Client.Cli/MxGatewayClientCli.cs

@@ -8,6 +8,8 @@ namespace MxGateway.Client.Cli;
 
 public static class MxGatewayClientCli
 {
+    private const uint MaxAggregateEvents = 10_000;
+
     private static readonly JsonFormatter ProtobufJsonFormatter = JsonFormatter.Default;
 
     private static readonly JsonSerializerOptions JsonOptions = new(JsonSerializerDefaults.Web);
@@ -342,8 +344,22 @@ public static class MxGatewayClientCli
         TextWriter output,
         CancellationToken cancellationToken)
     {
-        var events = new List<MxEvent>();
         uint maxEvents = arguments.GetUInt32("max-events", 0);
+        bool json = arguments.HasFlag("json");
+        bool jsonLines = arguments.HasFlag("jsonl");
+        if (json && !jsonLines && maxEvents is 0)
+        {
+            throw new ArgumentException("--json stream-events requires --max-events to bound aggregate output.");
+        }
+
+        if (maxEvents > MaxAggregateEvents)
+        {
+            throw new ArgumentException($"--max-events cannot exceed {MaxAggregateEvents}.");
+        }
+
+        var events = json && !jsonLines
+            ? new List<MxEvent>(checked((int)maxEvents))
+            : [];
         uint eventCount = 0;
         var request = new StreamEventsRequest
         {
@@ -355,7 +371,11 @@ public static class MxGatewayClientCli
             .WithCancellation(cancellationToken)
             .ConfigureAwait(false))
         {
-            if (arguments.HasFlag("json"))
+            if (jsonLines)
+            {
+                output.WriteLine(ProtobufJsonFormatter.Format(gatewayEvent));
+            }
+            else if (json)
             {
                 events.Add(gatewayEvent);
             }
@@ -371,7 +391,7 @@ public static class MxGatewayClientCli
             }
         }
 
-        if (arguments.HasFlag("json"))
+        if (json && !jsonLines)
         {
             output.WriteLine(JsonSerializer.Serialize(
                 new { events = events.Select(EventToJsonElement).ToArray() },

clients/dotnet/MxGateway.Client/GrpcMxGatewayClientTransport.cs

@@ -25,7 +25,7 @@ internal sealed class GrpcMxGatewayClientTransport(
         }
         catch (RpcException exception)
         {
-            throw MapRpcException(exception);
+            throw MapRpcException(exception, callOptions.CancellationToken);
         }
     }
 
@@ -41,7 +41,7 @@ internal sealed class GrpcMxGatewayClientTransport(
         }
         catch (RpcException exception)
         {
-            throw MapRpcException(exception);
+            throw MapRpcException(exception, callOptions.CancellationToken);
         }
     }
 
@@ -57,7 +57,7 @@ internal sealed class GrpcMxGatewayClientTransport(
         }
         catch (RpcException exception)
         {
-            throw MapRpcException(exception);
+            throw MapRpcException(exception, callOptions.CancellationToken);
         }
     }
 
@@ -87,7 +87,7 @@ internal sealed class GrpcMxGatewayClientTransport(
             }
             catch (RpcException exception)
             {
-                throw MapRpcException(exception);
+                throw MapRpcException(exception, effectiveCancellationToken);
             }
 
             yield return gatewayEvent;
@@ -101,8 +101,18 @@ internal sealed class GrpcMxGatewayClientTransport(
         return StreamEventsAsync(request, callOptions);
     }
 
-    private static MxGatewayException MapRpcException(RpcException exception)
+    private static Exception MapRpcException(
+        RpcException exception,
+        CancellationToken cancellationToken)
     {
+        if (cancellationToken.IsCancellationRequested || exception.StatusCode == StatusCode.Cancelled)
+        {
+            return new OperationCanceledException(
+                exception.Status.Detail,
+                exception,
+                cancellationToken);
+        }
+
         return exception.StatusCode switch
         {
             StatusCode.Unauthenticated => new MxGatewayAuthenticationException(

clients/dotnet/MxGateway.Client/MxGatewayClient.cs

@@ -3,6 +3,9 @@ using Grpc.Net.Client;
 using Microsoft.Extensions.Logging;
 using MxGateway.Contracts.Proto;
 using Polly;
+using System.Net.Http;
+using System.Net.Security;
+using System.Security.Cryptography.X509Certificates;
 
 namespace MxGateway.Client;
 
@@ -54,10 +57,12 @@ public sealed class MxGatewayClient : IAsyncDisposable
         ArgumentNullException.ThrowIfNull(options);
         options.Validate();
 
+        HttpMessageHandler handler = CreateHttpHandler(options);
         var channel = GrpcChannel.ForAddress(
             options.Endpoint,
             new GrpcChannelOptions
             {
+                HttpHandler = handler,
                 LoggerFactory = options.LoggerFactory,
             });
 
@@ -126,7 +131,7 @@ public sealed class MxGatewayClient : IAsyncDisposable
         ArgumentNullException.ThrowIfNull(request);
         ThrowIfDisposed();
 
-        return _transport.StreamEventsAsync(request, CreateCallOptions(cancellationToken));
+        return _transport.StreamEventsAsync(request, CreateStreamCallOptions(cancellationToken));
     }
 
     public ValueTask DisposeAsync()
@@ -142,6 +147,18 @@ public sealed class MxGatewayClient : IAsyncDisposable
     }
 
     internal CallOptions CreateCallOptions(CancellationToken cancellationToken)
+    {
+        return CreateCallOptions(cancellationToken, Options.DefaultCallTimeout);
+    }
+
+    internal CallOptions CreateStreamCallOptions(CancellationToken cancellationToken)
+    {
+        return CreateCallOptions(cancellationToken, Options.StreamTimeout);
+    }
+
+    internal CallOptions CreateCallOptions(
+        CancellationToken cancellationToken,
+        TimeSpan? timeout)
     {
         Metadata headers = new()
         {
@@ -150,18 +167,61 @@ public sealed class MxGatewayClient : IAsyncDisposable
 
         return new CallOptions(
             headers,
-            DateTime.UtcNow.Add(Options.DefaultCallTimeout),
+            timeout is null ? null : DateTime.UtcNow.Add(timeout.Value),
             cancellationToken);
     }
 
-    private Task<T> ExecuteSafeUnaryAsync<T>(
+    private async Task<T> ExecuteSafeUnaryAsync<T>(
         Func<CancellationToken, Task<T>> call,
         CancellationToken cancellationToken)
     {
-        return _safeUnaryRetryPipeline.ExecuteAsync(
+        using CancellationTokenSource timeout = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
+        timeout.CancelAfter(Options.DefaultCallTimeout);
+
+        return await _safeUnaryRetryPipeline.ExecuteAsync(
                 async token => await call(token).ConfigureAwait(false),
-                cancellationToken)
-            .AsTask();
+                timeout.Token)
+            .ConfigureAwait(false);
+    }
+
+    private static HttpMessageHandler CreateHttpHandler(MxGatewayClientOptions options)
+    {
+        SocketsHttpHandler handler = new()
+        {
+            ConnectTimeout = options.ConnectTimeout,
+        };
+
+        if (options.UseTls)
+        {
+            handler.SslOptions = new SslClientAuthenticationOptions();
+            if (!string.IsNullOrWhiteSpace(options.ServerNameOverride))
+            {
+                handler.SslOptions.TargetHost = options.ServerNameOverride;
+            }
+
+            if (!string.IsNullOrWhiteSpace(options.CaCertificatePath))
+            {
+                X509Certificate2 trustedRoot = X509CertificateLoader.LoadCertificateFromFile(options.CaCertificatePath);
+                handler.SslOptions.RemoteCertificateValidationCallback = (_, certificate, chain, errors) =>
+                {
+                    if (certificate is null)
+                    {
+                        return false;
+                    }
+
+                    using X509Chain customChain = new();
+                    customChain.ChainPolicy.TrustMode = X509ChainTrustMode.CustomRootTrust;
+                    customChain.ChainPolicy.CustomTrustStore.Add(trustedRoot);
+                    customChain.ChainPolicy.RevocationMode = X509RevocationMode.NoCheck;
+                    customChain.ChainPolicy.VerificationFlags = X509VerificationFlags.NoFlag;
+                    X509Certificate2 certificateToValidate = certificate as X509Certificate2
+                        ?? X509CertificateLoader.LoadCertificate(certificate.Export(X509ContentType.Cert));
+                    return customChain.Build(certificateToValidate);
+                };
+            }
+        }
+
+        return handler;
     }
 
     private void ThrowIfDisposed()

clients/dotnet/MxGateway.Client/MxGatewayClientOptions.cs

@@ -21,6 +21,8 @@ public sealed class MxGatewayClientOptions
 
     public TimeSpan DefaultCallTimeout { get; init; } = TimeSpan.FromSeconds(30);
 
+    public TimeSpan? StreamTimeout { get; init; }
+
     public MxGatewayClientRetryOptions Retry { get; init; } = new();
 
     public ILoggerFactory? LoggerFactory { get; init; }
@@ -57,6 +59,27 @@ public sealed class MxGatewayClientOptions
                 "The default call timeout must be greater than zero.");
         }
 
+        if (StreamTimeout is not null && StreamTimeout <= TimeSpan.Zero)
+        {
+            throw new ArgumentOutOfRangeException(
+                nameof(StreamTimeout),
+                "The stream timeout must be greater than zero when configured.");
+        }
+
+        if (UseTls && Endpoint.Scheme != Uri.UriSchemeHttps)
+        {
+            throw new ArgumentException(
+                "UseTls requires an https gateway endpoint.",
+                nameof(Endpoint));
+        }
+
+        if (!UseTls && Endpoint.Scheme == Uri.UriSchemeHttps)
+        {
+            throw new ArgumentException(
+                "An https gateway endpoint requires UseTls.",
+                nameof(Endpoint));
+        }
+
         Retry.Validate();
     }
 }