| 3.2.3 | July 29, 2025 |
A patch release that introduces improvements to YAML config handling, DI resolution, and Wasm/JS stability, along with
diff --git a/topics/server-auto-reload.topic b/topics/server-auto-reload.topic
index 4bd630f1d..db7b07b40 100644
--- a/topics/server-auto-reload.topic
+++ b/topics/server-auto-reload.topic
@@ -40,7 +40,58 @@
+
+ Auto-reload works only for specific module declarations. The following table shows support across versions:
+
+
+ | Module type |
+ <= 3.2 |
+ > 3.2 |
+
+
+ | Lambda initializer |
+ ❌ Not supported |
+ ❌ Not supported |
+
+
+ | Blocking function reference |
+ ❌ Not supported |
+ ✅ Supported |
+
+
+ | Suspend function reference |
+ ✅ Supported |
+ ❌ Not supported |
+
+
+ | Config reference |
+ ✅ Supported |
+ ✅ Supported |
+
+
+
+
+ // Suspend function reference
+ embeddedServer(Netty, port = 8080, module = Application::mySuspendModule)
+ // Configuration reference
+ ktor {
+ application {
+ modules = [ com.example.ApplicationKt.mySuspendModule ]
+ }
+ }
+
+
+
+
+ // Lambda
+ embeddedServer(Netty, port = 8080) { configureServer() }
+
+ // Blocking function reference
+ embeddedServer(Netty, port = 8080, module = Application::myBlockingModule)
+
+
+
To use Auto-reload, you need to enable the
@@ -57,7 +108,7 @@
If you run a server using embeddedServer, you can use the
- io.ktor.development
+ io.ktor.development
system property.
@@ -69,7 +120,6 @@
-
When you enable development mode,
diff --git a/topics/server-http2.md b/topics/server-http2.md
index b317e3e47..1fc644dd8 100644
--- a/topics/server-http2.md
+++ b/topics/server-http2.md
@@ -49,9 +49,6 @@ The next step is configuring Ktor to use your keystore. See the example `applica
-
-
-
## ALPN implementation {id="apln_implementation"}
HTTP/2 requires ALPN ([Application-Layer Protocol Negotiation](https://en.wikipedia.org/wiki/Application-Layer_Protocol_Negotiation)) to be enabled. The first option is to use an external ALPN implementation that needs to be added to the boot classpath.
@@ -78,3 +75,24 @@ The example below shows how to add a native implementation (statically linked Bo
`tc.native.classifier` should be one of the following: `linux-x86_64`, `osx-x86_64`, or `windows-x86_64`.
The [http2-netty](https://github.com/ktorio/ktor-documentation/tree/%ktor_version%/codeSnippets/snippets/http2-netty) runnable example demonstrates how to enable HTTP/2 support for Netty.
+
+#### HTTP/2 without TLS
+
+The Netty engine also supports [HTTP/2 over cleartext (h2c)](https://httpwg.org/specs/rfc7540.html#discover-http).
+This allows HTTP/2 communication without TLS, typically within private networks where encryption is not required.
+Clients can initiate communication with an HTTP/1.1 request and then upgrade to HTTP/2.
+
+To enable h2c, set the `enableH2c` flag to `true` in the engine configuration:
+
+```kotlin
+embeddedServer(Netty, configure = {
+ connector {
+ port = 8080
+ }
+ enableHttp2 = true
+ enableH2c = true
+})
+```
+
+
+Note that h2c requires `enableHttp2 = true` and cannot be used if an SSL connector is configured on the server.
\ No newline at end of file
diff --git a/topics/server-openapi.md b/topics/server-openapi.md
index 286894885..404b365d1 100644
--- a/topics/server-openapi.md
+++ b/topics/server-openapi.md
@@ -19,10 +19,9 @@
The OpenAPI plugin allows you to generate OpenAPI documentation for your project.
-Ktor allows you to generate and serve OpenAPI documentation for your project based on the existing OpenAPI specification.
-
-
-
+Ktor allows you to generate and serve OpenAPI documentation for your project based on an existing OpenAPI specification.
+You can serve an existing YAML or JSON specification, or generate one using the
+[OpenAPI extension](openapi-spec-generation.md) of the Ktor Gradle plugin.
## Add dependencies {id="add_dependencies"}
diff --git a/topics/server-static-content.md b/topics/server-static-content.md
index bc4d0f07f..2904a72fc 100644
--- a/topics/server-static-content.md
+++ b/topics/server-static-content.md
@@ -19,8 +19,8 @@ stylesheets, scripts, or images.
While it is certainly possible with Ktor to load the contents of a file and [send it in a response](server-responses.md)
to a client, Ktor simplifies this process by providing additional functions for serving static content.
-With Ktor, you can serve content from [folders](#folders),[ZIP files](#zipped)
-, and [embedded application resources](#resources).
+With Ktor, you can serve content from [folders](#folders), [ZIP files](#zipped),
+and [embedded application resources](#resources).
## Folders {id="folders"}
@@ -31,7 +31,7 @@ function. In this case, relative paths are resolved using the current working di
```kotlin
```
-{src="snippets/static-files/src/main/kotlin/com/example/Application.kt" include-lines="10-11,35"}
+{src="snippets/static-files/src/main/kotlin/com/example/Application.kt" include-lines="15-16,57"}
In the example above, any request from `/resources` is mapped to the `files` physical folder in the current working
directory.
@@ -57,7 +57,7 @@ In this example, any request from the root URL `/` is mapped directly to the con
The `staticZip()` function also supports automatic reloading. If any changes are detected in the ZIP file's parent
directory, the ZIP file system is reloaded on the next request. This ensures that the served content remains
-up-to-date without requiring a server restart.
+up to date without requiring a server restart.
For the full example,
see [static-zip](https://github.com/ktorio/ktor-documentation/tree/%ktor_version%/codeSnippets/snippets/static-zip).
@@ -74,7 +74,7 @@ function.
{src="snippets/static-resources/src/main/kotlin/com/example/Application.kt" include-lines="8,9,17"}
This maps any request from `/resources` to the `static` package in application resources.
-In this case, Ktor recursively serves up any file from the `static` package as long as a URL path and a path to resource
+In this case, Ktor recursively serves up any file from the `static` package as long as a URL path and a path-to-resource
match.
For the full example,
@@ -104,7 +104,7 @@ To use this functionality, define the `preCompressed()` function inside a block
```kotlin
```
-{src="snippets/static-files/src/main/kotlin/com/example/Application.kt" include-lines="12,14,18"}
+{src="snippets/static-files/src/main/kotlin/com/example/Application.kt" include-lines="17,19,23"}
In this example, for a request made to `/js/script.js`, Ktor can serve `/js/script.js.br` or `/js/script.js.gz`.
@@ -120,29 +120,29 @@ static route that has a `GET` defined.
### Default file response {id="default-file"}
-The `default()` function provides the ability to reply with a file for any request inside static route that has no
+The `default()` function provides the ability to reply with a file for any request inside a static route that has no
corresponding file.
```kotlin
```
-{src="snippets/static-files/src/main/kotlin/com/example/Application.kt" include-lines="12-13,18"}
+{src="snippets/static-files/src/main/kotlin/com/example/Application.kt" include-lines="17-18,23"}
In this example when the client requests a resource that doesn't exist, the `index.html` file will
be served as a response.
### Content type {id="content-type"}
-By default, Ktor tries to guess value of the `Content-Type` header from the file extension. You can use
+By default, Ktor tries to guess the value of the `Content-Type` header from the file extension. You can use
the `contentType()` function to set the `Content-Type` header explicitly.
```kotlin
```
-{src="snippets/static-files/src/main/kotlin/com/example/Application.kt" include-lines="19,22-27,34"}
+{src="snippets/static-files/src/main/kotlin/com/example/Application.kt" include-lines="24,35-40,47"}
-In this example, the response for file `html-file.txt` will have `Content-Type: text/html` header and for every other
-file default behaviour will be applied.
+In this example, the response for the file `html-file.txt` will have the `Content-Type: text/html` header, and for every
+other file the default behavior will be applied.
### Caching {id="caching"}
@@ -151,7 +151,28 @@ The `cacheControl()` function allows you to configure the `Cache-Control` header
```kotlin
```
-{src="snippets/static-files/src/main/kotlin/com/example/Application.kt" include-lines="9-10,19,28-36,38-40"}
+{src="snippets/static-files/src/main/kotlin/com/example/Application.kt" include-lines="14-15,24,41-47,57-58,60-62"}
+
+When the [`ConditionalHeaders`](server-conditional-headers.md) plugin is installed, Ktor can serve static resources with
+`ETag` and `LastModified` headers and process conditional headers to avoid sending the body of content if it hasn't changed
+since the last request:
+
+```kotlin
+```
+
+{src="snippets/static-files/src/main/kotlin/com/example/Application.kt" include-lines="49-52"}
+
+In this example, the `etag` and `lastModified` values are calculated dynamically based on each resource and applied to the response.
+
+To simplify `ETag` generation, you can also use a predefined provider:
+
+```kotlin
+```
+
+{src="snippets/static-files/src/main/kotlin/com/example/Application.kt" include-lines="54-56"}
+
+In this example, a strong `ETag` is generated using the SHA‑256 hash of the resource content.
+If an I/O error occurs, no `ETag` is generated.
> For more information on caching in Ktor, see [Caching headers](server-caching-headers.md).
>
@@ -165,7 +186,7 @@ the server will respond with a `403 Forbidden` status code.
```kotlin
```
-{src="snippets/static-files/src/main/kotlin/com/example/Application.kt" include-lines="19,21,34"}
+{src="snippets/static-files/src/main/kotlin/com/example/Application.kt" include-lines="24,26,47"}
### File extensions fallbacks {id="extensions"}
@@ -178,6 +199,22 @@ When a requested file is not found, Ktor can add the given extensions to the fil
In this example, when `/index` is requested, Ktor will search for `/index.html` and serve the found content.
+### Custom fallback
+
+To configure custom fallback behavior when a requested static resource is not found, use the `fallback()` function.
+With `fallback()`, you can inspect the requested path and decide how to respond. For example, you might redirect to
+another resource, return a specific HTTP status, or serve an alternative file.
+
+You can add `fallback()` inside `staticFiles()`, `staticResources()`, `staticZip()`, or `staticFileSystem()`. The callback provides
+the requested path and the current `ApplicationCall`.
+
+The example below shows how to redirect certain extensions, return a custom status, or fall back to `index.html`:
+
+```kotlin
+```
+
+{src="snippets/static-files/src/main/kotlin/com/example/Application.kt" include-lines="24,27-34,47"}
+
### Custom modifications {id="modify"}
The `modify()` function allows you to apply custom modification to a resulting response.
@@ -185,7 +222,7 @@ The `modify()` function allows you to apply custom modification to a resulting r
```kotlin
```
-{src="snippets/static-files/src/main/kotlin/com/example/Application.kt" include-lines="12,15-18"}
+{src="snippets/static-files/src/main/kotlin/com/example/Application.kt" include-lines="17,20-23"}
## Handle errors {id="errors"}
diff --git a/topics/server-swagger-ui.md b/topics/server-swagger-ui.md
index 9567a47d4..1b1736fbb 100644
--- a/topics/server-swagger-ui.md
+++ b/topics/server-swagger-ui.md
@@ -20,14 +20,8 @@ The SwaggerUI plugin allows you to generate Swagger UI for your project.
Ktor allows you to generate and serve Swagger UI for your project based on the existing OpenAPI specification.
-With Swagger UI, you can visualize and interact with the API resources.
-
-> The following tools are available for generating OpenAPI definitions from code and vice versa:
-> - The [Ktor plugin](https://www.jetbrains.com/help/idea/ktor.html#openapi) for IntelliJ IDEA provides the ability to generate OpenAPI documentation for server-side Ktor applications.
-> - The [OpenAPI generator](https://github.com/OpenAPITools/openapi-generator) allows you to create a Ktor project from your API definitions by using the [kotlin-server](https://github.com/OpenAPITools/openapi-generator/blob/master/docs/generators/kotlin-server.md) generator. Alternatively, you can use IntelliJ IDEA's [functionality](https://www.jetbrains.com/help/idea/openapi.html#codegen).
->
-{id="open-api-note"}
-
+With Swagger UI, you can visualize and interact with the API resources. You can serve an existing YAML or JSON
+specification, or generate one using the [OpenAPI extension](openapi-spec-generation.md) of the Ktor Gradle plugin.
## Add dependencies {id="add_dependencies"}
diff --git a/topics/server-war.md b/topics/server-war.md
index e1d43300b..522bbc9c9 100644
--- a/topics/server-war.md
+++ b/topics/server-war.md
@@ -90,6 +90,11 @@ Then, configure the URL pattern for this servlet:
## Configure Gretty {id="configure-gretty"}
+> Ktor 3.3.0 requires Jetty 12, which is not yet supported by Gretty. If you rely on Gretty for development or
+> deployment, use Ktor 3.2.3 instead until Gretty adds Jetty 12 support.
+>
+{style="warning"}
+
The [Gretty](https://plugins.gradle.org/plugin/org.gretty) plugin allows you to [run](#run) a servlet application on Jetty and Tomcat. To install this plugin, open the `build.gradle.kts` file and add the following code to the `plugins` block:
```groovy
diff --git a/topics/whats-new-320.md b/topics/whats-new-320.md
index db49f3181..4b45ef7d9 100644
--- a/topics/whats-new-320.md
+++ b/topics/whats-new-320.md
@@ -17,6 +17,11 @@ Here are the highlights for this feature release:
Starting with Ktor 3.2.0, [application modules](server-modules.md) have support for suspendable functions.
+> With the introduction of suspend module support, auto-reload in development mode no longer works with blocking
+> function references. For more information, see [](#regression).
+>
+{style="warning"}
+
Previously, adding asynchronous functions inside Ktor modules required the `runBlocking` block that could lead to a
deadlock on server creation:
@@ -274,6 +279,26 @@ This simplifies working with structured configuration and supports automatic par
For more information and advanced usage, see [](server-dependency-injection.md).
+### Development mode auto-reload regression {id="regression"}
+
+As a side effect to the support of suspending functions, blocking function references (`Application::myModule`) are now
+wrapped into anonymous inner classes during casting. This breaks auto-reload, because the function name is no longer
+retained as a stable reference.
+
+This means that auto-reload in `development` mode only works with suspend function modules and configuration references:
+
+```kotlin
+// Suspend function reference
+embeddedServer(Netty, port = 8080, module = Application::mySuspendModule)
+
+// Configuration reference
+ktor {
+ application {
+ modules = [ com.example.ApplicationKt.mySuspendModule ]
+ }
+}
+```
+
## Ktor Client
### `SaveBodyPlugin` and `HttpRequestBuilder.skipSavingBody()` are deprecated
diff --git a/topics/whats-new-330.md b/topics/whats-new-330.md
new file mode 100644
index 000000000..68efb909c
--- /dev/null
+++ b/topics/whats-new-330.md
@@ -0,0 +1,226 @@
+[//]: # (title: What's new in Ktor 3.3.0)
+
+
+
+_[Released: September 11, 2025](releases.md#release-details)_
+
+Ktor 3.3.0 delivers new capabilities across server, client, and tooling. Here are the highlights for this feature
+release:
+
+* [Custom fallback mechanism for static resources](#custom-fallback)
+* [OpenAPI specification generation](#openapi-spec-gen)
+* [HTTP/2 cleartext (h2c) support](#http2-h2c-support)
+* [Experimental WebRTC client](#webrtc-client)
+
+## Ktor Server
+
+### Custom fallback for static resources {id="custom-fallback"}
+
+Ktor 3.3.0 introduces a new `fallback()` function for static content, allowing you to define custom
+behavior when a requested resource is not found.
+
+Unlike `default()`, which always serves the same fallback file, `fallback()` gives you access to the original requested
+path and the current `ApplicationCall`. You can use this to redirect, return custom status codes, or serve different
+files dynamically.
+
+To define custom fallback behaviour, use the `fallback()` function within `staticFiles()`, `staticResources()`, `staticZip()`, or
+`staticFileSystem()`:
+
+```kotlin
+```
+
+{src="snippets/static-files/src/main/kotlin/com/example/Application.kt" include-lines="24,27-34,47"}
+
+### LastModified and Etag headers for static content
+
+Ktor 3.3.0 introduces support for `ETag` and `LastModified` headers for static resources. When the [`ConditionalHeaders`](server-conditional-headers.md)
+plugin is installed, you can process conditional headers to avoid sending the body of content if it hasn't changed since
+the last request:
+
+```kotlin
+```
+
+{src="snippets/static-files/src/main/kotlin/com/example/Application.kt" include-lines="49-52"}
+
+The values are calculated dynamically based on each resource and applied to the response.
+
+You can also use a predefined provider, for example to generate a strong `ETag` using the SHA‑256 hash of the resource content:
+
+```kotlin
+```
+
+{src="snippets/static-files/src/main/kotlin/com/example/Application.kt" include-lines="54-56"}
+
+### Development mode auto-reload limitations
+
+In Ktor 3.2.0, the introduced [support for suspend module functions](whats-new-320.md#suspendable-module-functions)
+caused a regression where auto-reload stopped working for applications that use blocking module references.
+
+This regression remains in 3.3.0 and auto-reload continues to work only with `suspend` function modules and
+configuration references.
+
+Examples of supported module declarations:
+
+```kotlin
+// Supported — suspend function reference
+embeddedServer(Netty, port = 8080, module = Application::mySuspendModule)
+
+// Supported — configuration reference (application.conf / application.yaml)
+ktor {
+ application {
+ modules = [ com.example.ApplicationKt.mySuspendModule ]
+ }
+}
+```
+
+We plan to restore support for blocking function references in a future release. Until then, prefer a `suspend` module
+or configuration reference in `development` mode.
+
+### HTTP/2 cleartext (h2c) support {id="http2-h2c-support"}
+
+Ktor 3.3.0 introduces support for HTTP/2 over cleartext (h2c) for the Netty engine,
+which allows HTTP/2 communication without TLS encryption.
+This setup is typically used in trusted environments, such as local testing or private networks.
+
+To enable h2c, set the `enableH2c` flag to true in the engine configuration.
+For more information, see [HTTP/2 without TLS](server-http2.md#http-2-without-tls).
+
+## Ktor Client
+
+### SSE response body buffer
+
+Until now, attempting to call `response.bodyAsText()` after an SSE error failed due to double-consume issues.
+
+Ktor 3.3.0 introduces a configurable diagnostic buffer that allows you to capture already-processed SSE data for
+debugging and error handling.
+
+You can configure the buffer globally when installing the [SSE plugin](client-server-sent-events.topic):
+
+```kotlin
+install(SSE) {
+ bufferPolicy = SSEBufferPolicy.LastEvents(10)
+}
+```
+
+Or per call:
+
+```kotlin
+client.sse(url, { bufferPolicy(SSEBufferPolicy.All) }) {
+ // …
+}
+```
+
+As the SSE stream is consumed, the client maintains a snapshot of the processed data in an in-memory buffer (without
+re-reading from the network). If an error occurs, you can safely call `response?.bodyAsText()` for logging or
+diagnostics.
+
+For more information, see [Response buffering](client-server-sent-events.topic#response-buffering).
+
+### WebRTC client {id="webrtc-client"}
+
+This release introduces experimental WebRTC client support for peer-to-peer real-time communication in multiplatform
+projects.
+
+WebRTC enables applications such as video calls, multiplayer gaming, and collaborative tools. With this release, you
+can now use a unified Kotlin API to establish peer connections and exchange data channels across JavaScript/Wasm and
+Android targets. Additional targets such as iOS, JVM desktop, and Native are planned for future releases.
+
+You can create a `WebRtcClient` by selecting an engine for your platform and providing configuration, similar to
+`HttpClient`:
+
+
+
+Once created, the client can establish peer-to-peer connections using Interactive Connectivity Establishment (ICE).
+After negotiation completes, peers can open data channels and exchange messages.
+
+```kotlin
+val connection = client.createPeerConnection()
+
+// Add a remote ICE candidate (received via your signaling channel)
+connection.addIceCandidate(WebRtc.IceCandidate(candidateString, sdpMid, sdpMLineIndex))
+
+// Wait until all local candidates are gathered
+connection.awaitIceGatheringComplete()
+
+// Listen for incoming data channel events
+connection.dataChannelEvents.collect { event ->
+ when (event) {
+ is Open -> println("Another peer opened a chanel: ${event.channel}")
+ is Closed -> println("Data channel is closed")
+ is Closing, is BufferedAmountLow, is Error -> println(event)
+ }
+}
+
+// Create a channel and send/receive messages
+val channel = connection.createDataChannel("chat")
+channel.send("hello")
+val answer = channel.receiveText()
+```
+
+For more details on usage and limitations, see the [WebRTC client](client-webrtc.md) documentation.
+
+### Updated OkHttp version
+
+In Ktor 3.3.0, the Ktor client's `OkHttp` engine has been upgraded to use OkHttp 5.1.0 (previously 4.12.0). This major
+version bump may introduce API changes for projects that interact directly with OkHttp. Such projects should verify
+compatibility.
+
+### Unified OkHttp SSE session
+
+The OkHttp engine now uses the standard API for Server-Sent Events (SSE),
+replacing the previously introduced `OkHttpSSESession`.
+This change unifies SSE handling across all client engines and addresses the limitations of the OkHttp-specific implementation.
+
+
+## Gradle plugin
+
+### OpenAPI specification generation {id="openapi-spec-gen"}
+
+
+Ktor 3.3.0 introduces an experimental OpenAPI generation feature via the Gradle plugin and a compiler plugin. This
+allows you to generate OpenAPI specifications directly from your application code at build time.
+
+It provides the following capabilities:
+- Analyze Ktor route definitions and merge nested routes, local extensions, and resource paths.
+- Parse preceding KDoc annotations to supply OpenAPI metadata, including:
+ - Path, query, header, cookie, and body parameters
+ - Response codes and types
+ - Security, descriptions, deprecations, and external documentation links
+- Infer request and response bodies from `call.receive()` and `call.respond()`.
+
+
+
+
+#### Generate the OpenAPI specification
+
+To generate the OpenAPI specification file from your Ktor routes and KDoc annotations, use the following command:
+
+```shell
+./gradlew buildOpenApi
+```
+
+#### Serve the specification
+
+To make the generated specification available at runtime, you can then use the [OpenAPI](server-openapi.md)
+or [SwaggerUI](server-swagger-ui.md) plugins.
+
+The following example serves the generated specification file at an OpenAPI endpoint:
+
+```kotlin
+routing {
+ openAPI("/docs", swaggerFile = "openapi/generated.json")
+}
+```
+
+For more details about this feature, see [OpenAPI specification generation](openapi-spec-generation.md).
+
+
+## Shared
+
+### Updated Jetty version
+
+The Jetty server and client engines have been upgraded to use Jetty 12. For most applications, this upgrade is fully
+backward-compatible, but client and server code now leverage the updated Jetty APIs internally.
+
+If your project uses Jetty APIs directly, be aware that there are breaking changes. For more details, refer to
+[the official Jetty migration guide](https://jetty.org/docs/jetty/12.1/programming-guide/migration/11-to-12.html).
diff --git a/v.list b/v.list
index 2cb51eb1c..9a6264da7 100644
--- a/v.list
+++ b/v.list
@@ -4,8 +4,8 @@
-
-
+
+
|