lmxopcua/tests/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests/AbLegacyServerFixture.cs

using System.Net.Sockets;
using Xunit;
using Xunit.Sdk;
using ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.PlcFamilies;

namespace ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.IntegrationTests;

/// <summary>
///     Reachability probe for the <c>ab_server</c> Docker container running in a PCCC
///     plc mode (<c>SLC500</c> / <c>Micrologix</c> / <c>PLC/5</c>). Same container image
///     the AB CIP integration suite uses — libplctag's <c>ab_server</c> supports both
///     CIP + PCCC families from one binary. Tests skip via
///     <see cref="AbLegacyFactAttribute"/> / <see cref="AbLegacyTheoryAttribute"/> when
///     the port isn't live, so <c>dotnet test</c> stays green on a fresh clone without
///     Docker running.
/// </summary>
/// <remarks>
///     Env-var overrides:
///     <list type="bullet">
///       <item><c>AB_LEGACY_ENDPOINT</c> — <c>host:port</c> of the PCCC-mode simulator.
///         Defaults to <c>localhost:44818</c> (EtherNet/IP port; ab_server's PCCC
///         emulation exposes PCCC-over-CIP on the same port as CIP itself).</item>
///     </list>
///     Distinct from <c>AB_SERVER_ENDPOINT</c> used by the AB CIP fixture so both
///     can point at different containers simultaneously during a combined test run.
/// </remarks>
public sealed class AbLegacyServerFixture : IAsyncLifetime
{
    private const string EndpointEnvVar = "AB_LEGACY_ENDPOINT";

    /// <summary>
    ///     Opt-in flag that promises the endpoint can actually round-trip PCCC reads/writes
    ///     (real SLC 5/05 / MicroLogix 1100/1400 / PLC-5 hardware, or a RSEmulate 500
    ///     golden-box per <c>docs/v2/lmx-followups.md</c>). Without this, the fixture assumes
    ///     the endpoint is libplctag's <c>ab_server --plc=SLC500</c> Docker container — whose
    ///     PCCC dispatcher is a known upstream gap — and skips cleanly rather than failing
    ///     every test with <c>BadCommunicationError</c>.
    /// </summary>
    private const string TrustWireEnvVar = "AB_LEGACY_TRUST_WIRE";

    /// <summary>Standard EtherNet/IP port. PCCC-over-CIP rides on the same port as
    /// native CIP; the differentiator is the <c>--plc</c> flag ab_server was started
    /// with, not a different TCP listener.</summary>
    public const int DefaultPort = 44818;

    public string Host { get; } = "127.0.0.1";
    public int Port { get; } = DefaultPort;
    public string? SkipReason { get; }

    public AbLegacyServerFixture()
    {
        if (Environment.GetEnvironmentVariable(EndpointEnvVar) is { Length: > 0 } raw)
        {
            var parts = raw.Split(':', 2);
            Host = parts[0];
            if (parts.Length == 2 && int.TryParse(parts[1], out var p)) Port = p;
        }

        SkipReason = ResolveSkipReason(Host, Port);
    }

    public ValueTask InitializeAsync() => ValueTask.CompletedTask;
    public ValueTask DisposeAsync() => ValueTask.CompletedTask;

    /// <summary>
    ///     Used by <see cref="AbLegacyFactAttribute"/> + <see cref="AbLegacyTheoryAttribute"/>
    ///     during test-class construction — gates whether the test runs at all. Duplicates the
    ///     fixture logic because attribute ctors fire before the collection fixture instance
    ///     exists.
    /// </summary>
    public static bool IsServerAvailable()
    {
        var (host, port) = ResolveEndpoint();
        return ResolveSkipReason(host, port) is null;
    }

    private static string? ResolveSkipReason(string host, int port)
    {
        if (!TcpProbe(host, port))
        {
            return $"AB Legacy PCCC endpoint at {host}:{port} not reachable within 2 s. " +
                   $"Start the Docker container (docker compose -f Docker/docker-compose.yml " +
                   $"--profile slc500 up -d), attach real hardware, or override {EndpointEnvVar}.";
        }

        // TCP reaches — but is the peer a real PLC (wire-trustworthy) or ab_server's PCCC
        // mode (dispatcher is upstream-broken, every read surfaces BadCommunicationError)?
        // We can't detect it at the wire without issuing a full libplctag session, so we
        // require an explicit opt-in for wire-level runs. See
        // `tests/.../Docker/README.md` §"Known limitations" for the upstream-tracking pointer.
        if (Environment.GetEnvironmentVariable(TrustWireEnvVar) is not { Length: > 0 } trust
            || !(trust == "1" || string.Equals(trust, "true", StringComparison.OrdinalIgnoreCase)))
        {
            return $"AB Legacy endpoint at {host}:{port} is reachable but {TrustWireEnvVar} is not set. " +
                   "ab_server's PCCC dispatcher is a known upstream gap (libplctag/libplctag), so by " +
                   "default the integration suite assumes the simulator is in play and skips. Set " +
                   $"{TrustWireEnvVar}=1 when pointing at real SLC 5/05 / MicroLogix 1100/1400 / PLC-5 " +
                   "hardware or a RSEmulate 500 golden-box.";
        }

        return null;
    }

