Send a ServerFailureResult's UserMessage in the 500's body; 3.3.0

CHANGELOG.md

@@ -1,4 +1,10 @@
 # Changelog
+## [3.3.0] - 2026-10-05
+### Changes
+- A `ServerFailureResult` (500) now sends its `UserMessage` (new in Linn.Common.Facade 13.6.0, which this
+  version needs) in the body - text written to be shown, e.g. "The change was saved, but ... failed",
+  which tells a caller not to simply retry. Its `Message` (diagnostic detail) is never sent, so existing
+  `ServerFailureResult`s - which have no `UserMessage` - are still an empty 500.
 ## [3.2.0] - 2026-08-20
 ### Changes
 - StreamCopyingResultHandler now handles ForbiddenResult<StreamResponse> (403). Previously a forbidden result fell through to the default case and returned 500.

src/Handlers/ResultResponseWriter.cs

@@ -77,8 +77,12 @@ await res.WriteAsync(
                         cancellationToken);
                     break;
 
-                case ServerFailureResult<T> _:
+                case ServerFailureResult<T> r:
                     res.StatusCode = 500;
+
+                    // only the UserMessage, written to be shown (e.g. Linn.Common.Facade's "The change was
+                    // saved, but ... failed"); Message is diagnostic detail and is never sent
+                    await res.WriteAsync(this.SerializeOptional(NullIfEmpty(r.UserMessage), null), cancellationToken);
                     break;
 
                 default:
@@ -87,6 +91,8 @@ await res.WriteAsync(
             }
         }
 
+        private static string? NullIfEmpty(string? message) => string.IsNullOrEmpty(message) ? null : message;
+
         private string SerializeOptional(object? a, object? b)
         {
             if (a != null)

src/Linn.Common.Service.csproj

@@ -5,15 +5,15 @@
 		<ImplicitUsings>enable</ImplicitUsings>
 		<AssemblyName>Linn.Common.Service</AssemblyName>
 		<PackageId>Linn.Common.Service</PackageId>
-		<Version>3.2.0</Version>
+		<Version>3.3.0</Version>
 	  <Nullable>enable</Nullable>
 	</PropertyGroup>
 	<ItemGroup>
 		<FrameworkReference Include="Microsoft.AspNetCore.App" />
 	</ItemGroup>
 	<ItemGroup>
 		<PackageReference Include="Linn.Common.Configuration" Version="3.0.0" />
-		<PackageReference Include="Linn.Common.Facade" Version="13.5.0" />
+		<PackageReference Include="Linn.Common.Facade" Version="13.6.0" />
 		<PackageReference Include="Linn.Common.Rendering" Version="1.0.0" />
 		<PackageReference Include="Linn.Common.Reporting.Resources" Version="1.7.2" />
 		<PackageReference Include="Newtonsoft.Json" Version="13.0.3" />

tests/Linn.Common.Service.Tests.csproj

@@ -12,7 +12,7 @@
 
 	<ItemGroup>
 		<PackageReference Include="FluentAssertions" Version="6.10.0" />
-		<PackageReference Include="Linn.Common.Facade" Version="13.5.0" />
+		<PackageReference Include="Linn.Common.Facade" Version="13.6.0" />
 		<PackageReference Include="Linn.Common.Rendering" Version="1.0.0" />
 		<PackageReference Include="Microsoft.AspNetCore.TestHost" Version="7.0.3" />
 		<PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="7.0.0" />

tests/WhenWritingAServerFailure.cs

@@ -0,0 +1,62 @@
+namespace Linn.Common.Service.Tests
+{
+    using System.IO;
+    using System.Net;
+    using System.Threading;
+    using System.Threading.Tasks;
+
+    using FluentAssertions;
+
+    using Linn.Common.Facade;
+    using Linn.Common.Service.Handlers;
+    using Linn.Common.Service.Tests.Fake.Resources;
+
+    using Microsoft.AspNetCore.Http;
+
+    using NUnit.Framework;
+
+    public class WhenWritingAServerFailure
+    {
+        private JsonResultHandler<WidgetResource> handler;
+
+        private DefaultHttpContext context;
+
+        [SetUp]
+        public void SetUp()
+        {
+            this.handler = new JsonResultHandler<WidgetResource>();
+            this.context = new DefaultHttpContext();
+            this.context.Response.Body = new MemoryStream();
+        }
+
+        [Test]
+        public async Task ShouldSendTheUserMessageButNotTheDetail()
+        {
+            await this.Write(new ServerFailureResult<WidgetResource>(
+                "The change was saved, but writing its log failed (SqlException: deadlock on log_table)",
+                "The change was saved, but writing its log failed"));
+
+            this.context.Response.StatusCode.Should().Be((int)HttpStatusCode.InternalServerError);
+            (await this.Body()).Should().Be("\"The change was saved, but writing its log failed\"");
+        }
+
+        [Test]
+        public async Task ShouldSendNothingForAnExistingServerFailure()
+        {
+            // a message only - diagnostic, e.g. an upstream service's raw error - stays unsent
+            await this.Write(new ServerFailureResult<WidgetResource>("Unexpected status code 502: upstream stack trace"));
+
+            this.context.Response.StatusCode.Should().Be((int)HttpStatusCode.InternalServerError);
+            (await this.Body()).Should().BeEmpty();
+        }
+
+        private Task Write(IResult<WidgetResource> result) =>
+            this.handler.Handle(this.context.Request, this.context.Response, result, CancellationToken.None);
+
+        private async Task<string> Body()
+        {
+            this.context.Response.Body.Position = 0;
+            return await new StreamReader(this.context.Response.Body).ReadToEndAsync();
+        }
+    }
+}