Merge origin/main with local pending work and update AGENTS.md references

- Resolve 14 conflicts from popping local stash on top of origin's eed1e88 + 8d3352f doc-comment additions (11 mechanical, plus version.rs, DashboardAuthenticatorTests.cs, DashboardGalaxyProjector.cs) - Fix 4 test files that used AGENTS.md as the repo-root sentinel (now use CLAUDE.md, since AGENTS.md was removed in 4731ab5) - Redirect 10 doc citations from AGENTS.md to the matching gateway.md sections (Value Model, Status Model, Security, STA Worker Thread Model, gRPC Layer rule, cancellation rule) Verified: solution build clean, x86 worker build clean, 266/266 gateway tests passing, 121/121 worker tests passing. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-30 14:13:33 -04:00
parent 8d3352f2c6
commit ddad573b75
101 changed files with 6053 additions and 621 deletions
@@ -824,9 +824,7 @@ public static class MxGatewayClientCli
        TextWriter output,
        CancellationToken cancellationToken)
    {
-        DiscoverHierarchyReply reply = await client.GalaxyDiscoverHierarchyAsync(
-                new DiscoverHierarchyRequest(),
-                cancellationToken)
+        DiscoverHierarchyReply reply = await DiscoverAllGalaxyHierarchyAsync(client, cancellationToken)
            .ConfigureAwait(false);

        if (arguments.HasFlag("json"))
@@ -844,6 +842,39 @@ public static class MxGatewayClientCli
        return 0;
    }

+    private static async Task<DiscoverHierarchyReply> DiscoverAllGalaxyHierarchyAsync(
+        IMxGatewayCliClient client,
+        CancellationToken cancellationToken)
+    {
+        DiscoverHierarchyReply aggregate = new();
+        HashSet<string> seenPageTokens = new(StringComparer.Ordinal);
+        string pageToken = string.Empty;
+        do
+        {
+            DiscoverHierarchyReply page = await client.GalaxyDiscoverHierarchyAsync(
+                    new DiscoverHierarchyRequest
+                    {
+                        PageSize = 5000,
+                        PageToken = pageToken,
+                    },
+                    cancellationToken)
+                .ConfigureAwait(false);
+
+            aggregate.Objects.Add(page.Objects);
+            aggregate.TotalObjectCount = page.TotalObjectCount;
+            pageToken = page.NextPageToken;
+            if (!string.IsNullOrWhiteSpace(pageToken)
+                && !seenPageTokens.Add(pageToken))
+            {
+                throw new MxGatewayException(
+                    $"Galaxy DiscoverHierarchy returned a repeated page token '{pageToken}'.");
+            }
+        }
+        while (!string.IsNullOrWhiteSpace(pageToken));
+
+        return aggregate;
+    }
+
    private static async Task<int> GalaxyWatchAsync(
        CliArguments arguments,
        IMxGatewayCliClient client,
@@ -48,6 +48,8 @@ internal sealed class FakeGalaxyRepositoryTransport(MxGatewayClientOptions optio
    /// </summary>
    public DiscoverHierarchyReply DiscoverHierarchyReply { get; set; } = new();

+    public Queue<DiscoverHierarchyReply> DiscoverHierarchyReplies { get; } = new();
+
    /// <summary>
    /// Gets the queue of exceptions to throw from TestConnection; dequeued in FIFO order.
    /// </summary>
@@ -114,7 +116,10 @@ internal sealed class FakeGalaxyRepositoryTransport(MxGatewayClientOptions optio
            throw exception;
        }

-        return Task.FromResult(DiscoverHierarchyReply);
+        return Task.FromResult(
+            DiscoverHierarchyReplies.TryDequeue(out DiscoverHierarchyReply? reply)
+                ? reply
+                : DiscoverHierarchyReply);
    }

    /// <summary>
@@ -83,8 +83,10 @@ public sealed class GalaxyRepositoryClientTests
    public async Task DiscoverHierarchyAsync_ReturnsObjectsFromReply()
    {
        FakeGalaxyRepositoryTransport transport = CreateTransport();
-        transport.DiscoverHierarchyReply = new DiscoverHierarchyReply
+        transport.DiscoverHierarchyReplies.Enqueue(new DiscoverHierarchyReply
        {
+            NextPageToken = "page-2",
+            TotalObjectCount = 2,
            Objects =
            {
                new GalaxyObject
@@ -106,12 +108,29 @@ public sealed class GalaxyRepositoryClientTests
                    },
                },
            },
-        };
+        });
+        transport.DiscoverHierarchyReplies.Enqueue(new DiscoverHierarchyReply
+        {
+            TotalObjectCount = 2,
+            Objects =
+            {
+                new GalaxyObject
+                {
+                    GobjectId = 13,
+                    TagName = "DelmiaReceiver_002",
+                },
+            },
+        });
        await using GalaxyRepositoryClient client = CreateClient(transport);

        IReadOnlyList<GalaxyObject> objects = await client.DiscoverHierarchyAsync();

