mxaccessgw/src/MxGateway.Worker/MxAccess/MxAccessSession.cs

using System;
using System.Collections.Generic;
using System.Runtime.InteropServices;
using Google.Protobuf.WellKnownTypes;
using MxGateway.Contracts.Proto;

namespace MxGateway.Worker.MxAccess;

public sealed class MxAccessSession : IDisposable
{
    private readonly object mxAccessComObject;
    private readonly IMxAccessServer mxAccessServer;
    private readonly IMxAccessEventSink eventSink;
    private readonly MxAccessHandleRegistry handleRegistry;
    private bool disposed;

    private MxAccessSession(
        object mxAccessComObject,
        IMxAccessServer mxAccessServer,
        IMxAccessEventSink eventSink,
        MxAccessHandleRegistry handleRegistry,
        int creationThreadId)
    {
        this.mxAccessComObject = mxAccessComObject ?? throw new ArgumentNullException(nameof(mxAccessComObject));
        this.mxAccessServer = mxAccessServer ?? throw new ArgumentNullException(nameof(mxAccessServer));
        this.eventSink = eventSink ?? throw new ArgumentNullException(nameof(eventSink));
        this.handleRegistry = handleRegistry ?? throw new ArgumentNullException(nameof(handleRegistry));
        CreationThreadId = creationThreadId;
    }

    /// <summary>The thread ID where this session was created.</summary>
    public int CreationThreadId { get; }

    /// <summary>The registry for tracking opened handles.</summary>
    public MxAccessHandleRegistry HandleRegistry => handleRegistry;

    /// <summary>Creates a WorkerReady message with session metadata.</summary>
    /// <param name="workerProcessId">Process ID of the worker.</param>
    public WorkerReady CreateWorkerReady(int workerProcessId)
    {
        return new WorkerReady
        {
            WorkerProcessId = workerProcessId,
            MxaccessProgid = MxAccessInteropInfo.ProgId,
            MxaccessClsid = MxAccessInteropInfo.Clsid,
            ReadyTimestamp = Timestamp.FromDateTime(DateTime.UtcNow),
        };
    }

    /// <summary>Creates and initializes an MXAccess COM session.</summary>
    /// <param name="factory">Factory to create the MXAccess COM object.</param>
    /// <param name="eventSink">Event sink to attach to the COM object.</param>
    /// <param name="sessionId">Identifier of the session.</param>
    public static MxAccessSession Create(
        IMxAccessComObjectFactory factory,
        IMxAccessEventSink eventSink,
        string sessionId)
    {
        if (factory is null)
        {
            throw new ArgumentNullException(nameof(factory));
        }

        if (eventSink is null)
        {
            throw new ArgumentNullException(nameof(eventSink));
        }

        object? mxAccessComObject = null;

        try
        {
            mxAccessComObject = factory.Create();
            if (mxAccessComObject is null)
            {
                throw new InvalidOperationException("MXAccess COM factory returned null.");
            }

            eventSink.Attach(mxAccessComObject, sessionId);

            return new MxAccessSession(
                mxAccessComObject,
                new MxAccessComServer(mxAccessComObject),
                eventSink,
                new MxAccessHandleRegistry(),
                Environment.CurrentManagedThreadId);
        }
        catch (Exception exception)
        {
            try
            {
                eventSink.Detach();
            }
            catch
            {
                // Preserve the creation failure while still releasing the COM object below.
            }

            if (mxAccessComObject is not null && Marshal.IsComObject(mxAccessComObject))
            {
                Marshal.FinalReleaseComObject(mxAccessComObject);
            }

            throw MxAccessCreationException.From(exception);
        }
    }

    /// <summary>Registers a client with MXAccess and returns the server handle.</summary>
    /// <param name="clientName">Name of the client to register.</param>
    public int Register(string clientName)
    {
        ThrowIfDisposed();

        int serverHandle = mxAccessServer.Register(clientName);
        handleRegistry.RegisterServerHandle(serverHandle, clientName);

        return serverHandle;
    }

    /// <summary>Unregisters a client from MXAccess.</summary>
    /// <param name="serverHandle">Handle returned by the worker.</param>
    public void Unregister(int serverHandle)
    {
        ThrowIfDisposed();

        mxAccessServer.Unregister(serverHandle);
        handleRegistry.UnregisterServerHandle(serverHandle);
    }

