Reviewing files that changed from the base of the PR and between e081285 and 2541ece.

• ktor-client/ktor-client-core/common/src/io/ktor/client/request/forms/FormDataContent.kt (1 hunks)
• ktor-http/common/src/io/ktor/http/HttpUrlEncoded.kt (2 hunks)
• ktor-http/common/test/io/ktor/tests/http/CodecTest.kt (1 hunks)

ktor-http/common/src/io/ktor/http/HttpUrlEncoded.kt (2)

31-40: Space encoding flag is wired correctly through all form encoders

The new spaceToPlus flag is consistently propagated through list- and Parameters-based formUrlEncode* functions and into encodeURLParameter(spaceToPlus = spaceToPlus). Defaulting to true preserves existing + behavior while allowing %20 when needed. From a behavior perspective this looks solid and backwards-compatible for callers who recompile.

Also applies to: 48-58, 67-70, 78-80, 82-84, 86-90

---

38-40: Ensure ABI changes are properly tracked via ./gradlew updateLegacyAbi

All four formUrlEncode / formUrlEncodeTo signatures now take spaceToPlus: Boolean = true. Run ./gradlew updateLegacyAbi to document this intentional API change in the API signature files. Note that breaking changes in unreleased code are acceptable per Ktor development practices—the key requirement is that API changes must be tracked in the /api/ directories.

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

25-33: FormDataContent wiring to spaceToPlus looks correct

The new spaceToPlus parameter feeds directly into formData.formUrlEncode(spaceToPlus) and the KDoc documents it clearly; the default preserves existing behavior while allowing %20 when required.

---

28-33: Constructor change needs verification against ABI tracking

Verify whether this constructor change has been tracked in the /api/ktor-client-core.api descriptor files. If the change is unreleased and properly documented in the API files, breaking changes may be acceptable per Ktor's development guidelines. If the change is not yet tracked in API descriptors, run ./gradlew updateLegacyAbi to update them. Only add a secondary constructor if empirical ABI checks via ./gradlew checkLegacyAbi fail.

ktor-http/common/test/io/ktor/tests/http/CodecTest.kt (1)

156-185: Good coverage for spaceToPlus behavior on both map and list encoders

The two new tests correctly exercise:

• Default plus behavior and explicit spaceToPlus = true/false for map-based entries.formUrlEncodeTo.
• Default plus behavior and explicit %20 behavior for list-based formUrlEncode.

This should prevent regressions around the new flag.

Reviewing files that changed from the base of the PR and between 2541ece and 95d04c9.

• ktor-http/common/src/io/ktor/http/HttpUrlEncoded.kt (1 hunks)

ktor-http/common/src/io/ktor/http/HttpUrlEncoded.kt (4)

40-58: Implementation looks solid.

The spaceToPlus parameter is correctly propagated to both key and value encoding using named parameter syntax, and null values are handled appropriately.

---

60-68: LGTM!

The parameter chaining is correct, and the documentation clearly describes the behavior.

---

82-84: LGTM!

The internal function correctly propagates the parameter through the call chain.

---

86-90: LGTM!

The flattening logic correctly handles empty value lists and properly delegates with the spaceToPlus parameter.

Reviewing files that changed from the base of the PR and between 95d04c9 and a179fa8.

• ktor-http/api/ktor-http.api (1 hunks)
• ktor-http/api/ktor-http.klib.api (2 hunks)

ktor-http/api/ktor-http.api (1)

771-778: API changes look correct and consistent.

The addition of the Boolean parameter to form URL encoding methods is properly reflected in the API descriptor with:

• Both formUrlEncode and formUrlEncodeTo method families updated
• Both Parameters and List overloads covered
• Synthetic $default methods correctly generated for JVM default parameter support

This maintains binary compatibility through default parameters.

Please verify the following to ensure completeness:

#!/bin/bash
# Verify that the default value is spaceToPlus = true for backward compatibility
echo "=== Checking default parameter value in implementation ==="
rg -n "fun formUrlEncode.*spaceToPlus.*=" --type=kt -A2

echo -e "\n=== Checking KDoc for the new parameter ==="
rg -n "@param spaceToPlus" --type=kt -B2 -A2

