feat: support returning the built HttpRequestMessage without sending (#2235)

* feat: support returning the built HttpRequestMessage without sending

- Add a return-type-driven build-only shape: a method declared
  Task<HttpRequestMessage> builds the full request (URL, headers,
  body/multipart content) and returns it to the caller instead of
  dispatching it (Retrofit's Call.request()).
- Emit the build-and-return path in the source generator and add the
  RequestMessage case to the shared return-type classifiers so it is
  inline-eligible and the RF006 analyzer agrees.
- Add the same case to the reflection request builder, building the
  request without sending or disposing it.
- Keep both paths in parity: the async authorization token getter is a
  dispatch-time step and is skipped when only building the request.
- The caller owns the returned request and its content (not disposed).
- Document the feature in the README and breaking-changes notes.

* test: cover request-message return-shape eligibility branches

- Add a classifier test that drives inline eligibility for a
  Task<HttpRequestMessage> return and a Task<T> of another result type,
  exercising both outcomes of the request-message classification arm.
- Check the task result type directly in the classifier instead of
  re-validating the already-matched task shape, dropping conditions no
  caller could reach and keeping the generator and analyzer
  classification paths in agreement.

Author: glennawatson

README.md

@@ -1986,6 +1986,42 @@ so `Wrapper<User>` closes it over `User`. Adapters must have a public parameterl
 the request eagerly and captures it, so a generated deferred call is **single-use**; the reflection path rebuilds the
 request on each invocation, so it can re-run.
 
+### Obtaining the built request without sending
+
+Sometimes you want the fully built `HttpRequestMessage` — to inspect it, sign it, log it, or dispatch it yourself — without
+Refit sending it. Declare the method to return `Task<HttpRequestMessage>` and Refit runs the whole request-building path
+(URL, headers, and body/multipart content) and hands the request back instead of dispatching it. This is the equivalent of
+Retrofit's `Call.request()`, and it removes the need for the old `DelegatingHandler`-mock workaround.
+
+```csharp
+public interface IUserApi
+{
+    [Get("/users/{id}")]
+    Task<HttpRequestMessage> BuildGetUser(int id, [Query] string filter);
+
+    [Post("/users")]
+    Task<HttpRequestMessage> BuildCreateUser([Body] User user);
+}
+
+var api = RestService.For<IUserApi>("https://api.example.com");
+
+using var request = await api.BuildGetUser(42, "active");
+// request.Method        -> GET
+// request.RequestUri     -> /users/42?filter=active (relative; the HttpClient merges the base address on send)
+// request.Headers        -> the built headers
+// dispatch it yourself, or inspect/sign/log it first
+```
+
+Notes:
+
+* **The caller owns the returned request** — Refit does **not** dispose it (and does not dispose its content), so its body
+  stays readable and you can dispatch it yourself. Wrap it in `using` (or dispose it) once you are done.
+* Only `Task<HttpRequestMessage>` is supported (not a synchronous `HttpRequestMessage`), because request building is
+  asynchronous — body serialization in particular. A `CancellationToken` parameter is still allowed.
+* Both the source-generated and reflection request paths build byte-identical requests.
+* A configured async `AuthorizationHeaderValueGetter` runs at dispatch time, so it is **not** applied to a request obtained
+  this way; add its header yourself if you dispatch the request manually.
+
 ### Using generic interfaces
 
 When using something like ASP.NET Web API, it's a fairly common pattern to have a whole stack of CRUD REST services.

docs/breaking-changes.md

@@ -199,6 +199,13 @@ visible in three places.
   generator discovers adapters declared in your project at compile time and emits a direct `Adapt` call — no reflection,
   so adapter-backed methods stay trim and Native AOT clean; the reflection request builder resolves adapters registered
   in `RefitSettings.ReturnTypeAdapters`. See [Custom return types](../README.md#custom-return-types-ireturntypeadapter).
+* **Obtain the built request without sending it.** A method declared to return `Task<HttpRequestMessage>` builds the
+  full request (method, URL, headers, and body/multipart content) and hands it back to the caller instead of dispatching
+  it — the equivalent of Retrofit's `Call.request()`, useful for inspection, signing, logging, or manual dispatch. Both
+  the generated and reflection paths build byte-identical requests. The caller owns the returned request and its content
+  and is responsible for disposing it; the request is not disposed for you and its content stays readable. A configured
+  async `AuthorizationHeaderValueGetter` runs at dispatch time and is therefore not applied to a request obtained this
+  way. See [Obtaining the built request without sending](../README.md#obtaining-the-built-request-without-sending).
 * **Optional URL path segments (`{name?}`).** Append `?` to a placeholder name (matching ASP.NET routing) to make the
   segment optional. When the bound argument is `null` the segment and its preceding `/` are dropped, so a route such as
   `[Get("/push/notifMsg/{deviceId}/{notifMsgId?}")]` produces `/push/notifMsg/device1` (not a 404-prone

src/InterfaceStubGenerator.Shared/Emitter.Helpers.cs

@@ -101,6 +101,7 @@ internal static (bool IsAsync, string ReturnPrefix, string ConfigureAwaitSuffix)
             ReturnTypeInfo.AsyncResult => (true, "return await (", ").ConfigureAwait(false)"),
             ReturnTypeInfo.AsyncEnumerable => (false, ReturnStatementPrefix, string.Empty),
             ReturnTypeInfo.Observable => (false, ReturnStatementPrefix, string.Empty),
+            ReturnTypeInfo.RequestMessage => (false, ReturnStatementPrefix, string.Empty),
             ReturnTypeInfo.Return => (false, ReturnStatementPrefix, string.Empty),
             ReturnTypeInfo.SyncVoid => (false, string.Empty, string.Empty),
             _ => throw new ArgumentOutOfRangeException(

src/InterfaceStubGenerator.Shared/Emitter.Inline.cs

@@ -227,7 +227,12 @@ private static string BuildInlineRefitMethodBody(
             return BuildInlineObservableMethodSource(methodPrefix, requestConstruction, buildRequestLocal, requestLocal, observableReturn, bodyIndent, methodIndent);
         }
 
-        var returnSource = BuildInlineReturn(methodModel, request, plan.BufferBodyExpression, plan.CancellationTokenExpression, requestLocal, settingsLocal, plan.AdapterTokenLocal);
+        // A Task<HttpRequestMessage> method hands the fully built request back to the caller without dispatching it. The
+        // caller owns the returned request and its content, so it is neither sent nor disposed here; every other shape
+        // emits its normal send-and-deserialize return.
+        var returnSource = methodModel.ReturnTypeMetadata == ReturnTypeInfo.RequestMessage
+            ? BuildInlineRequestMessageReturn(requestLocal)
+            : BuildInlineReturn(methodModel, request, plan.BufferBodyExpression, plan.CancellationTokenExpression, requestLocal, settingsLocal, plan.AdapterTokenLocal);
         return $$"""
             {{methodPrefix}}{{requestConstruction}}{{returnSource}}{{methodIndent}}}
 
@@ -361,6 +366,18 @@ private static string BuildInlineObservableReturn(
             """;
     }
 
+    /// <summary>Builds the return statement for a <c>Task&lt;HttpRequestMessage&gt;</c> method that returns the built request.</summary>
+    /// <param name="requestLocal">The generated request message local name.</param>
+    /// <returns>The generated return statement handing the built request back without sending it.</returns>
+    private static string BuildInlineRequestMessageReturn(string requestLocal)
+    {
+        var bodyIndent = Indent(MethodBodyIndentation);
+        return $$"""
+            {{bodyIndent}}return global::System.Threading.Tasks.Task.FromResult({{requestLocal}});
+
+            """;
+    }
+
     /// <summary>Builds the return statement for an inline generated Refit method.</summary>
     /// <param name="methodModel">The method model being emitted.</param>
     /// <param name="request">The parsed request model.</param>

src/InterfaceStubGenerator.Shared/Models/ReturnTypeInfo.cs

@@ -22,5 +22,8 @@ internal enum ReturnTypeInfo
     Observable,
 
     /// <summary>The method returns void synchronously.</summary>
-    SyncVoid
+    SyncVoid,
+
+    /// <summary>The method returns the built <c>Task&lt;HttpRequestMessage&gt;</c> without sending it.</summary>
+    RequestMessage
 }

src/InterfaceStubGenerator.Shared/Parser.InlineEligibility.cs

@@ -14,6 +14,9 @@ namespace Refit.Generator;
 /// </content>
 internal static partial class Parser
 {
+    /// <summary>The <c>System.Threading.Tasks</c> namespace name, matched structurally to identify task return shapes.</summary>
+    private const string TasksNamespace = "System.Threading.Tasks";
+
     /// <summary>Determines whether generated request building can construct a method's request inline.</summary>
     /// <param name="methodSymbol">The Refit method symbol.</param>
     /// <param name="httpMethodBaseAttributeSymbol">The resolved <c>Refit.HttpMethodAttribute</c> symbol.</param>
@@ -81,11 +84,22 @@ private static ReturnTypeInfo ClassifyInlineReturnShape(ITypeSymbol returnType)
         var ns = namedType.ContainingNamespace.ToDisplayString();
         return namedType.MetadataName switch
         {
-            "Task" when ns == "System.Threading.Tasks" => ReturnTypeInfo.AsyncVoid,
-            "Task`1" or "ValueTask`1" when ns == "System.Threading.Tasks" => ReturnTypeInfo.AsyncResult,
+            "Task" when ns == TasksNamespace => ReturnTypeInfo.AsyncVoid,
+            "Task`1" when IsHttpRequestMessageType(namedType.TypeArguments[0]) => ReturnTypeInfo.RequestMessage,
+            "Task`1" or "ValueTask`1" when ns == TasksNamespace => ReturnTypeInfo.AsyncResult,
             "IAsyncEnumerable`1" when ns == "System.Collections.Generic" => ReturnTypeInfo.AsyncEnumerable,
             "IObservable`1" when ns == "System" => ReturnTypeInfo.Observable,
             _ => ReturnTypeInfo.Return
         };
     }
+
+    /// <summary>Determines whether a type is <c>System.Net.Http.HttpRequestMessage</c>, the type argument of the
+    /// build-and-return <c>Task&lt;HttpRequestMessage&gt;</c> shape.</summary>
+    /// <param name="type">The type to inspect.</param>
+    /// <returns><see langword="true"/> when the type is <c>HttpRequestMessage</c>.</returns>
+    /// <remarks>Only the <c>Task</c> wrapper is supported: request building is asynchronous (body serialization and the
+    /// authorization token getter), so a synchronous <c>HttpRequestMessage</c> return would force a blocking build.</remarks>
+    private static bool IsHttpRequestMessageType(ITypeSymbol type) =>
+        type is INamedTypeSymbol { MetadataName: "HttpRequestMessage" } named
+        && named.ContainingNamespace.ToDisplayString() == "System.Net.Http";
 }

src/InterfaceStubGenerator.Shared/Parser.Members.cs

@@ -232,6 +232,7 @@ private static ReturnTypeInfo GetReturnTypeInfo(IMethodSymbol methodSymbol) =>
         methodSymbol.ReturnType.MetadataName switch
         {
             "Task" => ReturnTypeInfo.AsyncVoid,
+            "Task`1" when IsHttpRequestMessageType(((INamedTypeSymbol)methodSymbol.ReturnType).TypeArguments[0]) => ReturnTypeInfo.RequestMessage,
             "Task`1" or "ValueTask`1" => ReturnTypeInfo.AsyncResult,
             "IAsyncEnumerable`1" => ReturnTypeInfo.AsyncEnumerable,
             "IObservable`1" => ReturnTypeInfo.Observable,

src/InterfaceStubGenerator.Shared/Parser.Request.cs

@@ -127,7 +127,7 @@ private static (string? AdapterTypeExpression, ITypeSymbol ResultTypeSource) Res
     /// <returns><see langword="true"/> when the return shape can be generated inline.</returns>
     private static bool IsInlineReturnShape(ReturnTypeInfo returnTypeInfo, string? adapterTypeExpression) =>
         returnTypeInfo is ReturnTypeInfo.AsyncVoid or ReturnTypeInfo.AsyncResult or ReturnTypeInfo.AsyncEnumerable
-            or ReturnTypeInfo.Observable
+            or ReturnTypeInfo.Observable or ReturnTypeInfo.RequestMessage
         || adapterTypeExpression is not null;
 
     /// <summary>Reports an error when a method uses a source-generation-only attribute but cannot generate inline.</summary>

src/Refit.Reflection/RequestBuilderImplementation.Execution.cs

@@ -73,6 +73,38 @@ private static bool IsBodyBuffered(
         HttpRequestMessage request) =>
         (restMethod.BodyParameterInfo?.Item2 ?? false) && request.Content is not null;
 
+    /// <summary>Builds a delegate that constructs and returns the request for a <c>Task&lt;HttpRequestMessage&gt;</c> method.</summary>
+    /// <param name="restMethod">The rest method to build a delegate for.</param>
+    /// <returns>A delegate that returns a task producing the built request without sending it.</returns>
+    [RequiresDynamicCode("Serializing a body by runtime Type requires runtime generic method instantiation.")]
+    private Func<HttpClient, object[], object?> BuildRequestMessageFuncForMethod(
+        RestMethodInfoInternal restMethod) =>
+        (client, paramList) => BuildRequestMessageWithoutSendingAsync(client, restMethod, paramList);
+
+    /// <summary>Builds the request message for a method and returns it to the caller without sending it.</summary>
+    /// <param name="client">The HTTP client whose base address the request is built against.</param>
+    /// <param name="restMethod">The rest method being invoked.</param>
+    /// <param name="paramList">The argument values for the call.</param>
+    /// <returns>The built request; the caller owns it and is responsible for disposing it.</returns>
+    /// <remarks>The request is intentionally not disposed here: it is handed to the caller for inspection, signing,
+    /// logging, or manual dispatch. Any configured async authorization token getter runs at dispatch time and is
+    /// therefore not applied to a request obtained this way.</remarks>
+    [RequiresDynamicCode("Serializing a body by runtime Type requires runtime generic method instantiation.")]
+    private Task<HttpRequestMessage> BuildRequestMessageWithoutSendingAsync(
+        HttpClient client,
+        RestMethodInfoInternal restMethod,
+        object[] paramList)
+    {
+        RequestExecutionHelpers.ThrowIfBaseAddressMissing(client);
+
+        return BuildRequestMessageForMethodAsync(
+            restMethod,
+            client.BaseAddress!.AbsolutePath,
+            restMethod.CancellationToken is not null,
+            paramList,
+            applyAuthorizationHeaderGetter: false);
+    }
+
     /// <summary>Builds and sends the request for a method with no response body, throwing on error.</summary>
     /// <param name="client">The HTTP client to send with.</param>
     /// <param name="restMethod">The rest method being invoked.</param>

src/Refit.Reflection/RequestBuilderImplementation.RequestBuilding.cs

@@ -255,13 +255,16 @@ private static void DropOptionalSegmentSeparator(ref ValueStringBuilder vsb)
     /// <param name="basePath">The base path from the client's base address.</param>
     /// <param name="paramsContainsCancellationToken">Whether the argument list contains a cancellation token.</param>
     /// <param name="paramList">The argument values for the call.</param>
+    /// <param name="applyAuthorizationHeaderGetter">Whether to run the configured async authorization token getter, a
+    /// dispatch-time step skipped when the request is built only to be handed back to the caller.</param>
     /// <returns>The constructed request message.</returns>
     [RequiresDynamicCode("Serializing a body by runtime Type requires runtime generic method instantiation.")]
     private async Task<HttpRequestMessage> BuildRequestMessageForMethodAsync(
         RestMethodInfoInternal restMethod,
         string basePath,
         bool paramsContainsCancellationToken,
-        object[] paramList)
+        object[] paramList,
+        bool applyAuthorizationHeaderGetter = true)
     {
         var cancellationToken = CancellationToken.None;
 
@@ -293,8 +296,11 @@ private async Task<HttpRequestMessage> BuildRequestMessageForMethodAsync(
             MapParametersToRequest(restMethod, paramList, ret, multiPartContent, ref headersToAdd, ref queryParamsToAdd);
 
             AddHeadersToRequest(headersToAdd, ret);
-            await AddAuthorizationHeadersFromGetterAsync(ret, cancellationToken)
-                .ConfigureAwait(false);
+            if (applyAuthorizationHeaderGetter)
+            {
+                await AddAuthorizationHeadersFromGetterAsync(ret, cancellationToken)
+                    .ConfigureAwait(false);
+            }
 
             AddPropertiesToRequest(restMethod, ret, paramList, declaredArguments);
 #if NET6_0_OR_GREATER