    /// <summary>Adds an item to an MXAccess server and returns the item handle.</summary>
    /// <param name="serverHandle">Handle returned by the worker.</param>
    /// <param name="itemDefinition">Definition or address of the item to add.</param>
    public int AddItem(
        int serverHandle,
        string itemDefinition)
    {
        ThrowIfDisposed();

        int itemHandle = mxAccessServer.AddItem(serverHandle, itemDefinition);
        handleRegistry.RegisterItemHandle(
            serverHandle,
            itemHandle,
            itemDefinition,
            string.Empty,
            hasItemContext: false);

        return itemHandle;
    }

    /// <summary>Adds an item with context to an MXAccess server and returns the item handle.</summary>
    /// <param name="serverHandle">Handle returned by the worker.</param>
    /// <param name="itemDefinition">Definition or address of the item to add.</param>
    /// <param name="itemContext">Context string for the item.</param>
    public int AddItem2(
        int serverHandle,
        string itemDefinition,
        string itemContext)
    {
        ThrowIfDisposed();

        int itemHandle = mxAccessServer.AddItem2(serverHandle, itemDefinition, itemContext);
        handleRegistry.RegisterItemHandle(
            serverHandle,
            itemHandle,
            itemDefinition,
            itemContext,
            hasItemContext: true);

        return itemHandle;
    }

    /// <summary>Removes an item from an MXAccess server.</summary>
    /// <param name="serverHandle">Handle returned by the worker.</param>
    /// <param name="itemHandle">Handle returned by the worker.</param>
    public void RemoveItem(
        int serverHandle,
        int itemHandle)
    {
        ThrowIfDisposed();

        mxAccessServer.RemoveItem(serverHandle, itemHandle);
        handleRegistry.RemoveItemHandle(serverHandle, itemHandle);
    }

    /// <summary>Advises on item changes with plain subscription.</summary>
    /// <param name="serverHandle">Handle returned by the worker.</param>
    /// <param name="itemHandle">Handle returned by the worker.</param>
    public void Advise(
        int serverHandle,
        int itemHandle)
    {
        ThrowIfDisposed();

        mxAccessServer.Advise(serverHandle, itemHandle);
        handleRegistry.RegisterAdviceHandle(
            serverHandle,
            itemHandle,
            MxAccessAdviceKind.Plain);
    }

    /// <summary>Removes plain advice subscription from an item.</summary>
    /// <param name="serverHandle">Handle returned by the worker.</param>
    /// <param name="itemHandle">Handle returned by the worker.</param>
    public void UnAdvise(
        int serverHandle,
        int itemHandle)
    {
        ThrowIfDisposed();

        mxAccessServer.UnAdvise(serverHandle, itemHandle);
        handleRegistry.RemoveAdviceHandles(serverHandle, itemHandle);
    }

    /// <summary>Advises on item changes with supervisory subscription.</summary>
    /// <param name="serverHandle">Handle returned by the worker.</param>
    /// <param name="itemHandle">Handle returned by the worker.</param>
    public void AdviseSupervisory(
        int serverHandle,
        int itemHandle)
    {
        ThrowIfDisposed();

        mxAccessServer.AdviseSupervisory(serverHandle, itemHandle);
        handleRegistry.RegisterAdviceHandle(
            serverHandle,
            itemHandle,
            MxAccessAdviceKind.Supervisory);
    }

    /// <summary>Writes a value to an item.</summary>
    /// <param name="serverHandle">Handle returned by the worker.</param>
    /// <param name="itemHandle">Handle returned by the worker.</param>
    /// <param name="value">COM-marshalable value to write.</param>
    /// <param name="userId">MXAccess user id (security classification) for the write.</param>
    public void Write(
        int serverHandle,
        int itemHandle,
        object? value,
        int userId)
    {
        ThrowIfDisposed();

        mxAccessServer.Write(serverHandle, itemHandle, value, userId);
    }

    /// <summary>Writes a value with an explicit source timestamp to an item.</summary>
    /// <param name="serverHandle">Handle returned by the worker.</param>
    /// <param name="itemHandle">Handle returned by the worker.</param>
    /// <param name="value">COM-marshalable value to write.</param>
    /// <param name="timestamp">COM-marshalable source timestamp for the write.</param>
    /// <param name="userId">MXAccess user id (security classification) for the write.</param>
    public void Write2(
        int serverHandle,
        int itemHandle,
        object? value,
        object? timestamp,
        int userId)
    {
        ThrowIfDisposed();

        mxAccessServer.Write2(serverHandle, itemHandle, value, timestamp, userId);
    }