-        GalaxyObject obj = Assert.Single(objects);
+        Assert.Equal(2, objects.Count);
+        Assert.Equal(2, transport.DiscoverHierarchyCalls.Count);
+        Assert.Equal(5000, transport.DiscoverHierarchyCalls[0].Request.PageSize);
+        Assert.Equal("", transport.DiscoverHierarchyCalls[0].Request.PageToken);
+        Assert.Equal("page-2", transport.DiscoverHierarchyCalls[1].Request.PageToken);
+        GalaxyObject obj = objects[0];
        Assert.Equal(12, obj.GobjectId);
        Assert.Equal("DelmiaReceiver_001", obj.TagName);
        GalaxyAttribute attribute = Assert.Single(obj.Attributes);
@@ -142,6 +161,57 @@ public sealed class GalaxyRepositoryClientTests
    /// <summary>
    /// Verifies that TestConnectionAsync retries on transient gRPC failures.
    /// </summary>
+    [Fact]
+    public async Task DiscoverHierarchyAsync_WithRepeatedPageToken_ThrowsProtocolError()
+    {
+        FakeGalaxyRepositoryTransport transport = CreateTransport();
+        transport.DiscoverHierarchyReplies.Enqueue(new DiscoverHierarchyReply
+        {
+            NextPageToken = "7:1",
+        });
+        transport.DiscoverHierarchyReplies.Enqueue(new DiscoverHierarchyReply
+        {
+            NextPageToken = "7:1",
+        });
+        await using GalaxyRepositoryClient client = CreateClient(transport);
+
+        MxGatewayException exception = await Assert.ThrowsAsync<MxGatewayException>(
+            async () => await client.DiscoverHierarchyAsync());
+
+        Assert.Contains("repeated page token", exception.Message, StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public async Task DiscoverHierarchyAsync_WithOptions_MapsTypedFilters()
+    {
+        FakeGalaxyRepositoryTransport transport = CreateTransport();
+        await using GalaxyRepositoryClient client = CreateClient(transport);
+
+        await client.DiscoverHierarchyAsync(new DiscoverHierarchyOptions
+        {
+            RootContainedPath = "Area1/Line3",
+            MaxDepth = 2,
+            CategoryIds = [10, 13],
+            TemplateChainContains = ["Pump"],
+            TagNameGlob = "Pump_*",
+            IncludeAttributes = false,
+            AlarmBearingOnly = true,
+            HistorizedOnly = true,
+        });
+
+        DiscoverHierarchyRequest request = Assert.Single(transport.DiscoverHierarchyCalls).Request;
+        Assert.Equal(DiscoverHierarchyRequest.RootOneofCase.RootContainedPath, request.RootCase);
+        Assert.Equal("Area1/Line3", request.RootContainedPath);
+        Assert.Equal(2, request.MaxDepth);
+        Assert.Equal([10, 13], request.CategoryIds);
+        Assert.Equal(["Pump"], request.TemplateChainContains);
+        Assert.Equal("Pump_*", request.TagNameGlob);
+        Assert.True(request.HasIncludeAttributes);
+        Assert.False(request.IncludeAttributes);
+        Assert.True(request.AlarmBearingOnly);
+        Assert.True(request.HistorizedOnly);
+    }
+
    [Fact]
    public async Task TestConnectionAsync_RetriesOnTransientGrpcFailure()
    {
@@ -18,7 +18,7 @@ public sealed class MxGatewayClientCliTests
        var exitCode = MxGatewayClientCli.Run(["version"], output, error);

        Assert.Equal(0, exitCode);
-        Assert.Contains("gateway-protocol=1", output.ToString());
+        Assert.Contains("gateway-protocol=2", output.ToString());
        Assert.Contains("worker-protocol=1", output.ToString());
        Assert.Equal(string.Empty, error.ToString());
    }
@@ -33,7 +33,7 @@ public sealed class MxGatewayClientCliTests
        int exitCode = await MxGatewayClientCli.RunAsync(["version", "--json"], output, error);

        Assert.Equal(0, exitCode);
-        Assert.Contains("\"gatewayProtocolVersion\":1", output.ToString());
+        Assert.Contains("\"gatewayProtocolVersion\":2", output.ToString());
        Assert.Equal(string.Empty, error.ToString());
    }

@@ -216,8 +216,10 @@ public sealed class MxGatewayClientCliTests
        using var output = new StringWriter();
        using var error = new StringWriter();
        FakeCliClient fakeClient = new();
-        fakeClient.GalaxyDiscoverHierarchyReply = new DiscoverHierarchyReply
+        fakeClient.GalaxyDiscoverHierarchyReplies.Enqueue(new DiscoverHierarchyReply
        {
+            NextPageToken = "7:1",
+            TotalObjectCount = 2,
            Objects =
            {
                new GalaxyObject
@@ -236,7 +238,21 @@ public sealed class MxGatewayClientCliTests
                    },
                },
            },
-        };
+        });
+        fakeClient.GalaxyDiscoverHierarchyReplies.Enqueue(new DiscoverHierarchyReply
+        {
+            TotalObjectCount = 2,
+            Objects =
+            {
+                new GalaxyObject
+                {
+                    GobjectId = 8,
+                    TagName = "DelmiaReceiver_002",
+                    ContainedName = "DelmiaReceiver",
+                    ParentGobjectId = 1,
+                },
+            },
+        });

        int exitCode = await MxGatewayClientCli.RunAsync(
            [
@@ -251,10 +267,14 @@ public sealed class MxGatewayClientCliTests
            _ => fakeClient);

        Assert.Equal(0, exitCode);
-        Assert.Single(fakeClient.GalaxyDiscoverHierarchyRequests);
+        Assert.Equal(2, fakeClient.GalaxyDiscoverHierarchyRequests.Count);
+        Assert.Equal(5000, fakeClient.GalaxyDiscoverHierarchyRequests[0].PageSize);
+        Assert.Equal("", fakeClient.GalaxyDiscoverHierarchyRequests[0].PageToken);
+        Assert.Equal("7:1", fakeClient.GalaxyDiscoverHierarchyRequests[1].PageToken);
        string text = output.ToString();
-        Assert.Contains("objects=1", text);
+        Assert.Contains("objects=2", text);
        Assert.Contains("DelmiaReceiver_001", text);
+        Assert.Contains("DelmiaReceiver_002", text);
        Assert.Contains("attributes=1", text);
        Assert.Equal(string.Empty, error.ToString());
    }