    private static (string Host, int Port) ResolveEndpoint()
    {
        var raw = Environment.GetEnvironmentVariable(EndpointEnvVar);
        if (raw is null) return ("127.0.0.1", DefaultPort);
        var parts = raw.Split(':', 2);
        var port = parts.Length == 2 && int.TryParse(parts[1], out var p) ? p : DefaultPort;
        return (parts[0], port);
    }

    private static bool TcpProbe(string host, int port)
    {
        try
        {
            using var client = new TcpClient();
            var task = client.ConnectAsync(host, port);
            return task.Wait(TimeSpan.FromSeconds(2)) && client.Connected;
        }
        catch { return false; }
    }
}

/// <summary>
///     Per-family marker for the PCCC-mode compose profile a given test targets. The
///     compose file (<c>Docker/docker-compose.yml</c>) is the canonical source of truth
///     for which <c>--plc</c> mode + tags each family seeds; this record just ties a
///     family enum to its compose-profile name + operator-facing notes.
/// </summary>
public sealed record AbLegacyServerProfile(
    AbLegacyPlcFamily Family,
    string ComposeProfile,
    string Notes);

/// <summary>Canonical profiles covering every PCCC family the driver supports.</summary>
public static class KnownProfiles
{
    public static readonly AbLegacyServerProfile Slc500 = new(
        Family: AbLegacyPlcFamily.Slc500,
        ComposeProfile: "slc500",
        Notes: "SLC 500 / 5/05 family. ab_server SLC500 mode covers N/F/B/L files.");

    public static readonly AbLegacyServerProfile MicroLogix = new(
        Family: AbLegacyPlcFamily.MicroLogix,
        ComposeProfile: "micrologix",
        Notes: "MicroLogix 1000 / 1100 / 1400. Shares N/F/B file-type coverage with SLC500; ST (ASCII strings) included.");

    public static readonly AbLegacyServerProfile Plc5 = new(
        Family: AbLegacyPlcFamily.Plc5,
        ComposeProfile: "plc5",
        Notes: "PLC-5 family. ab_server PLC/5 mode covers N/F/B; per-family quirks on ST / timer file layouts unit-tested only.");

    public static IReadOnlyList<AbLegacyServerProfile> All { get; } =
        [Slc500, MicroLogix, Plc5];

    public static AbLegacyServerProfile ForFamily(AbLegacyPlcFamily family) =>
        All.FirstOrDefault(p => p.Family == family)
        ?? throw new ArgumentOutOfRangeException(nameof(family), family, "No integration profile for this family.");
}

[Xunit.CollectionDefinition(Name)]
public sealed class AbLegacyServerCollection : Xunit.ICollectionFixture<AbLegacyServerFixture>
{
    public const string Name = "AbLegacyServer";
}

/// <summary>
///     <c>[Fact]</c>-equivalent that skips when the PCCC endpoint isn't wire-trustworthy.
///     See <see cref="AbLegacyServerFixture"/> for the exact skip semantics.
/// </summary>
public sealed class AbLegacyFactAttribute : FactAttribute
{
    public AbLegacyFactAttribute()
    {
        if (!AbLegacyServerFixture.IsServerAvailable())
            Skip = "AB Legacy PCCC endpoint not wire-trustworthy. Either no simulator is " +
                   "running, or the Docker ab_server is up but AB_LEGACY_TRUST_WIRE is not " +
                   "set (ab_server's PCCC dispatcher is a known upstream gap). Set " +
                   "AB_LEGACY_TRUST_WIRE=1 when pointing AB_LEGACY_ENDPOINT at real hardware " +
                   "or a RSEmulate 500 golden-box.";
    }
}

/// <summary>
///     <c>[Theory]</c>-equivalent with the same gate as <see cref="AbLegacyFactAttribute"/>.
/// </summary>
public sealed class AbLegacyTheoryAttribute : TheoryAttribute
{
    public AbLegacyTheoryAttribute()
    {
        if (!AbLegacyServerFixture.IsServerAvailable())
            Skip = "AB Legacy PCCC endpoint not wire-trustworthy. Either no simulator is " +
                   "running, or the Docker ab_server is up but AB_LEGACY_TRUST_WIRE is not " +
                   "set (ab_server's PCCC dispatcher is a known upstream gap). Set " +
                   "AB_LEGACY_TRUST_WIRE=1 when pointing AB_LEGACY_ENDPOINT at real hardware " +
                   "or a RSEmulate 500 golden-box.";
    }
}