Merge branch 'main' into zibet27/fix-netty-engine-stop

Author: zibet27

CHANGELOG.md

@@ -1,3 +1,25 @@
+# 3.3.2
+> Published 5 November 2025
+
+### Improvements
+* WebRTC Client. Remove redundant targets ([KTOR-9062](https://youtrack.jetbrains.com/issue/KTOR-9062))
+* Add Socks proxy support to Darwin engine ([KTOR-8968](https://youtrack.jetbrains.com/issue/KTOR-8968))
+* Java: Improve error message when SOCKS proxy is used ([KTOR-2908](https://youtrack.jetbrains.com/issue/KTOR-2908))
+
+### Bugfixes
+* HttpRequestRetry: SendCountExceedException when max retries is more than maxSendCount of HttpSend ([KTOR-5850](https://youtrack.jetbrains.com/issue/KTOR-5850))
+* Darwin: The `maxFrameSize` option has no effect ([KTOR-6963](https://youtrack.jetbrains.com/issue/KTOR-6963))
+* OpenAPI: StackOverflowError when a response object has property with @Contextual serializer ([KTOR-8878](https://youtrack.jetbrains.com/issue/KTOR-8878))
+* OpenAPI gen: missing KDoc fields ([KTOR-9021](https://youtrack.jetbrains.com/issue/KTOR-9021))
+* Server call.request.path() returns routing selectors in path ([KTOR-7639](https://youtrack.jetbrains.com/issue/KTOR-7639))
+* StaticContent doesn't allow siblings ([KTOR-9012](https://youtrack.jetbrains.com/issue/KTOR-9012))
+* HttpCache: FileStorage doesn't use given dispatcher for all file operations ([KTOR-8832](https://youtrack.jetbrains.com/issue/KTOR-8832))
+* Curl: SOCKS proxy doesn't work ([KTOR-9008](https://youtrack.jetbrains.com/issue/KTOR-9008))
+* Netty: java.lang.VerifyError is thrown on Android since 3.3.0 ([KTOR-8916](https://youtrack.jetbrains.com/issue/KTOR-8916))
+* Response body channel is canceled while the body is being saved when having HttpRequestRetry and onDownload ([KTOR-8975](https://youtrack.jetbrains.com/issue/KTOR-8975))
+* HttpCache: InvalidCacheStateException when varyKeys stored in files contain uppercase letters since 3.3.0 ([KTOR-8970](https://youtrack.jetbrains.com/issue/KTOR-8970))
+
+
 # 3.3.1
 > Published 8 October 2025
 

CONTRIBUTING.md

@@ -41,17 +41,8 @@ Up to 12 GB of free RAM is required to build the project.
 This amount can be reduced by decreasing the `Xmx` value in `gradle.properties`.
 Read the comments in `gradle.properties` for more details.
 
-The path to the android sdk should be defined in the ANDROID_HOME environment variable or `sdk.dir` in the `local.properties` file, like:
-```properties
-sdk.dir=/Users/USER_NAME/Library/Android/sdk
-```
-
-If you target macOS and/or iOS, install `Xcode`, `Xcode command line tools`, `CocoaPods` and `Ruby` on macOS.
-An outdated Ruby version 2 is installed by default, but you should manually install a new version of it.
-We recommend using Ruby `3.3.x` or newer with [rbenv](https://github.com/rbenv/rbenv):
-- `rbenv install 3.3.x`
-- `rbenv global 3.3.x`
-- `sudo gem install -n /usr/local/bin cocoapods`
+On macOS, install [Xcode and Xcode Command line tools](https://developer.apple.com/download/) to build Apple targets.
+Launch it and accept the license terms first.
 
 <details>
 <summary>Requirements for Ktor before 3.1.0</summary>
@@ -85,6 +76,32 @@ libraries such as `libncurses`.
 
 </details>
 
+#### Optional: Android SDK
+
+The Android SDK is optional for building Ktor.
+If the Android SDK is not available, Android targets will be automatically excluded from the build.
+
+To install the Android SDK, use [Android Studio](https://developer.android.com/studio) or [sdkmanager](https://developer.android.com/tools/sdkmanager).
+
+To enable Android targets,
+define the path to the Android SDK in the `ANDROID_HOME` environment variable or `sdk.dir` in the `local.properties` file:
+```properties
+sdk.dir=/path/to/android/sdk
+```
+
+#### Optional: CocoaPods for Apple targets
+
+CocoaPods is optional for building Ktor.
+If CocoaPods is not available on macOS, Apple targets will be automatically excluded from modules that require CocoaPods dependencies (e.g., `ktor-client-webrtc`).
+Other modules will continue to build Apple targets normally.
+
+To install CocoaPods, follow the [Kotlin Multiplatform CocoaPods setup guide](https://www.jetbrains.com/help/kotlin-multiplatform-dev/multiplatform-cocoapods-overview.html).
+
+You can also specify the path to the `pod` executable using the `kotlin.native.cocoapods.bin` property in `local.properties`:
+```properties
+kotlin.native.cocoapods.bin=/path/to/pod/binary
+```
+
 #### Referencing artifacts locally
 
 There are two ways to reference artifacts from the development Ktor locally in another project, which is usually

README.md

@@ -9,7 +9,7 @@
 
 [![Official JetBrains project](http://jb.gg/badges/official.svg)](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub)
 [![Maven Central](https://img.shields.io/maven-central/v/io.ktor/ktor-server)](https://central.sonatype.com/search?namespace=io.ktor)
-[![Kotlin](https://img.shields.io/badge/kotlin-2.2.20-blue.svg?logo=kotlin)](http://kotlinlang.org)
+[![Kotlin](https://img.shields.io/badge/kotlin-2.2.21-blue.svg?logo=kotlin)](http://kotlinlang.org)
 [![Slack channel](https://img.shields.io/badge/chat-slack-green.svg?logo=slack)](https://kotlinlang.slack.com/messages/ktor/)
 [![GitHub License](https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat)](http://www.apache.org/licenses/LICENSE-2.0)
 [![Contribute with Gitpod](https://img.shields.io/badge/Contribute%20with-Gitpod-908a85?logo=gitpod)](https://gitpod.io/#https://github.com/ktorio/ktor)

build-logic/build.gradle.kts

@@ -15,7 +15,7 @@ dependencies {
     implementation(libs.gradleDoctor)
     implementation(libs.kotlinter)
     implementation(libs.mavenPublishing)
-    implementation(libs.android.kmp.library)
+    implementation(libs.android.gradlePlugin)
 
     // Needed for patches/DokkaVersioningPluginParameters
     // TODO: Remove when the PR fixing this file will be merged and released. Probably in Dokka 2.2.0
@@ -33,5 +33,6 @@ kotlin {
 
     compilerOptions {
         allWarningsAsErrors = true
+        freeCompilerArgs.add("-Xcontext-parameters")
     }
 }

build-logic/src/main/kotlin/ktorbuild.kmp.gradle.kts

@@ -47,16 +47,9 @@ configureCommon()
 if (targets.hasJvm) configureJvm()
 if (targets.hasJs) configureJs()
 if (targets.hasWasmJs) configureWasmJs()
+if (targets.hasWeb) configureWeb()
 if (targets.hasAndroidJvm && project.hasAndroidPlugin()) configureAndroidJvm()
 
-if (targets.hasJsOrWasmJs) {
-    configureNodeJs()
-
-    tasks.configureEach {
-        if (name == "compileJsAndWasmSharedMainKotlinMetadata") enabled = false
-    }
-}
-
 // Run native tests only on matching host.
 // There is no need to configure `onlyIf` for Darwin targets as they're configured by KGP.
 @Suppress("UnstableApiUsage")

build-logic/src/main/kotlin/ktorbuild.optional.android-library.gradle.kts

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2014-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+import ktorbuild.internal.*
+import ktorbuild.internal.gradle.localProperty
+import org.gradle.kotlin.dsl.support.serviceOf
+
+if (isAndroidSdkAvailable()) {
+    apply(plugin = "com.android.kotlin.multiplatform.library")
+} else @Suppress("UnstableApiUsage") {
+    val problemReporter = project.serviceOf<Problems>().reporter
+    problemReporter.reportVisible(
+        KtorBuildProblems.missingAndroidSdk,
+        details = "Android SDK not found.",
+        contextualLabel = "Android target won't be added to the project ${project.path}.",
+    ) {
+        solution("Download Android SDK from Android Studio or sdkmanager: https://developer.android.com/tools/sdkmanager")
+        solution("Set ANDROID_HOME environment variable to your Android SDK path")
+        solution("Create local.properties file with: sdk.dir=/path/to/your/android/sdk")
+        buildFileLocation()
+        documentedAt("https://github.com/ktorio/ktor/blob/main/CONTRIBUTING.md#building-the-project")
+    }
+}
+
+private fun Project.isAndroidSdkAvailable(): Boolean =
+    providers.environmentVariable("ANDROID_HOME")
+        .orElse(localProperty("sdk.dir"))
+        .isPresent

build-logic/src/main/kotlin/ktorbuild.optional.cocoapods.gradle.kts

@@ -0,0 +1,51 @@
+/*
+ * Copyright 2014-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+import ktorbuild.internal.*
+import ktorbuild.internal.gradle.localProperty
+import ktorbuild.targets.*
+import org.gradle.kotlin.dsl.support.serviceOf
+import org.jetbrains.kotlin.konan.target.HostManager
+import java.io.OutputStream
+
+pluginManager.withPlugin("org.jetbrains.kotlin.multiplatform") {
+    val cocoaPodsAvailable = localProperty(COCOAPODS_BIN_PROPERTY).map { true }
+        .orElse(providers.gradleProperty(COCOAPODS_BIN_PROPERTY).map { true })
+        .orElse(providers.of(CocoaPodsAvailableValueSource::class) {})
+
+    if (!HostManager.hostIsMac || cocoaPodsAvailable.get()) {
+        apply(plugin = COCOAPODS_PLUGIN_ID)
+    } else @Suppress("UnstableApiUsage") {
+        // Disable Darwin targets if CocoaPods is not available
+        ktorBuild.targets["darwin"] = false
+
+        val problemReporter = project.serviceOf<Problems>().reporter
+        problemReporter.reportVisible(
+            KtorBuildProblems.missingCocoaPods,
+            details = "CocoaPods not found.",
+            contextualLabel = "Apple targets won't be added in the project.",
+        ) {
+            solution("Install CocoaPods")
+            solution("Ensure 'pod' command is available in PATH")
+            buildFileLocation()
+            documentedAt("https://github.com/ktorio/ktor/blob/main/CONTRIBUTING.md#building-the-project")
+        }
+    }
+}
+
+internal abstract class CocoaPodsAvailableValueSource @Inject constructor(
+    val execOperations: ExecOperations,
+) : ValueSource<Boolean, ValueSourceParameters.None> {
+
+    override fun obtain(): Boolean {
+        val result = execOperations.exec {
+            commandLine("which", "pod")
+            isIgnoreExitValue = true
+            standardOutput = OutputStream.nullOutputStream()
+            errorOutput = OutputStream.nullOutputStream()
+        }
+
+        return result.exitValue == 0
+    }
+}

build-logic/src/main/kotlin/ktorbuild/CInterop.kt

@@ -21,6 +21,14 @@ fun KotlinMultiplatformExtension.disableNativeCompileConfigurationCache() {
     project.tasks.withType<KotlinNativeCompile>()
         .named { it.endsWith("MainKotlinMetadata") }
         .configureEach { notCompatibleWithConfigurationCache("Workaround for KT-76147") }
+
+    // The problem with compile*MainKotlinMetadata tasks also affects Dokka tasks
+    project.tasks.withType<DokkaGeneratePublicationTask>()
+        .named { it == "dokkaGeneratePublicationHtml" }
+        .configureEach { notCompatibleWithConfigurationCache("Workaround for KT-76147") }
+    project.tasks.withType<DokkaGenerateModuleTask>()
+        .named { it == "dokkaGenerateModuleHtml" }
+        .configureEach { notCompatibleWithConfigurationCache("Workaround for KT-76147") }
 }
 
 /**
@@ -75,12 +83,4 @@ fun KotlinMultiplatformExtension.createCInterop(
         }
 
     disableNativeCompileConfigurationCache()
-
-    // The problem with compile*MainKotlinMetadata tasks also affects Dokka tasks
-    project.tasks.withType<DokkaGeneratePublicationTask>()
-        .named { it == "dokkaGeneratePublicationHtml" }
-        .configureEach { notCompatibleWithConfigurationCache("Workaround for KT-76147") }
-    project.tasks.withType<DokkaGenerateModuleTask>()
-        .named { it == "dokkaGenerateModuleHtml" }
-        .configureEach { notCompatibleWithConfigurationCache("Workaround for KT-76147") }
 }

build-logic/src/main/kotlin/ktorbuild/dsl/KotlinSourceSets.kt

@@ -6,12 +6,15 @@
 
 import org.gradle.api.NamedDomainObjectContainer
 import org.gradle.api.NamedDomainObjectProvider
+import org.gradle.api.NamedDomainObjectSet
 import org.jetbrains.kotlin.gradle.ExperimentalKotlinGradlePluginApi
 import org.jetbrains.kotlin.gradle.dsl.KotlinSourceSetConvention
+import org.jetbrains.kotlin.gradle.plugin.KotlinDependencyHandler
 import org.jetbrains.kotlin.gradle.plugin.KotlinSourceSet
 
 private typealias KotlinSourceSets = NamedDomainObjectContainer<KotlinSourceSet>
 private typealias KotlinSourceSetProvider = NamedDomainObjectProvider<KotlinSourceSet>
+private typealias OptionalKotlinSourceSetProvider = NamedDomainObjectSet<KotlinSourceSet>
 
 // Additional accessors to the ones declared in KotlinMultiplatformSourceSetConventions
 
@@ -22,3 +25,18 @@ val KotlinSourceSets.desktopMain: KotlinSourceSetProvider by KotlinSourceSetConv
 val KotlinSourceSets.desktopTest: KotlinSourceSetProvider by KotlinSourceSetConvention
 val KotlinSourceSets.windowsMain: KotlinSourceSetProvider by KotlinSourceSetConvention
 val KotlinSourceSets.windowsTest: KotlinSourceSetProvider by KotlinSourceSetConvention
+
+val KotlinSourceSets.optional: OptionalSourceSets get() = OptionalSourceSets(this)
+
+@JvmInline
+value class OptionalSourceSets(private val sourceSets: KotlinSourceSets) {
+    val androidMain: OptionalKotlinSourceSetProvider get() = optional("androidMain")
+    val androidTest: OptionalKotlinSourceSetProvider get() = optional("androidTest")
+    val androidDeviceTest: OptionalKotlinSourceSetProvider get() = optional("androidDeviceTest")
+
+    private fun optional(name: String): OptionalKotlinSourceSetProvider = sourceSets.named { it == name }
+}
+
+fun OptionalKotlinSourceSetProvider.dependencies(handler: KotlinDependencyHandler.() -> Unit) {
+    configureEach { dependencies(handler) }
+}

build-logic/src/main/kotlin/ktorbuild/internal/Accessors.kt

@@ -21,6 +21,8 @@ internal val Project.ktorBuild: KtorBuildExtension get() = extensions.getByType(
 
 internal val Project.java: JavaPluginExtension get() = extensions.getByType()
 
+internal val Project.kotlin: KotlinMultiplatformExtension get() = extensions.getByType()
+
 internal fun Project.kotlin(configure: KotlinMultiplatformExtension.() -> Unit) =
     extensions.configure("kotlin", configure)