Merge 3.2.0 release documentation

codeSnippets/settings.gradle.kts

@@ -162,6 +162,7 @@ module("snippets", "tutorial-server-routing-and-requests")
 module("snippets", "tutorial-server-restful-api")
 module("snippets", "tutorial-server-websockets")
 module("snippets", "tutorial-server-docker-compose")
+module("snippets", "htmx-integration")
 
 if(!System.getProperty("os.name").startsWith("Windows")) {
     module("snippets", "embedded-server-native")

codeSnippets/snippets/htmx-integration/README.md

@@ -0,0 +1,13 @@
+# HTMX integration
+
+A sample Ktor project demonstrating how to integrate HTMX using the HTML DSL and HTMX-aware server-side routing.
+
+> This sample is a part of the [codeSnippets](../../README.md) Gradle project.
+
+## Running
+
+To run this sample, execute the following command in a repository's root directory:
+
+```bash
+./gradlew :htmx-integration:run
+```

codeSnippets/snippets/htmx-integration/build.gradle.kts

@@ -0,0 +1,33 @@
+
+val kotlin_version: String by project
+val logback_version: String by project
+
+plugins {
+    kotlin("jvm")
+    id("io.ktor.plugin") version "3.2.0"
+}
+
+group = "com.example"
+version = "0.0.1"
+
+application {
+    mainClass = "io.ktor.server.netty.EngineMain"
+}
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    implementation("io.ktor:ktor-server-core-jvm")
+    implementation("io.ktor:ktor-server-netty")
+    implementation("ch.qos.logback:logback-classic:$logback_version")
+    implementation("io.ktor:ktor-server-core")
+    implementation("io.ktor:ktor-server-htmx")
+    implementation("io.ktor:ktor-htmx")
+    implementation("io.ktor:ktor-htmx-html")
+    implementation("io.ktor:ktor-server-html-builder")
+    implementation("io.ktor:ktor-server-config-yaml")
+    testImplementation("io.ktor:ktor-server-test-host")
+    testImplementation("org.jetbrains.kotlin:kotlin-test-junit:$kotlin_version")
+}

codeSnippets/snippets/htmx-integration/src/main/kotlin/Application.kt

@@ -0,0 +1,11 @@
+package com.example
+
+import io.ktor.server.application.*
+
+fun main(args: Array<String>) {
+    io.ktor.server.netty.EngineMain.main(args)
+}
+
+fun Application.module() {
+    configureHtmx()
+}

codeSnippets/snippets/htmx-integration/src/main/kotlin/Routing.kt

@@ -0,0 +1,83 @@
+package com.example
+
+import io.ktor.htmx.HxSwap
+import io.ktor.htmx.html.hx
+import io.ktor.server.application.*
+import io.ktor.server.html.respondHtml
+import io.ktor.server.htmx.hx
+import io.ktor.server.response.*
+import io.ktor.server.routing.*
+import io.ktor.utils.io.ExperimentalKtorApi
+import kotlinx.html.*
+
+fun Application.configureRouting() {
+    routing {
+        get("/") {
+            call.respondText("Hello World!")
+        }
+    }
+}
+
+@OptIn(ExperimentalKtorApi::class)
+fun Application.configureHtmx() {
+    routing {
+        get("/") {
+            call.respondHtml {
+                head {
+                    // Include HTMX library
+                    script(src = "https://unpkg.com/[email protected]") {}
+                }
+                body {
+                    div {
+                        id = "content"
+                        h1 { +"HTMX Demo" }
+
+                        button {
+                            id = "load-button"
+                            attributes.hx {
+                                get = "/data"
+                                target = "#result"
+                                swap = HxSwap.innerHtml
+                                trigger = "click"
+                            }
+                            +"Load Data"
+                        }
+
+                        div {
+                            id = "result"
+                            +"Data will appear here"
+                        }
+                    }
+                }
+            }
+        }
+
+        route("data") {
+            // Regular request
+            get {
+                call.respondText("Please use HTMX to load this data")
+            }
+
+            // Any HTMX request
+            hx.get {
+                call.respondText("<p>Data loaded via HTMX!</p>")
+            }
+
+            // HTMX request with specific target
+            hx {
+                target("#result") {
+                    get {
+                        call.respondText("<p>Data specifically for #result element</p>")
+                    }
+                }
+
+                // HTMX request with specific trigger
+                trigger("#load-button") {
+                    get {
+                        call.respondText("<p>Data loaded by #load-button</p>")
+                    }
+                }
+            }
+        }
+    }
+}

codeSnippets/snippets/htmx-integration/src/main/resources/application.yaml

@@ -0,0 +1,6 @@
+ktor:
+    application:
+        modules:
+            - com.example.ApplicationKt.module
+    deployment:
+        port: 8080

codeSnippets/snippets/htmx-integration/src/main/resources/logback.xml