    /// <summary>Performs a secured/verified write to an item.</summary>
    /// <param name="serverHandle">Handle returned by the worker.</param>
    /// <param name="itemHandle">Handle returned by the worker.</param>
    /// <param name="currentUserId">MXAccess user id of the operator performing the write.</param>
    /// <param name="verifierUserId">MXAccess user id of the verifier authorizing the write.</param>
    /// <param name="value">COM-marshalable value to write.</param>
    public void WriteSecured(
        int serverHandle,
        int itemHandle,
        int currentUserId,
        int verifierUserId,
        object? value)
    {
        ThrowIfDisposed();

        mxAccessServer.WriteSecured(serverHandle, itemHandle, currentUserId, verifierUserId, value);
    }

    /// <summary>Performs a secured/verified write with an explicit source timestamp.</summary>
    /// <param name="serverHandle">Handle returned by the worker.</param>
    /// <param name="itemHandle">Handle returned by the worker.</param>
    /// <param name="currentUserId">MXAccess user id of the operator performing the write.</param>
    /// <param name="verifierUserId">MXAccess user id of the verifier authorizing the write.</param>
    /// <param name="value">COM-marshalable value to write.</param>
    /// <param name="timestamp">COM-marshalable source timestamp for the write.</param>
    public void WriteSecured2(
        int serverHandle,
        int itemHandle,
        int currentUserId,
        int verifierUserId,
        object? value,
        object? timestamp)
    {
        ThrowIfDisposed();

        mxAccessServer.WriteSecured2(serverHandle, itemHandle, currentUserId, verifierUserId, value, timestamp);
    }

    /// <summary>Adds multiple items in bulk, returning success/failure results.</summary>
    /// <param name="serverHandle">Handle returned by the worker.</param>
    /// <param name="tagAddresses">Enumerable of item definitions to add.</param>
    public IReadOnlyList<SubscribeResult> AddItemBulk(
        int serverHandle,
        IEnumerable<string> tagAddresses)
    {
        ThrowIfDisposed();
        if (tagAddresses is null)
        {
            throw new ArgumentNullException(nameof(tagAddresses));
        }

        List<SubscribeResult> results = new();
        foreach (string? tagAddress in tagAddresses)
        {
            if (string.IsNullOrWhiteSpace(tagAddress))
            {
                results.Add(Failed(serverHandle, tagAddress ?? string.Empty, itemHandle: 0, "Tag address is required."));
                continue;
            }

            try
            {
                int itemHandle = AddItem(serverHandle, tagAddress);
                results.Add(Succeeded(serverHandle, tagAddress, itemHandle));
            }
            catch (Exception exception)
            {
                results.Add(Failed(serverHandle, tagAddress, itemHandle: 0, exception.Message));
            }
        }

        return results;
    }

    /// <summary>Advises on multiple items in bulk, returning success/failure results.</summary>
    /// <param name="serverHandle">Handle returned by the worker.</param>
    /// <param name="itemHandles">Enumerable of item handles to advise on.</param>
    public IReadOnlyList<SubscribeResult> AdviseItemBulk(
        int serverHandle,
        IEnumerable<int> itemHandles)
    {
        ThrowIfDisposed();
        if (itemHandles is null)
        {
            throw new ArgumentNullException(nameof(itemHandles));
        }

        List<SubscribeResult> results = new();
        foreach (int itemHandle in itemHandles)
        {
            try
            {
                Advise(serverHandle, itemHandle);
                results.Add(Succeeded(serverHandle, string.Empty, itemHandle));
            }
            catch (Exception exception)
            {
                results.Add(Failed(serverHandle, string.Empty, itemHandle, exception.Message));
            }
        }

        return results;
    }

    /// <summary>Removes multiple items in bulk, returning success/failure results.</summary>
    /// <param name="serverHandle">Handle returned by the worker.</param>
    /// <param name="itemHandles">Enumerable of item handles to remove.</param>
    public IReadOnlyList<SubscribeResult> RemoveItemBulk(
        int serverHandle,
        IEnumerable<int> itemHandles)
    {
        ThrowIfDisposed();
        if (itemHandles is null)
        {
            throw new ArgumentNullException(nameof(itemHandles));
        }

        List<SubscribeResult> results = new();
        foreach (int itemHandle in itemHandles)
        {
            try
            {
                RemoveItem(serverHandle, itemHandle);
                results.Add(Succeeded(serverHandle, string.Empty, itemHandle));
            }
            catch (Exception exception)
            {
                results.Add(Failed(serverHandle, string.Empty, itemHandle, exception.Message));
            }
        }

        return results;
    }

