lmxopcua/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/SynchronizedFocasClient.cs

namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS;

/// <summary>
///     Decorates an <see cref="IFocasClient"/> so that every wire operation on the device's
///     single FOCAS/2 socket is (1) <b>serialized</b> against all other operations and
///     (2) <b>time-bounded</b>.
/// </summary>
/// <remarks>
///     <para>FOCAS/2 over TCP:8193 is a strict request→response protocol on ONE socket. The
///     driver holds a single <see cref="IFocasClient"/> per device, but several independent loops
///     read from it concurrently — the equipment poll (<see cref="FocasDriver.ReadAsync"/>), the
///     fixed-tree loop (<c>FixedTreeLoopAsync</c>), the connectivity probe, and the recycle loop.
///     Without serialization, two reads interleave their <c>send(request); read(response)</c> on the
///     same socket: one reader consumes the other's response PDU and the victim then blocks forever
///     waiting for bytes that never arrive — leaving the bound OPC UA node stuck at
///     <c>BadWaitingForInitialData</c>. This was the root cause of FOCAS equipment tags never
///     surfacing a value while the probe reported HEALTHY (the probe reads work single-threaded on a
///     dev box, but collide deployed once the fixed-tree loop runs concurrently).</para>
///
///     <para>The gate (<see cref="SemaphoreSlim"/> of count 1) makes each request→response atomic on
///     the socket. The per-call timeout ensures a stalled response can never hold the gate — and thus
///     the socket — indefinitely; a hung read surfaces as a recoverable error at the configured
///     <c>Timeout</c> budget instead of permanent silence. The gate and timeout are paired
///     deliberately: a lock around an <i>unbounded</i> read would deadlock all I/O for the device.</para>
///
///     <para><see cref="ConnectAsync"/> and <see cref="ProbeAsync"/> are serialized but NOT bounded by
///     this decorator's call timeout — they carry their own budgets (the connect timeout argument and
///     the probe's caller-supplied linked token respectively), and double-bounding would shrink them.</para>
/// </remarks>
public sealed class SynchronizedFocasClient : IFocasClient
{
    private readonly IFocasClient _inner;
    private readonly TimeSpan _callTimeout;
    private readonly SemaphoreSlim _gate = new(1, 1);
    /// <summary>Ops holding or queued for <see cref="_gate"/> — what <see cref="DisposeWhenIdleAsync"/> drains.</summary>
    private int _pending;
    private int _disposed;

    /// <summary>Wraps <paramref name="inner"/> with per-device serialization + a per-call timeout.</summary>
    /// <param name="inner">The underlying FOCAS client to serialize access to.</param>
    /// <param name="callTimeout">
    ///     The budget applied to each data read/write. <see cref="TimeSpan.Zero"/> or negative disables
    ///     the per-call timeout (callers' own cancellation tokens still apply).
    /// </param>
    public SynchronizedFocasClient(IFocasClient inner, TimeSpan callTimeout)
    {
        _inner = inner ?? throw new ArgumentNullException(nameof(inner));
        _callTimeout = callTimeout;
    }

    /// <inheritdoc />
    public bool IsConnected => _inner.IsConnected;

    /// <inheritdoc />
    public Task ConnectAsync(FocasHostAddress address, TimeSpan timeout, CancellationToken cancellationToken) =>
        RunGatedAsync(ct => _inner.ConnectAsync(address, timeout, ct), cancellationToken);

    /// <inheritdoc />
    public Task<bool> ProbeAsync(CancellationToken cancellationToken) =>
        RunGatedAsync(ct => _inner.ProbeAsync(ct), cancellationToken);

    /// <inheritdoc />
    public Task<(object? value, uint status)> ReadAsync(
        FocasAddress address, FocasDataType type, CancellationToken cancellationToken) =>
        RunBoundedAsync(ct => _inner.ReadAsync(address, type, ct), cancellationToken);

    /// <inheritdoc />
    public Task<(IReadOnlyList<long>? slots, uint status)> ReadPmcSlotsAsync(
        string letter, FocasDataType slotType, int start, int end, CancellationToken cancellationToken) =>
        RunBoundedAsync(ct => _inner.ReadPmcSlotsAsync(letter, slotType, start, end, ct), cancellationToken);

    /// <inheritdoc />
    public Task<uint> WriteAsync(
        FocasAddress address, FocasDataType type, object? value, CancellationToken cancellationToken) =>
        RunBoundedAsync(ct => _inner.WriteAsync(address, type, value, ct), cancellationToken);

    /// <inheritdoc />
    public Task<IReadOnlyList<FocasActiveAlarm>> ReadAlarmsAsync(CancellationToken cancellationToken) =>
        RunBoundedAsync(ct => _inner.ReadAlarmsAsync(ct), cancellationToken);

    /// <inheritdoc />
    public Task<FocasSysInfo> GetSysInfoAsync(CancellationToken cancellationToken) =>
        RunBoundedAsync(ct => _inner.GetSysInfoAsync(ct), cancellationToken);

    /// <inheritdoc />
    public Task<IReadOnlyList<FocasAxisName>> GetAxisNamesAsync(CancellationToken cancellationToken) =>
        RunBoundedAsync(ct => _inner.GetAxisNamesAsync(ct), cancellationToken);

    /// <inheritdoc />
    public Task<IReadOnlyList<FocasSpindleName>> GetSpindleNamesAsync(CancellationToken cancellationToken) =>
        RunBoundedAsync(ct => _inner.GetSpindleNamesAsync(ct), cancellationToken);

