using ZB.MOM.WW.OtOpcUa.Configuration.Enums;

namespace ZB.MOM.WW.OtOpcUa.AdminUI.Acls;

/// <summary>
///     Backs the ACL authoring surface (#520 stage 7): the scope picker's two trees, and the
///     authoring-time checks that stop a grant being saved against a principal or a scope that names
///     nothing.
/// </summary>
/// <remarks>
///     <para>
///         <b>A service rather than logic in the Razor pages, because this repo has no bUnit</b> — anything
///         only a page can reach is untestable, and the whole point of the stage is that authoring stops
///         producing grants that silently authorize nobody. The same rationale
///         <c>IApiKeyAdminService</c> carries.
///     </para>
///     <para>
///         <b>The picker chooses the kind and the id together.</b> Before this, <c>ScopeKind</c> was a
///         dropdown and <c>ScopeId</c> a free-text box, so the two could disagree — a
///         <see cref="NodeAclScopeKind.RawDevice"/> row pointing at a TagId is well-formed, saves, deploys,
///         and resolves to nothing. Selecting a tree node produces both, so that pairing cannot be made by
///         hand. <see cref="CheckScopeAsync"/> is what catches the rows that already exist, or that were
///         typed in before the picker was reached.
///     </para>
/// </remarks>
public interface IAclScopeService
{
    /// <summary>
    ///     Loads the raw and UNS scope trees for one cluster. Both are rooted at that cluster, so a scope in
    ///     another cluster is unreachable through the picker rather than merely discouraged — the structural
    ///     equivalent of the deploy gate's <c>NodeAclScopeCrossCluster</c> rule.
    /// </summary>
    /// <param name="clusterId">The cluster the grant belongs to.</param>
    /// <param name="ct">The cancellation token.</param>
    /// <returns>The two trees; either may be empty when the cluster has nothing of that kind yet.</returns>
    Task<AclScopeRoots> LoadRootsAsync(string clusterId, CancellationToken ct = default);

    /// <summary>
    ///     Loads one lazy level beneath a raw-tree node. UNS nodes are loaded whole by
    ///     <see cref="LoadRootsAsync"/> and never reach here.
    /// </summary>
    /// <param name="parent">The node being expanded.</param>
    /// <param name="ct">The cancellation token.</param>
    /// <returns>The child rows, or empty for a leaf.</returns>
    Task<IReadOnlyList<AclScopeNode>> LoadChildrenAsync(AclScopeNode parent, CancellationToken ct = default);

    /// <summary>
    ///     Resolves an authored scope against the current configuration, mirroring the deploy gate's
    ///     <c>NodeAclScope*</c> rules so the page rejects what the deployment would reject.
    /// </summary>
    /// <param name="clusterId">The cluster the grant belongs to.</param>
    /// <param name="kind">The authored scope kind.</param>
    /// <param name="scopeId">The authored scope id; null or blank for a cluster-wide grant.</param>
    /// <param name="ct">The cancellation token.</param>
    /// <returns>What the scope resolves to, or why it does not.</returns>
    Task<AclScopeCheck> CheckScopeAsync(
        string clusterId, NodeAclScopeKind kind, string? scopeId, CancellationToken ct = default);

    /// <summary>
    ///     Lists the principal names worth suggesting: every principal an API key authenticates as, every
    ///     principal an existing grant already names, and the reserved <c>anonymous</c> principal.
    /// </summary>
    /// <param name="ct">The cancellation token.</param>
    /// <returns>Distinct principal names, ordered.</returns>
    Task<IReadOnlyList<string>> LoadKnownPrincipalsAsync(CancellationToken ct = default);

    /// <summary>Reports how many API keys currently authenticate as a principal.</summary>
    /// <param name="principal">The principal name as authored.</param>
    /// <param name="ct">The cancellation token.</param>
    /// <returns>The usage counts.</returns>
    Task<PrincipalUsage> CheckPrincipalAsync(string principal, CancellationToken ct = default);
}