Merge pull request JasperFx#2437 from JasperFx/2406-content-negotiation

Add response content negotiation with [Writes] and ConnegMode

Author: jeremydmiller

docs/.vitepress/config.mts

@@ -222,6 +222,7 @@ const config: UserConfig<DefaultTheme.Config> = {
                         {text: 'Integration with ASP.Net Core', link: '/guide/http/integration'},
                         {text: 'Endpoints', link: '/guide/http/endpoints'},
                         {text: 'Json', link: '/guide/http/json'},
+                        {text: 'Content Negotiation', link: '/guide/http/conneg'},
                         {text: 'Routing', link: '/guide/http/routing'},
                         {text: 'Authentication and Authorization', link: '/guide/http/security'},
                         {text: 'Antiforgery / CSRF Protection', link: '/guide/http/antiforgery'},

docs/guide/http/conneg.md

@@ -0,0 +1,184 @@
+# Content Negotiation
+
+Wolverine supports content negotiation for HTTP endpoints, allowing you to serve different response formats based on the client's `Accept` header. This is done through the `[Writes]` attribute and the `WriteResponse` naming convention.
+
+## Response Content Negotiation
+
+To add content negotiation support for responses, add methods with the `[Writes("content-type")]` attribute to your endpoint class. These methods will be called instead of the default JSON serialization when the client's `Accept` header matches:
+
+<!-- snippet: sample_conneg_write_response -->
+<a id='snippet-sample_conneg_write_response'></a>
+```cs
+/// <summary>
+/// Demonstrates content negotiation with [Writes] attribute.
+/// Multiple WriteResponse methods handle different content types.
+/// </summary>
+public static class ConnegWriteEndpoints
+{
+    [WolverineGet("/conneg/write")]
+    public static ConnegItem GetItem()
+    {
+        return new ConnegItem("Widget", 42);
+    }
+
+    /// <summary>
+    /// Writes the response as plain text when Accept: text/plain
+    /// </summary>
+    [Writes("text/plain")]
+    public static Task WriteResponse(HttpContext context, ConnegItem response)
+    {
+        context.Response.ContentType = "text/plain";
+        return context.Response.WriteAsync($"{response.Name}: {response.Value}");
+    }
+
+    /// <summary>
+    /// Writes the response as CSV when Accept: text/csv
+    /// </summary>
+    [Writes("text/csv")]
+    public static Task WriteResponseCsv(HttpContext context, ConnegItem response)
+    {
+        context.Response.ContentType = "text/csv";
+        return context.Response.WriteAsync($"Name,Value\n{response.Name},{response.Value}");
+    }
+}
+```
+<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Http/WolverineWebApi/ConnegEndpoints.cs#L11-L52' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_conneg_write_response' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
+
+Key points:
+- Methods must have the `[Writes("content-type")]` attribute to specify which content type they handle
+- The method name can be anything — it's the `[Writes]` attribute that matters
+- Methods receive the `HttpContext` and the response resource as parameters
+- Methods can be sync (`void`) or async (`Task`)
+- Multiple `[Writes]` methods can coexist on the same class for different content types
+
+## Loose vs Strict Mode
+
+By default, content negotiation uses **Loose** mode: if no `[Writes]` method matches the client's `Accept` header, Wolverine falls back to JSON serialization. This ensures clients always get a response.
+
+### Strict Mode
+
+Use `[StrictConneg]` to enable **Strict** mode. In strict mode, if no `[Writes]` method matches, Wolverine returns HTTP 406 Not Acceptable:
+
+<!-- snippet: sample_conneg_strict -->
+<a id='snippet-sample_conneg_strict'></a>
+```cs
+/// <summary>
+/// Strict content negotiation — returns 406 when Accept header doesn't match
+/// </summary>
+[StrictConneg]
+public static class StrictConnegEndpoints
+{
+    [WolverineGet("/conneg/strict")]
+    public static ConnegItem GetStrictItem()
+    {
+        return new ConnegItem("StrictWidget", 99);
+    }
+
+    [Writes("text/plain")]
+    public static Task WriteResponse(HttpContext context, ConnegItem response)
+    {
+        context.Response.ContentType = "text/plain";
+        return context.Response.WriteAsync($"{response.Name}: {response.Value}");
+    }
+}
+```
+<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Http/WolverineWebApi/ConnegEndpoints.cs#L54-L76' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_conneg_strict' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
+
+### Global Configuration
+
+You can set the default `ConnegMode` for all endpoints using a policy:
+
+```csharp
+app.MapWolverineEndpoints(opts =>
+{
+    // Set strict mode globally
+    opts.ConfigureEndpoints(chain =>
+    {
+        chain.ConnegMode = ConnegMode.Strict;
+    });
+});
+```
+
+Per-endpoint configuration (via `[StrictConneg]` attribute) overrides the global setting.
+
+## Loose Mode Fallback
+
+In the default **Loose** mode, when no `[Writes]` method matches the `Accept` header, the response falls back to JSON serialization — exactly the same as an endpoint without any content negotiation:
+
+<!-- snippet: sample_conneg_loose_fallback -->
+<a id='snippet-sample_conneg_loose_fallback'></a>
+```cs
+/// <summary>
+/// Loose content negotiation (default) — falls back to JSON when no match
+/// </summary>
+public static class LooseConnegEndpoints
+{
+    [WolverineGet("/conneg/loose")]
+    public static ConnegItem GetLooseItem()
+    {
+        return new ConnegItem("LooseWidget", 77);
+    }
+
+    [Writes("text/plain")]
+    public static Task WriteResponse(HttpContext context, ConnegItem response)
+    {
+        context.Response.ContentType = "text/plain";
+        return context.Response.WriteAsync($"{response.Name}: {response.Value}");
+    }
+}
+```
+<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Http/WolverineWebApi/ConnegEndpoints.cs#L78-L99' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_conneg_loose_fallback' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
+
+## How It Works
+
+At code generation time, Wolverine generates branching code that checks the `Accept` header and dispatches to the correct writer:
+
+```csharp
+// Generated code (simplified)
+var acceptHeader = httpContext.Request.Headers.Accept.ToString();
+
+if (acceptHeader.Contains("text/plain"))
+{
+    httpContext.Response.ContentType = "text/plain";
+    await ConnegWriteEndpoints.WriteResponse(httpContext, item_response);
+}
+else if (acceptHeader.Contains("text/csv"))
+{
+    httpContext.Response.ContentType = "text/csv";
+    await ConnegWriteEndpoints.WriteResponseCsv(httpContext, item_response);
+}
+else
+{
+    // Loose: fallback to JSON
+    await WriteJsonAsync(httpContext, item_response);
+    // Strict: httpContext.Response.StatusCode = 406;
+}
+```
+
+This means there is **zero runtime reflection** — the content type dispatching is compiled at startup.
+
+## Request Content Type Negotiation
+
+For request-side content negotiation (dispatching based on `Content-Type` header), use the existing `[AcceptsContentType]` attribute to create separate endpoint methods for different request formats:
+
+```csharp
+public static class RequestConnegEndpoints
+{
+    [WolverinePost("/items"), AcceptsContentType("application/vnd.item.v1+json")]
+    public static ItemCreated CreateV1(CreateItemV1 command)
+    {
+        return new ItemCreated(command.Name, "v1");
+    }
+
+    [WolverinePost("/items"), AcceptsContentType("application/vnd.item.v2+json")]
+    public static ItemCreated CreateV2(CreateItemV2 command)
+    {
+        return new ItemCreated(command.Name, "v2");
+    }
+}
+```
+
+This allows the same route and HTTP method to handle different request body formats.

src/Http/Wolverine.Http.Tests/ContentNegotiationTests.cs

@@ -0,0 +1,115 @@
+using Alba;
+using Shouldly;
+using WolverineWebApi;
+using Xunit;
+using Xunit.Abstractions;
+
+namespace Wolverine.Http.Tests;
+
+public class ContentNegotiationTests : IntegrationContext
+{
+    private readonly ITestOutputHelper _output;
+
+    public ContentNegotiationTests(AppFixture fixture, ITestOutputHelper output) : base(fixture)
+    {
+        _output = output;
+    }
+
+    [Fact]
+    public async Task writes_text_plain_when_accept_header_matches()
+    {
+        var result = await Scenario(x =>
+        {
+            x.Get.Url("/conneg/write");
+            x.WithRequestHeader("Accept", "text/plain");
+            x.StatusCodeShouldBeOk();
+        });
+
+        var text = result.ReadAsText();
+        text.ShouldBe("Widget: 42");
+    }
+
+    [Fact]
+    public async Task writes_csv_when_accept_header_matches()
+    {
+        var result = await Scenario(x =>
+        {
+            x.Get.Url("/conneg/write");
+            x.WithRequestHeader("Accept", "text/csv");
+            x.StatusCodeShouldBeOk();
+        });
+
+        var text = result.ReadAsText();
+        text.ShouldBe("Name,Value\nWidget,42");
+    }
+
+    [Fact]
+    public async Task falls_back_to_json_in_loose_mode()
+    {
+        var result = await Scenario(x =>
+        {
+            x.Get.Url("/conneg/write");
+            x.WithRequestHeader("Accept", "application/json");
+            x.StatusCodeShouldBeOk();
+        });
+
+        var item = result.ReadAsJson<ConnegItem>();
+        item.ShouldNotBeNull();
+        item!.Name.ShouldBe("Widget");
+        item.Value.ShouldBe(42);
+    }
+
+    [Fact]
+    public async Task falls_back_to_json_with_no_accept_header()
+    {
+        var result = await Scenario(x =>
+        {
+            x.Get.Url("/conneg/loose");
+            // No Accept header — falls back to JSON in loose mode
+            x.StatusCodeShouldBeOk();
+        });
+
+        var item = result.ReadAsJson<ConnegItem>();
+        item.ShouldNotBeNull();
+        item!.Name.ShouldBe("LooseWidget");
+    }
+
+    [Fact]
+    public async Task strict_mode_returns_406_when_no_match()
+    {
+        await Scenario(x =>
+        {
+            x.Get.Url("/conneg/strict");
+            x.WithRequestHeader("Accept", "application/xml");
+            x.StatusCodeShouldBe(406);
+        });
+    }
+
+    [Fact]
+    public async Task strict_mode_returns_ok_when_match()
+    {
+        var result = await Scenario(x =>
+        {
+            x.Get.Url("/conneg/strict");
+            x.WithRequestHeader("Accept", "text/plain");
+            x.StatusCodeShouldBeOk();
+        });
+
+        var text = result.ReadAsText();
+        text.ShouldBe("StrictWidget: 99");
+    }
+
+    [Fact]
+    public async Task loose_mode_text_plain_works()
+    {
+        var result = await Scenario(x =>
+        {
+            x.Get.Url("/conneg/loose");
+            x.WithRequestHeader("Accept", "text/plain");
+            x.StatusCodeShouldBeOk();
+        });
+
+        var text = result.ReadAsText();
+        text.ShouldBe("LooseWidget: 77");
+    }
+}

src/Http/Wolverine.Http/ContentNegotiation/ConnegMode.cs

@@ -0,0 +1,19 @@
+namespace Wolverine.Http.ContentNegotiation;
+
+/// <summary>
+/// Controls how content negotiation behaves when no matching content type writer is found
+/// </summary>
+public enum ConnegMode
+{
+    /// <summary>
+    /// Default. Falls back to JSON serialization when no specific writer matches the Accept header.
+    /// This is the most permissive mode and ensures clients always get a response.
+    /// </summary>
+    Loose,
+
+    /// <summary>
+    /// Returns HTTP 406 Not Acceptable when no specific writer matches the Accept header.
+    /// Use this mode to strictly enforce content negotiation.
+    /// </summary>
+    Strict
+}