ScadaBridge/src/ZB.MOM.WW.ScadaBridge.HealthMonitoring/ISiteHealthCollector.cs

using ZB.MOM.WW.ScadaBridge.Commons.Messages.Health;
using ZB.MOM.WW.ScadaBridge.Commons.Types;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Enums;

namespace ZB.MOM.WW.ScadaBridge.HealthMonitoring;

/// <summary>
/// Interface for site-side health metric collection.
/// Consumed by Site Runtime actors to report errors, and by DCL to report connection health.
/// </summary>
public interface ISiteHealthCollector
{
    /// <summary>
    /// Increments the script error count.
    /// </summary>
    void IncrementScriptError();

    /// <summary>
    /// Increments the alarm error count.
    /// </summary>
    void IncrementAlarmError();

    /// <summary>
    /// Increments the dead letter count.
    /// </summary>
    void IncrementDeadLetter();

    /// <summary>
    /// Audit Log (#23) Bundle G — increment the per-interval count of
    /// <c>FallbackAuditWriter</c> primary failures. Bridged from the
    /// <c>IAuditWriteFailureCounter</c> binding registered via
    /// <c>AddAuditLogHealthMetricsBridge()</c>.
    /// </summary>
    void IncrementSiteAuditWriteFailures();

    /// <summary>
    /// Audit Log (#23) M5 Bundle C — increment the per-interval count of
    /// payload-filter redactor over-redactions (header / body / SQL
    /// parameter stage throws routed to the
    /// <c>&lt;redacted: redactor error&gt;</c> marker). Bridged from the
    /// <c>IAuditRedactionFailureCounter</c> binding registered via
    /// <c>AddAuditLogHealthMetricsBridge()</c>.
    /// </summary>
    void IncrementAuditRedactionFailure();

    /// <summary>
    /// Audit Log (#23) M6 Bundle E (T6) — replace the latest site-local
    /// audit-queue backlog snapshot (pending count, oldest pending row,
    /// on-disk file bytes) used by the next <see cref="CollectReport"/> call.
    /// Refreshed periodically by the <c>SiteAuditBacklogReporter</c> hosted
    /// service so each report carries a recent point-in-time view of the
    /// site→central drain health.
    /// </summary>
    /// <param name="snapshot">The audit backlog snapshot.</param>
    void UpdateSiteAuditBacklog(SiteAuditBacklogSnapshot snapshot);

    /// <summary>
    /// Updates the health status for a data connection.
    /// </summary>
    /// <param name="connectionName">The name of the connection.</param>
    /// <param name="health">The connection health status.</param>
    void UpdateConnectionHealth(string connectionName, ConnectionHealth health);

    /// <summary>
    /// Removes a connection from health tracking.
    /// </summary>
    /// <param name="connectionName">The name of the connection.</param>
    void RemoveConnection(string connectionName);

    /// <summary>
    /// Updates tag resolution metrics for a connection.
    /// </summary>
    /// <param name="connectionName">The name of the connection.</param>
    /// <param name="totalSubscribed">Total number of subscribed tags.</param>
    /// <param name="successfullyResolved">Number of successfully resolved tags.</param>
    void UpdateTagResolution(string connectionName, int totalSubscribed, int successfullyResolved);

    /// <summary>
    /// Updates the endpoint for a connection.
    /// </summary>
    /// <param name="connectionName">The name of the connection.</param>
    /// <param name="endpoint">The connection endpoint.</param>
    void UpdateConnectionEndpoint(string connectionName, string endpoint);

    /// <summary>
    /// Updates tag quality metrics for a connection.
    /// </summary>
    /// <param name="connectionName">The name of the connection.</param>
    /// <param name="good">Number of good quality tags.</param>
    /// <param name="bad">Number of bad quality tags.</param>
    /// <param name="uncertain">Number of uncertain quality tags.</param>
    void UpdateTagQuality(string connectionName, int good, int bad, int uncertain);

    /// <summary>
    /// Sets the store-and-forward buffer depths for all categories.
    /// </summary>
    /// <param name="depths">Dictionary mapping category names to their buffer depths.</param>
    void SetStoreAndForwardDepths(IReadOnlyDictionary<string, int> depths);

    /// <summary>
    /// Sets the counts of instances in each state.
    /// </summary>
    /// <param name="deployed">Number of deployed instances.</param>
    /// <param name="enabled">Number of enabled instances.</param>
    /// <param name="disabled">Number of disabled instances.</param>
    void SetInstanceCounts(int deployed, int enabled, int disabled);

    /// <summary>
    /// Sets the count of parked messages.
    /// </summary>
    /// <param name="count">The number of parked messages.</param>
    void SetParkedMessageCount(int count);

    /// <summary>
    /// Sets the hostname of this node.
    /// </summary>
    /// <param name="hostname">The node hostname.</param>
    void SetNodeHostname(string hostname);

    /// <summary>
    /// Sets the list of cluster nodes.
    /// </summary>
    /// <param name="nodes">The list of cluster node statuses.</param>
    void SetClusterNodes(IReadOnlyList<Commons.Messages.Health.NodeStatus> nodes);

    /// <summary>
    /// Sets whether this node is the active node in the cluster.
    /// </summary>
    /// <param name="isActive">True if this node is active, false otherwise.</param>
    void SetActiveNode(bool isActive);

    /// <summary>
    /// Gets whether this node is the active node in the cluster.
    /// </summary>
    bool IsActiveNode { get; }

    /// <summary>
    /// Collects and returns a health report for a site.
    /// </summary>
    /// <param name="siteId">The site identifier.</param>
    /// <returns>A health report for the specified site.</returns>
    SiteHealthReport CollectReport(string siteId);

    /// <summary>
    /// HealthMonitoring-017: atomically add back the given per-interval error
    /// counts into the collector's accumulators. Called by the report sender
    /// when transport delivery of a freshly-collected report fails, so the
    /// counts that <see cref="CollectReport"/> already drained roll forward
    /// into the next report rather than being silently lost. Concurrent
    /// increments arriving between the failed Send and this restore are
    /// preserved — <c>Interlocked.Add</c> sums correctly with them. The
    /// default interface implementation is a no-op so existing test fakes
    /// (the only implementations outside <see cref="SiteHealthCollector"/>)
    /// continue to compile without per-fake updates; production callers see
    /// the real behaviour via the concrete class.
    /// </summary>
    /// <param name="scriptErrors">Script error count to add back.</param>
    /// <param name="alarmErrors">Alarm evaluation error count to add back.</param>
    /// <param name="deadLetters">Dead letter count to add back.</param>
    /// <param name="siteAuditWriteFailures">Site audit write failure count to add back.</param>
    /// <param name="auditRedactionFailures">Audit redaction failure count to add back.</param>
    void AddIntervalCounters(
        int scriptErrors,
        int alarmErrors,
        int deadLetters,
        int siteAuditWriteFailures,
        int auditRedactionFailures)
    {
        // Default no-op so test fakes do not need to be updated. The real
        // SiteHealthCollector overrides this with the Interlocked.Add restore.
    }
}