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/StoreAndForwardStorage.cs

@@ -164,6 +164,47 @@ public class StoreAndForwardStorage
         await cmd.ExecuteNonQueryAsync();
     }
 
+    /// <summary>
+    /// WP-10: Updates a message after a delivery attempt, but only if the row is still
+    /// in the expected status. Returns true if the row was updated, false if it had
+    /// already been changed (e.g. an operator retried or discarded the message) and so
+    /// was skipped.
+    ///
+    /// StoreAndForward-005: the retry sweep uses this for its state-changing writes so
+    /// it cannot clobber a concurrent operator action (RetryParkedMessageAsync /
+    /// DiscardParkedMessageAsync). Those operator operations are themselves SQL-
+    /// conditional on <c>status = Parked</c>; making the sweep's writes conditional on
+    /// the status the sweep observed closes the sweep-vs-management race rather than
+    /// relying only on the in-process overlapping-sweep guard.
+    /// </summary>
+    public async Task<bool> UpdateMessageIfStatusAsync(
+        StoreAndForwardMessage message,
+        StoreAndForwardMessageStatus expectedStatus)
+    {
+        await using var connection = new SqliteConnection(_connectionString);
+        await connection.OpenAsync();
+
+        await using var cmd = connection.CreateCommand();
+        cmd.CommandText = @"
+            UPDATE sf_messages
+            SET retry_count = @retryCount,
+                last_attempt_at = @lastAttempt,
+                status = @status,
+                last_error = @lastError
+            WHERE id = @id AND status = @expectedStatus";
+
+        cmd.Parameters.AddWithValue("@id", message.Id);
+        cmd.Parameters.AddWithValue("@retryCount", message.RetryCount);
+        cmd.Parameters.AddWithValue("@lastAttempt", message.LastAttemptAt.HasValue
+            ? message.LastAttemptAt.Value.ToString("O") : DBNull.Value);
+        cmd.Parameters.AddWithValue("@status", (int)message.Status);
+        cmd.Parameters.AddWithValue("@lastError", (object?)message.LastError ?? DBNull.Value);
+        cmd.Parameters.AddWithValue("@expectedStatus", (int)expectedStatus);
+
+        var rows = await cmd.ExecuteNonQueryAsync();
+        return rows > 0;
+    }
+
     /// <summary>
     /// WP-10: Removes a successfully delivered message.
     /// </summary>
@@ -221,6 +262,13 @@ public class StoreAndForwardStorage
 
     /// <summary>
     /// WP-12: Moves a parked message back to pending for retry.
+    ///
+    /// StoreAndForward-010: <c>last_attempt_at</c> is reset to NULL so the re-queued
+    /// message is unambiguously due on the next retry sweep. An operator-initiated
+    /// retry means "attempt this again now"; leaving the stale parked timestamp in
+    /// place would make the message's retry timing depend on the configured retry
+    /// interval relative to the original (pre-park) attempt — "try immediately" only
+    /// by accident, and a long interval would instead delay the operator's retry.
     /// </summary>
     public async Task<bool> RetryParkedMessageAsync(string messageId)
     {
@@ -230,7 +278,7 @@ public class StoreAndForwardStorage
         await using var cmd = connection.CreateCommand();
         cmd.CommandText = @"
             UPDATE sf_messages
-            SET status = @pending, retry_count = 0, last_error = NULL
+            SET status = @pending, retry_count = 0, last_error = NULL, last_attempt_at = NULL
             WHERE id = @id AND status = @parked";
 
         cmd.Parameters.AddWithValue("@id", messageId);