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
@@ -140,6 +140,16 @@ internal sealed class WireFakeGatewayServer : IAsyncDisposable
/// </summary>
public bool DenyInvoke { get; set; }
/// <summary>
/// Gets or sets a value indicating whether <c>Invoke</c> fails with
/// <see cref="StatusCode.ResourceExhausted"/>; <see cref="ExhaustedReason"/> (when set) rides the
/// <c>mxgw-reason</c> trailer the way the real gateway attaches it.
/// </summary>
public bool ExhaustInvoke { get; set; }
/// <summary>Gets or sets the reason-code trailer value sent with the exhausted failure.</summary>
public string? ExhaustedReason { get; set; }
/// <summary>
/// Gets or sets the replay-gap sentinel emitted at the head of the event stream.
/// </summary>
@@ -189,6 +199,17 @@ internal sealed class WireFakeGatewayServer : IAsyncDisposable
throw new RpcException(new Status(StatusCode.PermissionDenied, "invoke scope required"));
}
if (ExhaustInvoke)
{
Metadata trailers = [];
if (ExhaustedReason is not null)
{
trailers.Add(ZB.MOM.WW.MxGateway.Contracts.ResourceExhaustedReasons.TrailerKey, ExhaustedReason);
}
throw new RpcException(new Status(StatusCode.ResourceExhausted, "exhausted"), trailers);
}
return Task.FromResult(new MxCommandReply
{
SessionId = request.SessionId,