Merge branch 'feature/uniqueness-sqlite-deployment-hardening'

SQLite deployment hardening for the Uniqueness library: WAL + busy_timeout
enforced on every connection open, with a read-back guard that fails the boot
if SQLite silently refuses WAL. All three assertions mutation-proven
load-bearing (M32/M33/M34 each RED). 41/41.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012eBz8Xt5TA1LbF94tdbMZV

Author: rafalmaciag

src/MicroPlumberd.Services.Uniqueness.Sqlite/MicroPlumberd.Services.Uniqueness.Sqlite.csproj

@@ -11,6 +11,14 @@
 
   <ItemGroup>
     <PackageReference Include="Microsoft.EntityFrameworkCore.Sqlite" Version="10.0.7" />
+    <!--
+      Pins the native SQLite bundle off GHSA-2m69-gcr7-jv3q (High): SQLitePCLRaw.lib.e_sqlite3 <= 2.1.11
+      has a vulnerable dependency on SQLite. EF Core Sqlite 10.0.7 resolves the family to 2.1.11
+      transitively, so without this pin the vulnerability ships to every consumer of this package.
+      The bundle drags core/lib/provider with it, so one pin lifts all four.
+      Remove once Microsoft.EntityFrameworkCore.Sqlite depends on 2.1.12 or later by itself.
+    -->
+    <PackageReference Include="SQLitePCLRaw.bundle_e_sqlite3" Version="2.1.12" />
   </ItemGroup>
 
   <ItemGroup>

src/MicroPlumberd.Services.Uniqueness.Sqlite/ServiceCollectionExtensions.cs

@@ -8,29 +8,66 @@ namespace MicroPlumberd.Services.Uniqueness;
 public static class SqliteUniquenessServiceCollectionExtensions
 {
     /// <summary>
-    /// Registers <see cref="IUniqueNameReservation{TCategory}"/> for a category, backed by SQLite.
+    /// Registers <see cref="IUniqueNameReservation{TCategory}"/> for a category, backed by SQLite — the
+    /// light, serverless option for a host whose instances share a volume. No server to run or operate.
     /// </summary>
     /// <remarks>
-    /// <b>Development, test and single-instance hosts only — NOT production.</b> SQLite is file-local and
-    /// single-writer, so it cannot arbitrate across replicas: each instance would enforce uniqueness
-    /// against its own file, which amounts to no uniqueness at all. Two replicas would happily accept the
-    /// same name. The production default is PostgreSQL — see
-    /// <c>MicroPlumberd.Services.Uniqueness.Postgres</c>.
+    /// <b>SAME HOST ONLY. Read the boundary below before deploying this.</b>
+    /// <para>
+    /// <b>SUPPORTED — one host.</b> A docker named volume or bind mount, shared by any number of containers
+    /// on ONE machine. SQLite's POSIX advisory locks arbitrate correctly between separate processes, so N
+    /// containers sharing the file get real uniqueness. Verified: 16 independent OS processes racing to
+    /// insert the same value against one file left exactly one row.
+    /// </para>
+    /// <para>
+    /// <b>PROHIBITED — across hosts.</b> NFS, SMB, or any cloud file share. SQLite's locking is unreliable
+    /// on network filesystems, and the failure mode is <b>DATABASE CORRUPTION</b>, not merely lost
+    /// uniqueness — strictly worse than the bug this library exists to prevent. Use
+    /// <c>MicroPlumberd.Services.Uniqueness.Postgres</c> for any deployment spanning hosts.
+    /// </para>
+    /// <para>
+    /// That boundary is enforced, not merely documented. This registration requires WAL, and WAL needs a
+    /// shared-memory (-shm) file, which needs every process on one kernel — so it cannot be enabled over a
+    /// network filesystem. A cross-host deployment therefore FAILS LOUDLY at startup instead of corrupting
+    /// silently. (The same-host mechanism is verified; the cross-host failure is reasoned from SQLite's
+    /// documented WAL constraints and has not been observed here.)
+    /// </para>
+    /// <para>
+    /// A busy timeout is also applied to every connection, so a writer meeting a held lock waits in SQLite's
+    /// own busy handler. Note this is defence in depth rather than a fix for instant failures:
+    /// Microsoft.Data.Sqlite already retries a locked write at the command level for <c>Default Timeout</c>
+    /// (30s by default), so contended writers wait even without it. What it buys is that the wait no longer
+    /// depends on an ADO-layer retry outside SQLite's contract, and is explicit rather than inherited.
+    /// </para>
     /// </remarks>
     /// <typeparam name="TCategory">The uniqueness category; names its table.</typeparam>
     /// <param name="services">The service collection.</param>
     /// <param name="connectionString">The SQLite connection string, e.g. <c>Data Source=uniqueness.db</c>.</param>
     /// <param name="ensureSchema">Create the table on start if absent (idempotent). Turn off when the
     /// schema is owned by migrations or the database user cannot issue DDL.</param>
+    /// <param name="busyTimeout">How long a writer waits in SQLite's busy handler for a held lock. Default
+    /// 5s; costs nothing when uncontended. Keep it BELOW the connection string's <c>Default Timeout</c>
+    /// (30s unless you set it): a larger busy timeout silently defeats the command timeout for lock waits,
+    /// because the native handler blocks inside SQLite and never surfaces the busy the provider would time
+    /// out on.</param>
     /// <returns>The service collection for chaining.</returns>
     public static IServiceCollection AddUniquenessSqlite<TCategory>(
         this IServiceCollection services,
         string connectionString,
-        bool ensureSchema = true)
+        bool ensureSchema = true,
+        TimeSpan? busyTimeout = null)
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(connectionString);
 
