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

/// <summary>
///     Required capability for every driver instance. Owns lifecycle, metadata, health.
///     Other capabilities (<see cref="ITagDiscovery"/>, <see cref="IReadable"/>,
///     <see cref="IWritable"/>, <see cref="ISubscribable"/>, <see cref="IAlarmSource"/>,
///     <see cref="IHistoryProvider"/>, <see cref="IRediscoverable"/>,
///     <see cref="IHostConnectivityProbe"/>) are composable — a driver implements only what its
///     backend actually supports.
/// </summary>
public interface IDriver
{
    /// <summary>Stable logical ID of this driver instance, sourced from the central config DB.</summary>
    string DriverInstanceId { get; }

    /// <summary>Driver type name (e.g. "Galaxy", "Modbus", "AbCip"). Matches <c>DriverInstance.DriverType</c>.</summary>
    string DriverType { get; }

    /// <summary>Initialize the driver from its <c>DriverConfig</c> JSON; open connections; prepare for first use.</summary>
    /// <param name="driverConfigJson">The driver configuration as JSON.</param>
    /// <param name="cancellationToken">Cancellation token for the operation.</param>
    /// <returns>A task that represents the asynchronous operation.</returns>
    Task InitializeAsync(string driverConfigJson, CancellationToken cancellationToken);

    /// <summary>
    ///     Apply a config change in place without tearing down the driver process.
    ///     Invoked by the v2 <c>DriverInstanceActor</c> when ApplyDelta reports that only this
    ///     driver's config changed in the new deployment.
    /// </summary>
    /// <remarks>
    ///     Per <c>docs/v2/driver-stability.md</c> §"In-process only (Tier A/B)" — Reinitialize is the
    ///     only Core-initiated recovery path for in-process drivers; if it fails, the driver instance
    ///     is marked Faulted and its nodes go Bad quality, but the server process keeps running.
    /// </remarks>
    /// <param name="driverConfigJson">The driver configuration as JSON.</param>
    /// <param name="cancellationToken">Cancellation token for the operation.</param>
    /// <returns>A task that represents the asynchronous operation.</returns>
    Task ReinitializeAsync(string driverConfigJson, CancellationToken cancellationToken);

    /// <summary>Stop the driver, close connections, release resources. Called on shutdown or driver removal.</summary>
    /// <remarks>
    ///     <para><b>Land the terminal health value AFTER the teardown, never only before it</b> (Gitea #517).
    ///     Teardown drains in-flight poll / probe loops, and those loops write health as they unwind — so a
    ///     driver that wrote <see cref="DriverState.Unknown"/> first and then tore down could have a late
    ///     loop overwrite it with <see cref="DriverState.Healthy"/> and leave THAT as the resting state,
    ///     with every connection already closed. This is why the fleet writes last, and it is the reason
    ///     #517's original suggestion — "write the transitional value before disposing" — is only safe as an
    ///     ADDITIONAL write, bracketing the teardown, rather than as a move.</para>
    ///     <para>Bracketing matters wherever a <see cref="GetHealth"/> can land mid-teardown. It cannot on
    ///     this path today: <c>DriverInstanceActor</c> calls this from <c>PostStop</c>, on the actor thread,
    ///     after the mailbox has drained, so its health poll is serialised against it. It CAN on the
    ///     initialize path, which the same actor runs on a fire-and-forget <c>Task.Run</c> while the health
    ///     tick keeps firing — so a driver whose <see cref="InitializeAsync"/> disposes anything on its
    ///     failure path must write the failed state before disposing as well as after.</para>
    /// </remarks>
    /// <param name="cancellationToken">Cancellation token for the operation.</param>
    /// <returns>A task that represents the asynchronous operation.</returns>
    Task ShutdownAsync(CancellationToken cancellationToken);

    /// <summary>Current health snapshot, polled by Core for the status dashboard and ServiceLevel.
    /// <para>Must reflect the driver's ACTUAL state rather than a constant — a hard-coded
    /// <see cref="DriverState.Healthy"/> reports a healthy driver after shutdown and before initialize
    /// alike, which is what Gitea #517 found in <c>CalculationDriver</c>. A driver with no transport still
    /// has a running / not-running distinction worth reporting.</para></summary>
    /// <returns>The driver's current health snapshot.</returns>
    DriverHealth GetHealth();
}