KTOR-6711 Add configurable space encoding (spaceToPlus) to form parameters

ktor-client/ktor-client-core/common/src/io/ktor/client/request/forms/FormDataContent.kt

@@ -23,11 +23,13 @@ private val RN_BYTES = "\r\n".toByteArray()
  * [Report a problem](https://ktor.io/feedback/?fqname=io.ktor.client.request.forms.FormDataContent)
  *
  * @param formData data to send.
+ * @param spaceToPlus if true, space character is encoded as `+`, otherwise as `%20`. Defaults to true.
  */
 public class FormDataContent(
-    public val formData: Parameters
+    public val formData: Parameters,
+    spaceToPlus: Boolean = true
 ) : OutgoingContent.ByteArrayContent() {
-    private val content = formData.formUrlEncode().toByteArray()
+    private val content = formData.formUrlEncode(spaceToPlus).toByteArray()
 
     override val contentLength: Long = content.size.toLong()
     override val contentType: ContentType = ContentType.Application.FormUrlEncoded.withCharset(Charsets.UTF_8)

ktor-http/common/src/io/ktor/http/HttpUrlEncoded.kt

@@ -32,21 +32,26 @@ public fun String.parseUrlEncodedParameters(defaultEncoding: Charset = Charsets.
  * Encode form parameters from a list of pairs
  *
  * [Report a problem](https://ktor.io/feedback/?fqname=io.ktor.http.formUrlEncode)
+ *
+ * @param spaceToPlus if true, space character is encoded as `+`, otherwise as `%20`. Defaults to true.
  */
-public fun List<Pair<String, String?>>.formUrlEncode(): String = buildString { formUrlEncodeTo(this) }
+public fun List<Pair<String, String?>>.formUrlEncode(spaceToPlus: Boolean = true): String =
+    buildString { formUrlEncodeTo(this, spaceToPlus) }
 
 /**
  * Encode form parameters from a list of pairs to the specified [out] appendable
  *
  * [Report a problem](https://ktor.io/feedback/?fqname=io.ktor.http.formUrlEncodeTo)
+ *
+ * @param spaceToPlus if true, space character is encoded as `+`, otherwise as `%20`. Defaults to true.
  */
-public fun List<Pair<String, String?>>.formUrlEncodeTo(out: Appendable) {
+public fun List<Pair<String, String?>>.formUrlEncodeTo(out: Appendable, spaceToPlus: Boolean = true) {
     joinTo(out, "&") {
-        val key = it.first.encodeURLParameter(spaceToPlus = true)
+        val key = it.first.encodeURLParameter(spaceToPlus = spaceToPlus)
         if (it.second == null) {
             key
         } else {
-            val value = it.second.toString().encodeURLParameterValue()
+            val value = it.second.toString().encodeURLParameter(spaceToPlus = spaceToPlus)
             "$key=$value"
         }
     }
@@ -56,26 +61,30 @@ public fun List<Pair<String, String?>>.formUrlEncodeTo(out: Appendable) {
  * Encode form parameters
  *
  * [Report a problem](https://ktor.io/feedback/?fqname=io.ktor.http.formUrlEncode)
+ *
+ * @param spaceToPlus if true, space character is encoded as `+`, otherwise as `%20`. Defaults to true.
  */
-public fun Parameters.formUrlEncode(): String = entries()
+public fun Parameters.formUrlEncode(spaceToPlus: Boolean = true): String = entries()
     .flatMap { e -> e.value.map { e.key to it } }
-    .formUrlEncode()
+    .formUrlEncode(spaceToPlus)
 
 /**
  * Encode form parameters to the specified [out] appendable
  *
  * [Report a problem](https://ktor.io/feedback/?fqname=io.ktor.http.formUrlEncodeTo)
+ *
+ * @param spaceToPlus if true, space character is encoded as `+`, otherwise as `%20`. Defaults to true.
  */
-public fun Parameters.formUrlEncodeTo(out: Appendable) {
-    entries().formUrlEncodeTo(out)
+public fun Parameters.formUrlEncodeTo(out: Appendable, spaceToPlus: Boolean = true) {
+    entries().formUrlEncodeTo(out, spaceToPlus)
 }
 
-internal fun ParametersBuilder.formUrlEncodeTo(out: Appendable) {
-    entries().formUrlEncodeTo(out)
+internal fun ParametersBuilder.formUrlEncodeTo(out: Appendable, spaceToPlus: Boolean = true) {
+    entries().formUrlEncodeTo(out, spaceToPlus)
 }
 
-internal fun Set<Map.Entry<String, List<String>>>.formUrlEncodeTo(out: Appendable) {
+internal fun Set<Map.Entry<String, List<String>>>.formUrlEncodeTo(out: Appendable, spaceToPlus: Boolean = true) {
     flatMap { (key, value) ->
         if (value.isEmpty()) listOf(key to null) else value.map { key to it }
-    }.formUrlEncodeTo(out)
+    }.formUrlEncodeTo(out, spaceToPlus)
 }

ktor-http/common/test/io/ktor/tests/http/CodecTest.kt

@@ -153,6 +153,37 @@ class CodecTest {
         assertEquals("/path/%F0%9F%90%95", surrogateSymbolUrlPath.encodeURLPath())
     }
 
+    @Test
+    fun testFormUrlEncodeWithSpaceToPlus() {
+        val result = StringBuilder()
+        val params = mapOf("a" to listOf("b c"))
+
+        // Test Default (spaceToPlus = true) -> Expect +
+        params.entries.formUrlEncodeTo(result)
+        assertEquals("a=b+c", result.toString())
+
+        // Test Explicit (spaceToPlus = true) -> Expect +
+        result.clear()
+        params.entries.formUrlEncodeTo(result, spaceToPlus = true)
+        assertEquals("a=b+c", result.toString())
+
+        // Test Explicit (spaceToPlus = false) -> Expect %20
+        result.clear()
+        params.entries.formUrlEncodeTo(result, spaceToPlus = false)
+        assertEquals("a=b%20c", result.toString())
+    }
+
+    @Test
+    fun testListFormUrlEncodeWithSpaceToPlus() {
+        val params = listOf("a" to "b c")
+
+        // Default behavior -> +
+        assertEquals("a=b+c", params.formUrlEncode())
+
+        // Explicit false -> %20
+        assertEquals("a=b%20c", params.formUrlEncode(spaceToPlus = false))
+    }
+
     private fun encodeAndDecodeTest(text: String) {
         val encode1 = text.encodeURLQueryComponent()
         val decode1 = encode1.decodeURLQueryComponent()