namespace ZB.MOM.WW.OtOpcUa.Core.Abstractions;

/// <summary>
///     Optional driver capability that maps a per-tag full reference to the underlying host
///     name responsible for serving it. Drivers with a one-host topology (Galaxy on one
///     MXAccess endpoint, OpcUaClient against one remote server, S7 against one PLC) do NOT
///     need to implement this — the dispatch layer falls back to
///     <see cref="IDriver.DriverInstanceId"/> as a single-host key.
/// </summary>
/// <remarks>
///     <para>Multi-host drivers (Modbus with N PLCs, hypothetical AB CIP across a rack, etc.)
///     implement this so the Phase 6.1 resilience pipeline can be keyed on
///     <c>(DriverInstanceId, ResolvedHostName, DriverCapability)</c> per decision #144. One
///     dead PLC behind a multi-device Modbus driver then trips only its own breaker; healthy
///     siblings keep serving.</para>
///
///     <para>Implementations must be fast + allocation-free on the hot path — <c>ReadAsync</c>
///     / <c>WriteAsync</c> call this once per tag. A simple <c>Dictionary&lt;string, string&gt;</c>
///     lookup is typical.</para>
///
///     <para>When the fullRef doesn't map to a known host (caller passes an unregistered
///     reference, or the tag was removed mid-flight), implementations should return the
///     driver's default-host string rather than throwing — the invoker falls back to a
///     single-host pipeline for that call, which is safer than tearing down the request.</para>
/// </remarks>
public interface IPerCallHostResolver
{
    /// <summary>
    ///     Resolve the host name for the given driver-side full reference. Returned value is
    ///     used as the <c>hostName</c> argument to the Phase 6.1 <c>CapabilityInvoker</c> so
    ///     per-host breaker isolation + per-host bulkhead accounting both kick in.
    /// </summary>
    string ResolveHost(string fullReference);
}