+        var timeout = busyTimeout ?? TimeSpan.FromSeconds(5);
+        if (timeout <= TimeSpan.Zero)
+            throw new ArgumentOutOfRangeException(nameof(busyTimeout), timeout,
+                "A busy timeout of zero means a writer fails the instant it meets a held lock, which is the " +
+                "default this registration exists to correct.");
+
         services.TryAddEnumerable(ServiceDescriptor.Singleton<IUniquenessDialect, SqliteUniquenessDialect>());
-        return services.AddUniqueness<TCategory>(o => o.UseSqlite(connectionString), ensureSchema);
+        return services.AddUniqueness<TCategory>(
+            o => o.UseSqlite(connectionString).AddInterceptors(new SqlitePragmaInterceptor(timeout)),
+            ensureSchema);
     }
 }

src/MicroPlumberd.Services.Uniqueness.Sqlite/SqlitePragmaInterceptor.cs

@@ -0,0 +1,107 @@
+using System.Data.Common;
+using Microsoft.EntityFrameworkCore.Diagnostics;
+
+namespace MicroPlumberd.Services.Uniqueness;
+
+/// <summary>
+/// Applies the pragmas the shared-volume deployment depends on to EVERY connection: a busy timeout, then
+/// WAL.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Why an interceptor and not the connection string: Microsoft.Data.Sqlite rejects <c>journal_mode</c> and
+/// <c>busy_timeout</c> as connection-string keywords outright ("Connection string keyword 'busy_timeout'
+/// is not supported"), so there is no declarative route. Its <c>Default Timeout</c> keyword is a different
+/// mechanism — an ADO-level command retry, not sqlite3_busy_timeout — and would leave
+/// <c>PRAGMA busy_timeout</c> reading 0.
+/// </para>
+/// <para>
+/// Why on every OPEN and not once at startup: <c>busy_timeout</c> is PER-CONNECTION state, so a one-shot
+/// pragma at boot would configure one connection and leave every later pooled connection at the default.
+/// <c>journal_mode</c> is by contrast PERSISTENT in the file, so setting it per-open is a cheap no-op after
+/// the first — worth it to keep one code path and to re-assert the WAL check below.
+/// </para>
+/// <para>
+/// What <c>busy_timeout</c> does and does NOT buy, MEASURED — do not restate the folklore. It is often said
+/// that at <c>busy_timeout=0</c> a writer meeting a held lock fails instantly. That is NOT true on this
+/// stack: Microsoft.Data.Sqlite retries SQLITE_BUSY at the command level for <c>Default Timeout</c>
+/// (default 30s), so with the shipped connection string a contended writer WAITS and succeeds even at
+/// <c>busy_timeout=0</c> (measured: 3.2s against a 3s lock holder). Setting it buys three real things
+/// instead: the wait happens in SQLite's own busy handler rather than the provider's 150ms poll loop; the
+/// behaviour stops depending on an ADO-layer retry that is not part of SQLite's contract; and the wait
+/// becomes explicit rather than inherited from an unrelated <c>Default Timeout</c> default.
+/// </para>
+/// <para>
+/// CAVEAT worth knowing before raising it: a busy timeout LARGER than <c>Default Timeout</c> silently
+/// defeats the command timeout for lock waits. The native busy handler blocks inside sqlite3_step and never
+/// returns SQLITE_BUSY, so the provider's timeout check never fires — measured: <c>busy_timeout=5000</c>
+/// with <c>Default Timeout=1</c> waited the full 3s and succeeded, while <c>busy_timeout=0</c> with the
+/// same command timeout failed at 1.1s. Keep the busy timeout below <c>Default Timeout</c> unless that
+/// override is what you want.
+/// </para>
+/// <para>
+/// ORDER IS LOAD-BEARING: the busy timeout is set FIRST. Switching to WAL needs a brief exclusive lock, so
+/// with N containers booting against one file simultaneously the WAL switch is itself contended — at the
+/// default timeout of 0 it would fail instantly on whichever container lost.
+/// </para>
+/// </remarks>
+class SqlitePragmaInterceptor(TimeSpan busyTimeout) : DbConnectionInterceptor
+{
+    public override void ConnectionOpened(DbConnection connection, ConnectionEndEventData eventData)
+    {
+        Execute(connection, $"PRAGMA busy_timeout={(int)busyTimeout.TotalMilliseconds}");
+        RequireWal(Execute(connection, "PRAGMA journal_mode=WAL"));
+    }
+
+    public override async Task ConnectionOpenedAsync(DbConnection connection, ConnectionEndEventData eventData,
+        CancellationToken cancellationToken = default)
+    {
+        await ExecuteAsync(connection, $"PRAGMA busy_timeout={(int)busyTimeout.TotalMilliseconds}", cancellationToken);
+        RequireWal(await ExecuteAsync(connection, "PRAGMA journal_mode=WAL", cancellationToken));
+    }
+
+    static object? Execute(DbConnection connection, string sql)
+    {
+        using var cmd = connection.CreateCommand();
+        cmd.CommandText = sql;
+        return cmd.ExecuteScalar();
+    }
+
+    static async Task<object?> ExecuteAsync(DbConnection connection, string sql, CancellationToken cancellationToken)
+    {
+        await using var cmd = connection.CreateCommand();
+        cmd.CommandText = sql;
+        return await cmd.ExecuteScalarAsync(cancellationToken);
+    }
+
+    /// <summary>
+    /// Fails loudly when WAL did not take effect.
+    /// </summary>
+    /// <remarks>
+    /// This is the point of requiring WAL. It needs shared memory (the -shm file), and shared memory needs
+    /// all processes on ONE HOST — so WAL cannot be enabled over a network filesystem. SQLite reports that
+    /// by leaving the journal mode alone rather than by failing, which means an unchecked WAL switch would
+    /// hand back a working-looking database whose locking is unreliable across hosts. That failure mode is
+    /// CORRUPTION, not merely lost uniqueness — strictly worse than the bug this library prevents — so the
+    /// only safe response is to refuse to start.
+    /// <para>
+    /// In-memory databases report "memory" and are accepted: they are single-process by construction, so
+    /// the cross-host hazard cannot arise.
+    /// </para>
+    /// </remarks>
+    static void RequireWal(object? journalMode)
+    {
+        var mode = journalMode as string ?? journalMode?.ToString() ?? "(null)";
+        if (string.Equals(mode, "wal", StringComparison.OrdinalIgnoreCase)) return;
+        if (string.Equals(mode, "memory", StringComparison.OrdinalIgnoreCase)) return;
+
+        throw new InvalidOperationException(
+            $"Uniqueness: SQLite refused to enable WAL on this database (journal_mode is '{mode}'). The " +
+            "usual cause is that the file is on a NETWORK filesystem (NFS / SMB / a cloud file share), " +
+            "where WAL's shared-memory file cannot work. SQLite's locking is unreliable there and the " +
+            "failure mode is DATABASE CORRUPTION, so this configuration is refused rather than run. Put " +
+            "the file on a volume local to ONE host (a docker named volume or bind mount is fine, and may " +
+            "be shared by any number of containers on that host), or use " +
+            "MicroPlumberd.Services.Uniqueness.Postgres for a deployment that spans hosts.");
+    }
+}

