Merge branch 'master' into remove-content-type-header-with-empty-post-body

Author: velo

.mvn/extensions.xml

@@ -19,11 +19,11 @@
     <extension>
         <groupId>com.gradle</groupId>
         <artifactId>develocity-maven-extension</artifactId>
-        <version>1.22</version>
+        <version>1.22.1</version>
     </extension>
     <extension>
         <groupId>com.gradle</groupId>
         <artifactId>common-custom-user-data-maven-extension</artifactId>
-        <version>2.0</version>
+        <version>2.0.1</version>
     </extension>
 </extensions>

README.md

@@ -1275,3 +1275,261 @@ The Bill Of Material is a special POM file that groups dependency versions that
   </dependencyManagement>
 </project>
 ```
+# Form Encoder
+
+[![build_status](https://travis-ci.org/OpenFeign/feign-form.svg?branch=master)](https://travis-ci.org/OpenFeign/feign-form)
+[![maven_central](https://maven-badges.herokuapp.com/maven-central/io.github.openfeign.form/feign-form/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.github.openfeign.form/feign-form)
+[![License](http://img.shields.io/:license-apache-brightgreen.svg)](http://www.apache.org/licenses/LICENSE-2.0.html)
+
+This module adds support for encoding **application/x-www-form-urlencoded** and **multipart/form-data** forms.
+
+## Add dependency
+
+Include the dependency to your app:
+
+**Maven**:
+
+```xml
+<dependencies>
+  ...
+  <dependency>
+    <groupId>io.github.openfeign.form</groupId>
+    <artifactId>feign-form</artifactId>
+    <version>4.0.0</version>
+  </dependency>
+  ...
+</dependencies>
+```
+
+**Gradle**:
+
+```groovy
+compile 'io.github.openfeign.form:feign-form:4.0.0'
+```
+
+## Requirements
+
+The `feign-form` extension depend on `OpenFeign` and its *concrete* versions:
+
+- all `feign-form` releases before **3.5.0** works with `OpenFeign` **9.\*** versions;
+- starting from `feign-form`'s version **3.5.0**, the module works with `OpenFeign` **10.1.0** versions and greater.
+
+> **IMPORTANT:** there is no backward compatibility and no any gurantee that the `feign-form`'s versions after **3.5.0** work with `OpenFeign` before **10.\***. `OpenFeign` was refactored in 10th release, so the best approach - use the freshest `OpenFeign` and `feign-form` versions.
+
+Notes:
+
+- [spring-cloud-openfeign](https://github.com/spring-cloud/spring-cloud-openfeign) uses `OpenFeign` **9.\*** till **v2.0.3.RELEASE** and uses **10.\*** after. Anyway, the dependency already has suitable `feign-form` version, see [dependency pom](https://github.com/spring-cloud/spring-cloud-openfeign/blob/master/spring-cloud-openfeign-dependencies/pom.xml#L19), so you don't need to specify it separately;
+
+- `spring-cloud-starter-feign` is a **deprecated** dependency and it always uses the `OpenFeign`'s **9.\*** versions.
+
+## Usage
+
+Add `FormEncoder` to your `Feign.Builder` like so:
+
+```java
+SomeApi github = Feign.builder()
+                      .encoder(new FormEncoder())
+                      .target(SomeApi.class, "http://api.some.org");
+```
+
+Moreover, you can decorate the existing encoder, for example JsonEncoder like this:
+
+```java
+SomeApi github = Feign.builder()
+                      .encoder(new FormEncoder(new JacksonEncoder()))
+                      .target(SomeApi.class, "http://api.some.org");
+```
+
+And use them together:
+
+```java
+interface SomeApi {
+
+  @RequestLine("POST /json")
+  @Headers("Content-Type: application/json")
+  void json (Dto dto);
+
+  @RequestLine("POST /form")
+  @Headers("Content-Type: application/x-www-form-urlencoded")
+  void from (@Param("field1") String field1, @Param("field2") String[] values);
+}
+```
+
+You can specify two types of encoding forms by `Content-Type` header.
+
+### application/x-www-form-urlencoded
+
+```java
+interface SomeApi {
+
+  @RequestLine("POST /authorization")
+  @Headers("Content-Type: application/x-www-form-urlencoded")
+  void authorization (@Param("email") String email, @Param("password") String password);
+
+  // Group all parameters within a POJO
+  @RequestLine("POST /user")
+  @Headers("Content-Type: application/x-www-form-urlencoded")
+  void addUser (User user);
+
+  class User {
+
+    Integer id;
+
+    String name;
+  }
+}
+```
+
+### multipart/form-data
+
+```java
+interface SomeApi {
+
+  // File parameter
+  @RequestLine("POST /send_photo")
+  @Headers("Content-Type: multipart/form-data")
+  void sendPhoto (@Param("is_public") Boolean isPublic, @Param("photo") File photo);
+
+  // byte[] parameter
+  @RequestLine("POST /send_photo")
+  @Headers("Content-Type: multipart/form-data")
+  void sendPhoto (@Param("is_public") Boolean isPublic, @Param("photo") byte[] photo);
+
+  // FormData parameter
+  @RequestLine("POST /send_photo")
+  @Headers("Content-Type: multipart/form-data")
+  void sendPhoto (@Param("is_public") Boolean isPublic, @Param("photo") FormData photo);
+
+  // Group all parameters within a POJO
+  @RequestLine("POST /send_photo")
+  @Headers("Content-Type: multipart/form-data")
+  void sendPhoto (MyPojo pojo);
+
+  class MyPojo {
+
+    @FormProperty("is_public")
+    Boolean isPublic;
+
+    File photo;
+  }
+}
+```
+
+In the example above, the `sendPhoto` method uses the `photo` parameter using three different supported types.
+
+* `File` will use the File's extension to detect the `Content-Type`;
+* `byte[]` will use `application/octet-stream` as `Content-Type`;
+* `FormData` will use the `FormData`'s `Content-Type` and `fileName`;
+* Client's custom POJO for grouping parameters (including types above).
+
+`FormData` is custom object that wraps a `byte[]` and defines a `Content-Type` and `fileName` like this:
+
+```java
+  FormData formData = new FormData("image/png", "filename.png", myDataAsByteArray);
+  someApi.sendPhoto(true, formData);
+```
+
+### Spring MultipartFile and Spring Cloud Netflix @FeignClient support
+
+You can also use Form Encoder with Spring `MultipartFile` and `@FeignClient`.
+
+Include the dependencies to your project's pom.xml file:
+
+```xml
+<dependencies>
+  <dependency>
+    <groupId>io.github.openfeign.form</groupId>
+    <artifactId>feign-form</artifactId>
+    <version>4.0.0</version>
+  </dependency>
+  <dependency>
+    <groupId>io.github.openfeign.form</groupId>
+    <artifactId>feign-form-spring</artifactId>
+    <version>4.0.0</version>
+  </dependency>
+</dependencies>
+```
+
+```java
+@FeignClient(
+    name = "file-upload-service",
+    configuration = FileUploadServiceClient.MultipartSupportConfig.class
+)
+public interface FileUploadServiceClient extends IFileUploadServiceClient {
+
+  public class MultipartSupportConfig {
+
+    @Autowired
+    private ObjectFactory<HttpMessageConverters> messageConverters;
+
+    @Bean
+    public Encoder feignFormEncoder () {
+      return new SpringFormEncoder(new SpringEncoder(messageConverters));
+    }
+  }
+}
+```
+
+Or, if you don't need Spring's standard encoder:
+
+```java
+@FeignClient(
+    name = "file-upload-service",
+    configuration = FileUploadServiceClient.MultipartSupportConfig.class
+)
+public interface FileUploadServiceClient extends IFileUploadServiceClient {
+
+  public class MultipartSupportConfig {
+
+    @Bean
+    public Encoder feignFormEncoder () {
+      return new SpringFormEncoder();
+    }
+  }
+}
+```
+
+Thanks to [tf-haotri-pham](https://github.com/tf-haotri-pham) for his feature, which makes use of Apache commons-fileupload library, which handles the parsing of the multipart response. The body data parts are held as byte arrays in memory.
+
+To use this feature, include SpringManyMultipartFilesReader in the list of message converters for the Decoder and have the Feign client return an array of MultipartFile:
+
+```java
+@FeignClient(
+    name = "${feign.name}",
+    url = "${feign.url}"
+    configuration = DownloadClient.ClientConfiguration.class
+)
+public interface DownloadClient {
+
+  @RequestMapping("/multipart/download/{fileId}")
+  MultipartFile[] download(@PathVariable("fileId") String fileId);
+
+  class ClientConfiguration {
+
+    @Autowired
+    private ObjectFactory<HttpMessageConverters> messageConverters;
+
+    @Bean
+    public Decoder feignDecoder () {
+      List<HttpMessageConverter<?>> springConverters =
+            messageConverters.getObject().getConverters();
+
+      List<HttpMessageConverter<?>> decoderConverters =
+            new ArrayList<HttpMessageConverter<?>>(springConverters.size() + 1);
+
+      decoderConverters.addAll(springConverters);
+      decoderConverters.add(new SpringManyMultipartFilesReader(4096));
+
+      HttpMessageConverters httpMessageConverters = new HttpMessageConverters(decoderConverters);
+
+      return new SpringDecoder(new ObjectFactory<HttpMessageConverters>() {
+
+        @Override
+        public HttpMessageConverters getObject() {
+          return httpMessageConverters;
+        }
+      });
+    }
+  }
+}
+```

core/src/test/java/feign/template/UriUtilsTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2023 The Feign Authors
+ * Copyright 2012-2024 The Feign Authors
  *
  * 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
@@ -14,9 +14,15 @@
 package feign.template;
 
 
+import feign.Param;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
+import java.nio.charset.StandardCharsets;
+import java.util.stream.Stream;
 import static java.nio.charset.StandardCharsets.UTF_8;
 import static org.assertj.core.api.Assertions.assertThat;
-import org.junit.jupiter.api.Test;
 
 class UriUtilsTest {
 
@@ -41,4 +47,26 @@ void pctEncodeWithReservedCharacters() {
     String encoded = UriUtils.encode(withReserved, UTF_8, true);
     assertThat(encoded).isEqualTo("/api/user@host:port#section[a-z]/data");
   }
+
+  @ParameterizedTest
+  @MethodSource("provideValuesToEncode")
+  void testVariousEncodingScenarios(String input, String expected) {
+    assertThat(UriUtils.encode(input, UTF_8)).isEqualTo(expected);
+  }
+
+  private static Stream<Arguments> provideValuesToEncode() {
+    return Stream.of(
+        Arguments.of("foo", "foo"),
+        Arguments.of("foo bar", "foo%20bar"),
+        Arguments.of("foo%20bar", "foo%20bar"),
+        Arguments.of("foo%2520bar", "foo%2520bar"),
+        Arguments.of("foo&bar", "foo%26bar"),
+        Arguments.of("foo& bar", "foo%26%20bar"),
+        Arguments.of("foo = bar", "foo%20%3D%20bar"),
+        Arguments.of("foo   ", "foo%20%20%20"),
+        Arguments.of("foo/bar", "foo%2Fbar"),
+        Arguments.of("foo!\"/$%?&   *( )  _%20^¨  >`:É.   ',.  é ;`^ ¸< nasty stuff here!",
+            "foo%21%22%2F%24%25%3F%26%20%20%20%2A%28%20%29%20%20_%2520%5E%C2%A8%20%20%3E%60%3A%C3%89.%20%20%20%27%2C.%20%20%C3%A9%20%3B%60%5E%20%C2%B8%3C%20nasty%20stuff%20here%21"));
+
+  }
 }