feat(connections): AFK hysteresis tracking in TeamStateTracker

HandyS11 · HandyS11 · commit a1bace9a8af6 · 2026-06-18T21:25:32.000+02:00
diff --git a/src/RustPlusBot.Features.Connections/ConnectionOptions.cs b/src/RustPlusBot.Features.Connections/ConnectionOptions.cs
@@ -35,4 +35,10 @@ public sealed class ConnectionOptions
 
     /// <summary>How often the rig-timer tick advances rig phases and emits timed boundary events. Default 30s.</summary>
     public TimeSpan RigTickInterval { get; set; } = TimeSpan.FromSeconds(30);
+
+    /// <summary>How long a member must be still (and online + alive) before being flagged AFK. Default 5m.</summary>
+    public TimeSpan AfkThreshold { get; set; } = TimeSpan.FromMinutes(5);
+
+    /// <summary>Movement tolerance (world units) below which a member is considered still. Default 1.</summary>
+    public float AfkEpsilon { get; set; } = 1f;
 }
diff --git a/src/RustPlusBot.Features.Connections/Listening/TeamStateTracker.cs b/src/RustPlusBot.Features.Connections/Listening/TeamStateTracker.cs
@@ -7,11 +7,17 @@ namespace RustPlusBot.Features.Connections.Listening;
 internal sealed class TeamStateTracker
 {
     private Dictionary<ulong, TeamMemberSnapshot>? _baseline;
+    private readonly Dictionary<ulong, DateTimeOffset> _stillSince = new();
+    private readonly HashSet<ulong> _afk = new();
 
     /// <summary>Diffs <paramref name="snapshot"/> against the previous one. First non-null call primes silently.</summary>
     /// <param name="snapshot">The latest team snapshot, or null when the poll returned no data.</param>
+    /// <param name="now">Current wall-clock time (from <c>IClock.UtcNow</c>).</param>
+    /// <param name="afkThreshold">How long a member must be still before being flagged AFK.</param>
+    /// <param name="afkEpsilon">Movement tolerance (world units) below which a member is considered still.</param>
     /// <returns>The transitions since the previous snapshot; empty on prime, null input, or no change.</returns>
-    public IReadOnlyList<PlayerTransition> Diff(TeamInfoSnapshot? snapshot)
+    public IReadOnlyList<PlayerTransition> Diff(
+        TeamInfoSnapshot? snapshot, DateTimeOffset now, TimeSpan afkThreshold, float afkEpsilon)
     {
         if (snapshot is null)
         {
@@ -22,42 +28,91 @@ public IReadOnlyList<PlayerTransition> Diff(TeamInfoSnapshot? snapshot)
 
         if (_baseline is null)
         {
-            _baseline = current; // first poll: silent baseline
+            _baseline = current;
+            foreach (var m in current.Values)
+            {
+                _stillSince[m.SteamId] = now;
+            }
+
             return [];
         }
 
         var transitions = new List<PlayerTransition>();
-        foreach (var (id, now) in current)
+        foreach (var (id, nowMember) in current)
         {
             if (!_baseline.TryGetValue(id, out var was))
             {
-                continue; // brand-new member: prime silently this poll
+                _stillSince[id] = now; // prime new member's stillness clock
+                continue;
             }
 
-            if (now.IsOnline && !was.IsOnline)
-            {
-                transitions.Add(new PlayerTransition(PlayerTransitionKind.Connect, id, now.Name, null));
-            }
-            else if (!now.IsOnline && was.IsOnline)
-            {
-                transitions.Add(new PlayerTransition(PlayerTransitionKind.Disconnect, id, now.Name, null));
-            }
+            AddPresenceTransitions(transitions, id, was, nowMember, snapshot);
+            UpdateAfk(transitions, id, was, nowMember, now, afkThreshold, afkEpsilon);
+        }
+
+        _baseline = current;
+        return transitions;
+    }
+
+    private static void AddPresenceTransitions(
+        List<PlayerTransition> transitions, ulong id,
+        TeamMemberSnapshot was, TeamMemberSnapshot now, TeamInfoSnapshot snapshot)
+    {
+        if (now.IsOnline && !was.IsOnline)
+        {
+            transitions.Add(new PlayerTransition(PlayerTransitionKind.Connect, id, now.Name, null));
+        }
+        else if (!now.IsOnline && was.IsOnline)
+        {
+            transitions.Add(new PlayerTransition(PlayerTransitionKind.Disconnect, id, now.Name, null));
+        }
 
-            if (now.LastDeathTimeUtc > was.LastDeathTimeUtc)
+        if (now.LastDeathTimeUtc > was.LastDeathTimeUtc)
+        {
+            transitions.Add(new PlayerTransition(
+                PlayerTransitionKind.Death, id, now.Name, ResolveDeathLocation(id, snapshot, was)));
+        }
+
+        if (now.LastSpawnTimeUtc > was.LastSpawnTimeUtc)
+        {
+            transitions.Add(new PlayerTransition(PlayerTransitionKind.Respawn, id, now.Name, (now.X, now.Y)));
+        }
+    }
+
+    private void UpdateAfk(
+        List<PlayerTransition> transitions, ulong id,
+        TeamMemberSnapshot was, TeamMemberSnapshot now, DateTimeOffset clock, TimeSpan threshold, float epsilon)
+    {
+        var eligible = now.IsOnline && now.IsAlive;
+        if (!eligible)
+        {
+            if (_afk.Remove(id))
             {
-                transitions.Add(new PlayerTransition(
-                    PlayerTransitionKind.Death, id, now.Name, ResolveDeathLocation(id, snapshot, was)));
+                transitions.Add(new PlayerTransition(PlayerTransitionKind.ReturnedFromAfk, id, now.Name, null));
             }
 
-            if (now.LastSpawnTimeUtc > was.LastSpawnTimeUtc)
+            _stillSince[id] = clock;
+            return;
+        }
+
+        var moved = Math.Abs(now.X - was.X) > epsilon || Math.Abs(now.Y - was.Y) > epsilon;
+        if (moved)
+        {
+            _stillSince[id] = clock;
+            if (_afk.Remove(id))
             {
-                transitions.Add(new PlayerTransition(
-                    PlayerTransitionKind.Respawn, id, now.Name, (now.X, now.Y)));
+                transitions.Add(new PlayerTransition(PlayerTransitionKind.ReturnedFromAfk, id, now.Name, null));
             }
+
+            return;
         }
 
-        _baseline = current;
-        return transitions;
+        var since = _stillSince.TryGetValue(id, out var s) ? s : clock;
+        _stillSince.TryAdd(id, since);
+        if (clock - since >= threshold && _afk.Add(id))
+        {
+            transitions.Add(new PlayerTransition(PlayerTransitionKind.BecameAfk, id, now.Name, (now.X, now.Y)));
+        }
     }
 
     private static (float X, float Y)? ResolveDeathLocation(
diff --git a/src/RustPlusBot.Features.Connections/Supervisor/ConnectionSupervisor.cs b/src/RustPlusBot.Features.Connections/Supervisor/ConnectionSupervisor.cs
@@ -5,6 +5,7 @@
 using Microsoft.Extensions.Options;
 using RustPlusBot.Abstractions.Credentials;
 using RustPlusBot.Abstractions.Events;
+using RustPlusBot.Abstractions.Time;
 using RustPlusBot.Discord.Notifications;
 using RustPlusBot.Domain.Connections;
 using RustPlusBot.Domain.Credentials;
@@ -20,6 +21,7 @@ namespace RustPlusBot.Features.Connections.Supervisor;
 /// <param name="dmSender">DMs an owner when their credential is rejected.</param>
 /// <param name="protector">Unprotects stored tokens before connecting.</param>
 /// <param name="eventBus">Publishes ConnectionStatusChangedEvent on state changes.</param>
+/// <param name="clock">Wall-clock source used for AFK hysteresis timestamps.</param>
 /// <param name="options">Timeouts/backoff/heartbeat settings.</param>
 /// <param name="logger">The logger.</param>
 internal sealed partial class ConnectionSupervisor(
@@ -28,6 +30,7 @@ internal sealed partial class ConnectionSupervisor(
     IUserDmSender dmSender,
     ICredentialProtector protector,
     IEventBus eventBus,
+    IClock clock,
     IOptions<ConnectionOptions> options,
     ILogger<ConnectionSupervisor> logger) : IConnectionSupervisor, ITeamChatSender, IRustServerQuery, IAsyncDisposable
 {
@@ -478,7 +481,7 @@ await eventBus.PublishAsync(
                 await DetectRigActivationsAsync(key, current, rigs, dims, rigsInRadius, ct).ConfigureAwait(false);
 
                 var team = await connection.GetTeamInfoAsync(_options.HeartbeatTimeout, ct).ConfigureAwait(false);
-                var transitions = tracker.Diff(team);
+                var transitions = tracker.Diff(team, clock.UtcNow, _options.AfkThreshold, _options.AfkEpsilon);
                 if (transitions.Count > 0)
                 {
                     await eventBus.PublishAsync(
diff --git a/tests/RustPlusBot.Features.Connections.Tests/TeamStateTrackerAfkTests.cs b/tests/RustPlusBot.Features.Connections.Tests/TeamStateTrackerAfkTests.cs
@@ -0,0 +1,68 @@
+using RustPlusBot.Abstractions.Events;
+using RustPlusBot.Features.Connections.Listening;
+
+namespace RustPlusBot.Features.Connections.Tests;
+
+public sealed class TeamStateTrackerAfkTests
+{
+    private static readonly TimeSpan Threshold = TimeSpan.FromMinutes(5);
+    private const float Eps = 1f;
+
+    private static TeamMemberSnapshot Member(ulong id, float x, float y, bool online = true, bool alive = true)
+        => new(id, $"P{id}", x, y, online, alive, DateTimeOffset.UnixEpoch, DateTimeOffset.UnixEpoch);
+
+    private static TeamInfoSnapshot Team(params TeamMemberSnapshot[] m) => new(1, m);
+
+    [Fact]
+    public void Still_for_threshold_emits_one_BecameAfk()
+    {
+        var t = new TeamStateTracker();
+        var t0 = DateTimeOffset.UnixEpoch;
+        t.Diff(Team(Member(1, 0, 0)), t0, Threshold, Eps);                       // prime
+        Assert.Empty(t.Diff(Team(Member(1, 0, 0)), t0.AddMinutes(2), Threshold, Eps)); // still, < threshold
+        var afk = t.Diff(Team(Member(1, 0, 0)), t0.AddMinutes(6), Threshold, Eps);     // crossed
+        Assert.Single(afk, x => x.Kind == PlayerTransitionKind.BecameAfk && x.Location == (0f, 0f));
+        Assert.Empty(t.Diff(Team(Member(1, 0, 0)), t0.AddMinutes(9), Threshold, Eps)); // latched, no repeat
+    }
+
+    [Fact]
+    public void Moving_after_afk_emits_ReturnedFromAfk()
+    {
+        var t = new TeamStateTracker();
+        var t0 = DateTimeOffset.UnixEpoch;
+        t.Diff(Team(Member(1, 0, 0)), t0, Threshold, Eps);
+        t.Diff(Team(Member(1, 0, 0)), t0.AddMinutes(6), Threshold, Eps);          // BecameAfk
+        var back = t.Diff(Team(Member(1, 50, 50)), t0.AddMinutes(7), Threshold, Eps);
+        Assert.Single(back, x => x.Kind == PlayerTransitionKind.ReturnedFromAfk && x.Location == null);
+    }
+
+    [Fact]
+    public void Going_offline_while_afk_emits_ReturnedFromAfk()
+    {
+        var t = new TeamStateTracker();
+        var t0 = DateTimeOffset.UnixEpoch;
+        t.Diff(Team(Member(1, 0, 0)), t0, Threshold, Eps);
+        t.Diff(Team(Member(1, 0, 0)), t0.AddMinutes(6), Threshold, Eps);          // BecameAfk
+        var off = t.Diff(Team(Member(1, 0, 0, online: false)), t0.AddMinutes(7), Threshold, Eps);
+        Assert.Contains(off, x => x.Kind == PlayerTransitionKind.ReturnedFromAfk);
+    }
+
+    [Fact]
+    public void Dead_member_is_never_afk()
+    {
+        var t = new TeamStateTracker();
+        var t0 = DateTimeOffset.UnixEpoch;
+        t.Diff(Team(Member(1, 0, 0, alive: false)), t0, Threshold, Eps);
+        Assert.Empty(t.Diff(Team(Member(1, 0, 0, alive: false)), t0.AddMinutes(10), Threshold, Eps));
+    }
+
+    [Fact]
+    public void Small_jitter_below_epsilon_still_counts_as_still()
+    {
+        var t = new TeamStateTracker();
+        var t0 = DateTimeOffset.UnixEpoch;
+        t.Diff(Team(Member(1, 0, 0)), t0, Threshold, Eps);
+        var afk = t.Diff(Team(Member(1, 0.5f, 0.5f)), t0.AddMinutes(6), Threshold, Eps); // < 1 unit move
+        Assert.Single(afk, x => x.Kind == PlayerTransitionKind.BecameAfk);
+    }
+}
diff --git a/tests/RustPlusBot.Features.Connections.Tests/TeamStateTrackerTests.cs b/tests/RustPlusBot.Features.Connections.Tests/TeamStateTrackerTests.cs
@@ -17,45 +17,45 @@ private static TeamInfoSnapshot Team(ulong leader, params TeamMemberSnapshot[] m
     public void First_snapshot_primes_silently()
     {
         var tracker = new TeamStateTracker();
-        var result = tracker.Diff(Team(1, Member(1)));
+        var result = tracker.Diff(Team(1, Member(1)), DateTimeOffset.UnixEpoch, TimeSpan.FromMinutes(5), 1f);
         Assert.Empty(result);
     }
 
     [Fact]
     public void Null_snapshot_emits_nothing_and_keeps_baseline()
     {
         var tracker = new TeamStateTracker();
-        tracker.Diff(Team(1, Member(1, online: true)));
-        Assert.Empty(tracker.Diff(null));
+        tracker.Diff(Team(1, Member(1, online: true)), DateTimeOffset.UnixEpoch, TimeSpan.FromMinutes(5), 1f);
+        Assert.Empty(tracker.Diff(null, DateTimeOffset.UnixEpoch, TimeSpan.FromMinutes(5), 1f));
         // After the null, an offline flip is still detected against the original baseline.
-        var result = tracker.Diff(Team(1, Member(1, online: false)));
+        var result = tracker.Diff(Team(1, Member(1, online: false)), DateTimeOffset.UnixEpoch, TimeSpan.FromMinutes(5), 1f);
         Assert.Single(result, t => t.Kind == PlayerTransitionKind.Disconnect);
     }
 
     [Fact]
     public void Brand_new_member_is_primed_silently()
     {
         var tracker = new TeamStateTracker();
-        tracker.Diff(Team(1, Member(1)));
-        var result = tracker.Diff(Team(1, Member(1), Member(2, online: true)));
+        tracker.Diff(Team(1, Member(1)), DateTimeOffset.UnixEpoch, TimeSpan.FromMinutes(5), 1f);
+        var result = tracker.Diff(Team(1, Member(1), Member(2, online: true)), DateTimeOffset.UnixEpoch, TimeSpan.FromMinutes(5), 1f);
         Assert.DoesNotContain(result, t => t.SteamId == 2);
     }
 
     [Fact]
     public void Connect_detected_on_offline_to_online()
     {
         var tracker = new TeamStateTracker();
-        tracker.Diff(Team(1, Member(1, online: false)));
-        var result = tracker.Diff(Team(1, Member(1, online: true)));
+        tracker.Diff(Team(1, Member(1, online: false)), DateTimeOffset.UnixEpoch, TimeSpan.FromMinutes(5), 1f);
+        var result = tracker.Diff(Team(1, Member(1, online: true)), DateTimeOffset.UnixEpoch, TimeSpan.FromMinutes(5), 1f);
         Assert.Single(result, t => t.Kind == PlayerTransitionKind.Connect && t.SteamId == 1);
     }
 
     [Fact]
     public void Disconnect_detected_on_online_to_offline()
     {
         var tracker = new TeamStateTracker();
-        tracker.Diff(Team(1, Member(1, online: true)));
-        var result = tracker.Diff(Team(1, Member(1, online: false)));
+        tracker.Diff(Team(1, Member(1, online: true)), DateTimeOffset.UnixEpoch, TimeSpan.FromMinutes(5), 1f);
+        var result = tracker.Diff(Team(1, Member(1, online: false)), DateTimeOffset.UnixEpoch, TimeSpan.FromMinutes(5), 1f);
         Assert.Single(result, t => t.Kind == PlayerTransitionKind.Disconnect && t.SteamId == 1);
     }
 
@@ -64,9 +64,9 @@ public void Death_detected_on_deathtime_advance_even_if_alive_again()
     {
         var t0 = DateTimeOffset.UnixEpoch;
         var tracker = new TeamStateTracker();
-        tracker.Diff(Team(1, Member(1, alive: true, death: t0)));
+        tracker.Diff(Team(1, Member(1, alive: true, death: t0)), DateTimeOffset.UnixEpoch, TimeSpan.FromMinutes(5), 1f);
         // Died and already respawned: IsAlive true both times, but LastDeathTime advanced.
-        var result = tracker.Diff(Team(1, Member(1, alive: true, death: t0.AddMinutes(1))));
+        var result = tracker.Diff(Team(1, Member(1, alive: true, death: t0.AddMinutes(1))), DateTimeOffset.UnixEpoch, TimeSpan.FromMinutes(5), 1f);
         Assert.Contains(result, t => t.Kind == PlayerTransitionKind.Death && t.SteamId == 1);
     }
 
@@ -75,8 +75,8 @@ public void Respawn_detected_on_spawntime_advance_with_current_location()
     {
         var t0 = DateTimeOffset.UnixEpoch;
         var tracker = new TeamStateTracker();
-        tracker.Diff(Team(1, Member(1, spawn: t0)));
-        var result = tracker.Diff(Team(1, Member(1, x: 50, y: 60, spawn: t0.AddMinutes(1))));
+        tracker.Diff(Team(1, Member(1, spawn: t0)), DateTimeOffset.UnixEpoch, TimeSpan.FromMinutes(5), 1f);
+        var result = tracker.Diff(Team(1, Member(1, x: 50, y: 60, spawn: t0.AddMinutes(1))), DateTimeOffset.UnixEpoch, TimeSpan.FromMinutes(5), 1f);
         var respawn = Assert.Single(result, t => t.Kind == PlayerTransitionKind.Respawn);
         Assert.Equal((50f, 60f), respawn.Location);
     }
@@ -86,16 +86,16 @@ public void Unchanged_snapshot_emits_nothing()
     {
         var tracker = new TeamStateTracker();
         var m = Member(1, spawn: DateTimeOffset.UnixEpoch, death: DateTimeOffset.UnixEpoch);
-        tracker.Diff(new TeamInfoSnapshot(1, [m]));
-        Assert.Empty(tracker.Diff(new TeamInfoSnapshot(1, [m])));
+        tracker.Diff(new TeamInfoSnapshot(1, [m]), DateTimeOffset.UnixEpoch, TimeSpan.FromMinutes(5), 1f);
+        Assert.Empty(tracker.Diff(new TeamInfoSnapshot(1, [m]), DateTimeOffset.UnixEpoch, TimeSpan.FromMinutes(5), 1f));
     }
 
     [Fact]
     public void Connect_and_disconnect_have_no_location()
     {
         var tracker = new TeamStateTracker();
-        tracker.Diff(Team(1, Member(1, online: false)));
-        var result = tracker.Diff(Team(1, Member(1, online: true, x: 9, y: 9)));
+        tracker.Diff(Team(1, Member(1, online: false)), DateTimeOffset.UnixEpoch, TimeSpan.FromMinutes(5), 1f);
+        var result = tracker.Diff(Team(1, Member(1, online: true, x: 9, y: 9)), DateTimeOffset.UnixEpoch, TimeSpan.FromMinutes(5), 1f);
         Assert.Null(Assert.Single(result).Location);
     }
 
@@ -104,9 +104,9 @@ public void Leader_death_uses_deathnote_location()
     {
         var t0 = DateTimeOffset.UnixEpoch;
         var tracker = new TeamStateTracker();
-        tracker.Diff(new TeamInfoSnapshot(1, [Member(1, death: t0)]));
+        tracker.Diff(new TeamInfoSnapshot(1, [Member(1, death: t0)]), DateTimeOffset.UnixEpoch, TimeSpan.FromMinutes(5), 1f);
         var snap = new TeamInfoSnapshot(1, [Member(1, x: 1, y: 1, death: t0.AddMinutes(1))], (700f, 800f));
-        var death = Assert.Single(tracker.Diff(snap), t => t.Kind == PlayerTransitionKind.Death);
+        var death = Assert.Single(tracker.Diff(snap, DateTimeOffset.UnixEpoch, TimeSpan.FromMinutes(5), 1f), t => t.Kind == PlayerTransitionKind.Death);
         Assert.Equal((700f, 800f), death.Location);
     }
 
@@ -116,10 +116,10 @@ public void Nonleader_death_uses_previous_poll_position_not_current()
         var t0 = DateTimeOffset.UnixEpoch;
         var tracker = new TeamStateTracker();
         // Member 2 is alive at (10,10) on the baseline poll...
-        tracker.Diff(new TeamInfoSnapshot(1, [Member(1), Member(2, x: 10, y: 10, death: t0)]));
+        tracker.Diff(new TeamInfoSnapshot(1, [Member(1), Member(2, x: 10, y: 10, death: t0)]), DateTimeOffset.UnixEpoch, TimeSpan.FromMinutes(5), 1f);
         // ...then dies and respawns at (999,999); death must report the PRE-death (10,10).
         var snap = new TeamInfoSnapshot(1, [Member(1), Member(2, x: 999, y: 999, death: t0.AddMinutes(1))], (5f, 5f));
-        var death = Assert.Single(tracker.Diff(snap), t => t.Kind == PlayerTransitionKind.Death);
+        var death = Assert.Single(tracker.Diff(snap, DateTimeOffset.UnixEpoch, TimeSpan.FromMinutes(5), 1f), t => t.Kind == PlayerTransitionKind.Death);
         Assert.Equal((10f, 10f), death.Location); // leader DeathNote (5,5) must NOT apply to a non-leader
     }
 
@@ -129,9 +129,9 @@ public void Death_with_no_prior_position_and_no_deathnote_has_null_location()
         var t0 = DateTimeOffset.UnixEpoch;
         var tracker = new TeamStateTracker();
         // Prime member 1 only.
-        tracker.Diff(new TeamInfoSnapshot(1, [Member(1)]));
+        tracker.Diff(new TeamInfoSnapshot(1, [Member(1)]), DateTimeOffset.UnixEpoch, TimeSpan.FromMinutes(5), 1f);
         // Member 2 appears already-dead-advanced in the same poll it is first seen → primed silently, no death.
-        var first = tracker.Diff(new TeamInfoSnapshot(1, [Member(1), Member(2, death: t0)]));
+        var first = tracker.Diff(new TeamInfoSnapshot(1, [Member(1), Member(2, death: t0)]), DateTimeOffset.UnixEpoch, TimeSpan.FromMinutes(5), 1f);
         Assert.DoesNotContain(first, t => t.SteamId == 2);
     }
 }
