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
@@ -149,6 +149,57 @@ public sealed class MxGatewayClientWireTests
() => session.RegisterAsync("wire-test-client"));
}
/// <summary>
/// A <c>RESOURCE_EXHAUSTED</c> status carrying the <c>mxgw-reason</c> trailer surfaces the
/// reason as a typed property, so overflow and limit rejections can be told apart.
/// </summary>
/// <param name="reason">The reason code the fake gateway attaches.</param>
/// <param name="overflow">Whether the client should classify it as an overflow.</param>
/// <param name="limit">Whether the client should classify it as a subscriber-limit rejection.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
[Theory]
[InlineData("event-queue-overflow", true, false)]
[InlineData("subscriber-limit", false, true)]
public async Task ResourceExhaustedStatus_ExposesReasonFromTrailer(string reason, bool overflow, bool limit)
{
await using WireFakeGatewayServer server = await WireFakeGatewayServer.StartAsync(
service =>
{
service.ExhaustInvoke = true;
service.ExhaustedReason = reason;
});
await using MxGatewayClient client = server.CreateClient(ApiKey);
MxGatewaySession session = await client.OpenSessionAsync(
new OpenSessionRequest { ClientSessionName = "wire-test" });
MxGatewayResourceExhaustedException exception =
await Assert.ThrowsAsync<MxGatewayResourceExhaustedException>(
() => session.RegisterAsync("wire-test-client"));
Assert.Equal(reason, exception.Reason);
Assert.Equal(overflow, exception.IsOverflow);
Assert.Equal(limit, exception.IsSubscriberLimit);
Assert.IsAssignableFrom<MxGatewayException>(exception);
}
/// <summary>A <c>RESOURCE_EXHAUSTED</c> from an older gateway (no trailer) has a null reason.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ResourceExhaustedStatus_WithoutTrailer_HasNullReason()
{
await using WireFakeGatewayServer server = await WireFakeGatewayServer.StartAsync(
service => service.ExhaustInvoke = true);
await using MxGatewayClient client = server.CreateClient(ApiKey);
MxGatewaySession session = await client.OpenSessionAsync(
new OpenSessionRequest { ClientSessionName = "wire-test" });
MxGatewayResourceExhaustedException exception =
await Assert.ThrowsAsync<MxGatewayResourceExhaustedException>(
() => session.RegisterAsync("wire-test-client"));
Assert.Null(exception.Reason);
}
private static async Task<List<MxEvent>> CollectAsync(IAsyncEnumerable<MxEvent> stream)
{
List<MxEvent> events = [];