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
@@ -3,6 +3,8 @@ using Grpc.Core;
 using Microsoft.Data.SqlClient;
 using MxGateway.Contracts.Proto.Galaxy;
 using GalaxyDb = MxGateway.Server.Galaxy;
+using MxGateway.Server.Security.Authentication;
+using MxGateway.Server.Security.Authorization;
 using ProtoGalaxyRepository = MxGateway.Contracts.Proto.Galaxy.GalaxyRepository;

 namespace MxGateway.Server.Grpc;
@@ -18,9 +20,12 @@ public sealed class GalaxyRepositoryGrpcService(
    GalaxyDb.GalaxyRepository repository,
    GalaxyDb.IGalaxyHierarchyCache cache,
    GalaxyDb.IGalaxyDeployNotifier notifier,
+    IGatewayRequestIdentityAccessor identityAccessor,
    ILogger<GalaxyRepositoryGrpcService> logger) : ProtoGalaxyRepository.GalaxyRepositoryBase
 {
    private static readonly TimeSpan FirstLoadWaitBudget = TimeSpan.FromSeconds(5);
+    private const int DefaultDiscoverPageSize = 1000;
+    private const int MaxDiscoverPageSize = 5000;

    /// <inheritdoc />
    public override async Task<TestConnectionReply> TestConnection(
@@ -62,16 +67,44 @@ public sealed class GalaxyRepositoryGrpcService(
        await WaitForCacheBootstrap(context.CancellationToken).ConfigureAwait(false);
        GalaxyDb.GalaxyHierarchyCacheEntry entry = cache.Current;

-        if (!entry.HasData || entry.Reply is null)
+        if (!entry.HasData)
        {
            throw new RpcException(new Status(
                StatusCode.Unavailable,
                ResolveUnavailableMessage(entry)));
        }

-        // Same materialized reply is shared across all clients — gRPC serialization is
-        // read-only and the entry is replaced atomically on the next refresh.
-        return entry.Reply;
+        int pageSize = ResolvePageSize(request.PageSize);
+        IReadOnlyList<string> browseSubtrees = ResolveBrowseSubtrees();
+        string filterSignature = GalaxyDb.GalaxyHierarchyProjector.ComputeFilterSignature(request, browseSubtrees);
+        PageToken pageToken = ParsePageToken(request.PageToken, entry.Sequence, filterSignature);
+        GalaxyDb.GalaxyHierarchyQueryResult query = GalaxyDb.GalaxyHierarchyProjector.Project(
+            entry,
+            request,
+            browseSubtrees,
+            pageToken.Offset,
+            pageSize);
+        int offset = pageToken.Offset;
+        if (offset > query.TotalObjectCount)
+        {
+            throw new RpcException(new Status(
+                StatusCode.InvalidArgument,
+                "DiscoverHierarchy page_token is outside the current hierarchy."));
+        }
+
+        DiscoverHierarchyReply reply = new()
+        {
+            TotalObjectCount = query.TotalObjectCount,
+        };
+        reply.Objects.Add(query.Objects);
+
+        int nextOffset = offset + query.Objects.Count;
+        if (nextOffset < query.TotalObjectCount)
+        {
+            reply.NextPageToken = FormatPageToken(entry.Sequence, query.FilterSignature, nextOffset);
+        }
+
+        return reply;
    }

    /// <inheritdoc />
@@ -96,7 +129,7 @@ public sealed class GalaxyRepositoryGrpcService(
            }
            lastSeen = null;

-            await responseStream.WriteAsync(MapDeployEvent(info), context.CancellationToken).ConfigureAwait(false);
+            await responseStream.WriteAsync(MapDeployEvent(info, ResolveBrowseSubtrees()), context.CancellationToken).ConfigureAwait(false);
        }
    }

@@ -124,14 +157,28 @@ public sealed class GalaxyRepositoryGrpcService(
        }
    }