    /// <inheritdoc />
    public Task<FocasDynamicSnapshot> ReadDynamicAsync(int axisIndex, CancellationToken cancellationToken) =>
        RunBoundedAsync(ct => _inner.ReadDynamicAsync(axisIndex, ct), cancellationToken);

    /// <inheritdoc />
    public Task<FocasProgramInfo> GetProgramInfoAsync(CancellationToken cancellationToken) =>
        RunBoundedAsync(ct => _inner.GetProgramInfoAsync(ct), cancellationToken);

    /// <inheritdoc />
    public Task<FocasStatus> GetStatusAsync(CancellationToken cancellationToken) =>
        RunBoundedAsync(ct => _inner.GetStatusAsync(ct), cancellationToken);

    /// <inheritdoc />
    public Task<FocasTimer> GetTimerAsync(FocasTimerKind kind, CancellationToken cancellationToken) =>
        RunBoundedAsync(ct => _inner.GetTimerAsync(kind, ct), cancellationToken);

    /// <inheritdoc />
    public Task<IReadOnlyList<FocasServoLoad>> GetServoLoadsAsync(CancellationToken cancellationToken) =>
        RunBoundedAsync(ct => _inner.GetServoLoadsAsync(ct), cancellationToken);

    /// <inheritdoc />
    public Task<IReadOnlyList<double?>> GetSpindleLoadsAsync(CancellationToken cancellationToken) =>
        RunBoundedAsync(ct => _inner.GetSpindleLoadsAsync(ct), cancellationToken);

    /// <inheritdoc />
    public Task<IReadOnlyList<double?>> GetSpindleMotorSpeedsAsync(CancellationToken cancellationToken) =>
        RunBoundedAsync(ct => _inner.GetSpindleMotorSpeedsAsync(ct), cancellationToken);

    /// <summary>
    ///     Disposes the inner client. Ops still queued on the call gate then fail with
    ///     <see cref="ObjectDisposedException"/> instead of running on a disposed socket. The gate itself is NOT
    ///     disposed: an op that already holds it releases it on the way out, and releasing a disposed
    ///     <see cref="SemaphoreSlim"/> threw out of a read that had otherwise completed.
    /// </summary>
    public void Dispose()
    {
        if (Interlocked.Exchange(ref _disposed, 1) != 0) return;
        _inner.Dispose();
    }

    /// <summary>
    ///     Disposes once every op that already holds (or is queued for) this client has finished, waiting at most
    ///     <paramref name="maxWait"/>. Used by the handle-recycle loop, which detaches the client under the device's
    ///     connect gate first — so nothing new can reach it — and then must not kill a read that is mid-flight on
    ///     it (that read used to surface BadCommunicationError + Degraded on every recycle tick).
    /// </summary>
    /// <param name="maxWait">Upper bound on the wait; the client is disposed regardless once it passes.</param>
    /// <returns>A task that completes when the client is disposed.</returns>
    public async Task DisposeWhenIdleAsync(TimeSpan maxWait)
    {
        var deadline = DateTime.UtcNow + maxWait;
        while (Volatile.Read(ref _pending) > 0 && DateTime.UtcNow < deadline)
            await Task.Delay(5, CancellationToken.None).ConfigureAwait(false);
        Dispose();
    }

    /// <summary>Gets the number of ops currently holding or queued for the call gate. Test seam.</summary>
    internal int PendingOperations => Volatile.Read(ref _pending);

    private void ThrowIfDisposed()
    {
        if (Volatile.Read(ref _disposed) != 0)
            throw new ObjectDisposedException(nameof(SynchronizedFocasClient), "The FOCAS client was recycled or disposed.");
    }

    // Gate only — the caller already governs the budget (connect timeout arg / probe linked token).
    private async Task<T> RunGatedAsync<T>(Func<CancellationToken, Task<T>> op, CancellationToken ct)
    {
        Interlocked.Increment(ref _pending);
        try
        {
            await _gate.WaitAsync(ct).ConfigureAwait(false);
            try { ThrowIfDisposed(); return await op(ct).ConfigureAwait(false); }
            finally { _gate.Release(); }
        }
        finally { Interlocked.Decrement(ref _pending); }
    }

    private async Task RunGatedAsync(Func<CancellationToken, Task> op, CancellationToken ct)
    {
        Interlocked.Increment(ref _pending);
        try
        {
            await _gate.WaitAsync(ct).ConfigureAwait(false);
            try { ThrowIfDisposed(); await op(ct).ConfigureAwait(false); }
            finally { _gate.Release(); }
        }
        finally { Interlocked.Decrement(ref _pending); }
    }

    // Gate + per-call timeout. A fired timeout surfaces as OperationCanceledException whose token is
    // the linked (not the caller's) token — callers distinguish it from real cancellation by testing
    // their own token's IsCancellationRequested.
    private async Task<T> RunBoundedAsync<T>(Func<CancellationToken, Task<T>> op, CancellationToken ct)
    {
        Interlocked.Increment(ref _pending);
        try
        {
            await _gate.WaitAsync(ct).ConfigureAwait(false);
            try
            {
                ThrowIfDisposed();
                if (_callTimeout <= TimeSpan.Zero)
                    return await op(ct).ConfigureAwait(false);

                using var linked = CancellationTokenSource.CreateLinkedTokenSource(ct);
                linked.CancelAfter(_callTimeout);
                return await op(linked.Token).ConfigureAwait(false);
            }
            finally { _gate.Release(); }
        }
        finally { Interlocked.Decrement(ref _pending); }
    }
}