    /// <summary>Removes advice subscriptions from multiple items in bulk, returning success/failure results.</summary>
    /// <param name="serverHandle">Handle returned by the worker.</param>
    /// <param name="itemHandles">Enumerable of item handles to unadvise.</param>
    public IReadOnlyList<SubscribeResult> UnAdviseItemBulk(
        int serverHandle,
        IEnumerable<int> itemHandles)
    {
        ThrowIfDisposed();
        if (itemHandles is null)
        {
            throw new ArgumentNullException(nameof(itemHandles));
        }

        List<SubscribeResult> results = new();
        foreach (int itemHandle in itemHandles)
        {
            try
            {
                UnAdvise(serverHandle, itemHandle);
                results.Add(Succeeded(serverHandle, string.Empty, itemHandle));
            }
            catch (Exception exception)
            {
                results.Add(Failed(serverHandle, string.Empty, itemHandle, exception.Message));
            }
        }

        return results;
    }

    /// <summary>Adds multiple items and subscribes to them in bulk, returning success/failure results.</summary>
    /// <param name="serverHandle">Handle returned by the worker.</param>
    /// <param name="tagAddresses">Enumerable of item definitions to add and subscribe to.</param>
    public IReadOnlyList<SubscribeResult> SubscribeBulk(
        int serverHandle,
        IEnumerable<string> tagAddresses)
    {
        ThrowIfDisposed();
        if (tagAddresses is null)
        {
            throw new ArgumentNullException(nameof(tagAddresses));
        }

        List<SubscribeResult> results = new();
        foreach (string? tagAddress in tagAddresses)
        {
            if (string.IsNullOrWhiteSpace(tagAddress))
            {
                results.Add(Failed(serverHandle, tagAddress ?? string.Empty, itemHandle: 0, "Tag address is required."));
                continue;
            }

            int itemHandle = 0;
            try
            {
                itemHandle = AddItem(serverHandle, tagAddress);
                Advise(serverHandle, itemHandle);
                results.Add(Succeeded(serverHandle, tagAddress, itemHandle));
            }
            catch (Exception exception)
            {
                string errorMessage = exception.Message;
                if (itemHandle != 0)
                {
                    errorMessage = AppendRemoveItemCleanup(serverHandle, itemHandle, errorMessage);
                }

                results.Add(Failed(serverHandle, tagAddress, itemHandle, errorMessage));
            }
        }

        return results;
    }

    /// <summary>Unsubscribes from multiple items in bulk, returning success/failure results.</summary>
    /// <param name="serverHandle">Handle returned by the worker.</param>
    /// <param name="itemHandles">Enumerable of item handles to unsubscribe from.</param>
    public IReadOnlyList<SubscribeResult> UnsubscribeBulk(
        int serverHandle,
        IEnumerable<int> itemHandles)
    {
        ThrowIfDisposed();
        if (itemHandles is null)
        {
            throw new ArgumentNullException(nameof(itemHandles));
        }

        List<SubscribeResult> results = new();
        foreach (int itemHandle in itemHandles)
        {
            List<string> errors = new();

            try
            {
                UnAdvise(serverHandle, itemHandle);
            }
            catch (Exception exception)
            {
                errors.Add($"UnAdvise failed: {exception.Message}");
            }

            try
            {
                RemoveItem(serverHandle, itemHandle);
            }
            catch (Exception exception)
            {
                errors.Add($"RemoveItem failed: {exception.Message}");
            }

            results.Add(errors.Count == 0
                ? Succeeded(serverHandle, string.Empty, itemHandle)
                : Failed(serverHandle, string.Empty, itemHandle, string.Join("; ", errors)));
        }

        return results;
    }

    /// <summary>Gracefully shuts down the session, cleaning up all handles.</summary>
    public MxAccessShutdownResult ShutdownGracefully()
    {
        if (disposed)
        {
            return new MxAccessShutdownResult(Array.Empty<MxAccessShutdownFailure>());
        }

        List<MxAccessShutdownFailure> failures = new();

        CleanupAdviceHandles(failures);
        CleanupItemHandles(failures);
        CleanupServerHandles(failures);
        DisposeCore(failures);

        return new MxAccessShutdownResult(failures);
    }

    /// <summary>Releases the MXAccess COM object and resources.</summary>
    public void Dispose()
    {
        if (disposed)
        {
            return;
        }

        DisposeCore(failures: null);
    }

