feat(body): configure the request compressor directly

- Add RefitSettings.RequestCompressionOptions so a client can set the
  compressor's own knobs - window size, strategy, a Zstandard dictionary -
  which a CompressionLevel cannot express.
- Options set for a coding replace the level for that coding; the codings
  left unset still compress by level.
- The options types arrived with .NET 9.0, and Zstandard's with .NET 11.0,
  so the surface only exists from net9.0 onward.

Author: glennawatson

README.md

@@ -1042,6 +1042,24 @@ var settings = new RefitSettings
 };
 ```
 
+For knobs a level cannot express — window size, strategy, a Zstandard dictionary — set the compressor's own options.
+Options set for a coding replace the level for that coding; the codings left unset still compress by level:
+
+```csharp
+var settings = new RefitSettings
+{
+    RequestCompression = RequestCompression.Brotli,
+    RequestCompressionOptions = new()
+    {
+        Brotli = new() { Quality = 9, WindowLog2 = 22 },
+        GZip = new() { CompressionLevel = 6 },
+    },
+};
+```
+
+`RequestCompressionOptions` needs .NET 9.0 or later, where `ZLibCompressionOptions` and `BrotliCompressionOptions`
+were introduced; its `Zstandard` property needs .NET 11.0.
+
 There is no negotiation for a compressed request body, so only turn this on against a server you know accepts one.
 The compressed length is unknown until the body has been written, so these requests are sent chunked.
 

src/Refit/CompressedContent.cs

@@ -47,13 +47,22 @@ internal CompressedContent(HttpContent inner, RequestCompression compression, Co
         Headers.ContentEncoding.Add(RequestContentCoding.Token(compression));
     }
 
+#if NET9_0_OR_GREATER
+    /// <summary>Gets the per-coding compressor settings that override the level, or <see langword="null"/>.</summary>
+    internal RequestCompressionOptions? Options { get; init; }
+#endif
+
     /// <inheritdoc/>
     protected override async Task SerializeToStreamAsync(Stream stream, TransportContext? context)
     {
         // leaveOpen, because the request stream belongs to the transport; only the compressor is finished here, and
         // finishing it is what writes the trailer that makes the body readable.
         Stream compressor = _compression switch
         {
+#if NET9_0_OR_GREATER
+            RequestCompression.GZip when Options?.GZip is { } gzip => new GZipStream(stream, gzip, leaveOpen: true),
+            RequestCompression.Brotli when Options?.Brotli is { } brotli => new BrotliStream(stream, brotli, leaveOpen: true),
+#endif
             RequestCompression.GZip => new GZipStream(stream, _level, leaveOpen: true),
 #if NET8_0_OR_GREATER
             RequestCompression.Brotli => new BrotliStream(stream, _level, leaveOpen: true),

src/Refit/GeneratedRequestRunner.BodyContent.cs

@@ -42,7 +42,7 @@ public static HttpContent CompressBodyContent(
 
         return resolved is RequestCompression.Default or RequestCompression.None
             ? content
-            : RequestContentCoding.Wrap(content, resolved, resolvedLevel);
+            : RequestContentCoding.Wrap(content, settings, resolved, resolvedLevel);
     }
 
     /// <summary>Serializes a generated request body using Refit body rules.</summary>

src/Refit/PublicAPI/net10.0/PublicAPI.txt

@@ -622,6 +622,7 @@ public class RefitSettings
     public Refit.RequestBodySerializationMode RequestBodySerialization { get; set; }
     public Refit.RequestCompression RequestCompression { get; set; }
     public System.IO.Compression.CompressionLevel RequestCompressionLevel { get; set; }
+    public Refit.RequestCompressionOptions? RequestCompressionOptions { get; set; }
     public System.Collections.Generic.IList<System.Type> ReturnTypeAdapters { get; }
     public System.Func<System.Net.Http.HttpRequestMessage, System.Exception, System.Threading.CancellationToken, System.Exception> TransportExceptionFactory { get; set; }
     public Refit.IUrlParameterFormatter UrlParameterFormatter { get; set; }
@@ -667,6 +668,13 @@ public enum RequestCompression
     Brotli = 3,
     Zstandard = 4,
 }
+[System.Diagnostics.DebuggerDisplay("{GZip} {Brotli}")]
+public sealed class RequestCompressionOptions
+{
+    public RequestCompressionOptions() { }
+    public System.IO.Compression.BrotliCompressionOptions? Brotli { get; set; }
+    public System.IO.Compression.ZLibCompressionOptions? GZip { get; set; }
+}
 [System.Diagnostics.DebuggerDisplay("{ToString(),nq}")]
 public record RestMethodInfo : System.IEquatable<Refit.RestMethodInfo>
 {

src/Refit/PublicAPI/net11.0/PublicAPI.txt

@@ -622,6 +622,7 @@ public class RefitSettings
     public Refit.RequestBodySerializationMode RequestBodySerialization { get; set; }
     public Refit.RequestCompression RequestCompression { get; set; }
     public System.IO.Compression.CompressionLevel RequestCompressionLevel { get; set; }
+    public Refit.RequestCompressionOptions? RequestCompressionOptions { get; set; }
     public System.Collections.Generic.IList<System.Type> ReturnTypeAdapters { get; }
     public System.Func<System.Net.Http.HttpRequestMessage, System.Exception, System.Threading.CancellationToken, System.Exception> TransportExceptionFactory { get; set; }
     public Refit.IUrlParameterFormatter UrlParameterFormatter { get; set; }
@@ -667,6 +668,14 @@ public enum RequestCompression
     Brotli = 3,
     Zstandard = 4,
 }
+[System.Diagnostics.DebuggerDisplay("{GZip} {Brotli}")]
+public sealed class RequestCompressionOptions
+{
+    public RequestCompressionOptions() { }
+    public System.IO.Compression.BrotliCompressionOptions? Brotli { get; set; }
+    public System.IO.Compression.ZLibCompressionOptions? GZip { get; set; }
+    public System.IO.Compression.ZstandardCompressionOptions? Zstandard { get; set; }
+}
 [System.Diagnostics.DebuggerDisplay("{ToString(),nq}")]
 public record RestMethodInfo : System.IEquatable<Refit.RestMethodInfo>
 {

src/Refit/PublicAPI/net9.0/PublicAPI.txt

@@ -621,6 +621,7 @@ public class RefitSettings
     public Refit.RequestBodySerializationMode RequestBodySerialization { get; set; }
     public Refit.RequestCompression RequestCompression { get; set; }
     public System.IO.Compression.CompressionLevel RequestCompressionLevel { get; set; }
+    public Refit.RequestCompressionOptions? RequestCompressionOptions { get; set; }
     public System.Collections.Generic.IList<System.Type> ReturnTypeAdapters { get; }
     public System.Func<System.Net.Http.HttpRequestMessage, System.Exception, System.Threading.CancellationToken, System.Exception> TransportExceptionFactory { get; set; }
     public Refit.IUrlParameterFormatter UrlParameterFormatter { get; set; }
@@ -666,6 +667,13 @@ public enum RequestCompression
     Brotli = 3,
     Zstandard = 4,
 }
+[System.Diagnostics.DebuggerDisplay("{GZip} {Brotli}")]
+public sealed class RequestCompressionOptions
+{
+    public RequestCompressionOptions() { }
+    public System.IO.Compression.BrotliCompressionOptions? Brotli { get; set; }
+    public System.IO.Compression.ZLibCompressionOptions? GZip { get; set; }
+}
 [System.Diagnostics.DebuggerDisplay("{ToString(),nq}")]
 public record RestMethodInfo : System.IEquatable<Refit.RestMethodInfo>
 {

src/Refit/RefitSettings.cs

@@ -276,6 +276,13 @@ public Func<
     public System.IO.Compression.CompressionLevel RequestCompressionLevel { get; set; } =
         System.IO.Compression.CompressionLevel.Optimal;
 
+#if NET9_0_OR_GREATER
+    /// <summary>Gets or sets the per-coding compressor settings, or null to compress by level alone.</summary>
+    /// <remarks>Options set for a coding override the level for that coding, including where a <c>[Body]</c> parameter
+    /// named the coding and its own level.</remarks>
+    public RequestCompressionOptions? RequestCompressionOptions { get; set; }
+#endif
+
     /// <summary>Gets optional Key-Value pairs, which are displayed in the property <see cref="HttpRequestMessage.Properties"/>.</summary>
     public Dictionary<string, object>? HttpRequestMessageOptions { get; init; }
 

src/Refit/RequestCompressionOptions.cs

@@ -0,0 +1,30 @@
+// Copyright (c) 2019-2026 ReactiveUI and Contributors. All rights reserved.
+// ReactiveUI and Contributors licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for full license information.
+#if NET9_0_OR_GREATER
+using System.IO.Compression;
+
+namespace Refit;
+
+/// <summary>The per-coding compressor settings used in place of <see cref="RefitSettings.RequestCompressionLevel"/>.</summary>
+/// <remarks>
+/// Each coding has its own options type carrying knobs a level cannot express - window size, strategy, a Zstandard
+/// dictionary. Setting the options for a coding overrides the level for that coding only; the codings left null still
+/// compress by level. The options types themselves arrived with .NET 9.0, and Zstandard's with .NET 11.0, so this type
+/// does not exist on earlier targets.
+/// </remarks>
+[System.Diagnostics.DebuggerDisplay("{GZip} {Brotli}")]
+public sealed class RequestCompressionOptions
+{
+    /// <summary>Gets or sets the gzip compressor settings, or <see langword="null"/> to compress by level.</summary>
+    public ZLibCompressionOptions? GZip { get; set; }
+
+    /// <summary>Gets or sets the Brotli compressor settings, or <see langword="null"/> to compress by level.</summary>
+    public BrotliCompressionOptions? Brotli { get; set; }
+
+#if NET11_0_OR_GREATER
+    /// <summary>Gets or sets the Zstandard compressor settings, or <see langword="null"/> to compress by level.</summary>
+    public ZstandardCompressionOptions? Zstandard { get; set; }
+#endif
+}
+#endif

src/Refit/RequestContentCoding.cs

@@ -44,26 +44,49 @@ internal static (RequestCompression Compression, CompressionLevel Level) Resolve
 
     /// <summary>Wraps content in the compressor for a coding.</summary>
     /// <param name="content">The content to compress.</param>
+    /// <param name="settings">The Refit settings supplying the per-coding compressor options.</param>
     /// <param name="compression">The resolved coding, never <see cref="RequestCompression.Default"/> or <see cref="RequestCompression.None"/>.</param>
-    /// <param name="level">How hard to compress.</param>
+    /// <param name="level">How hard to compress, used for any coding the settings left without options.</param>
     /// <returns>The compressing content.</returns>
     /// <exception cref="PlatformNotSupportedException">This framework cannot produce the coding.</exception>
-    internal static HttpContent Wrap(HttpContent content, RequestCompression compression, CompressionLevel level) =>
+    internal static HttpContent Wrap(
+        HttpContent content,
+        RefitSettings settings,
+        RequestCompression compression,
+        CompressionLevel level)
+    {
 #if NET11_0_OR_GREATER
-        compression switch
+        var options = settings.RequestCompressionOptions;
+
+        return compression switch
         {
-            RequestCompression.GZip => new GZipCompressedContent(content, level),
-            RequestCompression.Brotli => new BrotliCompressedContent(content, level),
-            RequestCompression.Zstandard => new ZstandardCompressedContent(content, level),
+            RequestCompression.GZip => options?.GZip is { } gzip
+                ? new GZipCompressedContent(content, gzip)
+                : new GZipCompressedContent(content, level),
+            RequestCompression.Brotli => options?.Brotli is { } brotli
+                ? new BrotliCompressedContent(content, brotli)
+                : new BrotliCompressedContent(content, level),
+            RequestCompression.Zstandard => options?.Zstandard is { } zstandard
+                ? new ZstandardCompressedContent(content, zstandard)
+                : new ZstandardCompressedContent(content, level),
             _ => throw Unsupported(compression),
         };
+#elif NET9_0_OR_GREATER
+        return compression is RequestCompression.GZip or RequestCompression.Brotli
+            ? new CompressedContent(content, compression, level) { Options = settings.RequestCompressionOptions }
+            : throw Unsupported(compression);
 #elif NET8_0_OR_GREATER
-        compression is RequestCompression.GZip or RequestCompression.Brotli
+        _ = settings;
+
+        return compression is RequestCompression.GZip or RequestCompression.Brotli
             ? new CompressedContent(content, compression, level)
             : throw Unsupported(compression);
 #else
-        compression is RequestCompression.GZip
+        _ = settings;
+
+        return compression is RequestCompression.GZip
             ? new CompressedContent(content, compression, level)
             : throw Unsupported(compression);
 #endif
+    }
 }

src/tests/Refit.Tests/RequestCompressionTests.cs

@@ -139,6 +139,34 @@ public async Task CompressedBodyRoundTrips()
         await Assert.That(await reader.ReadToEndAsync()).IsEqualTo(BodyText);
     }
 
+#if NET9_0_OR_GREATER
+    /// <summary>Verifies per-coding options replace the level for the coding they name.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
+    [Test]
+    public async Task PerCodingOptionsReplaceTheLevel()
+    {
+        // Zero is the zlib "store, do not compress" level, and the declared level asks for the smallest output.
+        var settings = new RefitSettings { RequestCompressionOptions = new() { GZip = new() { CompressionLevel = 0 } } };
+
+        var byOptions = await CompressAsync(settings, RequestCompression.GZip, CompressionLevel.SmallestSize);
+        var byLevel = await CompressAsync(new(), RequestCompression.GZip, CompressionLevel.SmallestSize);
+
+        await Assert.That(byOptions.Length).IsGreaterThan(byLevel.Length);
+    }
+
+    /// <summary>Verifies a coding the options left unset still compresses by level.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
+    [Test]
+    public async Task CodingWithoutOptionsStillCompressesByLevel()
+    {
+        var settings = new RefitSettings { RequestCompressionOptions = new() { Brotli = new() { Quality = 0 } } };
+
+        var bytes = await CompressAsync(settings, RequestCompression.GZip, CompressionLevel.SmallestSize);
+
+        await Assert.That(bytes.Length).IsLessThan(BodyText.Length);
+    }
+#endif
+
     /// <summary>Verifies the compressed content reports no length, so the request is sent chunked.</summary>
     /// <returns>A task that represents the asynchronous operation.</returns>
     [Test]
@@ -153,4 +181,22 @@ public async Task CompressedBodyReportsNoContentLength()
 
         await Assert.That(compressed.Headers.ContentLength).IsNull();
     }
+
+#if NET9_0_OR_GREATER
+    /// <summary>Compresses the shared body and returns the bytes that would reach the wire.</summary>
+    /// <param name="settings">The settings supplying any per-coding options.</param>
+    /// <param name="compression">The coding to apply.</param>
+    /// <param name="level">The level to apply where the options do not override it.</param>
+    /// <returns>The compressed bytes.</returns>
+    private static async Task<byte[]> CompressAsync(
+        RefitSettings settings,
+        RequestCompression compression,
+        CompressionLevel level)
+    {
+        using var content = new StringContent(BodyText);
+        using var compressed = GeneratedRequestRunner.CompressBodyContent(content, settings, compression, level);
+
+        return await compressed.ReadAsByteArrayAsync();
+    }
+#endif
 }