acdream/src/AcDream.Core.Net/NetDiagnostics.cs

namespace AcDream.Core.Net;

/// <summary>
/// Direction mask for the N5 <c>LossyTransportDecorator</c>
/// (<c>ACDREAM_NET_DROP_DIR</c>): drop outbound datagrams, inbound
/// datagrams, or both.
/// </summary>
public enum NetDropDirection
{
    Out,
    In,
    Both,
}

/// <summary>
/// Diagnostic owner for the <c>ACDREAM_PROBE_NET</c> probe family (#260).
/// Read once at startup, following the <c>PhysicsDiagnostics</c> pattern.
///
/// <para>
/// When enabled, four probe line families are emitted:
/// <list type="bullet">
/// <item><c>[net-out]</c> — one line per outbound reliable game message at the
/// <c>WorldSession.SendGameMessage</c> chokepoint: opcode, game-action type +
/// sequence (when the body is a 0xF7B1 GameAction), fragment/packet sequence,
/// managed thread id, and session state. An exception escaping the wire write
/// additionally emits <c>[net-out-EX]</c> via an exception filter (log
/// without catching — behavior is unchanged).</item>
/// <item><c>[net-tick]</c> — a once-per-second cadence summary from
/// <c>WorldSession.Tick</c>: inbound datagrams/s, remaining queue depth,
/// budget-break count, worst inter-tick gap (= worst frame stall as seen by
/// the net pump), outbound sends/s, acks/s, and — the N5 loss-observability
/// extension — per-second reliable-transport rates (resends, NAKs out/in,
/// rejects in, duplicate drops, parked keystream words, AD-51 reclaims)
/// plus the two instantaneous depths (sent-packet cache, inbound NAK set).
/// The counters themselves increment unconditionally in
/// <c>TransportStats</c>; only the string work is gated here.</item>
/// <item><c>[net-final]</c> — one cumulative <c>TransportStats</c> summary
/// emitted at <c>WorldSession.Dispose</c>, so a connected gate (N5's loss
/// gate) can assert exact totals instead of reconstructing them from
/// rounded per-second rates.</item>
/// <item><c>[cmd-gate]</c> — one line per generation-gated runtime command
/// REJECTION in <c>CurrentGameRuntimeCommandAdapter.Validate</c> (status,
/// expected vs view generation, lifecycle, IsInWorld) plus the combat-toggle
/// result. These rejections are otherwise completely silent, which is what
/// let #260's wedge hide.</item>
/// </list>
/// Zero steady-state cost when off: every site is behind this single bool.
/// </para>
/// </summary>
public static class NetDiagnostics
{
    /// <summary>
    /// <c>ACDREAM_PROBE_NET=1</c> — #260 outbound/command-gate probe family.
    /// </summary>
    public static bool ProbeNet { get; set; } =
        Environment.GetEnvironmentVariable("ACDREAM_PROBE_NET") == "1";

    /// <summary>
    /// <c>ACDREAM_NET_DROP_PCT</c> (int 0–100, default 0 = off) — N5
    /// deterministic loss injection. When &gt; 0 the session's DEFAULT
    /// transport factory wraps the socket transport in
    /// <c>LossyTransportDecorator</c>; at 0 the decorator is structurally
    /// absent (never constructed). Out-of-range or unparsable values read
    /// as 0 — a mistyped variable must never inject loss.
    /// </summary>
    public static int NetDropPercent { get; set; } =
        ParseDropPercent(
            Environment.GetEnvironmentVariable("ACDREAM_NET_DROP_PCT"));

    /// <summary>
    /// <c>ACDREAM_NET_DROP_SEED</c> (int, default 1) — the decorator's PRNG
    /// seed. Same seed ⇒ identical per-direction drop pattern.
    /// </summary>
    public static int NetDropSeed { get; set; } =
        int.TryParse(
            Environment.GetEnvironmentVariable("ACDREAM_NET_DROP_SEED"),
            out int seed)
            ? seed
            : 1;

    /// <summary>
    /// <c>ACDREAM_NET_DROP_DIR</c> (<c>out</c> | <c>in</c> | <c>both</c>,
    /// default <c>both</c>) — which directions the decorator drops.
    /// </summary>
    public static NetDropDirection NetDropDir { get; set; } =
        ParseDropDirection(
            Environment.GetEnvironmentVariable("ACDREAM_NET_DROP_DIR"));

    internal static int ParseDropPercent(string? value) =>
        int.TryParse(value, out int percent) && percent is >= 0 and <= 100
            ? percent
            : 0;

    internal static NetDropDirection ParseDropDirection(string? value) =>
        value?.ToLowerInvariant() switch
        {
            "out" => NetDropDirection.Out,
            "in" => NetDropDirection.In,
            _ => NetDropDirection.Both,
        };

    /// <summary>
    /// <c>ACDREAM_PROBE_REVEAL=1</c> — #260 reveal-stall probe: while a
    /// reveal destination's composite warmup is incomplete, emit one
    /// <c>[composite-warmup]</c> line per second naming the pending queue
    /// depth, scan state, upload-budget gate, and the first few unresolved
    /// GfxObj ids. The two permanent-stall shapes (a mesh id that never
    /// resolves vs. an upload budget that never reopens) are otherwise
    /// indistinguishable and invisible.
    /// </summary>
    public static bool ProbeReveal { get; set; } =
        Environment.GetEnvironmentVariable("ACDREAM_PROBE_REVEAL") == "1";
}