    private void CleanupAdviceHandles(ICollection<MxAccessShutdownFailure> failures)
    {
        HashSet<long> cleanedPairs = new();
        foreach (RegisteredAdviceHandle adviceHandle in handleRegistry.AdviceHandles)
        {
            long key = CreateItemKey(adviceHandle.ServerHandle, adviceHandle.ItemHandle);
            if (!cleanedPairs.Add(key))
            {
                continue;
            }

            try
            {
                mxAccessServer.UnAdvise(adviceHandle.ServerHandle, adviceHandle.ItemHandle);
                handleRegistry.RemoveAdviceHandles(adviceHandle.ServerHandle, adviceHandle.ItemHandle);
            }
            catch (Exception exception)
            {
                failures.Add(new MxAccessShutdownFailure(
                    nameof(UnAdvise),
                    adviceHandle.ServerHandle,
                    adviceHandle.ItemHandle,
                    exception));
            }
        }
    }

    private void CleanupItemHandles(ICollection<MxAccessShutdownFailure> failures)
    {
        foreach (RegisteredItemHandle itemHandle in handleRegistry.ItemHandles)
        {
            try
            {
                mxAccessServer.RemoveItem(itemHandle.ServerHandle, itemHandle.ItemHandle);
                handleRegistry.RemoveItemHandle(itemHandle.ServerHandle, itemHandle.ItemHandle);
            }
            catch (Exception exception)
            {
                failures.Add(new MxAccessShutdownFailure(
                    nameof(RemoveItem),
                    itemHandle.ServerHandle,
                    itemHandle.ItemHandle,
                    exception));
            }
        }
    }

    private void CleanupServerHandles(ICollection<MxAccessShutdownFailure> failures)
    {
        foreach (RegisteredServerHandle serverHandle in handleRegistry.ServerHandles)
        {
            try
            {
                mxAccessServer.Unregister(serverHandle.ServerHandle);
                handleRegistry.UnregisterServerHandle(serverHandle.ServerHandle);
            }
            catch (Exception exception)
            {
                failures.Add(new MxAccessShutdownFailure(
                    nameof(Unregister),
                    serverHandle.ServerHandle,
                    itemHandle: null,
                    exception));
            }
        }
    }

    private static long CreateItemKey(
        int serverHandle,
        int itemHandle)
    {
        return ((long)serverHandle << 32) | (uint)itemHandle;
    }

    private string AppendRemoveItemCleanup(
        int serverHandle,
        int itemHandle,
        string errorMessage)
    {
        try
        {
            RemoveItem(serverHandle, itemHandle);
            return $"{errorMessage}; cleanup RemoveItem succeeded.";
        }
        catch (Exception cleanupException)
        {
            return $"{errorMessage}; cleanup RemoveItem failed: {cleanupException.Message}";
        }
    }

    private static SubscribeResult Succeeded(
        int serverHandle,
        string tagAddress,
        int itemHandle)
    {
        return new SubscribeResult
        {
            ServerHandle = serverHandle,
            TagAddress = tagAddress,
            ItemHandle = itemHandle,
            WasSuccessful = true,
            ErrorMessage = string.Empty,
        };
    }

    private static SubscribeResult Failed(
        int serverHandle,
        string tagAddress,
        int itemHandle,
        string errorMessage)
    {
        return new SubscribeResult
        {
            ServerHandle = serverHandle,
            TagAddress = tagAddress,
            ItemHandle = itemHandle,
            WasSuccessful = false,
            ErrorMessage = errorMessage,
        };
    }

    private void DisposeCore(ICollection<MxAccessShutdownFailure>? failures)
    {
        Exception? detachException = null;
        try
        {
            eventSink.Detach();
        }
        catch (Exception exception)
        {
            detachException = exception;
            failures?.Add(new MxAccessShutdownFailure(
                "DetachEvents",
                serverHandle: null,
                itemHandle: null,
                exception));
        }

        try
        {
            if (Marshal.IsComObject(mxAccessComObject))
            {
                Marshal.FinalReleaseComObject(mxAccessComObject);
            }
        }
        catch (Exception exception) when (failures is not null)
        {
            failures.Add(new MxAccessShutdownFailure(
                "ReleaseComObject",
                serverHandle: null,
                itemHandle: null,
                exception));
        }

        disposed = true;
        if (detachException is not null && failures is null)
        {
            throw detachException;
        }
    }

    private void ThrowIfDisposed()
    {
        if (disposed)
        {
            throw new ObjectDisposedException(nameof(MxAccessSession));
        }
    }
}