@@ -436,6 +456,8 @@ public sealed class MxGatewayClientCliTests
        /// <summary>Galaxy discover hierarchy reply to return.</summary>
        public DiscoverHierarchyReply GalaxyDiscoverHierarchyReply { get; set; } = new();

+        public Queue<DiscoverHierarchyReply> GalaxyDiscoverHierarchyReplies { get; } = new();
+
        /// <summary>List of received galaxy test connection requests.</summary>
        public List<TestConnectionRequest> GalaxyTestConnectionRequests { get; } = [];

@@ -469,7 +491,10 @@ public sealed class MxGatewayClientCliTests
            CancellationToken cancellationToken)
        {
            GalaxyDiscoverHierarchyRequests.Add(request);
-            return Task.FromResult(GalaxyDiscoverHierarchyReply);
+            return Task.FromResult(
+                GalaxyDiscoverHierarchyReplies.TryDequeue(out DiscoverHierarchyReply? reply)
+                    ? reply
+                    : GalaxyDiscoverHierarchyReply);
        }

        /// <summary>List of received galaxy watch deploy events requests.</summary>
@@ -18,6 +18,8 @@ namespace MxGateway.Client;
 /// </summary>
 public sealed class GalaxyRepositoryClient : IAsyncDisposable
 {
+    private const int DiscoverHierarchyPageSize = 5000;
+
    private readonly GrpcChannel? _channel;
    private readonly IGalaxyRepositoryClientTransport _transport;
    private readonly ResiliencePipeline _safeUnaryRetryPipeline;
@@ -84,6 +86,8 @@ public sealed class GalaxyRepositoryClient : IAsyncDisposable
            {
                HttpHandler = handler,
                LoggerFactory = options.LoggerFactory,
+                MaxReceiveMessageSize = options.MaxGrpcMessageBytes,
+                MaxSendMessageSize = options.MaxGrpcMessageBytes,
            });

        return new GalaxyRepositoryClient(
@@ -175,12 +179,81 @@ public sealed class GalaxyRepositoryClient : IAsyncDisposable
    /// <returns>The collection of Galaxy objects in the hierarchy.</returns>
    public async Task<IReadOnlyList<GalaxyObject>> DiscoverHierarchyAsync(CancellationToken cancellationToken = default)
    {
-        DiscoverHierarchyReply reply = await DiscoverHierarchyRawAsync(
-                new DiscoverHierarchyRequest(),
-                cancellationToken)
-            .ConfigureAwait(false);
+        return await DiscoverHierarchyAsync(new DiscoverHierarchyOptions(), cancellationToken).ConfigureAwait(false);
+    }

-        return reply.Objects;
+    public async Task<IReadOnlyList<GalaxyObject>> DiscoverHierarchyAsync(
+        DiscoverHierarchyOptions options,
+        CancellationToken cancellationToken = default)
+    {
+        List<GalaxyObject> objects = [];
+        HashSet<string> seenPageTokens = new(StringComparer.Ordinal);
+        string pageToken = string.Empty;
+        do
+        {
+            DiscoverHierarchyRequest request = CreateDiscoverHierarchyRequest(options);
+            request.PageSize = DiscoverHierarchyPageSize;
+            request.PageToken = pageToken;
+            DiscoverHierarchyReply reply = await DiscoverHierarchyRawAsync(
+                    request,
+                    cancellationToken)
+                .ConfigureAwait(false);
+
+            objects.AddRange(reply.Objects);
+            pageToken = reply.NextPageToken;
+            if (!string.IsNullOrWhiteSpace(pageToken)
+                && !seenPageTokens.Add(pageToken))
+            {
+                throw new MxGatewayException(
+                    $"Galaxy DiscoverHierarchy returned a repeated page token '{pageToken}'.");
+            }
+        }
+        while (!string.IsNullOrWhiteSpace(pageToken));
+
+        return objects;
+    }
+
+    private static DiscoverHierarchyRequest CreateDiscoverHierarchyRequest(DiscoverHierarchyOptions options)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+
+        DiscoverHierarchyRequest request = new()
+        {
+            AlarmBearingOnly = options.AlarmBearingOnly,
+            HistorizedOnly = options.HistorizedOnly,
+        };
+
+        if (options.RootGobjectId.HasValue)
+        {
+            request.RootGobjectId = options.RootGobjectId.Value;
+        }
+        else if (!string.IsNullOrWhiteSpace(options.RootTagName))
+        {
+            request.RootTagName = options.RootTagName;
+        }
+        else if (!string.IsNullOrWhiteSpace(options.RootContainedPath))
+        {
+            request.RootContainedPath = options.RootContainedPath;
+        }
+
+        if (options.MaxDepth.HasValue)
+        {
+            request.MaxDepth = options.MaxDepth.Value;
+        }
+
+        request.CategoryIds.Add(options.CategoryIds);
+        request.TemplateChainContains.Add(options.TemplateChainContains);
+        if (!string.IsNullOrWhiteSpace(options.TagNameGlob))
+        {
+            request.TagNameGlob = options.TagNameGlob;
+        }
+
+        if (options.IncludeAttributes.HasValue)
+        {
+            request.IncludeAttributes = options.IncludeAttributes.Value;
+        }
+
+        return request;
    }

    /// <summary>
@@ -80,6 +80,8 @@ public sealed class MxGatewayClient : IAsyncDisposable
            {
                HttpHandler = handler,
                LoggerFactory = options.LoggerFactory,
+                MaxReceiveMessageSize = options.MaxGrpcMessageBytes,
+                MaxSendMessageSize = options.MaxGrpcMessageBytes,
            });

        return new MxGatewayClient(
@@ -47,6 +47,8 @@ public sealed class MxGatewayClientOptions
    /// </summary>
    public TimeSpan? StreamTimeout { get; init; }

+    public int MaxGrpcMessageBytes { get; init; } = 16 * 1024 * 1024;
+
    /// <summary>
    /// Gets the retry configuration for safe unary calls.
    /// </summary>
@@ -102,6 +104,13 @@ public sealed class MxGatewayClientOptions
                "The stream timeout must be greater than zero when configured.");
        }

+        if (MaxGrpcMessageBytes <= 0)
+        {
+            throw new ArgumentOutOfRangeException(
+                nameof(MaxGrpcMessageBytes),
+                "The maximum gRPC message size must be greater than zero.");
+        }
+
        if (UseTls && Endpoint.Scheme != Uri.UriSchemeHttps)
        {
            throw new ArgumentException(