feat(devices): periodic reachability poll publishes on change

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: HandyS11

src/RustPlusBot.Features.Connections/ConnectionOptions.cs

@@ -41,4 +41,7 @@ public sealed class ConnectionOptions
 
     /// <summary>Movement tolerance (world units) below which a member is considered still. Default 1.</summary>
     public float AfkEpsilon { get; set; } = 1f;
+
+    /// <summary>How often to poll managed devices for reachability changes while connected. Default 5m.</summary>
+    public TimeSpan ReachabilityPollInterval { get; set; } = TimeSpan.FromMinutes(5);
 }

src/RustPlusBot.Features.Connections/Supervisor/ConnectionSupervisor.cs

@@ -519,6 +519,8 @@ void OnStorage(object? sender, StorageMonitorTrigger trigger)
         using var pollCts = CancellationTokenSource.CreateLinkedTokenSource(ct);
         var markerPoll = Task.Run(() => PollMarkersAsync(key, connection, dims, rigs, tracker, pollCts.Token),
             CancellationToken.None);
+        var reachabilityPoll = Task.Run(() => PollReachabilityAsync(key, connection, pollCts.Token),
+            CancellationToken.None);
         try
         {
             return await RunHeartbeatLoopAsync(key, connection, credentialId, ct).ConfigureAwait(false);
@@ -528,8 +530,8 @@ void OnStorage(object? sender, StorageMonitorTrigger trigger)
             await pollCts.CancelAsync().ConfigureAwait(false);
             try
             {
-#pragma warning disable VSTHRD003 // Suppress: markerPoll is owned by this connected window and explicitly joined on exit.
-                await markerPoll.ConfigureAwait(false);
+#pragma warning disable VSTHRD003 // Suppress: markerPoll and reachabilityPoll are owned by this connected window and explicitly joined on exit.
+                await Task.WhenAll(markerPoll, reachabilityPoll).ConfigureAwait(false);
 #pragma warning restore VSTHRD003
             }
             catch (OperationCanceledException)
@@ -632,6 +634,91 @@ await eventBus.PublishAsync(
         }
     }
 
+    private async Task PollReachabilityAsync(
+        (ulong Guild, Guid Server) key,
+        IRustServerConnection connection,
+        CancellationToken ct)
+    {
+        var previous = new Dictionary<ulong, DeviceReachability>();
+        var seeded = false;
+        while (!ct.IsCancellationRequested)
+        {
+            await Task.Delay(_options.ReachabilityPollInterval, ct).ConfigureAwait(false);
+            Dictionary<ulong, DeviceReachability> current;
+            try
+            {
+                current = await ReadAllReachabilityAsync(key, connection, ct).ConfigureAwait(false);
+            }
+            catch (OperationCanceledException)
+            {
+                throw;
+            }
+#pragma warning disable CA1031 // Broad catch: a failed reachability sweep is logged and retried next cycle.
+            catch (Exception ex)
+#pragma warning restore CA1031
+            {
+                LogReachabilityPollFailed(logger, ex, key.Server);
+                continue;
+            }
+
+            if (!seeded)
+            {
+                foreach (var kvp in current)
+                {
+                    previous[kvp.Key] = kvp.Value;
+                }
+
+                seeded = true;
+                continue; // first cycle: silent baseline
+            }
+
+            foreach (var change in ReachabilitySweep.Diff(previous, current))
+            {
+                previous[change.Key] = change.Value;
+                await eventBus.PublishAsync(
+                        new DeviceReachabilityChangedEvent(key.Guild, key.Server, change.Key, change.Value), ct)
+                    .ConfigureAwait(false);
+            }
+        }
+    }
+
+    private async Task<Dictionary<ulong, DeviceReachability>> ReadAllReachabilityAsync(
+        (ulong Guild, Guid Server) key,
+        IRustServerConnection connection,
+        CancellationToken ct)
+    {
+        var result = new Dictionary<ulong, DeviceReachability>();
+        var scope = scopeFactory.CreateAsyncScope();
+        await using (scope.ConfigureAwait(false))
+        {
+            var switches = await scope.ServiceProvider.GetRequiredService<ISwitchStore>()
+                .ListByServerAsync(key.Guild, key.Server, ct).ConfigureAwait(false);
+            var alarms = await scope.ServiceProvider.GetRequiredService<IAlarmStore>()
+                .ListByServerAsync(key.Guild, key.Server, ct).ConfigureAwait(false);
+            var monitors = await scope.ServiceProvider.GetRequiredService<IStorageMonitorStore>()
+                .ListByServerAsync(key.Guild, key.Server, ct).ConfigureAwait(false);
+
+            foreach (var entityId in switches.Select(s => s.EntityId).Concat(alarms.Select(a => a.EntityId)))
+            {
+                var reading = await connection.GetSmartDeviceInfoAsync(entityId, _options.HeartbeatTimeout, ct)
+                    .ConfigureAwait(false);
+                result[entityId] = reading.Reachability;
+            }
+
+#pragma warning disable S3267 // Not a projection: each iteration awaits with per-monitor best-effort error handling.
+            foreach (var monitor in monitors)
+#pragma warning restore S3267
+            {
+                var reading = await connection
+                    .GetStorageMonitorInfoAsync(monitor.EntityId, _options.HeartbeatTimeout, ct)
+                    .ConfigureAwait(false);
+                result[monitor.EntityId] = reading.Reachability;
+            }
+        }
+
+        return result;
+    }
+
     private async Task DetectRigActivationsAsync(
         (ulong Guild, Guid Server) key,
         IReadOnlyList<MapMarkerSnapshot> current,
@@ -1118,6 +1205,9 @@ await eventBus.PublishAsync(
     [LoggerMessage(Level = LogLevel.Warning, Message = "Marker poll for server {ServerId} failed.")]
     private static partial void LogMarkerPollFailed(ILogger logger, Exception exception, Guid serverId);
 
+    [LoggerMessage(Level = LogLevel.Warning, Message = "Reachability poll for server {ServerId} failed.")]
+    private static partial void LogReachabilityPollFailed(ILogger logger, Exception exception, Guid serverId);
+
     [LoggerMessage(Level = LogLevel.Warning,
         Message =
             "Fetching monuments for oil-rig detection on server {ServerId} failed; rig detection disabled for this connection.")]

src/RustPlusBot.Features.Connections/Supervisor/ReachabilitySweep.cs

@@ -0,0 +1,28 @@
+using RustPlusBot.Abstractions.Connections;
+
+namespace RustPlusBot.Features.Connections.Supervisor;
+
+/// <summary>Pure helper: which entities' reachability changed between two poll snapshots.</summary>
+internal static class ReachabilitySweep
+{
+    /// <summary>Entities in <paramref name="current"/> whose reachability differs from <paramref name="previous"/> (absent ⇒ Reachable).</summary>
+    /// <param name="previous">The reachability snapshot from the previous poll cycle.</param>
+    /// <param name="current">The reachability snapshot from the current poll cycle.</param>
+    /// <returns>A list of (entityId, newReachability) pairs where the state has changed.</returns>
+    public static IReadOnlyList<KeyValuePair<ulong, DeviceReachability>> Diff(
+        IReadOnlyDictionary<ulong, DeviceReachability> previous,
+        IReadOnlyDictionary<ulong, DeviceReachability> current)
+    {
+        var changes = new List<KeyValuePair<ulong, DeviceReachability>>();
+        foreach (var (entityId, reachability) in current)
+        {
+            var before = previous.TryGetValue(entityId, out var p) ? p : DeviceReachability.Reachable;
+            if (before != reachability)
+            {
+                changes.Add(new KeyValuePair<ulong, DeviceReachability>(entityId, reachability));
+            }
+        }
+
+        return changes;
+    }
+}

tests/RustPlusBot.Features.Connections.Tests/ConnectionOptionsTests.cs

@@ -18,4 +18,12 @@ public void Defaults_match_the_2a_ii_design()
         Assert.Equal(TimeSpan.FromMinutes(15), o.RigOfflineWindow);
         Assert.Equal(TimeSpan.FromSeconds(30), o.RigTickInterval);
     }
+
+    /// <summary>Verifies that the reachability poll interval defaults to 5 minutes.</summary>
+    [Fact]
+    public void ReachabilityPollInterval_DefaultIs5Minutes()
+    {
+        var o = new ConnectionOptions();
+        Assert.Equal(TimeSpan.FromMinutes(5), o.ReachabilityPollInterval);
+    }
 }

