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() },