src/MicroPlumberd.Services.Uniqueness.Tests.Worker/MicroPlumberd.Services.Uniqueness.Tests.Worker.csproj

@@ -0,0 +1,21 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <!-- A real OS process used by UQ-SQLITE-01. Test-only: never packed, never shipped. -->
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <IsPackable>false</IsPackable>
+    <RootNamespace>MicroPlumberd.Services.Uniqueness.Tests.Worker</RootNamespace>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Hosting" Version="10.0.7" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\MicroPlumberd.Services.Uniqueness.Sqlite\MicroPlumberd.Services.Uniqueness.Sqlite.csproj" />
+  </ItemGroup>
+
+</Project>

src/MicroPlumberd.Services.Uniqueness.Tests.Worker/Program.cs

@@ -0,0 +1,78 @@
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using MicroPlumberd.Services.Uniqueness;
+
+// A REAL OS process that reserves a name through the shipped library (UQ-SQLITE-01).
+//
+// This exists because threads cannot test what the shared-volume SQLite deployment rests on. Threads in
+// one process share a connection pool and an in-process lock manager; N containers on a shared volume
+// share NEITHER. Only separate processes exercise cross-process file locking, so this is a separate
+// executable rather than a Task.
+//
+// Usage: <connectionString> <name> <sourceGuid> <startAtUtcTicks>
+// Exit codes are the test's assertion surface — see UqExit.
+
+if (args.Length != 4)
+{
+    Console.Error.WriteLine("usage: <connectionString> <name> <sourceGuid> <startAtUtcTicks>");
+    return UqExit.BadUsage;
+}
+
+var (connectionString, name, source, startAt) =
+    (args[0], args[1], Guid.Parse(args[2]), new DateTime(long.Parse(args[3]), DateTimeKind.Utc));
+
+var builder = Host.CreateApplicationBuilder();
+builder.Services.AddLogging(l => l.ClearProviders());
+// ensureSchema:false — the test creates the table once up front. This process is here to race the
+// INSERT, not the DDL.
+builder.Services.AddUniquenessSqlite<CompanyNip>(connectionString, ensureSchema: false);
+
+using var host = builder.Build();
+await host.StartAsync();
+
+var uq = host.Services.GetRequiredService<IUniqueNameReservation<CompanyNip>>();
+
+// All processes are released at the same instant, so they genuinely contend. Without this the spawn
+// cost (tens of ms each) would serialise them and the "race" would prove nothing.
+var wait = startAt - DateTime.UtcNow;
+if (wait > TimeSpan.Zero) await Task.Delay(wait);
+while (DateTime.UtcNow < startAt) { /* tighten the last moment */ }
+
+try
+{
+    await uq.Reserve(name, source);
+    Console.Out.WriteLine($"WON {source}");
+    return UqExit.Won;
+}
+catch (UniqueNameConflictException ex)
+{
+    // The correct way to lose: someone else holds the name and we were told who.
+    Console.Out.WriteLine($"CONFLICT heldBy={ex.HeldBy}");
+    return UqExit.Conflict;
+}
+catch (Microsoft.Data.Sqlite.SqliteException ex)
+{
+    // The failure mode the deployment must NOT exhibit: contention surfacing as SQLITE_BUSY (5) /
+    // SQLITE_LOCKED (6) instead of waiting. Reported distinctly so the test can tell them apart.
+    Console.Error.WriteLine($"SQLITE {ex.SqliteErrorCode}/{ex.SqliteExtendedErrorCode}: {ex.Message}");
+    return UqExit.SqliteError;
+}
+catch (Exception ex)
+{
+    Console.Error.WriteLine($"OTHER {ex.GetType().Name}: {ex.Message}");
+    return UqExit.OtherError;
+}
+
+/// <summary>Exit codes: the contract between this worker and the test that spawns it.</summary>
+static class UqExit
+{
+    public const int Won = 0;
+    public const int Conflict = 3;
+    public const int SqliteError = 4;   // SQLITE_BUSY and friends — a failure, never acceptable
+    public const int OtherError = 5;
+    public const int BadUsage = 64;
+}
+
+/// <summary>Must match the test's category type NAME — that is what names the table.</summary>
+record CompanyNip;

src/MicroPlumberd.Services.Uniqueness.Tests/MicroPlumberd.Services.Uniqueness.Tests.csproj

@@ -29,6 +29,9 @@
     <ProjectReference Include="..\MicroPlumberd.Services.Uniqueness.Postgres\MicroPlumberd.Services.Uniqueness.Postgres.csproj" />
     <ProjectReference Include="..\MicroPlumberd.Services.Uniqueness.SqlServer\MicroPlumberd.Services.Uniqueness.SqlServer.csproj" />
     <ProjectReference Include="..\MicroPlumberd.Testing\MicroPlumberd.Testing.csproj" />
+    <!-- UQ-SQLITE-01 spawns this as real OS processes; referenced so it is always built alongside. -->
+    <ProjectReference Include="..\MicroPlumberd.Services.Uniqueness.Tests.Worker\MicroPlumberd.Services.Uniqueness.Tests.Worker.csproj"
+                      ReferenceOutputAssembly="false" />
   </ItemGroup>
 
 </Project>