-    private static DeployEvent MapDeployEvent(GalaxyDb.GalaxyDeployEventInfo info)
+    private DeployEvent MapDeployEvent(
+        GalaxyDb.GalaxyDeployEventInfo info,
+        IReadOnlyList<string> browseSubtrees)
    {
+        int objectCount = info.ObjectCount;
+        int attributeCount = info.AttributeCount;
+        if (browseSubtrees.Count > 0 && cache.Current.HasData)
+        {
+            GalaxyDb.GalaxyHierarchyQueryResult scoped = GalaxyDb.GalaxyHierarchyProjector.Project(
+                cache.Current,
+                new DiscoverHierarchyRequest(),
+                browseSubtrees);
+            objectCount = scoped.TotalObjectCount;
+            attributeCount = scoped.Objects.Sum(obj => obj.Attributes.Count);
+        }
+
        DeployEvent ev = new()
        {
            Sequence = (ulong)info.Sequence,
            ObservedAt = Timestamp.FromDateTimeOffset(info.ObservedAt),
-            ObjectCount = info.ObjectCount,
-            AttributeCount = info.AttributeCount,
+            ObjectCount = objectCount,
+            AttributeCount = attributeCount,
            TimeOfLastDeployPresent = info.TimeOfLastDeploy.HasValue,
        };
        if (info.TimeOfLastDeploy.HasValue)
@@ -148,6 +195,80 @@ public sealed class GalaxyRepositoryGrpcService(
        _ => "Galaxy cache has no data available.",
    };

+    private static int ResolvePageSize(int requestedPageSize)
+    {
+        if (requestedPageSize < 0)
+        {
+            throw new RpcException(new Status(
+                StatusCode.InvalidArgument,
+                "DiscoverHierarchy page_size must be greater than zero when provided."));
+        }
+
+        int pageSize = requestedPageSize == 0 ? DefaultDiscoverPageSize : requestedPageSize;
+        return Math.Min(pageSize, MaxDiscoverPageSize);
+    }
+
+    private IReadOnlyList<string> ResolveBrowseSubtrees()
+    {
+        ApiKeyConstraints constraints = identityAccessor.Current?.EffectiveConstraints ?? ApiKeyConstraints.Empty;
+        return constraints.BrowseSubtrees;
+    }
+
+    private static string FormatPageToken(long sequence, string filterSignature, int offset)
+    {
+        return string.Concat(
+            sequence.ToString(System.Globalization.CultureInfo.InvariantCulture),
+            ":",
+            filterSignature,
+            ":",
+            offset.ToString(System.Globalization.CultureInfo.InvariantCulture));
+    }
+
+    private static PageToken ParsePageToken(string pageToken, long currentSequence, string currentFilterSignature)
+    {
+        if (string.IsNullOrWhiteSpace(pageToken))
+        {
+            return new PageToken(currentSequence, currentFilterSignature, Offset: 0);
+        }
+
+        string[] parts = pageToken.Split(':', count: 3);
+        if (parts.Length != 3
+            || !long.TryParse(
+                parts[0],
+                System.Globalization.NumberStyles.None,
+                System.Globalization.CultureInfo.InvariantCulture,
+                out long sequence)
+            || !int.TryParse(
+                parts[2],
+                System.Globalization.NumberStyles.None,
+                System.Globalization.CultureInfo.InvariantCulture,
+                out int offset)
+            || offset < 0)
+        {
+            throw new RpcException(new Status(
+                StatusCode.InvalidArgument,
+                "DiscoverHierarchy page_token is invalid."));
+        }
+
+        if (sequence != currentSequence)
+        {
+            throw new RpcException(new Status(
+                StatusCode.InvalidArgument,
+                "DiscoverHierarchy page_token is stale."));
+        }
+
+        if (!string.Equals(parts[1], currentFilterSignature, StringComparison.Ordinal))
+        {
+            throw new RpcException(new Status(
+                StatusCode.InvalidArgument,
+                "DiscoverHierarchy page_token does not match the current filters."));
+        }
+
+        return new PageToken(sequence, parts[1], offset);
+    }
+
+    private sealed record PageToken(long Sequence, string FilterSignature, int Offset);
+
    [System.Diagnostics.CodeAnalysis.SuppressMessage(
        "Style",
        "IDE0051:Remove unused private members",
@@ -1,8 +1,10 @@
 using System.Diagnostics;
 using Grpc.Core;
+using Google.Protobuf.WellKnownTypes;
 using MxGateway.Contracts;
 using MxGateway.Contracts.Proto;
 using MxGateway.Server.Metrics;
+using MxGateway.Server.Security.Authentication;
 using MxGateway.Server.Security.Authorization;
 using MxGateway.Server.Sessions;
 using MxGateway.Server.Workers;
@@ -13,6 +15,7 @@ namespace MxGateway.Server.Grpc;
 public sealed class MxAccessGatewayService(
    ISessionManager sessionManager,
    IGatewayRequestIdentityAccessor identityAccessor,
+    IConstraintEnforcer constraintEnforcer,
    MxAccessGrpcRequestValidator requestValidator,
    MxAccessGrpcMapper mapper,
    IEventStreamService eventStreamService,
@@ -91,12 +94,35 @@ public sealed class MxAccessGatewayService(
        try
        {
            requestValidator.ValidateInvoke(request);
-            WorkerCommand workerCommand = mapper.MapCommand(request);
+            GatewaySession session = ResolveSession(request.SessionId);
+            MxCommand command = request.Command;
+            BulkConstraintPlan? bulkConstraintPlan = await ApplyConstraintsAsync(
+                    session,
+                    command,
+                    context.CancellationToken)
+                .ConfigureAwait(false);
+
+            MxCommand commandToInvoke = bulkConstraintPlan?.Command ?? command;
+            if (bulkConstraintPlan is { HasAllowedItems: false })
+            {
+                return CreateDeniedBulkReply(request, bulkConstraintPlan);
+            }
+
+            MxCommandRequest invokeRequest = request.Clone();
+            invokeRequest.Command = commandToInvoke;
+            WorkerCommand workerCommand = mapper.MapCommand(invokeRequest);
            WorkerCommandReply workerReply = await sessionManager
                .InvokeAsync(request.SessionId, workerCommand, context.CancellationToken)
                .ConfigureAwait(false);

-            return mapper.MapCommandReply(workerReply);
+            MxCommandReply publicReply = mapper.MapCommandReply(workerReply);
+            if (bulkConstraintPlan is not null)
+            {
+                publicReply = MergeDeniedBulkResults(publicReply, command.Kind, bulkConstraintPlan);
+            }
+
+            session.TrackCommandReply(commandToInvoke, publicReply);
+            return publicReply;
        }
        catch (Exception exception) when (exception is not RpcException)
        {
@@ -134,6 +160,323 @@ public sealed class MxAccessGatewayService(
        return identityAccessor.Current?.DisplayName ?? identityAccessor.Current?.KeyId;
    }

+    private GatewaySession ResolveSession(string sessionId)
+    {
+        if (!sessionManager.TryGetSession(sessionId, out GatewaySession session))
+        {
+            throw new SessionManagerException(
+                SessionManagerErrorCode.SessionNotFound,
+                $"Session {sessionId} was not found.");
+        }
+
+        return session;
+    }
+
+    private async Task<BulkConstraintPlan?> ApplyConstraintsAsync(
+        GatewaySession session,
+        MxCommand command,
+        CancellationToken cancellationToken)
+    {
+        ApiKeyIdentity? identity = identityAccessor.Current;
+        switch (command.Kind)
+        {
+            case MxCommandKind.AddItem:
+                await EnforceReadTagAsync(identity, command.Kind, command.AddItem.ItemDefinition, cancellationToken)
+                    .ConfigureAwait(false);
+                return null;
+            case MxCommandKind.AddItem2:
+                await EnforceReadTagAsync(identity, command.Kind, command.AddItem2.ItemDefinition, cancellationToken)
+                    .ConfigureAwait(false);
+                return null;
+            case MxCommandKind.AddItemBulk:
+                return await FilterTagBulkAsync(
+                        identity,
+                        command,
+                        command.AddItemBulk.ServerHandle,
+                        command.AddItemBulk.TagAddresses,
+                        cancellationToken)
+                    .ConfigureAwait(false);
+            case MxCommandKind.SubscribeBulk:
+                return await FilterTagBulkAsync(
+                        identity,
+                        command,
+                        command.SubscribeBulk.ServerHandle,
+                        command.SubscribeBulk.TagAddresses,
+                        cancellationToken)
+                    .ConfigureAwait(false);
+            case MxCommandKind.AdviseItemBulk:
+                return await FilterHandleBulkAsync(
+                        identity,
+                        session,
+                        command,
+                        command.AdviseItemBulk.ServerHandle,
+                        command.AdviseItemBulk.ItemHandles,
+                        cancellationToken)
+                    .ConfigureAwait(false);
+            case MxCommandKind.Write:
+                await EnforceWriteHandleAsync(
+                        identity,
+                        session,
+                        command.Kind,
+                        command.Write.ServerHandle,
+                        command.Write.ItemHandle,
+                        cancellationToken)
+                    .ConfigureAwait(false);
+                return null;
+            case MxCommandKind.Write2:
+                await EnforceWriteHandleAsync(
+                        identity,
+                        session,
+                        command.Kind,
+                        command.Write2.ServerHandle,
+                        command.Write2.ItemHandle,
+                        cancellationToken)
+                    .ConfigureAwait(false);
+                return null;
+            case MxCommandKind.WriteSecured:
+                await EnforceWriteHandleAsync(
+                        identity,
+                        session,
+                        command.Kind,
+                        command.WriteSecured.ServerHandle,
+                        command.WriteSecured.ItemHandle,
+                        cancellationToken)
+                    .ConfigureAwait(false);
+                return null;
+            case MxCommandKind.WriteSecured2:
+                await EnforceWriteHandleAsync(
+                        identity,
+                        session,
+                        command.Kind,
+                        command.WriteSecured2.ServerHandle,
+                        command.WriteSecured2.ItemHandle,
+                        cancellationToken)
+                    .ConfigureAwait(false);
+                return null;
+            default:
+                return null;
+        }
+    }
+
+    private async Task EnforceReadTagAsync(
+        ApiKeyIdentity? identity,
+        MxCommandKind commandKind,
+        string tagAddress,
+        CancellationToken cancellationToken)
+    {
+        ConstraintFailure? failure = await constraintEnforcer
+            .CheckReadTagAsync(identity, tagAddress, cancellationToken)
+            .ConfigureAwait(false);
+        if (failure is null)
+        {
+            return;
+        }
+
+        await constraintEnforcer.RecordDenialAsync(identity, commandKind.ToString(), tagAddress, failure, cancellationToken)
+            .ConfigureAwait(false);
+        throw new RpcException(new Status(StatusCode.PermissionDenied, failure.Message));
+    }
+
+    private async Task EnforceWriteHandleAsync(
+        ApiKeyIdentity? identity,
+        GatewaySession session,
+        MxCommandKind commandKind,
+        int serverHandle,
+        int itemHandle,
+        CancellationToken cancellationToken)
+    {
+        ConstraintFailure? failure = await constraintEnforcer
+            .CheckWriteHandleAsync(identity, session, serverHandle, itemHandle, cancellationToken)
+            .ConfigureAwait(false);
+        if (failure is null)
+        {
+            return;
+        }
+
+        await constraintEnforcer.RecordDenialAsync(identity, commandKind.ToString(), itemHandle.ToString(System.Globalization.CultureInfo.InvariantCulture), failure, cancellationToken)
+            .ConfigureAwait(false);
+        throw new RpcException(new Status(StatusCode.PermissionDenied, failure.Message));
+    }
+
+    private async Task<BulkConstraintPlan?> FilterTagBulkAsync(
+        ApiKeyIdentity? identity,
+        MxCommand command,
+        int serverHandle,
+        IReadOnlyList<string> tagAddresses,
+        CancellationToken cancellationToken)
+    {
+        Dictionary<int, SubscribeResult> denied = [];
+        List<string> allowed = [];
+        for (int index = 0; index < tagAddresses.Count; index++)
+        {
+            string tagAddress = tagAddresses[index];
+            ConstraintFailure? failure = await constraintEnforcer
+                .CheckReadTagAsync(identity, tagAddress, cancellationToken)
+                .ConfigureAwait(false);
+            if (failure is null)
+            {
+                allowed.Add(tagAddress);
+                continue;
+            }
+
+            await constraintEnforcer.RecordDenialAsync(identity, command.Kind.ToString(), tagAddress, failure, cancellationToken)
+                .ConfigureAwait(false);
+            denied[index] = new SubscribeResult
+            {
+                ServerHandle = serverHandle,
+                TagAddress = tagAddress,
+                WasSuccessful = false,
+                ErrorMessage = failure.Message,
+            };
+        }
+
+        if (denied.Count == 0)
+        {
+            return null;
+        }
+
+        MxCommand filtered = command.Clone();
+        if (filtered.Kind == MxCommandKind.AddItemBulk)
+        {
+            filtered.AddItemBulk.TagAddresses.Clear();
+            filtered.AddItemBulk.TagAddresses.Add(allowed);
+        }
+        else
+        {
+            filtered.SubscribeBulk.TagAddresses.Clear();
+            filtered.SubscribeBulk.TagAddresses.Add(allowed);
+        }
+
+        return new BulkConstraintPlan(filtered, tagAddresses.Count, denied, allowed.Count > 0);
+    }
+
+    private async Task<BulkConstraintPlan?> FilterHandleBulkAsync(
+        ApiKeyIdentity? identity,
+        GatewaySession session,
+        MxCommand command,
+        int serverHandle,
+        IReadOnlyList<int> itemHandles,
+        CancellationToken cancellationToken)
+    {
+        Dictionary<int, SubscribeResult> denied = [];
+        List<int> allowed = [];
+        for (int index = 0; index < itemHandles.Count; index++)
+        {
+            int itemHandle = itemHandles[index];
+            ConstraintFailure? failure = await constraintEnforcer
+                .CheckReadHandleAsync(identity, session, serverHandle, itemHandle, cancellationToken)
+                .ConfigureAwait(false);
+            if (failure is null)
+            {
+                allowed.Add(itemHandle);
+                continue;
+            }
+
+            await constraintEnforcer.RecordDenialAsync(identity, command.Kind.ToString(), itemHandle.ToString(System.Globalization.CultureInfo.InvariantCulture), failure, cancellationToken)
+                .ConfigureAwait(false);
+            denied[index] = new SubscribeResult
+            {
+                ServerHandle = serverHandle,
+                ItemHandle = itemHandle,
+                WasSuccessful = false,
+                ErrorMessage = failure.Message,
+            };
+        }
+
+        if (denied.Count == 0)
+        {
+            return null;
+        }
+
+        MxCommand filtered = command.Clone();
+        filtered.AdviseItemBulk.ItemHandles.Clear();
+        filtered.AdviseItemBulk.ItemHandles.Add(allowed);
+
+        return new BulkConstraintPlan(filtered, itemHandles.Count, denied, allowed.Count > 0);
+    }
+
+    private static MxCommandReply CreateDeniedBulkReply(
+        MxCommandRequest request,
+        BulkConstraintPlan plan)
+    {
+        MxCommandReply reply = new()
+        {
+            SessionId = request.SessionId,
+            CorrelationId = request.ClientCorrelationId,
+            Kind = request.Command.Kind,
+            ProtocolStatus = MxAccessGrpcMapper.Ok(),
+        };
+        SetBulkPayload(reply, request.Command.Kind, BuildMergedBulkReply(new BulkSubscribeReply(), plan));
+        return reply;
+    }
+
+    private static MxCommandReply MergeDeniedBulkResults(
+        MxCommandReply reply,
+        MxCommandKind commandKind,
+        BulkConstraintPlan plan)
+    {
+        BulkSubscribeReply allowed = GetBulkPayload(reply, commandKind) ?? new BulkSubscribeReply();
+        SetBulkPayload(reply, commandKind, BuildMergedBulkReply(allowed, plan));
+        return reply;
+    }
+
+    private static BulkSubscribeReply BuildMergedBulkReply(
+        BulkSubscribeReply allowed,
+        BulkConstraintPlan plan)
+    {
+        Queue<SubscribeResult> allowedResults = new(allowed.Results);
+        BulkSubscribeReply merged = new();
+        for (int index = 0; index < plan.OriginalCount; index++)
+        {
+            if (plan.DeniedResults.TryGetValue(index, out SubscribeResult? denied))
+            {
+                merged.Results.Add(denied);
+            }
+            else if (allowedResults.TryDequeue(out SubscribeResult? allowedResult))
+            {
+                merged.Results.Add(allowedResult);
+            }
+        }
+
+        return merged;
+    }
+
+    private static BulkSubscribeReply? GetBulkPayload(MxCommandReply reply, MxCommandKind commandKind)
+    {
+        return commandKind switch
+        {
+            MxCommandKind.AddItemBulk => reply.AddItemBulk,
+            MxCommandKind.AdviseItemBulk => reply.AdviseItemBulk,
+            MxCommandKind.SubscribeBulk => reply.SubscribeBulk,
+            _ => null,
+        };
+    }
+
+    private static void SetBulkPayload(
+        MxCommandReply reply,
+        MxCommandKind commandKind,
+        BulkSubscribeReply payload)
+    {
+        switch (commandKind)
+        {
+            case MxCommandKind.AddItemBulk:
+                reply.AddItemBulk = payload;
+                break;
+            case MxCommandKind.AdviseItemBulk:
+                reply.AdviseItemBulk = payload;
+                break;
+            case MxCommandKind.SubscribeBulk:
+                reply.SubscribeBulk = payload;
+                break;
+        }
+    }
+
+    private sealed record BulkConstraintPlan(
+        MxCommand Command,
+        int OriginalCount,
+        IReadOnlyDictionary<int, SubscribeResult> DeniedResults,
+        bool HasAllowedItems);
+
    private RpcException MapException(Exception exception)
    {
        if (exception is OperationCanceledException)