refactor(devices): widen connection reads/actuation to carry DeviceReachability

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

Author: HandyS11

src/RustPlusBot.Features.Connections/Listening/IRustServerConnection.cs

@@ -49,41 +49,41 @@ internal interface IRustServerConnection : IAsyncDisposable
     /// <returns>True if the promotion succeeded; false on failure/timeout.</returns>
     Task<bool> PromoteToLeaderAsync(ulong steamId, TimeSpan timeout, CancellationToken cancellationToken);
 
-    /// <summary>Reads a smart device's on/off state, or null on failure/timeout. Also primes the socket's interest in the entity (so triggers fire for it thereafter).</summary>
+    /// <summary>Reads a smart device's on/off state and reachability. Also primes the socket's interest in the entity (so triggers fire for it thereafter).</summary>
     /// <param name="entityId">The in-game entity id (switch or alarm).</param>
     /// <param name="timeout">How long to wait for the response.</param>
     /// <param name="cancellationToken">A cancellation token.</param>
-    /// <returns>True/false for on/off, or null on failure/timeout.</returns>
-    Task<bool?> GetSmartDeviceInfoAsync(ulong entityId, TimeSpan timeout, CancellationToken cancellationToken);
+    /// <returns>A <see cref="DeviceReading"/> with the active state (non-null only when <see cref="DeviceReachability.Reachable"/>) and the reachability outcome.</returns>
+    Task<DeviceReading> GetSmartDeviceInfoAsync(ulong entityId, TimeSpan timeout, CancellationToken cancellationToken);
 
-    /// <summary>Reads a storage monitor's contents, or null on failure/timeout. Also primes the socket's interest so triggers fire for it thereafter.</summary>
+    /// <summary>Reads a storage monitor's contents and reachability. Also primes the socket's interest so triggers fire for it thereafter.</summary>
     /// <param name="entityId">The in-game storage-monitor entity id.</param>
     /// <param name="timeout">How long to wait for the response.</param>
     /// <param name="cancellationToken">A cancellation token.</param>