tests/RustPlusBot.Features.Connections.Tests/ReachabilitySweepTests.cs

@@ -0,0 +1,46 @@
+using RustPlusBot.Abstractions.Connections;
+using RustPlusBot.Features.Connections.Supervisor;
+
+namespace RustPlusBot.Features.Connections.Tests;
+
+/// <summary>Unit tests for <see cref="ReachabilitySweep.Diff"/>.</summary>
+public sealed class ReachabilitySweepTests
+{
+    /// <summary>Verifies that a first-observed Removed state is reported (absent ⇒ Reachable default, so Removed is a change).</summary>
+    [Fact]
+    public void Diff_FirstObservedRemoved_IsReported()
+    {
+        var current = new Dictionary<ulong, DeviceReachability> { [1] = DeviceReachability.Removed };
+        var changes = ReachabilitySweep.Diff(new Dictionary<ulong, DeviceReachability>(), current);
+        // 1 went from (absent==Reachable default) to Removed
+        Assert.Single(changes);
+    }
+
+    /// <summary>Verifies that both recoveries and new degradations are reported.</summary>
+    [Fact]
+    public void Diff_ReportsChangesIncludingRecovery()
+    {
+        var previous = new Dictionary<ulong, DeviceReachability>
+        {
+            [1] = DeviceReachability.Removed,
+            [2] = DeviceReachability.Reachable,
+        };
+        var current = new Dictionary<ulong, DeviceReachability>
+        {
+            [1] = DeviceReachability.Reachable, // recovered
+            [2] = DeviceReachability.NoPrivilege, // newly degraded
+        };
+        var changes = ReachabilitySweep.Diff(previous, current);
+        Assert.Equal(2, changes.Count);
+        Assert.Contains(changes, c => c.Key == 1 && c.Value == DeviceReachability.Reachable);
+        Assert.Contains(changes, c => c.Key == 2 && c.Value == DeviceReachability.NoPrivilege);
+    }
+
+    /// <summary>Verifies that unchanged states produce an empty result.</summary>
+    [Fact]
+    public void Diff_NoChanges_ReturnsEmpty()
+    {
+        var same = new Dictionary<ulong, DeviceReachability> { [1] = DeviceReachability.Reachable };
+        Assert.Empty(ReachabilitySweep.Diff(same, new Dictionary<ulong, DeviceReachability>(same)));
+    }
+}