@@ -0,0 +1,12 @@
+<configuration>
+    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+        <encoder>
+            <pattern>%d{YYYY-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
+        </encoder>
+    </appender>
+    <root level="INFO">
+        <appender-ref ref="STDOUT"/>
+    </root>
+    <logger name="org.eclipse.jetty" level="INFO"/>
+    <logger name="io.netty" level="INFO"/>
+</configuration>

codeSnippets/snippets/json-kotlinx/src/test/kotlin/jsonkotlinx/ApplicationTest.kt

@@ -33,7 +33,7 @@ class CustomerTests {
         application {
             main()
         }
-        val client = createClient {
+        client = createClient {
             install(ContentNegotiation) {
                 json()
             }

ktor.tree

@@ -53,6 +53,7 @@
                              accepts-web-file-names="configuration.html,configurations.html,environments.html,configuration-file.html"/>
                 <toc-element topic="server-modules.md"
                              accepts-web-file-names="modules.html"/>
+                <toc-element topic="server-dependency-injection.md"/>
                 <toc-element topic="server-plugins.md"
                              toc-title="Plugins"
                              accepts-web-file-names="zfeatures.html,features.html,plugins.html"/>
@@ -376,11 +377,13 @@
 
     <toc-element toc-title="Integrations">
         <toc-element topic="full-stack-development-with-kotlin-multiplatform.topic"/>
+        <toc-element topic="htmx-integration.md"/>
         <toc-element topic="tutorial-first-steps-with-kotlin-rpc.topic"/>
     </toc-element>
 
     <toc-element toc-title="Releases">
         <toc-element topic="releases.md"/>
+        <toc-element topic="whats-new-320.md"/>
         <toc-element topic="migration-to-20x.md"
                      accepts-web-file-names="migrating-2.html"/>
         <toc-element topic="migration-to-22x.md"

labels.list

@@ -9,6 +9,9 @@
     <primary-label id="server-plugin" short-name="S" name="Server Plugin" color="purple">
         Server Plugin
     </primary-label>
+    <primary-label id="experimental" name="Experimental" short-name="" color="tangerine">
+        This feature is experimental. It may be dropped or changed at any time. Opt-in is required (see details below).
+    </primary-label>
 
     <secondary-label id="wip" name="WIP" color="purple">Work in progress</secondary-label>
     <secondary-label id="beta" name="β" color="tangerine">Beta</secondary-label>

topics/client-default-request.md

@@ -22,7 +22,8 @@ The [DefaultRequest](https://api.ktor.io/ktor-client/ktor-client-core/io.ktor.cl
 
 ## Install DefaultRequest {id="install_plugin"}
 
-To install `DefaultRequest`, pass it to the `install` function inside a [client configuration block](client-create-and-configure.md#configure-client) ...
+To install `DefaultRequest`, pass it to the `install` function inside a [client configuration block](client-create-and-configure.md#configure-client):
+
 ```kotlin
 import io.ktor.client.*
 import io.ktor.client.engine.cio.*
@@ -33,7 +34,7 @@ val client = HttpClient(CIO) {
 }
 ```
 
-... or call the `defaultRequest` function and [configure](#configure) required request parameters:
+Or call the `defaultRequest` function and [configure](#configure) required request parameters:
 
 ```kotlin
 import io.ktor.client.*
@@ -99,6 +100,36 @@ defaultRequest {
 }
 ```
 
+### Unix domain sockets
+
+> Unix domain sockets are supported only in the CIO engine.
+>
+{style="note"}
+
+You can [build individual requests with Unix domain sockets](client-requests.md#specify-a-unix-domain-socket),
+but you can also configure a default request with a socket parameter.
+
+To do that, pass a `unixSocket` call with the path to the socket to the `defaultRequest` function,
+for example:
+
+```kotlin
+val client = HttpClient(CIO)
+
+// Sending a single request to a Unix domain socket
+val response: HttpResponse = client.get("/") {
+    unixSocket("/tmp/test-unix-socket-ktor.sock")
+}
+
+// Setting up the socket for all requests from that client
+val clientDefault = HttpClient(CIO) {
+    defaultRequest {
+        unixSocket("/tmp/test-unix-socket-ktor.sock")
+    }    
+}
+
+val response: HttpResponse = clientDefault.get("/")
+```
+
 ## Example {id="example"}
 
 The example below uses the following `DefaultRequest` configuration:

topics/client-dependencies.md

@@ -105,3 +105,46 @@ which dependencies you need from a topic for a required plugin.
 
 > For a multiplatform project, a plugin dependency should be added to the `commonMain` source set. Note that some
 plugins might have  [limitations](client-engines.md#limitations) for specific platforms.
+
+## Ensure Ktor version consistency
+
+<chapter title="Using the Ktor BOM dependency">
+
+The Ktor BOM allows you to ensure that all Ktor modules use the same consistent version without specifying
+the version for each dependency individually.
+
+To add the Ktor BOM dependency, declare it in your build script as follows:
+
+<tabs group="languages">
+    <tab title="Gradle (Kotlin)" group-key="kotlin">
+        <code-block lang="Kotlin">
+            implementation(platform("io.ktor:ktor-bom:$ktor_version"))
+        </code-block>
+    </tab>
+    <tab title="Gradle (Groovy)" group-key="groovy">
+        <code-block lang="Groovy">
+            implementation platform "io.ktor:ktor-bom:$ktor_version"
+        </code-block>
+    </tab>
+    <tab title="Maven" group-key="maven">
+        <code-block lang="XML">
+        <![CDATA[
+            <dependencyManagement>
+              <dependencies>
+                  <dependency>
+                      <groupId>io.ktor</groupId>
+                      <artifactId>ktor-bom</artifactId>
+                      <version>%ktor_version%</version>
+                      <type>pom</type>
+                      <scope>import</scope>
+                  </dependency>
+              </dependencies>
+          </dependencyManagement>
+        ]]>
+      </code-block>
+    </tab>
+</tabs>
+</chapter>
+
+<var name="target_module" value="client"/>
+<include from="server-dependencies.topic" element-id="using-version-catalog"/>

topics/client-requests.md

@@ -16,6 +16,7 @@ Learn how to make requests and specify various request parameters: a request URL
 After [setting up the client](client-create-and-configure.md), you can make HTTP requests. The main way of making HTTP requests is the [request](https://api.ktor.io/ktor-client/ktor-client-core/io.ktor.client.request/request.html) function that can take a URL as a parameter. Inside this function, you can configure various request parameters: 
 * Specify an HTTP method, such as `GET`, `POST`, `PUT`, `DELETE`, `HEAD`, `OPTIONS`, or `PATCH`.
 * Specify a URL as a string or configure URL components (a domain, a path, query parameters, etc.) separately.
+* Specify a Unix domain socket.
 * Add headers and cookies.
 * Set the body of a request, for example, a plain text, a data object, or form parameters.
 
@@ -119,6 +120,25 @@ You can configure a URL fragment using the `fragment` property.
 Note that `fragment` [encodes][percent_encoding] a URL fragment.
 To disable encoding, use `encodedFragment`.
 
+## Specify a Unix domain socket
+
+> Unix domain sockets are supported only in the CIO engine.
+> To use a Unix socket with a Ktor server, [configure the server](server-configuration-code.topic#cio-code) accordingly.
+> 
+{style="note"}
+
+You can make requests to a server listening to a Unix domain socket by calling the `unixSocket` function
+for a CIO client:
+
+```kotlin
+val client = HttpClient(CIO)
+
+val response: HttpResponse = client.get("/") {
+    unixSocket("/tmp/test-unix-socket-ktor.sock")
+}
+```
+
+You can also set up a Unix domain socket as a part of a [default request](client-default-request.md#unix-domain-sockets). 
 
 ## Set request parameters {id="parameters"}
 In this section, we'll see how to specify various request parameters, including an HTTP method, headers, and cookies. If you need to configure some default parameters for all requests of a specific client, use the [DefaultRequest](client-default-request.md) plugin.
@@ -134,8 +154,7 @@ To add headers to the request, you can use the following ways:
 - The [header](https://api.ktor.io/ktor-client/ktor-client-core/io.ktor.client.request/header.html) function allows you to append a single header.
 - The `basicAuth` and `bearerAuth` functions add the `Authorization` header with a corresponding HTTP scheme.
    > For advanced authentication configuration, refer to [](client-auth.md).
-
-
+
 
 ### Cookies {id="cookies"}
 To send cookies, use the [cookie](https://api.ktor.io/ktor-client/ktor-client-core/io.ktor.client.request/cookie.html) function:
@@ -147,7 +166,6 @@ To send cookies, use the [cookie](https://api.ktor.io/ktor-client/ktor-client-co
 Ktor also provides the [HttpCookies](client-cookies.md) plugin that allows you to keep cookies between calls. If this plugin is installed, cookies added using the `cookie` function are ignored.
 
 
-
 ## Set request body {id="body"}
 To set the body of a request, you need to call the `setBody` function exposed by [HttpRequestBuilder](https://api.ktor.io/ktor-client/ktor-client-core/io.ktor.client.request/-http-request-builder/index.html). This function accepts different types of payloads, including plain text, arbitrary class instances, form data, byte arrays, and so on. Below, we'll take a look at several examples.
 

topics/client-responses.md

@@ -76,8 +76,11 @@ below shows how to get a response as a `ByteArray` and save it to a file:
 The [`onDownload()`](https://api.ktor.io/ktor-client/ktor-client-core/io.ktor.client.plugins/on-download.html) extension
 function in the example above is used to display download progress.
 
-This approach loads the entire response into memory at once, which can be problematic for large files. To reduce memory
-usage, consider [streaming the data](#streaming) in chunks.
+For non-streaming requests, the response body is automatically loaded and cached in memory, allowing repeated access.
+While this is efficient for small payloads, it may lead to high memory usage with large responses.
+
+To handle large responses efficiently, use a [streaming approach](#streaming),
+which processes the response incrementally without saving it in memory.
 
 ### JSON object {id="json"}