-    /// <returns>The contents snapshot, or null on failure/timeout.</returns>
-    Task<StorageContentsSnapshot?> GetStorageMonitorInfoAsync(ulong entityId,
+    /// <returns>A <see cref="StorageReading"/> with the contents snapshot (non-null only when <see cref="DeviceReachability.Reachable"/>) and the reachability outcome.</returns>
+    Task<StorageReading> GetStorageMonitorInfoAsync(ulong entityId,
         TimeSpan timeout,
         CancellationToken cancellationToken);
 
-    /// <summary>Sets a smart switch on/off; returns true on success, false on failure/timeout.</summary>
+    /// <summary>Sets a smart switch on/off; returns the reachability outcome.</summary>
     /// <param name="entityId">The in-game smart-switch entity id.</param>
     /// <param name="value">True to turn on, false to turn off.</param>
     /// <param name="timeout">How long to wait for the response.</param>
     /// <param name="cancellationToken">A cancellation token.</param>
-    /// <returns>True on success; false on failure/timeout.</returns>
-    Task<bool> SetSmartSwitchValueAsync(ulong entityId,
+    /// <returns>The <see cref="DeviceReachability"/> outcome of the operation.</returns>
+    Task<DeviceReachability> SetSmartSwitchValueAsync(ulong entityId,
         bool value,
         TimeSpan timeout,
         CancellationToken cancellationToken);
 
-    /// <summary>Strobes a smart switch; returns true on success, false on failure/timeout.</summary>
+    /// <summary>Strobes a smart switch; returns the reachability outcome.</summary>
     /// <param name="entityId">The in-game smart-switch entity id.</param>
     /// <param name="timeoutMs">The in-game strobe duration in milliseconds.</param>
     /// <param name="value">The terminal value after strobing.</param>
     /// <param name="timeout">How long to wait for the response.</param>
     /// <param name="cancellationToken">A cancellation token.</param>
-    /// <returns>True on success; false on failure/timeout.</returns>
-    Task<bool> StrobeSmartSwitchAsync(ulong entityId,
+    /// <returns>The <see cref="DeviceReachability"/> outcome of the operation.</returns>
+    Task<DeviceReachability> StrobeSmartSwitchAsync(ulong entityId,
         int timeoutMs,
         bool value,
         TimeSpan timeout,

src/RustPlusBot.Features.Connections/Listening/RustPlusSocketSource.cs

@@ -50,28 +50,28 @@ public Task SendTeamMessageAsync(string message, CancellationToken cancellationT
         public Task<bool> PromoteToLeaderAsync(ulong steamId, TimeSpan timeout, CancellationToken cancellationToken) =>
             Task.FromResult(false);
 
-        public Task<bool?> GetSmartDeviceInfoAsync(ulong entityId,
+        public Task<DeviceReading> GetSmartDeviceInfoAsync(ulong entityId,
             TimeSpan timeout,
             CancellationToken cancellationToken) =>
-            Task.FromResult<bool?>(null);
+            Task.FromResult(new DeviceReading(null, DeviceReachability.NoResponse));
 
-        public Task<StorageContentsSnapshot?> GetStorageMonitorInfoAsync(ulong entityId,
+        public Task<StorageReading> GetStorageMonitorInfoAsync(ulong entityId,
             TimeSpan timeout,
             CancellationToken cancellationToken) =>
-            Task.FromResult<StorageContentsSnapshot?>(null);
+            Task.FromResult(new StorageReading(null, DeviceReachability.NoResponse));
 
-        public Task<bool> SetSmartSwitchValueAsync(ulong entityId,
+        public Task<DeviceReachability> SetSmartSwitchValueAsync(ulong entityId,
             bool value,
             TimeSpan timeout,
             CancellationToken cancellationToken) =>
-            Task.FromResult(false);
+            Task.FromResult(DeviceReachability.NoResponse);
 
-        public Task<bool> StrobeSmartSwitchAsync(ulong entityId,
+        public Task<DeviceReachability> StrobeSmartSwitchAsync(ulong entityId,
             int timeoutMs,
             bool value,
             TimeSpan timeout,
             CancellationToken cancellationToken) =>
-            Task.FromResult(false);
+            Task.FromResult(DeviceReachability.NoResponse);
 
         public Task<IReadOnlyList<MapMarkerSnapshot>> GetMapMarkersAsync(TimeSpan timeout,
             CancellationToken cancellationToken = default) =>
@@ -363,7 +363,7 @@ public async Task<bool> PromoteToLeaderAsync(ulong steamId,
 
         public event EventHandler<StorageMonitorTrigger>? StorageMonitorTriggered;
 
-        public async Task<bool?> GetSmartDeviceInfoAsync(ulong entityId,
+        public async Task<DeviceReading> GetSmartDeviceInfoAsync(ulong entityId,
             TimeSpan timeout,
             CancellationToken cancellationToken)
         {
@@ -375,25 +375,28 @@ public async Task<bool> PromoteToLeaderAsync(ulong steamId,
                 // Task of Response of SmartDeviceInfo; Response.IsSuccess and Response.Data are the accessors and
                 // SmartDeviceInfo.IsActive is a bool. The call also primes the socket's interest in this
                 // entity, so OnSmartDeviceTriggered fires for it thereafter.
+                // CONFIRMED: Response.Error is ErrorMessage? (null on success), so response.Error?.Code is correct.
                 var response = await _rustPlus.GetSmartSwitchInfoAsync(entityId, timeoutCts.Token)
                     .WaitAsync(timeoutCts.Token).ConfigureAwait(false);
-                return response.IsSuccess && response.Data is { } info ? info.IsActive : null;
+                var reachability = ReachabilityMapping.FromResponse(response.IsSuccess, response.Error?.Code);
+                var isActive = response is { IsSuccess: true, Data: { } info } ? info.IsActive : (bool?)null;
+                return new DeviceReading(isActive, reachability);
             }
             catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested)
             {
-                return null;
+                return new DeviceReading(null, DeviceReachability.NoResponse);
             }
-#pragma warning disable CA1031 // Broad catch: any switch-info failure maps to null; never surface a token/secret.
+#pragma warning disable CA1031 // Broad catch: a failed read maps to NoResponse; never surface a token/secret.
             catch (Exception ex) when (!cancellationToken.IsCancellationRequested)
 #pragma warning restore CA1031
             {
                 LogQueryFailed(_logger, ex);
-                return null;
+                return new DeviceReading(null, DeviceReachability.NoResponse);
             }
         }
 
         /// <inheritdoc />
-        public async Task<StorageContentsSnapshot?> GetStorageMonitorInfoAsync(
+        public async Task<StorageReading> GetStorageMonitorInfoAsync(
             ulong entityId,
             TimeSpan timeout,
             CancellationToken cancellationToken)
@@ -405,23 +408,27 @@ public async Task<bool> PromoteToLeaderAsync(ulong steamId,
                 // CONFIRMED (2.0.0-beta.3): GetStorageMonitorInfoAsync(ulong, CancellationToken) returns
                 // Task<Response<StorageMonitorInfo?>>; the read also primes the entity so OnStorageMonitorTriggered
                 // fires for it thereafter.
+                // CONFIRMED: Response.Error is ErrorMessage? (null on success), so response.Error?.Code is correct.
                 var response = await _rustPlus.GetStorageMonitorInfoAsync(entityId, timeoutCts.Token)
                     .WaitAsync(timeoutCts.Token).ConfigureAwait(false);
-                return response is { IsSuccess: true, Data: { } info } ? MapContents(info) : null;
+                var reachability = ReachabilityMapping.FromResponse(response.IsSuccess, response.Error?.Code);
+                var contents = response is { IsSuccess: true, Data: { } info } ? MapContents(info) : null;
+                return new StorageReading(contents, reachability);
             }
             catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested)
             {
-                return null;
+                return new StorageReading(null, DeviceReachability.NoResponse);
             }
-#pragma warning disable CA1031 // Broad catch: a failed/timed-out storage read returns null; the caller treats null as unreachable.
-            catch (Exception)
+#pragma warning disable CA1031 // Broad catch: a failed read maps to NoResponse; never surface a token/secret.
+            catch (Exception ex) when (!cancellationToken.IsCancellationRequested)
 #pragma warning restore CA1031
             {
-                return null;
+                LogQueryFailed(_logger, ex);
+                return new StorageReading(null, DeviceReachability.NoResponse);
             }
         }
 
-        public async Task<bool> SetSmartSwitchValueAsync(ulong entityId,
+        public async Task<DeviceReachability> SetSmartSwitchValueAsync(ulong entityId,
             bool value,
             TimeSpan timeout,
             CancellationToken cancellationToken)
@@ -432,24 +439,25 @@ public async Task<bool> SetSmartSwitchValueAsync(ulong entityId,
             {
                 // CONFIRMED (2.0.0-beta.3): SetSmartSwitchValueAsync(ulong, bool, CancellationToken) returns
                 // Task of Response of SmartDeviceInfo; Response.IsSuccess indicates the outcome.
+                // CONFIRMED: Response.Error is ErrorMessage? (null on success), so response.Error?.Code is correct.
                 var response = await _rustPlus.SetSmartSwitchValueAsync(entityId, value, timeoutCts.Token)
                     .WaitAsync(timeoutCts.Token).ConfigureAwait(false);
-                return response.IsSuccess;
+                return ReachabilityMapping.FromResponse(response.IsSuccess, response.Error?.Code);
             }
             catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested)
             {
-                return false;
+                return DeviceReachability.NoResponse;
             }
-#pragma warning disable CA1031 // Broad catch: any set failure maps to false; never surface a token/secret.
+#pragma warning disable CA1031 // Broad catch: a failed set maps to NoResponse; never surface a token/secret.
             catch (Exception ex) when (!cancellationToken.IsCancellationRequested)
 #pragma warning restore CA1031
             {
                 LogQueryFailed(_logger, ex);
-                return false;
+                return DeviceReachability.NoResponse;
             }
         }
 
-        public async Task<bool> StrobeSmartSwitchAsync(ulong entityId,
+        public async Task<DeviceReachability> StrobeSmartSwitchAsync(ulong entityId,
             int timeoutMs,
             bool value,
             TimeSpan timeout,
@@ -461,20 +469,21 @@ public async Task<bool> StrobeSmartSwitchAsync(ulong entityId,
             {
                 // CONFIRMED (2.0.0-beta.3): StrobeSmartSwitchAsync(ulong, int timeoutMs, bool value, CancellationToken)
                 // returns Task of Response of SmartDeviceInfo; Response.IsSuccess indicates the outcome.
+                // CONFIRMED: Response.Error is ErrorMessage? (null on success), so response.Error?.Code is correct.
                 var response = await _rustPlus.StrobeSmartSwitchAsync(entityId, timeoutMs, value, timeoutCts.Token)
                     .WaitAsync(timeoutCts.Token).ConfigureAwait(false);
-                return response.IsSuccess;
+                return ReachabilityMapping.FromResponse(response.IsSuccess, response.Error?.Code);
             }
             catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested)
             {
-                return false;
+                return DeviceReachability.NoResponse;
             }
-#pragma warning disable CA1031 // Broad catch: any strobe failure maps to false; never surface a token/secret.
+#pragma warning disable CA1031 // Broad catch: a failed strobe maps to NoResponse; never surface a token/secret.
             catch (Exception ex) when (!cancellationToken.IsCancellationRequested)
 #pragma warning restore CA1031
             {
                 LogQueryFailed(_logger, ex);
-                return false;
+                return DeviceReachability.NoResponse;
             }
         }
 

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

@@ -263,8 +263,9 @@ public async Task<IReadOnlyList<MonumentSnapshot>> GetMonumentsAsync(
             return null;
         }
 
-        return await live.Connection.GetSmartDeviceInfoAsync(entityId, _options.HeartbeatTimeout, cancellationToken)
+        var reading = await live.Connection.GetSmartDeviceInfoAsync(entityId, _options.HeartbeatTimeout, cancellationToken)
             .ConfigureAwait(false);
+        return reading.IsActive;
     }
 
     /// <inheritdoc />
@@ -279,9 +280,10 @@ public async Task<IReadOnlyList<MonumentSnapshot>> GetMonumentsAsync(
             return null;
         }
 
-        return await live.Connection
+        var reading = await live.Connection
             .GetStorageMonitorInfoAsync(entityId, _options.HeartbeatTimeout, cancellationToken)
             .ConfigureAwait(false);
+        return reading.Contents;
     }
 
     /// <inheritdoc />
@@ -297,9 +299,10 @@ public async Task<bool> SetSmartSwitchAsync(
             return false;
         }
 
-        return await live.Connection
+        var reachability = await live.Connection
             .SetSmartSwitchValueAsync(entityId, value, _options.HeartbeatTimeout, cancellationToken)
             .ConfigureAwait(false);
+        return reachability == DeviceReachability.Reachable;
     }
 
     /// <inheritdoc />
@@ -316,9 +319,10 @@ public async Task<bool> StrobeSmartSwitchAsync(
             return false;
         }
 
-        return await live.Connection
+        var reachability = await live.Connection
             .StrobeSmartSwitchAsync(entityId, timeoutMs, value, _options.HeartbeatTimeout, cancellationToken)
             .ConfigureAwait(false);
+        return reachability == DeviceReachability.Reachable;
     }
 
     /// <inheritdoc />
@@ -1012,11 +1016,11 @@ private async Task PublishDevicePrimeAsync(
 
         try
         {
-            var isActive = await connection
+            var reading = await connection
                 .GetSmartDeviceInfoAsync(entityId, _options.HeartbeatTimeout, _shutdown.Token)
                 .ConfigureAwait(false);
             await eventBus.PublishAsync(
-                    new SmartDeviceTriggeredEvent(key.Guild, key.Server, entityId, isActive ?? false),
+                    new SmartDeviceTriggeredEvent(key.Guild, key.Server, entityId, reading.IsActive ?? false),
                     _shutdown.Token)
                 .ConfigureAwait(false);
         }
@@ -1077,10 +1081,10 @@ private async Task PublishStoragePrimeAsync(
 
         try
         {
-            var contents = await connection
+            var reading = await connection
                 .GetStorageMonitorInfoAsync(entityId, _options.HeartbeatTimeout, _shutdown.Token)
                 .ConfigureAwait(false);
-            if (contents is null)
+            if (reading.Contents is not { } contents)
             {
                 return; // unreachable read; the relay leaves the embed as-is (or unreachable via status events).
             }