feat(switches): surface actuation reachability reason + update embed

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

Author: HandyS11

src/RustPlusBot.Abstractions/Connections/IRustServerQuery.cs

@@ -79,28 +79,28 @@ Task<IReadOnlyList<MonumentSnapshot>> GetMonumentsAsync(
         ulong entityId,
         CancellationToken cancellationToken);
 
-    /// <summary>Sets a smart switch on/off; returns false when there is no live socket or the call fails.</summary>
+    /// <summary>Sets a smart switch on/off; returns the reachability reason when the call fails or there is no live socket.</summary>
     /// <param name="guildId">The owning guild snowflake.</param>
     /// <param name="serverId">The target server id.</param>
     /// <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="cancellationToken">A cancellation token.</param>
-    /// <returns>True on success; false when unavailable or the call fails.</returns>
-    Task<bool> SetSmartSwitchAsync(ulong guildId,
+    /// <returns><see cref="DeviceReachability.Reachable"/> on success; the failure reason otherwise.</returns>
+    Task<DeviceReachability> SetSmartSwitchAsync(ulong guildId,
         Guid serverId,
         ulong entityId,
         bool value,
         CancellationToken cancellationToken);
 
-    /// <summary>Strobes a smart switch; returns false when there is no live socket or the call fails.</summary>
+    /// <summary>Strobes a smart switch; returns the reachability reason when the call fails or there is no live socket.</summary>
     /// <param name="guildId">The owning guild snowflake.</param>
     /// <param name="serverId">The target server id.</param>
     /// <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="cancellationToken">A cancellation token.</param>
-    /// <returns>True on success; false when unavailable or the call fails.</returns>
-    Task<bool> StrobeSmartSwitchAsync(ulong guildId,
+    /// <returns><see cref="DeviceReachability.Reachable"/> on success; the failure reason otherwise.</returns>
+    Task<DeviceReachability> StrobeSmartSwitchAsync(ulong guildId,
         Guid serverId,
         ulong entityId,
         int timeoutMs,

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

@@ -288,7 +288,7 @@ public async Task<IReadOnlyList<MonumentSnapshot>> GetMonumentsAsync(
     }
 
     /// <inheritdoc />
-    public async Task<bool> SetSmartSwitchAsync(
+    public async Task<DeviceReachability> SetSmartSwitchAsync(
         ulong guildId,
         Guid serverId,
         ulong entityId,
@@ -297,17 +297,16 @@ public async Task<bool> SetSmartSwitchAsync(
     {
         if (!_liveSockets.TryGetValue((guildId, serverId), out var live))
         {
-            return false;
+            return DeviceReachability.NoResponse;
         }
 
-        var reachability = await live.Connection
+        return await live.Connection
             .SetSmartSwitchValueAsync(entityId, value, _options.HeartbeatTimeout, cancellationToken)
             .ConfigureAwait(false);
-        return reachability == DeviceReachability.Reachable;
     }
 
     /// <inheritdoc />
-    public async Task<bool> StrobeSmartSwitchAsync(
+    public async Task<DeviceReachability> StrobeSmartSwitchAsync(
         ulong guildId,
         Guid serverId,
         ulong entityId,
@@ -317,13 +316,12 @@ public async Task<bool> StrobeSmartSwitchAsync(
     {
         if (!_liveSockets.TryGetValue((guildId, serverId), out var live))
         {
-            return false;
+            return DeviceReachability.NoResponse;
         }
 
-        var reachability = await live.Connection
+        return await live.Connection
             .StrobeSmartSwitchAsync(entityId, timeoutMs, value, _options.HeartbeatTimeout, cancellationToken)
             .ConfigureAwait(false);
-        return reachability == DeviceReachability.Reachable;
     }
 
     /// <inheritdoc />

src/RustPlusBot.Features.Switches/Modules/SwitchActuationReply.cs

@@ -0,0 +1,24 @@
+using RustPlusBot.Abstractions.Connections;
+using RustPlusBot.Localization;
+
+namespace RustPlusBot.Features.Switches.Modules;
+
+/// <summary>Maps a failed actuation's reachability to a localized ephemeral reply.</summary>
+internal static class SwitchActuationReply
+{
+    /// <summary>Returns the localized reason text for a non-Reachable actuation result.</summary>
+    /// <param name="reachability">The device reachability returned by the actuation call.</param>
+    /// <param name="localizer">The localizer used to resolve the string.</param>
+    /// <param name="culture">The BCP-47 culture tag for the guild.</param>
+    public static string Describe(DeviceReachability reachability, ILocalizer localizer, string culture)
+    {
+        ArgumentNullException.ThrowIfNull(localizer);
+        var key = reachability switch
+        {
+            DeviceReachability.Removed => "switch.actuation.removed",
+            DeviceReachability.NoPrivilege => "switch.actuation.noprivilege",
+            _ => "switch.actuation.noresponse",
+        };
+        return localizer.Get(key, culture);
+    }
+}

src/RustPlusBot.Features.Switches/Modules/SwitchComponentModule.cs

@@ -6,18 +6,22 @@
 using RustPlusBot.Abstractions.Events;
 using RustPlusBot.Features.Switches.Pairing;
 using RustPlusBot.Features.Switches.Rendering;
+using RustPlusBot.Localization;
 using RustPlusBot.Persistence.Switches;
+using RustPlusBot.Persistence.Workspace;
 
 namespace RustPlusBot.Features.Switches.Modules;
 
 /// <summary>Thin handler for the #switches pairing prompt + control buttons + rename modal. Any guild member.</summary>
 /// <param name="scopeFactory">Creates a short-lived DI scope per interaction.</param>
 /// <param name="query">Live socket read/control.</param>
 /// <param name="eventBus">Publishes a state-changed event to drive an embed refresh.</param>
+/// <param name="localizer">Resolves localized strings for actuation failure replies.</param>
 public sealed class SwitchComponentModule(
     IServiceScopeFactory scopeFactory,
     IRustServerQuery query,
-    IEventBus eventBus) : InteractionModuleBase<SocketInteractionContext>
+    IEventBus eventBus,
+    ILocalizer localizer) : InteractionModuleBase<SocketInteractionContext>
 {
     private const string InvalidControlMessage = "That control wasn't valid.";
 
@@ -91,13 +95,25 @@ public async Task StrobeAsync(string tail)
         }
 
         await DeferAsync(ephemeral: true).ConfigureAwait(false);
-        var ok = await query
+        var strobeResult = await query
             .StrobeSmartSwitchAsync(Context.Guild.Id, serverId, entityId, timeoutMs: 1000, value: true,
                 CancellationToken.None)
             .ConfigureAwait(false);
-        if (!ok)
+        if (strobeResult != DeviceReachability.Reachable)
         {
-            await FollowupAsync("Switch is unreachable right now.", ephemeral: true).ConfigureAwait(false);
+            var strobeScope = scopeFactory.CreateAsyncScope();
+            await using (strobeScope.ConfigureAwait(false))
+            {
+                var culture = await strobeScope.ServiceProvider.GetRequiredService<IWorkspaceStore>()
+                    .GetCultureAsync(Context.Guild.Id, CancellationToken.None).ConfigureAwait(false);
+                await eventBus
+                    .PublishAsync(new DeviceReachabilityChangedEvent(Context.Guild.Id, serverId, entityId,
+                        strobeResult))
+                    .ConfigureAwait(false);
+                await FollowupAsync(SwitchActuationReply.Describe(strobeResult, localizer, culture), ephemeral: true)
+                    .ConfigureAwait(false);
+            }
+
             return;
         }
 
@@ -170,11 +186,23 @@ private async Task SetAsync(string tail, bool value)
         }
 
         await DeferAsync(ephemeral: true).ConfigureAwait(false);
-        var ok = await query.SetSmartSwitchAsync(Context.Guild.Id, serverId, entityId, value, CancellationToken.None)
+        var result = await query
+            .SetSmartSwitchAsync(Context.Guild.Id, serverId, entityId, value, CancellationToken.None)
             .ConfigureAwait(false);
-        if (!ok)
+        if (result != DeviceReachability.Reachable)
         {
-            await FollowupAsync("Switch is unreachable right now.", ephemeral: true).ConfigureAwait(false);
+            var setScope = scopeFactory.CreateAsyncScope();
+            await using (setScope.ConfigureAwait(false))
+            {
+                var culture = await setScope.ServiceProvider.GetRequiredService<IWorkspaceStore>()
+                    .GetCultureAsync(Context.Guild.Id, CancellationToken.None).ConfigureAwait(false);
+                await eventBus
+                    .PublishAsync(new DeviceReachabilityChangedEvent(Context.Guild.Id, serverId, entityId, result))
+                    .ConfigureAwait(false);
+                await FollowupAsync(SwitchActuationReply.Describe(result, localizer, culture), ephemeral: true)
+                    .ConfigureAwait(false);
+            }
+
             return;
         }
 

src/RustPlusBot.Localization/Strings.fr.resx

@@ -714,6 +714,15 @@
   <data name="switch.status.unreachable" xml:space="preserve">
     <value>⚠️ Injoignable</value>
   </data>
+  <data name="switch.actuation.noprivilege" xml:space="preserve">
+    <value>Aucun privilège de construction pour cet interrupteur.</value>
+  </data>
+  <data name="switch.actuation.noresponse" xml:space="preserve">
+    <value>L'interrupteur n'a pas répondu. Réessayez.</value>
+  </data>
+  <data name="switch.actuation.removed" xml:space="preserve">
+    <value>Cet interrupteur a été supprimé en jeu.</value>
+  </data>
   <data name="switch.unreachable.ephemeral" xml:space="preserve">
     <value>L'interrupteur est injoignable pour le moment.</value>
   </data>

src/RustPlusBot.Localization/Strings.resx

@@ -714,6 +714,15 @@
   <data name="switch.status.unreachable" xml:space="preserve">
     <value>⚠️ Unreachable</value>
   </data>
+  <data name="switch.actuation.noprivilege" xml:space="preserve">
+    <value>No building privilege for this switch.</value>
+  </data>
+  <data name="switch.actuation.noresponse" xml:space="preserve">
+    <value>The switch didn't respond. Try again.</value>
+  </data>
+  <data name="switch.actuation.removed" xml:space="preserve">
+    <value>This switch was removed in-game.</value>
+  </data>
   <data name="switch.unreachable.ephemeral" xml:space="preserve">
     <value>Switch is unreachable right now.</value>
   </data>

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

@@ -3,6 +3,7 @@
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Options;
 using NSubstitute;
+using RustPlusBot.Abstractions.Connections;
 using RustPlusBot.Abstractions.Credentials;
 using RustPlusBot.Abstractions.Events;
 using RustPlusBot.Abstractions.Time;
@@ -116,9 +117,9 @@ public async Task SetSmartSwitch_forwards_value_when_connected()
         await supervisor.EnsureConnectionAsync(10UL, serverId, cts.Token);
         await WaitUntilAsync(() => supervisor.HasLiveSocket(10UL, serverId), cts.Token);
 
-        var ok = await supervisor.SetSmartSwitchAsync(10UL, serverId, 42UL, value: true, cts.Token);
+        var result = await supervisor.SetSmartSwitchAsync(10UL, serverId, 42UL, value: true, cts.Token);
 
-        Assert.True(ok);
+        Assert.Equal(DeviceReachability.Reachable, result);
         Assert.Contains((42UL, true), source.LastConnection!.SetSwitchCalls);
         await supervisor.StopAllAsync();
     }
@@ -130,7 +131,8 @@ public async Task SetSmartSwitch_returns_false_when_no_live_socket()
         var (provider, supervisor, _) = CreateHarness(source);
         await using var disposeProvider = provider;
 
-        Assert.False(await supervisor.SetSmartSwitchAsync(10UL, Guid.NewGuid(), 42UL, true, CancellationToken.None));
+        Assert.Equal(DeviceReachability.NoResponse,
+            await supervisor.SetSmartSwitchAsync(10UL, Guid.NewGuid(), 42UL, true, CancellationToken.None));
     }
 
     [Fact]

tests/RustPlusBot.Features.Switches.Tests/Fakes/KeyEchoLocalizer.cs

@@ -0,0 +1,13 @@
+using RustPlusBot.Localization;
+
+namespace RustPlusBot.Features.Switches.Tests.Fakes;
+
+/// <summary>Test double: returns the key unchanged, enabling key-based assertions without depending on real resource strings.</summary>
+internal sealed class KeyEchoLocalizer : ILocalizer
+{
+    /// <inheritdoc />
+    public string Get(string key, string culture) => key;
+
+    /// <inheritdoc />
+    public string Get(string key, string culture, params object[] args) => key;
+}

tests/RustPlusBot.Features.Switches.Tests/SwitchActuationReplyTests.cs

@@ -0,0 +1,31 @@
+using RustPlusBot.Abstractions.Connections;
+using RustPlusBot.Features.Switches.Modules;
+using RustPlusBot.Features.Switches.Tests.Fakes;
+using RustPlusBot.Localization;
+
+namespace RustPlusBot.Features.Switches.Tests;
+
+public sealed class SwitchActuationReplyTests
+{
+    [Theory]
+    [InlineData(DeviceReachability.Removed, "switch.actuation.removed")]
+    [InlineData(DeviceReachability.NoPrivilege, "switch.actuation.noprivilege")]
+    [InlineData(DeviceReachability.NoResponse, "switch.actuation.noresponse")]
+    public void Describe_NonReachable_ReturnsReasonText(DeviceReachability reachability, string expectedKey)
+    {
+        // Fake localizer returns the key it is given (same pattern as other Switches.Tests).
+        var text = SwitchActuationReply.Describe(reachability, new KeyEchoLocalizer(), "en");
+        Assert.Equal(expectedKey, text);
+    }
+
+    [Theory]
+    [InlineData(DeviceReachability.Removed, "This switch was removed in-game.")]
+    [InlineData(DeviceReachability.NoPrivilege, "No building privilege for this switch.")]
+    [InlineData(DeviceReachability.NoResponse, "The switch didn't respond. Try again.")]
+    public void Describe_NonReachable_ReturnsCorrectEnglishText(DeviceReachability reachability, string expectedText)
+    {
+        // Real localizer for final EN text verification.
+        var text = SwitchActuationReply.Describe(reachability, new ResxLocalizer(), "en");
+        Assert.Equal(expectedText, text);
+    }
+}

tests/RustPlusBot.Localization.Tests/StringsResourceParityTests.cs

@@ -42,6 +42,6 @@ public void English_covers_every_french_key()
     [Fact]
     public void Catalog_has_expected_key_count()
     {
-        Assert.Equal(257, EnglishKeys().Count);
+        Assert.Equal(260, EnglishKeys().Count);
     }
 }