Based on learnings, API changes must be well-documented with parameter descriptions.

Reviewing files that changed from the base of the PR and between a179fa8 and 1b12f47.

• ktor-client/ktor-client-core/api/ktor-client-core.api (1 hunks)
• ktor-client/ktor-client-core/api/ktor-client-core.klib.api (1 hunks)
• ktor-http/api/ktor-http.api (1 hunks)
• ktor-http/api/ktor-http.klib.api (2 hunks)
• ktor-server/ktor-server-core/api/ktor-server-core.api (1 hunks)

ktor-http/api/ktor-http.klib.api (2)

1738-1739: spaceToPlus flag on Parameters-based formUrlEncode looks consistent; just confirm ABI expectations

The added Boolean parameter (with a default) on the Parameters.formUrlEncode / formUrlEncodeTo extensions matches the PR intent and preserves previous behavior when omitted. It does, however, change the function descriptors compared to the earlier single-parameter versions, which is an ABI-breaking change for callers compiled against the old signatures (especially in native/JS targets). Please confirm this break is acceptable for the branch you’re targeting, or consider adding overloads that keep the old signatures delegating to the new ones.

---

1759-1760: List<Pair<...>> overloads mirror Parameters APIs; same ABI caveat applies

The list-based formUrlEncode / formUrlEncodeTo extensions are updated symmetrically with the same Boolean default parameter, which is good for API consistency and behavior. As with the Parameters overloads, this changes the exported signatures; please double-check that this intended ABI break is acceptable, or add delegating overloads that retain the legacy one-parameter forms if you need binary compatibility.

ktor-client/ktor-client-core/api/ktor-client-core.klib.api (1)

909-920: Binary incompatibility introduced; clarify if acceptable for this development cycle

The constructor signature change from (Parameters) to (Parameters, Boolean = true) breaks binary compatibility. Even though the Boolean parameter has a default value, the old single-argument constructor is no longer available at the ABI level—existing binaries compiled against previous versions will fail to link.

Per the learnings from this project, breaking changes are acceptable for unreleased versions (similar to prior decisions on ktor-server-di). If this version is still in development, this change may be intentional and acceptable. However, verify this with the team or use the dual-constructor pattern suggested in the original review if binary compatibility with prior releases must be maintained:

public class FormDataContent(
    public val formData: Parameters,
    spaceToPlus: Boolean,
) : OutgoingContent.ByteArrayContent() {
    // ...
    
    constructor(formData: Parameters) : this(formData, spaceToPlus = true)
}

Note: The default parameter on the primary constructor maintains source-level compatibility for new code, which is good practice regardless.

ktor-http/api/ktor-http.api (1)

771-781: API surface changes are consistent and preserve backward compatibility.

The addition of the boolean spaceToPlus parameter to formUrlEncode and formUrlEncodeTo (for both Parameters and List<Pair> overloads) is handled correctly:

• Synthetic default methods (formUrlEncode$default, formUrlEncodeTo$default) enable Kotlin's default parameter semantics at the JVM boundary, ensuring existing callers continue to work without modification.
• All four encoding function variants are updated consistently.

Based on learnings, API changes must be intentional and well-documented. Please ensure:

1. The implementation correctly defaults spaceToPlus = true (as stated in PR objectives).
2. Public documentation (KDoc) clearly explains the behavior difference between spaceToPlus = true (spaces encoded as +) and spaceToPlus = false (spaces encoded as %20).
3. Migration guidance is provided if the default may change in future versions.

Run the following script to verify the implementation includes proper documentation and default values:

#!/bin/bash
# Verify implementation of formUrlEncode functions includes proper defaults and documentation

# Check for the spaceToPlus parameter with default value in implementation
rg -A5 -B2 'fun formUrlEncode.*spaceToPlus.*=.*true' ktor-http/common/src/io/ktor/http/

# Check for KDoc documentation on spaceToPlus parameter
rg -B10 'fun formUrlEncode' ktor-http/common/src/io/ktor/http/HttpUrlEncoded.kt | grep -E '(@param|spaceToPlus|%20|\+)'