using ZB.MOM.WW.ScadaBridge.Commons.Messages.Management;

namespace ZB.MOM.WW.ScadaBridge.CentralUI.Services;

/// <summary>
/// CentralUI facade over the central-to-site OPC UA browse command. Backs the
/// OPC UA Tag Browser dialog: each tree expansion / manual node-id paste calls
/// <see cref="BrowseChildrenAsync"/>, which forwards a
/// <see cref="BrowseNodeCommand"/> to the owning site via
/// <see cref="ZB.MOM.WW.ScadaBridge.Communication.CommunicationService"/>.
/// </summary>
/// <remarks>
/// The service is the trust boundary for the browse capability: it enforces the
/// <c>Design</c> role at central before any cross-cluster traffic is generated,
/// because site-side actors do not unwrap the central trust envelope. Transport
/// failures (timeouts, unreachable sites) are translated into a typed
/// <see cref="BrowseFailure"/> so the dialog can render an inline error and
/// remain usable (manual node-id paste still works).
/// </remarks>
public interface IBrowseService
{
    /// <summary>
    /// Enumerates the immediate children of an OPC UA node on the live server
    /// backing <paramref name="connectionName"/> at <paramref name="siteId"/>.
    /// Pass <c>null</c> for <paramref name="parentNodeId"/> to browse from the
    /// server root (ObjectsFolder).
    /// </summary>
    /// <param name="siteId">The target site identifier.</param>
    /// <param name="connectionName">Name of the site-local data connection to browse against — the site's <c>DataConnectionManagerActor</c> indexes its children by name.</param>
    /// <param name="parentNodeId">Node to browse, or <c>null</c> to browse from the server root.</param>
    /// <param name="continuationToken">Opaque cursor from a prior <see cref="BrowseNodeResult.ContinuationToken"/> to fetch the NEXT page under <paramref name="parentNodeId"/>; <c>null</c> for the first page.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A task that resolves to a <see cref="BrowseNodeResult"/> containing child nodes or a <see cref="BrowseFailure"/> on error.</returns>
    Task<BrowseNodeResult> BrowseChildrenAsync(
        string siteId,
        string connectionName,
        string? parentNodeId,
        string? continuationToken = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Runs a bounded recursive search of the address space on the live server
    /// backing <paramref name="connectionName"/> at <paramref name="siteId"/>,
    /// returning the nodes whose DisplayName or root-relative path contains
    /// <paramref name="query"/>. The address-space analogue of
    /// <see cref="BrowseChildrenAsync"/>: it forwards a
    /// <see cref="SearchAddressSpaceCommand"/> to the owning site via
    /// <see cref="ZB.MOM.WW.ScadaBridge.Communication.CommunicationService"/> and
    /// enforces the same <c>Design</c>-role trust boundary at central. The depth
    /// and result caps are supplied by the caller (the picker's search box) and
    /// chosen to stay well under Akka's remote frame size.
    /// </summary>
    /// <param name="siteId">The target site identifier.</param>
    /// <param name="connectionName">Name of the site-local data connection to search against.</param>
    /// <param name="query">Case-insensitive substring matched against each node's DisplayName and root-relative path.</param>
    /// <param name="maxDepth">Maximum number of levels below the root to descend.</param>
    /// <param name="maxResults">Maximum number of matches to return; when reached the walk stops early and the result's <c>CapReached</c> flag is set.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A task that resolves to a <see cref="SearchAddressSpaceResult"/> containing the matches or a <see cref="BrowseFailure"/> on error.</returns>
    Task<SearchAddressSpaceResult> SearchAsync(
        string siteId,
        string connectionName,
        string query,
        int maxDepth,
        int maxResults,
        CancellationToken cancellationToken = default);
}