feat(health): SiteAuditBacklog metric (count + age + bytes) (#23 M6)

src/ScadaLink.AuditLog/Site/SqliteAuditWriter.cs

@@ -4,6 +4,7 @@ using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Options;
 using ScadaLink.Commons.Entities.Audit;
 using ScadaLink.Commons.Interfaces.Services;
+using ScadaLink.Commons.Types;
 using ScadaLink.Commons.Types.Enums;
 
 namespace ScadaLink.AuditLog.Site;
@@ -484,6 +485,84 @@ public class SqliteAuditWriter : IAuditWriter, ISiteAuditQueue, IAsyncDisposable
         }
     }
 
+    /// <summary>
+    /// M6 Bundle E (T6) health-metric surface: returns a point-in-time snapshot
+    /// of the site queue's pending count, the oldest pending row's
+    /// <see cref="AuditEvent.OccurredAtUtc"/>, and the on-disk file size. Called
+    /// by the site-side <c>SiteAuditBacklogReporter</c> hosted service on its
+    /// 30 s tick to refresh the <c>SiteHealthReport.SiteAuditBacklog</c> field.
+    /// </summary>
+    /// <remarks>
+    /// The pending-count + oldest-row queries run inside the same write lock as
+    /// the hot-path INSERT batch so the snapshot is consistent against the
+    /// connection's view (no torn read of an in-flight transaction). The on-disk
+    /// size lookup happens OUTSIDE the lock — it's a stat() call on the file
+    /// path and doesn't touch the connection. In-memory and missing files
+    /// return 0 bytes (the snapshot is for ops dashboards, not a correctness
+    /// invariant).
+    /// </remarks>
+    public Task<SiteAuditBacklogSnapshot> GetBacklogStatsAsync(CancellationToken ct = default)
+    {
+        int pendingCount;
+        DateTime? oldestPending;
+
+        lock (_writeLock)
+        {
+            ObjectDisposedException.ThrowIf(_disposed, this);
+
+            // Single round-trip — COUNT(*) + MIN(OccurredAtUtc) over the same
+            // index range avoids a second scan. The IX_SiteAuditLog_ForwardState_Occurred
+            // index makes both aggregates cheap (count is a covering scan, min
+            // is the first key).
+            using var cmd = _connection.CreateCommand();
+            cmd.CommandText = """
+                SELECT COUNT(*), MIN(OccurredAtUtc)
+                FROM   AuditLog
+                WHERE  ForwardState = $pending;
+                """;
+            cmd.Parameters.AddWithValue("$pending", AuditForwardState.Pending.ToString());
+
+            using var reader = cmd.ExecuteReader();
+            reader.Read();
+            pendingCount = reader.GetInt32(0);
+            oldestPending = reader.IsDBNull(1)
+                ? null
+                : DateTime.Parse(reader.GetString(1),
+                    System.Globalization.CultureInfo.InvariantCulture,
+                    System.Globalization.DateTimeStyles.RoundtripKind);
+        }
+
+        // File-size lookup outside the lock — the DatabasePath option is the
+        // canonical source. The connection-string-override branch (used by
+        // some tests) keeps the same DatabasePath value, so this works
+        // uniformly. In-memory / mode=memory paths return 0 because the file
+        // doesn't exist on disk.
+        long onDiskBytes = 0;
+        try
+        {
+            if (!string.IsNullOrEmpty(_options.DatabasePath) &&
+                !_options.DatabasePath.StartsWith(":memory:", StringComparison.Ordinal) &&
+                !_options.DatabasePath.Contains("mode=memory", StringComparison.OrdinalIgnoreCase) &&
+                File.Exists(_options.DatabasePath))
+            {
+                onDiskBytes = new FileInfo(_options.DatabasePath).Length;
+            }
+        }
+        catch (Exception ex)
+        {
+            // File system probe is a best-effort health-metric — never abort
+            // a backlog snapshot because stat() failed. Log and report 0.
+            _logger.LogDebug(ex,
+                "SqliteAuditWriter could not stat DB path {Path} for backlog snapshot.",
+                _options.DatabasePath);
+        }
+
+        return Task.FromResult(new SiteAuditBacklogSnapshot(
+            PendingCount: pendingCount,
+            OldestPendingUtc: oldestPending,
+            OnDiskBytes: onDiskBytes));
+    }
+
     private static DateTime EnsureUtc(DateTime value) =>
         value.Kind == DateTimeKind.Utc
             ? value