fix(db): classify transient vs permanent SQL errors in Database.CachedWrite (#7)

CachedWrite buffered ALL write failures and retried forever, never returning a synchronous failure to the script — permanent SQL errors (constraint/syntax/ permission) were treated as transient. Mirror the External-System API path: attempt immediately, return Failed synchronously on permanent SQL errors (no buffering), buffer only transient errors; the S&F retry path parks permanent failures instead of retrying forever. New SqlErrorClassifier + PermanentDatabaseException.
2026-06-15 13:53:15 -04:00
parent 198770f578
commit d05270640d
7 changed files with 907 additions and 29 deletions
@@ -0,0 +1,65 @@
+namespace ZB.MOM.WW.ScadaBridge.ExternalSystemGateway.Tests;
+
+/// <summary>
+/// M2.3 (#7): unit tests for the transient-vs-permanent SQL error-number
+/// classifier that <c>DatabaseGateway</c> uses to decide whether a failed
+/// cached write should be buffered (transient) or returned to the script
+/// synchronously / parked (permanent).
+/// </summary>
+public class SqlErrorClassifierTests
+{
+    // The full transient set documented on SqlErrorClassifier — connection,
+    // timeout, deadlock, and Azure throttle error numbers. A retry can plausibly
+    // succeed for any of these, so they are buffered to store-and-forward.
+    [Theory]
+    [InlineData(-2)]      // timeout expired
+    [InlineData(-1)]      // connection error
+    [InlineData(2)]       // network / instance not found
+    [InlineData(53)]      // network path not found
+    [InlineData(64)]      // connection terminated mid-session
+    [InlineData(233)]     // no process on the other end of the pipe
+    [InlineData(1205)]    // deadlock victim
+    [InlineData(10053)]   // transport-level abort
+    [InlineData(10054)]   // connection reset by peer
+    [InlineData(10060)]   // connection timed out
+    [InlineData(40197)]   // Azure SQL service error, retry
+    [InlineData(40501)]   // Azure SQL service busy
+    [InlineData(40613)]   // Azure SQL database unavailable
+    [InlineData(49918)]   // Azure SQL cannot process request (throttle)
+    [InlineData(49919)]   // Azure SQL too many create/update operations
+    [InlineData(49920)]   // Azure SQL too many operations (throttle)
+    public void IsTransient_KnownTransientNumber_ReturnsTrue(int errorNumber)
+    {
+        Assert.True(SqlErrorClassifier.IsTransient(errorNumber));
+    }
+
+    // Constraint, syntax, and permission errors are permanent — retrying the
+    // identical statement cannot succeed and may cause duplicate side effects.
+    [Theory]
+    [InlineData(547)]   // constraint violation (FK/CHECK)
+    [InlineData(2627)]  // primary-key / unique constraint violation
+    [InlineData(2601)]  // duplicate key in a unique index
+    [InlineData(102)]   // incorrect syntax
+    [InlineData(156)]   // incorrect syntax near a keyword
+    [InlineData(207)]   // invalid column name
+    [InlineData(208)]   // invalid object name
+    [InlineData(229)]   // permission denied on object
+    [InlineData(230)]   // permission denied on column
+    [InlineData(262)]   // permission denied (CREATE etc.)
+    public void IsTransient_KnownPermanentNumber_ReturnsFalse(int errorNumber)
+    {
+        Assert.False(SqlErrorClassifier.IsTransient(errorNumber));
+    }
+
+    [Theory]
+    [InlineData(0)]       // no error number captured
+    [InlineData(99999)]   // unknown / undocumented number
+    [InlineData(12345)]
+    [InlineData(int.MaxValue)]
+    public void IsTransient_UnknownNumber_DefaultsToPermanent(int errorNumber)
+    {
+        // Fail-fast is the safer default: an unrecognised error number must NOT
+        // be silently retried forever. Unknown => permanent => false.
+        Assert.False(SqlErrorClassifier.IsTransient(errorNumber));
+    }
+}