using Grpc.Core;
using MxGateway.Contracts.Proto;

namespace MxGateway.Client;

/// <summary>
/// Exception thrown when a gateway RPC call fails or returns an error status.
/// </summary>
public class MxGatewayException : Exception
{
    /// <summary>
    /// Initializes a new instance of the MxGatewayException class with the specified message.
    /// </summary>
    /// <param name="message">Diagnostic message describing the failure.</param>
    public MxGatewayException(string message)
        : base(message)
    {
        Statuses = [];
    }

    /// <summary>
    /// Initializes a new instance of the MxGatewayException class with the specified message and inner exception.
    /// </summary>
    /// <param name="message">Diagnostic message describing the failure.</param>
    /// <param name="innerException">Underlying exception that caused this failure.</param>
    public MxGatewayException(string message, Exception? innerException)
        : base(message, innerException)
    {
        Statuses = [];
    }

    /// <summary>
    /// Initializes a new instance of the MxGatewayException class carrying the originating
    /// gRPC status code so callers can distinguish transient from permanent failures.
    /// </summary>
    /// <param name="message">Diagnostic message describing the failure.</param>
    /// <param name="statusCode">The gRPC status code reported by the failed call.</param>
    /// <param name="innerException">Underlying exception that caused this failure.</param>
    public MxGatewayException(string message, StatusCode statusCode, Exception? innerException)
        : base(message, innerException)
    {
        StatusCode = statusCode;
        Statuses = [];
    }

    /// <summary>
    /// Initializes a new instance of the MxGatewayException class with full diagnostic information.
    /// </summary>
    /// <param name="message">Diagnostic message describing the failure.</param>
    /// <param name="sessionId">Session ID associated with the exception, if available.</param>
    /// <param name="correlationId">Correlation ID associated with the exception, if available.</param>
    /// <param name="protocolStatus">Protocol-level status returned by the gateway, if available.</param>
    /// <param name="hResult">HRESULT code returned by the worker or MXAccess, if available.</param>
    /// <param name="statuses">List of MXAccess status codes returned by the operation.</param>
    /// <param name="innerException">Underlying exception that caused this failure.</param>
    /// <param name="statusCode">The gRPC status code reported by the failed call, if available.</param>
    public MxGatewayException(
        string message,
        string? sessionId,
        string? correlationId,
        ProtocolStatus? protocolStatus,
        int? hResult,
        IReadOnlyList<MxStatusProxy> statuses,
        Exception? innerException = null,
        StatusCode? statusCode = null)
        : base(message, innerException)
    {
        SessionId = sessionId;
        CorrelationId = correlationId;
        ProtocolStatus = protocolStatus;
        HResultCode = hResult;
        Statuses = statuses;
        StatusCode = statusCode;
    }

    /// <summary>
    /// Gets the session ID associated with the exception, if available.
    /// </summary>
    public string? SessionId { get; }

    /// <summary>
    /// Gets the correlation ID associated with the exception, if available.
    /// </summary>
    public string? CorrelationId { get; }

    /// <summary>
    /// Gets the protocol-level status returned by the gateway, if available.
    /// </summary>
    public ProtocolStatus? ProtocolStatus { get; }

    /// <summary>
    /// Gets the HRESULT code returned by the worker or MXAccess, if available.
    /// </summary>
    public int? HResultCode { get; }

    /// <summary>
    /// Gets the list of MXAccess status codes returned by the operation.
    /// </summary>
    public IReadOnlyList<MxStatusProxy> Statuses { get; }

    /// <summary>
    /// Gets the gRPC status code reported by the failed call, if the failure originated
    /// from a gRPC <see cref="RpcException"/>. <see langword="null"/> when the exception
    /// was not produced from a gRPC status (for example, a protocol-level reply failure).
    /// Callers can inspect this to distinguish a transient outage
    /// (<see cref="Grpc.Core.StatusCode.Unavailable"/>) from a permanent error
    /// (<see cref="Grpc.Core.StatusCode.InvalidArgument"/>) without downcasting
    /// <see cref="Exception.InnerException"/>.
    /// </summary>
    public StatusCode? StatusCode { get; }
}