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
@@ -0,0 +1,30 @@
namespace ZB.MOM.WW.MxGateway.Contracts;
/// <summary>
/// Machine-readable reason codes the gateway attaches to gRPC <c>ResourceExhausted</c> failures
/// via the <see cref="TrailerKey"/> response trailer, so a client can tell "you fell behind and
/// events were lost" from "a limit was reached". The gRPC status code itself is unchanged.
/// </summary>
public static class ResourceExhaustedReasons
{
/// <summary>Response-trailer key carrying the reason code (gRPC trailer keys are lower-case ASCII).</summary>
public const string TrailerKey = "mxgw-reason";
/// <summary>The subscriber fell behind its bounded event queue and was disconnected; events were lost. Re-subscribe and resync.</summary>
public const string EventQueueOverflow = "event-queue-overflow";
/// <summary>The alarm-feed subscriber fell behind its bounded queue and was dropped. Reconnect and re-snapshot.</summary>
public const string AlarmFeedOverflow = "alarm-feed-overflow";
/// <summary>The per-session event-subscriber cap was reached. Back off; do not retry immediately.</summary>
public const string SubscriberLimit = "subscriber-limit";
/// <summary>The session already has an active event subscriber and only one is allowed.</summary>
public const string SubscriberAlreadyActive = "subscriber-already-active";
/// <summary>The gateway session limit was reached.</summary>
public const string SessionLimit = "session-limit";
/// <summary>A command exceeded the maximum frame size.</summary>
public const string CommandTooLarge = "command-too-large";
}