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

namespace ZB.MOM.WW.ScadaBridge.InboundAPI;

/// <summary>
/// Seam over the cross-site routing transport used by <see cref="RouteHelper"/>.
/// The production implementation (<see cref="CommunicationServiceInstanceRouter"/>)
/// delegates to <c>ZB.MOM.WW.ScadaBridge.Communication.CommunicationService</c>; the interface
/// exists so <see cref="RouteHelper"/>/<see cref="RouteTarget"/> can be unit tested
/// without a live actor system.
/// </summary>
public interface IInstanceRouter
{
    /// <summary>Routes a script call request to the specified site.</summary>
    /// <param name="siteId">Target site identifier.</param>
    /// <param name="request">The call request to route.</param>
    /// <param name="cancellationToken">Cancellation token for the routed call.</param>
    /// <returns>A task that resolves to the call response from the target site.</returns>
    Task<RouteToCallResponse> RouteToCallAsync(
        string siteId, RouteToCallRequest request, CancellationToken cancellationToken);

    /// <summary>Routes a batch attribute read request to the specified site.</summary>
    /// <param name="siteId">Target site identifier.</param>
    /// <param name="request">The get-attributes request to route.</param>
    /// <param name="cancellationToken">Cancellation token for the routed call.</param>
    /// <returns>A task that resolves to the get-attributes response from the target site.</returns>
    Task<RouteToGetAttributesResponse> RouteToGetAttributesAsync(
        string siteId, RouteToGetAttributesRequest request, CancellationToken cancellationToken);

    /// <summary>Routes a batch attribute write request to the specified site.</summary>
    /// <param name="siteId">Target site identifier.</param>
    /// <param name="request">The set-attributes request to route.</param>
    /// <param name="cancellationToken">Cancellation token for the routed call.</param>
    /// <returns>A task that resolves to the set-attributes response from the target site.</returns>
    Task<RouteToSetAttributesResponse> RouteToSetAttributesAsync(
        string siteId, RouteToSetAttributesRequest request, CancellationToken cancellationToken);

    /// <summary>Routes a wait-for-attribute request to the specified site (spec §6).</summary>
    /// <param name="siteId">Target site identifier.</param>
    /// <param name="request">The wait-for-attribute request to route (value-equality only).</param>
    /// <param name="cancellationToken">Cancellation token for the routed call.</param>
    /// <returns>A task that resolves to the wait-for-attribute response from the target site.</returns>
    Task<RouteToWaitForAttributeResponse> RouteToWaitForAttributeAsync(
        string siteId, RouteToWaitForAttributeRequest request, CancellationToken cancellationToken);
}
