namespace ZB.MOM.WW.MxGateway.Contracts;

/// <summary>
/// Holds the protocol version constants shared by gateway components.
/// <see cref="GatewayProtocolVersion"/> is advertised to clients in
/// <c>OpenSessionReply</c>; <see cref="WorkerProtocolVersion"/> is used to
/// validate <c>WorkerEnvelope</c> protocol framing on the gateway↔worker pipe.
/// </summary>
public static class GatewayContractInfo
{
    /// <summary>Protocol version advertised to clients in <c>OpenSessionReply</c>.</summary>
    public const uint GatewayProtocolVersion = 3;

    /// <summary>Protocol version used to validate <c>WorkerEnvelope</c> framing on the gateway-worker pipe.</summary>
    public const uint WorkerProtocolVersion = 1;

    /// <summary>Default backend name identifying the MXAccess worker process type.</summary>
    public const string DefaultBackendName = "mxaccess-worker";

    /// <summary>
    /// Ceiling on how many events one <c>DrainEvents</c> command may move in a single reply.
    /// Shared so the gateway's request-validation ceiling
    /// (<c>MxAccessGrpcRequestValidator</c>, which rejects a larger <c>max_events</c> loudly at
    /// the public boundary) and the worker's per-reply clamp
    /// (<c>WorkerPipeSession.CreateDrainEventsReply</c>, the backstop that also interprets
    /// <c>max_events = 0</c>) cannot drift apart. A count cap alone is necessary but not
    /// sufficient: the worker additionally caps the reply by serialized bytes against the
    /// negotiated frame maximum (WRK-21), so a reply may carry fewer events than this ceiling
    /// and fewer than are queued. Callers drain iteratively until an empty reply.
    /// This is a documented behavioral bound, not wire schema — it is deliberately a C#
    /// constant and not a <c>.proto</c> field.
    /// </summary>
    public const uint MaxDrainEventsPerCommand = 10_000;

    /// <summary>
    /// Environment variable name that opts an xUnit suite into running live
    /// MXAccess COM tests. Single source of truth shared by both
    /// <c>ZB.MOM.WW.MxGateway.IntegrationTests.LiveMxAccessFactAttribute</c> and
    /// <c>ZB.MOM.WW.MxGateway.Worker.Tests.TestSupport.LiveMxAccessFactAttribute</c>
    /// so any future opt-in tweak does not silently leave one project
    /// behind.
    /// </summary>
    public const string LiveMxAccessOptInVariableName = "MXGATEWAY_RUN_LIVE_MXACCESS_TESTS";
}