Add streaming support for Gson request bodies (#4335)

Author: JakeWharton

CHANGELOG.md

@@ -7,6 +7,7 @@
  - First-party converters now support deferring serialization to happen when the request body is written (i.e., during HTTP execution) rather than when the HTTP request is created. In some cases this moves conversion from a calling thread to a background thread, such as in the case when using `Call.enqueue` directly.
 
    The following converters support this feature through a new `withStreaming()` factory method:
+   - Gson
    - Moshi
    - Wire
 

retrofit-converters/gson/build.gradle

@@ -9,6 +9,7 @@ dependencies {
   testImplementation libs.junit
   testImplementation libs.truth
   testImplementation libs.okhttp.mockwebserver
+  testImplementation libs.testParameterInjector
 }
 
 jar {

retrofit-converters/gson/src/main/java/retrofit2/converter/gson/GsonConverterFactory.java

@@ -22,6 +22,7 @@
 import java.lang.reflect.Type;
 import okhttp3.RequestBody;
 import okhttp3.ResponseBody;
+import retrofit2.Call;
 import retrofit2.Converter;
 import retrofit2.Retrofit;
 
@@ -49,13 +50,25 @@ public static GsonConverterFactory create() {
   @SuppressWarnings("ConstantConditions") // Guarding public API nullability.
   public static GsonConverterFactory create(Gson gson) {
     if (gson == null) throw new NullPointerException("gson == null");
-    return new GsonConverterFactory(gson);
+    return new GsonConverterFactory(gson, false);
   }
 
   private final Gson gson;
+  private final boolean streaming;
 
-  private GsonConverterFactory(Gson gson) {
+  private GsonConverterFactory(Gson gson, boolean streaming) {
     this.gson = gson;
+    this.streaming = streaming;
+  }
+
+  /**
+   * Return a new factory which streams serialization of request messages to bytes on the HTTP thread
+   * This is either the calling thread for {@link Call#execute()}, or one of OkHttp's background
+   * threads for {@link Call#enqueue}. Response bytes are always converted to message instances on
+   * one of OkHttp's background threads.
+   */
+  public GsonConverterFactory withStreaming() {
+    return new GsonConverterFactory(gson, true);
   }
 
   @Override
@@ -72,6 +85,6 @@ public Converter<?, RequestBody> requestBodyConverter(
       Annotation[] methodAnnotations,
       Retrofit retrofit) {
     TypeAdapter<?> adapter = gson.getAdapter(TypeToken.get(type));
-    return new GsonRequestBodyConverter<>(gson, adapter);
+    return new GsonRequestBodyConverter<>(gson, adapter, streaming);
   }
 }

retrofit-converters/gson/src/main/java/retrofit2/converter/gson/GsonRequestBodyConverter.java

@@ -26,26 +26,38 @@
 import okhttp3.MediaType;
 import okhttp3.RequestBody;
 import okio.Buffer;
+import okio.BufferedSink;
 import retrofit2.Converter;
 
 final class GsonRequestBodyConverter<T> implements Converter<T, RequestBody> {
-  private static final MediaType MEDIA_TYPE = MediaType.get("application/json; charset=UTF-8");
+  static final MediaType MEDIA_TYPE = MediaType.get("application/json; charset=UTF-8");
 
   private final Gson gson;
   private final TypeAdapter<T> adapter;
+  private final boolean streaming;
 
-  GsonRequestBodyConverter(Gson gson, TypeAdapter<T> adapter) {
+  GsonRequestBodyConverter(Gson gson, TypeAdapter<T> adapter, boolean streaming) {
     this.gson = gson;
     this.adapter = adapter;
+    this.streaming = streaming;
   }
 
   @Override
   public RequestBody convert(T value) throws IOException {
+    if (streaming) {
+      return new GsonStreamingRequestBody<>(gson, adapter, value);
+    }
+
     Buffer buffer = new Buffer();
-    Writer writer = new OutputStreamWriter(buffer.outputStream(), UTF_8);
+    writeJson(buffer, gson, adapter, value);
+    return RequestBody.create(MEDIA_TYPE, buffer.readByteString());
+  }
+
+  static <T> void writeJson(BufferedSink sink, Gson gson, TypeAdapter<T> adapter, T value)
+      throws IOException {
+    Writer writer = new OutputStreamWriter(sink.outputStream(), UTF_8);
     JsonWriter jsonWriter = gson.newJsonWriter(writer);
     adapter.write(jsonWriter, value);
     jsonWriter.close();
-    return RequestBody.create(MEDIA_TYPE, buffer.readByteString());
   }
 }

retrofit-converters/gson/src/main/java/retrofit2/converter/gson/GsonStreamingRequestBody.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright (C) 2025 Square, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package retrofit2.converter.gson;
+
+import static retrofit2.converter.gson.GsonRequestBodyConverter.MEDIA_TYPE;
+import static retrofit2.converter.gson.GsonRequestBodyConverter.writeJson;
+
+import com.google.gson.Gson;
+import com.google.gson.TypeAdapter;
+import java.io.IOException;
+import okhttp3.MediaType;
+import okhttp3.RequestBody;
+import okio.BufferedSink;
+
+final class GsonStreamingRequestBody<T> extends RequestBody {
+  private final Gson gson;
+  private final TypeAdapter<T> adapter;
+  private final T value;
+
+  public GsonStreamingRequestBody(Gson gson, TypeAdapter<T> adapter, T value) {
+    this.gson = gson;
+    this.adapter = adapter;
+    this.value = value;
+  }
+
+  @Override
+  public MediaType contentType() {
+    return MEDIA_TYPE;
+  }
+
+  @Override
+  public void writeTo(BufferedSink sink) throws IOException {
+    writeJson(sink, gson, adapter, value);
+  }
+}

retrofit-converters/gson/src/test/java/retrofit2/converter/gson/GsonConverterFactoryTest.java

@@ -17,6 +17,7 @@
 
 import static com.google.common.truth.Truth.assertThat;
 import static org.junit.Assert.fail;
+import static org.junit.Assume.assumeTrue;
 
 import com.google.gson.Gson;
 import com.google.gson.GsonBuilder;
@@ -25,20 +26,27 @@
 import com.google.gson.stream.JsonReader;
 import com.google.gson.stream.JsonToken;
 import com.google.gson.stream.JsonWriter;
+import com.google.testing.junit.testparameterinjector.TestParameter;
+import com.google.testing.junit.testparameterinjector.TestParameterInjector;
+import java.io.EOFException;
 import java.io.IOException;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.atomic.AtomicReference;
 import okhttp3.mockwebserver.MockResponse;
 import okhttp3.mockwebserver.MockWebServer;
 import okhttp3.mockwebserver.RecordedRequest;
-import org.junit.Before;
 import org.junit.Rule;
 import org.junit.Test;
+import org.junit.runner.RunWith;
 import retrofit2.Call;
+import retrofit2.Callback;
 import retrofit2.Response;
 import retrofit2.Retrofit;
 import retrofit2.http.Body;
 import retrofit2.http.GET;
 import retrofit2.http.POST;
 
+@RunWith(TestParameterInjector.class)
 public final class GsonConverterFactoryTest {
   interface AnInterface {
     String getName();
@@ -57,27 +65,27 @@ public String getName() {
     }
   }
 
-  static final class Value {
-    static final TypeAdapter<Value> BROKEN_ADAPTER =
-        new TypeAdapter<Value>() {
+  static final class ErroringValue {
+    static final TypeAdapter<ErroringValue> BROKEN_ADAPTER =
+        new TypeAdapter<ErroringValue>() {
           @Override
-          public void write(JsonWriter out, Value value) {
-            throw new AssertionError();
+          public void write(JsonWriter out, ErroringValue value) throws IOException {
+            throw new EOFException("oops!");
           }
 
           @Override
           @SuppressWarnings("CheckReturnValue")
-          public Value read(JsonReader reader) throws IOException {
+          public ErroringValue read(JsonReader reader) throws IOException {
             reader.beginObject();
             reader.nextName();
             String theName = reader.nextString();
-            return new Value(theName);
+            return new ErroringValue(theName);
           }
         };
 
     final String theName;
 
-    Value(String theName) {
+    ErroringValue(String theName) {
       this.theName = theName;
     }
   }
@@ -116,25 +124,36 @@ interface Service {
     Call<AnInterface> anInterface(@Body AnInterface impl);
 
     @GET("/")
-    Call<Value> value();
+    Call<ErroringValue> readErroringValue();
+
+    @POST("/")
+    Call<Void> writeErroringValue(@Body ErroringValue value);
   }
 
   @Rule public final MockWebServer server = new MockWebServer();
 
-  private Service service;
+  private final boolean streaming;
+  private final Service service;
+
+  public GsonConverterFactoryTest(@TestParameter boolean streaming) {
+    this.streaming = streaming;
 
-  @Before
-  public void setUp() {
     Gson gson =
         new GsonBuilder()
             .registerTypeAdapter(AnInterface.class, new AnInterfaceAdapter())
-            .registerTypeAdapter(Value.class, Value.BROKEN_ADAPTER)
+            .registerTypeAdapter(ErroringValue.class, ErroringValue.BROKEN_ADAPTER)
             .setLenient()
             .create();
+
+    GsonConverterFactory factory = GsonConverterFactory.create(gson);
+    if (streaming) {
+      factory = factory.withStreaming();
+    }
+
     Retrofit retrofit =
-        new Retrofit.Builder()
-            .baseUrl(server.url("/"))
-            .addConverterFactory(GsonConverterFactory.create(gson))
+        new Retrofit.Builder() //
+            .baseUrl(server.url("/")) //
+            .addConverterFactory(factory) //
             .build();
     service = retrofit.create(Service.class);
   }
@@ -191,12 +210,42 @@ public void deserializeUsesConfiguration() throws IOException, InterruptedExcept
   public void requireFullResponseDocumentConsumption() throws Exception {
     server.enqueue(new MockResponse().setBody("{\"theName\":\"value\"}"));
 
-    Call<Value> call = service.value();
+    Call<ErroringValue> call = service.readErroringValue();
     try {
       call.execute();
       fail();
     } catch (JsonIOException e) {
       assertThat(e).hasMessageThat().isEqualTo("JSON document was not fully consumed.");
     }
   }
+
+  @Test
+  public void serializeIsStreamed() throws InterruptedException {
+    assumeTrue(streaming);
+
+    Call<Void> call = service.writeErroringValue(new ErroringValue("hi"));
+
+    final AtomicReference<Throwable> throwableRef = new AtomicReference<>();
+    final CountDownLatch latch = new CountDownLatch(1);
+
+    // If streaming were broken, the call to enqueue would throw the exception synchronously.
+    call.enqueue(
+        new Callback<Void>() {
+          @Override
+          public void onResponse(Call<Void> call, Response<Void> response) {
+            latch.countDown();
+          }
+
+          @Override
+          public void onFailure(Call<Void> call, Throwable t) {
+            throwableRef.set(t);
+            latch.countDown();
+          }
+        });
+    latch.await();
+
+    Throwable throwable = throwableRef.get();
+    assertThat(throwable).isInstanceOf(EOFException.class);
+    assertThat(throwable).hasMessageThat().isEqualTo("oops!");
+  }
 }