feat(body): compress request bodies (#2311)

* feat(body): compress request bodies

- Add `[Body(Compression = ...)]` so a method can send its body under a
  content coding. Refit compresses whatever the serializer produced and sets
  Content-Encoding, so the coding composes with every serialization method.
- Add RefitSettings.RequestCompression for a client-wide default. A [Body]
  parameter naming its own coding overrides it, and None opts one method out.
- Use the framework's GZipCompressedContent, BrotliCompressedContent and
  ZstandardCompressedContent on net11.0, and compress through GZipStream or
  BrotliStream below it.
- Throw PlatformNotSupportedException for a coding this framework cannot
  produce rather than quietly sending the body uncompressed. gzip is always
  available, Brotli needs net8.0, Zstandard needs net11.0.

Closes #2307

* 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.

* test(body): cover the request compression paths

- Add generator tests for the coding and level a [Body] parameter declares,
  including the None case that emits no call and a level declared without a
  coding.
- Add direct tests for the coding-to-token map and for the wrap and the
  compressor refusing a value that names no coding.
- Add options tests for Brotli and Zstandard, so every coding that accepts
  its own compressor settings is exercised on the targets that have them.
- Read an erroneous named argument through its TypedConstant kind rather
  than its value, so a value the compiler already rejected leaves the
  defaults in place instead of being read as an int.

Author: glennawatson

README.md

@@ -1013,6 +1013,65 @@ var settings = new RefitSettings(new SystemTextJsonContentSerializer(options))
 Both modes require the content serializer to implement `ISynchronousContentSerializer` (the default
 `SystemTextJsonContentSerializer` does); otherwise the body falls back to the default asynchronous serialization.
 
+### Compressing the request body
+
+Set `Compression` on `[Body]` to send the body under a content coding. Refit compresses whatever the serializer
+produced and sets `Content-Encoding` to match, so the coding composes with every serialization method:
+
+```csharp
+public interface IUploadApi
+{
+    [Post("/measurements")]
+    Task Upload([Body(Compression = RequestCompression.GZip)] Measurement[] batch);
+
+    [Post("/measurements")]
+    Task UploadSmallest([Body(
+        Compression = RequestCompression.Brotli,
+        CompressionLevel = CompressionLevel.SmallestSize)] Measurement[] batch);
+}
+```
+
+To compress every body from one client, set it on the settings instead. A `[Body]` parameter naming its own coding
+overrides that, and `RequestCompression.None` on the parameter opts a single method out:
+
+```csharp
+var settings = new RefitSettings
+{
+    RequestCompression = RequestCompression.GZip,
+    RequestCompressionLevel = CompressionLevel.Optimal,
+};
+```
+
+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.
+
+Codings are not available on every target framework, and asking for one the running framework cannot produce throws
+`PlatformNotSupportedException` when the request is built rather than quietly sending the body uncompressed:
+
+| Coding | `Content-Encoding` | Available on |
+| --- | --- | --- |
+| `RequestCompression.GZip` | `gzip` | every target |
+| `RequestCompression.Brotli` | `br` | .NET 8.0 and later |
+| `RequestCompression.Zstandard` | `zstd` | .NET 11.0 and later |
+
 For instance, here is how to create a new `RefitSettings` instance using the `Newtonsoft.Json`-based serializer (you'll
 also need to add a `PackageReference` to `Refit.Newtonsoft.Json`):
 

src/InterfaceStubGenerator.Shared/Emitter.Inline.Content.cs

@@ -25,14 +25,16 @@ internal static string BuildInlineContent(
         var requestLocal = plan.RequestLocal;
         var settingsLocal = plan.SettingsLocal;
         var bodyParameter = plan.BodyParameter!.Value;
+        var compression = BuildContentCompression(bodyParameter, requestLocal, settingsLocal, bodyIndent);
         if (bodyParameter.BodySerializationMethod == "UrlEncoded")
         {
             if (IsUnrollableFormBody(bodyParameter))
             {
-                return BuildInlineFormUnroll(bodyParameter, requestLocal, supportsNullable, emission, plan.Locals);
+                return BuildInlineFormUnroll(bodyParameter, requestLocal, supportsNullable, emission, plan.Locals)
+                    + compression;
             }
 
-            return formFieldsFieldName is not null
+            return (formFieldsFieldName is not null
                 ? $$"""
                     {{bodyIndent}}{{requestLocal}}.Content = global::Refit.GeneratedRequestRunner.CreateUrlEncodedBodyContent<{{bodyParameter.Type}}>(
                     {{bodyIndent}}    {{settingsLocal}},
@@ -45,7 +47,7 @@ internal static string BuildInlineContent(
                     {{bodyIndent}}    {{settingsLocal}},
                     {{bodyIndent}}    @{{bodyParameter.Name}});
 
-                    """;
+                    """) + compression;
         }
 
         if (bodyParameter.BodySerializationMethod == "JsonLines")
@@ -55,7 +57,7 @@ internal static string BuildInlineContent(
                 {{bodyIndent}}    {{settingsLocal}},
                 {{bodyIndent}}    @{{bodyParameter.Name}});
 
-                """;
+                """ + compression;
         }
 
         var streamBodyExpression = BuildStreamBodyExpression(bodyParameter, settingsLocal);
@@ -68,7 +70,37 @@ internal static string BuildInlineContent(
             {{bodyIndent}}    {{serializationMethodExpression}},
             {{bodyIndent}}    {{streamBodyExpression}});
 
-            """;
+            """ + compression;
+    }
+
+    /// <summary>Emits the content-coding wrap for a body, or nothing when no coding can apply.</summary>
+    /// <param name="bodyParameter">The body parameter model.</param>
+    /// <param name="requestLocal">The generated request message local name.</param>
+    /// <param name="settingsLocal">The generated settings local name.</param>
+    /// <param name="bodyIndent">The method body indentation.</param>
+    /// <returns>The wrap statement, or an empty string.</returns>
+    /// <remarks>
+    /// A body that declares <c>None</c> can never be compressed, so nothing is emitted for it. Every other body emits
+    /// the wrap, because <c>Default</c> resolves against <c>RefitSettings</c> at request time.
+    /// </remarks>
+    internal static string BuildContentCompression(
+        in RequestParameterModel bodyParameter,
+        string requestLocal,
+        string settingsLocal,
+        string bodyIndent)
+    {
+        var compression = bodyParameter.Compression ?? "Default";
+
+        return compression == "None"
+            ? string.Empty
+            : $$"""
+                {{bodyIndent}}{{requestLocal}}.Content = global::Refit.GeneratedRequestRunner.CompressBodyContent(
+                {{bodyIndent}}    {{requestLocal}}.Content,
+                {{bodyIndent}}    {{settingsLocal}},
+                {{bodyIndent}}    global::Refit.RequestCompression.{{compression}},
+                {{bodyIndent}}    global::System.IO.Compression.CompressionLevel.{{bodyParameter.CompressionLevel ?? "Optimal"}});
+
+                """;
     }
 
     /// <summary>Emits straight-line form-url-encoded body serialization for an all-scalar body, mirroring the descriptor

src/InterfaceStubGenerator.Shared/Models/RequestParameterModel.cs

@@ -60,6 +60,14 @@ internal readonly record struct RequestParameterModel(
     /// placeholder with a formatted property value.</summary>
     internal ImmutableEquatableArray<PathObjectBindingModel>? PathObjectBindings { get; init; }
 
+    /// <summary>Gets the <c>Refit.RequestCompression</c> member name the body declared, or <see langword="null"/> for a
+    /// parameter that is not a body. <c>Default</c> means the request takes its coding from the settings.</summary>
+    internal string? Compression { get; init; }
+
+    /// <summary>Gets the <c>System.IO.Compression.CompressionLevel</c> member name the body declared, or
+    /// <see langword="null"/> for a parameter that is not a body.</summary>
+    internal string? CompressionLevel { get; init; }
+
     /// <summary>Gets the multipart part descriptor when this parameter contributes a <c>[Multipart]</c> form part —
     /// set for <see cref="RequestParameterKind.MultipartPart"/> parameters and <see langword="null"/> otherwise.</summary>
     internal MultipartPartModel? MultipartPart { get; init; }

src/InterfaceStubGenerator.Shared/Parser.Request.Body.cs

@@ -270,14 +270,36 @@ internal static BodyAttributeInfo ParseBodyAttribute(AttributeData attribute)
             }
         }
 
+        var compression = "Default";
+        var compressionLevel = "Optimal";
+
+        foreach (var named in attribute.NamedArguments)
+        {
+            // Both arguments are enum-typed, so anything else is a value the compiler already rejected; leave the
+            // defaults in place rather than reading a constant that is not there.
+            if (named.Value.Kind != TypedConstantKind.Enum)
+            {
+                continue;
+            }
+
+            if (named.Key == "Compression")
+            {
+                compression = GetRequestCompressionName((int)named.Value.Value!);
+            }
+            else if (named.Key == "CompressionLevel")
+            {
+                compressionLevel = GetCompressionLevelName((int)named.Value.Value!);
+            }
+        }
+
         var bufferMode = buffered switch
         {
             true => BodyBufferMode.Buffered,
             false => BodyBufferMode.Streaming,
             _ => BodyBufferMode.Settings
         };
 
-        return new(serializationMethod, bufferMode);
+        return new(serializationMethod, bufferMode, compression, compressionLevel);
     }
 
     /// <summary>Tries to parse a body serialization method constructor argument.</summary>
@@ -300,9 +322,13 @@ internal static bool TryGetBodySerializationMethodName(in TypedConstant argument
     /// <summary>Parsed body attribute data.</summary>
     /// <param name="SerializationMethod">The body serialization method name.</param>
     /// <param name="BufferMode">The body buffering mode.</param>
+    /// <param name="Compression">The <c>RequestCompression</c> member name the body declared.</param>
+    /// <param name="CompressionLevel">The <c>CompressionLevel</c> member name the body declared.</param>
     internal readonly record struct BodyAttributeInfo(
         string SerializationMethod,
-        BodyBufferMode BufferMode);
+        BodyBufferMode BufferMode,
+        string Compression,
+        string CompressionLevel);
 
     /// <summary>Form-relevant data parsed from a <c>[Query]</c> attribute on a parameter or body property.</summary>
     /// <param name="Delimiter">The delimiter combined with the prefix, or <see langword="null"/> when no

src/InterfaceStubGenerator.Shared/Parser.Request.Helpers.cs

@@ -17,6 +17,27 @@ internal static partial class Parser
     /// <summary>The underlying value for <c>BodySerializationMethod.JsonLines</c>.</summary>
     private const int BodySerializationJsonLines = 4;
 
+    /// <summary>The underlying value for <c>RequestCompression.None</c>.</summary>
+    private const int RequestCompressionNone = 1;
+
+    /// <summary>The underlying value for <c>RequestCompression.GZip</c>.</summary>
+    private const int RequestCompressionGZip = 2;
+
+    /// <summary>The underlying value for <c>RequestCompression.Brotli</c>.</summary>
+    private const int RequestCompressionBrotli = 3;
+
+    /// <summary>The underlying value for <c>RequestCompression.Zstandard</c>.</summary>
+    private const int RequestCompressionZstandard = 4;
+
+    /// <summary>The underlying value for <c>CompressionLevel.Fastest</c>.</summary>
+    private const int CompressionLevelFastest = 1;
+
+    /// <summary>The underlying value for <c>CompressionLevel.NoCompression</c>.</summary>
+    private const int CompressionLevelNoCompression = 2;
+
+    /// <summary>The underlying value for <c>CompressionLevel.SmallestSize</c>.</summary>
+    private const int CompressionLevelSmallestSize = 3;
+
     /// <summary>Determines whether a symbol's containing namespace equals a dotted namespace name, without allocating.</summary>
     /// <param name="symbol">The symbol whose containing namespace is compared, or null.</param>
     /// <param name="dottedNamespace">The expected namespace as a dotted name, for example <c>System.Threading.Tasks</c>.</param>
@@ -236,6 +257,31 @@ internal static string GetBodySerializationMethodName(int value) =>
             _ => string.Empty
         };
 
+    /// <summary>Gets the Refit request compression enum member name for an underlying value.</summary>
+    /// <param name="value">The enum value.</param>
+    /// <returns>The enum member name, or <c>Default</c> for a value this generator does not know.</returns>
+    internal static string GetRequestCompressionName(int value) =>
+        value switch
+        {
+            RequestCompressionNone => "None",
+            RequestCompressionGZip => "GZip",
+            RequestCompressionBrotli => "Brotli",
+            RequestCompressionZstandard => "Zstandard",
+            _ => "Default"
+        };
+
+    /// <summary>Gets the <c>System.IO.Compression.CompressionLevel</c> member name for an underlying value.</summary>
+    /// <param name="value">The enum value.</param>
+    /// <returns>The enum member name, or <c>Optimal</c> for a value this generator does not know.</returns>
+    internal static string GetCompressionLevelName(int value) =>
+        value switch
+        {
+            CompressionLevelFastest => "Fastest",
+            CompressionLevelNoCompression => "NoCompression",
+            CompressionLevelSmallestSize => "SmallestSize",
+            _ => "Optimal"
+        };
+
     /// <summary>Determines whether all body bindings are supported by the initial inline emitter.</summary>
     /// <param name="parameters">The parsed request parameter models.</param>
     /// <returns><see langword="true"/> when every body binding is supported.</returns>

src/InterfaceStubGenerator.Shared/Parser.Request.ParameterKinds.cs

@@ -195,7 +195,7 @@ internal static bool TryParseBodyParameter(
                     string.Empty,
                     string.Empty,
                     bodyInfo.SerializationMethod,
-                bodyInfo.BufferMode) { FormFields = formFields, };
+                bodyInfo.BufferMode) { FormFields = formFields, Compression = bodyInfo.Compression, CompressionLevel = bodyInfo.CompressionLevel, };
             return true;
         }
 

src/Refit.Reflection/RequestBuilderImplementation.Payload.cs

@@ -18,6 +18,27 @@ internal partial class RequestBuilderImplementation
     /// <param name="ret">The request message to populate.</param>
     [RequiresDynamicCode("Serializing a body by runtime Type requires runtime generic method instantiation.")]
     internal void AddBodyToRequest(RestMethodInfoInternal restMethod, object param, HttpRequestMessage ret)
+    {
+        SelectBodyContent(restMethod, param, ret);
+
+        if (ret.Content is null)
+        {
+            return;
+        }
+
+        ret.Content = GeneratedRequestRunner.CompressBodyContent(
+            ret.Content,
+            _settings,
+            restMethod.BodyCompression,
+            restMethod.BodyCompressionLevel);
+    }
+
+    /// <summary>Sets the request content from the body parameter, before any content coding is applied.</summary>
+    /// <param name="restMethod">The rest method being invoked.</param>
+    /// <param name="param">The body argument value.</param>
+    /// <param name="ret">The request message to populate.</param>
+    [RequiresDynamicCode("Serializing a body by runtime Type requires runtime generic method instantiation.")]
+    internal void SelectBodyContent(RestMethodInfoInternal restMethod, object param, HttpRequestMessage ret)
     {
         if (param is HttpContent httpContentParam)
         {

src/Refit.Reflection/RestMethodInfoInternal.AttributeReading.cs

@@ -218,6 +218,19 @@ internal static (BodyAttribute? Attribute, int Index, bool HasMultiple) FindBody
         return (bodyAttribute, bodyParameterIndex, false);
     }
 
+    /// <summary>Reads the content coding an explicit <see cref="BodyAttribute"/> declared.</summary>
+    /// <param name="sets">The classified attribute set for each parameter.</param>
+    /// <returns>The declared coding and level. An implicit body declares neither, so it follows the settings.</returns>
+    internal static (RequestCompression Compression, System.IO.Compression.CompressionLevel Level) FindBodyCompression(
+        ParameterAttributeSet[] sets)
+    {
+        var (bodyAttribute, _, _) = FindBodyAttribute(sets);
+
+        return bodyAttribute is null
+            ? (RequestCompression.Default, System.IO.Compression.CompressionLevel.Optimal)
+            : (bodyAttribute.Compression, bodyAttribute.CompressionLevel);
+    }
+
     /// <summary>Finds the parameter that carries the authorization value.</summary>
     /// <param name="sets">The classified attribute set for each parameter.</param>
     /// <returns>The authorization parameter information, or null when there is no authorize parameter.</returns>

src/Refit.Reflection/RestMethodInfoInternal.cs

@@ -93,6 +93,7 @@ internal RestMethodInfoInternal(
         UrlParameterInfo = ResolveUrlParameter(ParameterInfoArray, parameterAttributeSets, RelativePath);
         (ParameterMap, FragmentPath) = BuildParameterMap(RelativePath, ParameterInfoArray, RefitSettings.AllowUnmatchedRouteParameters || methodInfo.IsGenericMethodDefinition);
         BodyParameterInfo = FindBodyParameter(ParameterInfoArray, parameterAttributeSets, IsMultipart, hma.Method);
+        (BodyCompression, BodyCompressionLevel) = FindBodyCompression(parameterAttributeSets);
         AuthorizeParameterInfo = FindAuthorizationParameter(parameterAttributeSets);
 
         Headers = ParseHeaders(targetInterface, methodInfo);
@@ -160,6 +161,12 @@ internal RestMethodInfoInternal(
     /// <summary>Gets the body parameter information, or null when there is no body parameter.</summary>
     internal Tuple<BodySerializationMethod, bool, int>? BodyParameterInfo { get; }
 
+    /// <summary>Gets the content coding the <c>[Body]</c> parameter declared, <c>Default</c> to follow the settings.</summary>
+    internal RequestCompression BodyCompression { get; }
+
+    /// <summary>Gets how hard <see cref="BodyCompression"/> compresses.</summary>
+    internal System.IO.Compression.CompressionLevel BodyCompressionLevel { get; }
+
     /// <summary>Gets the authorization parameter information, or null when there is no authorize parameter.</summary>
     internal Tuple<string, int>? AuthorizeParameterInfo { get; }
 

src/Refit/BodyAttribute.cs

@@ -54,4 +54,16 @@ public BodyAttribute(BodySerializationMethod serializationMethod) =>
     /// </value>
     public BodySerializationMethod SerializationMethod { get; } =
         BodySerializationMethod.Default;
+
+    /// <summary>Gets or sets the content coding applied to this body, overriding <see cref="RefitSettings.RequestCompression"/>.</summary>
+    /// <remarks>
+    /// Leave unset to follow the settings. <see cref="RequestCompression.None"/> opts this method out of a coding the
+    /// settings turned on. Not every coding exists on every target framework - see <see cref="RequestCompression"/>.
+    /// </remarks>
+    public RequestCompression Compression { get; set; } = RequestCompression.Default;
+
+    /// <summary>Gets or sets how hard <see cref="Compression"/> compresses (defaults to <see cref="System.IO.Compression.CompressionLevel.Optimal"/>).</summary>
+    /// <remarks>Read only when <see cref="Compression"/> names a coding; otherwise the settings supply the level too.</remarks>
+    public System.IO.Compression.CompressionLevel CompressionLevel { get; set; } =
+        System.IO.Compression.CompressionLevel.Optimal;
 }