fix(store-and-forward): resolve StoreAndForward-004,005,010,013 — accurate handler-contract doc, conditional sweep writes, reset LastAttemptAt on parked retry, test coverage

src/ScadaLink.StoreAndForward/StoreAndForwardService.cs

@@ -36,8 +36,20 @@ public class StoreAndForwardService
     private int _retryInProgress;
 
     /// <summary>
-    /// WP-10: Delivery handler delegate. Returns true on success, throws on transient failure.
-    /// Permanent failures should return false (message will NOT be buffered).
+    /// WP-10: Delivery handler delegate. The return value / exception is interpreted
+    /// the same way on both the immediate-delivery path (<see cref="EnqueueAsync"/>)
+    /// and the background retry path (<c>RetryMessageAsync</c>):
+    /// <list type="bullet">
+    ///   <item><description><c>true</c> — delivered successfully. The message is
+    ///   removed from the buffer (or, on the immediate path, never buffered).</description></item>
+    ///   <item><description><c>false</c> — permanent failure. On the immediate path
+    ///   the message is NOT buffered; on a retry the message is already buffered and
+    ///   is parked immediately (no further retries).</description></item>
+    ///   <item><description>throws — transient failure. On the immediate path the
+    ///   message is buffered for retry; on a retry the retry count is incremented and
+    ///   the message is parked once <see cref="StoreAndForwardMessage.MaxRetries"/> is
+    ///   reached.</description></item>
+    /// </list>
     /// </summary>
     private readonly Dictionary<StoreAndForwardCategory, Func<StoreAndForwardMessage, Task<bool>>> _deliveryHandlers = new();
 
@@ -59,7 +71,9 @@ public class StoreAndForwardService
     }
 
     /// <summary>
-    /// Registers a delivery handler for a given message category.
+    /// Registers a delivery handler for a given message category. See the
+    /// <c>_deliveryHandlers</c> field documentation for the true/false/throws contract,
+    /// which applies identically on the immediate and retry paths.
     /// </summary>
     public void RegisterDeliveryHandler(
         StoreAndForwardCategory category,
@@ -241,11 +255,22 @@ public class StoreAndForwardService
                 return;
             }
 
-            // Permanent failure on retry — park immediately
+            // Permanent failure on retry — park immediately.
+            // StoreAndForward-005: the sweep observed this row as Pending; only commit
+            // the park if it is still Pending so a concurrent operator action that
+            // moved it (retry/discard) is not silently overwritten.
             message.Status = StoreAndForwardMessageStatus.Parked;
             message.LastAttemptAt = DateTimeOffset.UtcNow;
             message.LastError = "Permanent failure (handler returned false)";
-            await _storage.UpdateMessageAsync(message);
+            var parked = await _storage.UpdateMessageIfStatusAsync(
+                message, StoreAndForwardMessageStatus.Pending);
+            if (!parked)
+            {
+                _logger.LogDebug(
+                    "Message {MessageId} changed status during delivery; sweep park skipped",
+                    message.Id);
+                return;
+            }
             _replication?.ReplicatePark(message);
             RaiseActivity("Parked", message.Category,
                 $"Permanent failure for {message.Target}: handler returned false");
@@ -259,8 +284,18 @@ public class StoreAndForwardService
 
             if (message.MaxRetries > 0 && message.RetryCount >= message.MaxRetries)
             {
+                // StoreAndForward-005: conditional park — see the permanent-failure
+                // branch above for rationale.
                 message.Status = StoreAndForwardMessageStatus.Parked;
-                await _storage.UpdateMessageAsync(message);
+                var parked = await _storage.UpdateMessageIfStatusAsync(
+                    message, StoreAndForwardMessageStatus.Pending);
+                if (!parked)
+                {
+                    _logger.LogDebug(
+                        "Message {MessageId} changed status during delivery; sweep park skipped",
+                        message.Id);
+                    return;
+                }
                 _replication?.ReplicatePark(message);
                 RaiseActivity("Parked", message.Category,
                     $"Max retries ({message.MaxRetries}) reached for {message.Target}");
@@ -270,7 +305,17 @@ public class StoreAndForwardService
             }
             else
             {
-                await _storage.UpdateMessageAsync(message);
+                // StoreAndForward-005: the retry-count increment is also conditional
+                // on the row still being Pending so it cannot clobber an operator
+                // action that ran during the failed delivery.
+                if (!await _storage.UpdateMessageIfStatusAsync(
+                        message, StoreAndForwardMessageStatus.Pending))
+                {
+                    _logger.LogDebug(
+                        "Message {MessageId} changed status during delivery; sweep retry-count update skipped",
+                        message.Id);
+                    return;
+                }
                 RaiseActivity("Retried", message.Category,
                     $"Retry {message.RetryCount}/{message.MaxRetries} for {message.Target}: {ex.Message}");
             }