feat(events): distinguish ResourceExhausted causes with an mxgw-reason trailer (mxaccessgw#216)

Event-queue overflow, alarm-feed overflow, subscriber cap, session limit and
oversized commands all surfaced as ResourceExhausted. The status code is
unchanged; the gateway now attaches a machine-readable `mxgw-reason` trailer
(constants in Contracts ResourceExhaustedReasons). The .NET client maps
ResourceExhausted to MxGatewayResourceExhaustedException (an
MxGatewayException subclass; additive) exposing Reason/IsOverflow/
IsSubscriberLimit. Documented in docs/ClientBehaviorFixtures.md; the other
clients get a doc note only.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
This commit is contained in:
Joseph Doherty
2026-11-09 15:02:24 -05:00
parent 716c845fc7
commit fccc21ba8e
9 changed files with 253 additions and 5 deletions
@@ -668,16 +668,46 @@ public sealed class MxAccessGatewayServiceTests
new TestServerCallContext()));
Assert.Equal(StatusCode.ResourceExhausted, exception.StatusCode);
Assert.Equal(ResourceExhaustedReasons.AlarmFeedOverflow, exception.Trailers.GetValue(ResourceExhaustedReasons.TrailerKey));
Assert.DoesNotContain(logger.Entries, entry => entry.Level >= LogLevel.Warning);
}
/// <summary>
/// Event-queue overflow and the subscriber cap both stay <c>ResourceExhausted</c> but carry
/// distinct machine-readable reason trailers (#216).
/// </summary>
/// <param name="errorCode">The session-manager fault.</param>
/// <param name="expectedReason">The reason trailer expected.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
[Theory]
[InlineData(SessionManagerErrorCode.EventQueueOverflow, ResourceExhaustedReasons.EventQueueOverflow)]
[InlineData(SessionManagerErrorCode.EventSubscriberLimitReached, ResourceExhaustedReasons.SubscriberLimit)]
public async Task StreamEvents_ResourceExhaustedFaults_CarryDistinguishingReasonTrailer(
SessionManagerErrorCode errorCode,
string expectedReason)
{
MxAccessGatewayService service = CreateService(
new FakeSessionManager(),
eventStreamFault: new SessionManagerException(errorCode, "fault"));
RpcException exception = await Assert.ThrowsAsync<RpcException>(
() => service.StreamEvents(
new StreamEventsRequest { SessionId = "session-1" },
new RecordingServerStreamWriter<MxEvent>(),
new TestServerCallContext()));
Assert.Equal(StatusCode.ResourceExhausted, exception.StatusCode);
Assert.Equal(expectedReason, exception.Trailers.GetValue(ResourceExhaustedReasons.TrailerKey));
}
private static MxAccessGatewayService CreateService(
FakeSessionManager sessionManager,
IGatewayRequestIdentityAccessor? identityAccessor = null,
GatewayMetrics? metrics = null,
IConstraintEnforcer? constraintEnforcer = null,
IGatewayAlarmService? alarmService = null,
ILogger<MxAccessGatewayService>? logger = null)
ILogger<MxAccessGatewayService>? logger = null,
Exception? eventStreamFault = null)
{
return new MxAccessGatewayService(
sessionManager,
@@ -685,7 +715,7 @@ public sealed class MxAccessGatewayServiceTests
constraintEnforcer ?? new AllowAllConstraintEnforcer(),
new MxAccessGrpcRequestValidator(),
new MxAccessGrpcMapper(),
new FakeEventStreamService(sessionManager),
new FakeEventStreamService(sessionManager) { StreamFault = eventStreamFault },
metrics ?? new GatewayMetrics(),
logger ?? NullLogger<MxAccessGatewayService>.Instance,
alarmService ?? new FakeGatewayAlarmService());
@@ -917,6 +947,9 @@ public sealed class MxAccessGatewayServiceTests
private sealed class FakeEventStreamService(FakeSessionManager sessionManager) : IEventStreamService
{
/// <summary>Gets or sets a fault thrown when the stream starts.</summary>
public Exception? StreamFault { get; set; }
/// <inheritdoc />
public async IAsyncEnumerable<MxEvent> StreamEventsAsync(
StreamEventsRequest request,
@@ -924,6 +957,12 @@ public sealed class MxAccessGatewayServiceTests
[EnumeratorCancellation] CancellationToken cancellationToken)
{
sessionManager.RecordReadEventsSessionId(request.SessionId);
if (StreamFault is not null)
{
await Task.Yield();
throw StreamFault;
}
foreach (WorkerEvent workerEvent in sessionManager.Events)
{
cancellationToken.ThrowIfCancellationRequested();