using Microsoft.AspNetCore.Http;

namespace ZB.MOM.WW.ScadaBridge.InboundAPI;

/// <summary>
/// Standby-node forwarding seam for <c>POST /api/{methodName}</c>. When a request
/// lands on a standby central node, <see cref="InboundApiEndpointFilter"/> hands it
/// here instead of returning HTTP 503, and the implementation relays it verbatim to
/// the active central node over HTTP so callers that address a central node directly
/// (or that hit the load balancer inside its health-probe window after a failover)
/// still get a served response. Method scripts and <c>Route.To()</c> calls still run
/// ONLY on the active node — the standby is a pure relay.
/// </summary>
public interface IStandbyRequestForwarder
{
    /// <summary>
    /// <c>true</c> when at least one peer endpoint is configured
    /// (<see cref="InboundApiOptions.StandbyForwardPeerEndpoints"/>). When <c>false</c>
    /// the filter falls back to the pre-forwarding behaviour: HTTP 503 <c>STANDBY_NODE</c>.
    /// </summary>
    bool IsConfigured { get; }

    /// <summary>
    /// Relays the current request to the first peer that serves it and returns a
    /// result that replays the peer's status, content type and body to the caller.
    /// Never throws for peer failures: when no peer served the request the result is
    /// HTTP 503 <c>ACTIVE_NODE_UNREACHABLE</c>.
    /// </summary>
    /// <param name="context">The inbound HTTP context on the standby node.</param>
    /// <param name="cancellationToken">Cancelled when the caller aborts the request.</param>
    /// <returns>A result replaying the peer's response, or a 503 when no peer served it.</returns>
    Task<IResult> ForwardAsync(HttpContext context, CancellationToken cancellationToken);
}