using ZB.MOM.WW.MxGateway.Server.Security.Authentication;
using ZB.MOM.WW.MxGateway.Server.Sessions;

namespace ZB.MOM.WW.MxGateway.Server.Security.Authorization;

public interface IConstraintEnforcer
{
    /// <summary>
    ///     Gets a value indicating whether any read constraint applies to an identity at all, so a
    ///     bulk caller can hoist the question out of its per-item loop.
    /// </summary>
    /// <param name="identity">The API key identity.</param>
    /// <returns><see langword="true"/> when at least one read constraint applies; otherwise <see langword="false"/>.</returns>
    /// <remarks>
    ///     Every per-item <see cref="CheckReadTagAsync"/> / <see cref="CheckReadHandleAsync"/> call for
    ///     an unconstrained identity allows the item, so skipping the loop removes work without
    ///     changing a decision. The default implementation answers <see langword="true"/> — an
    ///     implementation that does not model constraints (test doubles, allow-all enforcers) keeps
    ///     being consulted per item rather than being silently bypassed.
    /// </remarks>
    bool HasReadConstraints(ApiKeyIdentity? identity) => true;

    /// <summary>
    ///     Gets a value indicating whether any write constraint applies to an identity at all, the
    ///     write-side counterpart of <see cref="HasReadConstraints"/>.
    /// </summary>
    /// <param name="identity">The API key identity.</param>
    /// <returns><see langword="true"/> when at least one write constraint applies; otherwise <see langword="false"/>.</returns>
    /// <remarks>The same conservative default as <see cref="HasReadConstraints"/> applies.</remarks>
    bool HasWriteConstraints(ApiKeyIdentity? identity) => true;

    /// <summary>Checks whether a read constraint is satisfied for a tag address.</summary>
    /// <param name="identity">The API key identity.</param>
    /// <param name="tagAddress">Tag address to check.</param>
    /// <param name="cancellationToken">Token to observe for cancellation.</param>
    /// <returns>The constraint failure details if denied; otherwise null.</returns>
    Task<ConstraintFailure?> CheckReadTagAsync(
        ApiKeyIdentity? identity,
        string tagAddress,
        CancellationToken cancellationToken);

    /// <summary>Checks whether a read constraint is satisfied for an item handle.</summary>
    /// <param name="identity">The API key identity.</param>
    /// <param name="session">The gateway session.</param>
    /// <param name="serverHandle">The MXAccess server handle.</param>
    /// <param name="itemHandle">The MXAccess item handle.</param>
    /// <param name="cancellationToken">Token to observe for cancellation.</param>
    /// <returns>The constraint failure details if denied; otherwise null.</returns>
    Task<ConstraintFailure?> CheckReadHandleAsync(
        ApiKeyIdentity? identity,
        GatewaySession session,
        int serverHandle,
        int itemHandle,
        CancellationToken cancellationToken);

    /// <summary>Checks whether a write constraint is satisfied for an item handle.</summary>
    /// <param name="identity">The API key identity.</param>
    /// <param name="session">The gateway session.</param>
    /// <param name="serverHandle">The MXAccess server handle.</param>
    /// <param name="itemHandle">The MXAccess item handle.</param>
    /// <param name="cancellationToken">Token to observe for cancellation.</param>
    /// <returns>The constraint failure details if denied; otherwise null.</returns>
    Task<ConstraintFailure?> CheckWriteHandleAsync(
        ApiKeyIdentity? identity,
        GatewaySession session,
        int serverHandle,
        int itemHandle,
        CancellationToken cancellationToken);

    /// <summary>Records a constraint denial for audit and metrics.</summary>
    /// <param name="identity">The API key identity.</param>
    /// <param name="commandKind">The kind of command denied.</param>
    /// <param name="target">The target of the denied command.</param>
    /// <param name="failure">The constraint failure details.</param>
    /// <param name="correlationId">
    ///     The per-request client correlation id, if any. Stored on the audit record's
    ///     <c>CorrelationId</c> when it parses as a GUID; otherwise left null.
    /// </param>
    /// <param name="cancellationToken">Token to observe for cancellation.</param>
    /// <returns>A task that represents the asynchronous operation.</returns>
    Task RecordDenialAsync(
        ApiKeyIdentity? identity,
        string commandKind,
        string target,
        ConstraintFailure failure,
        string? correlationId,
        CancellationToken cancellationToken);
}