Merge documentation for the Ktor 3.0.0 release

ktorio · Oct 10, 2024 · 8a84c1b · 8a84c1b
2 parents a6db611 + b798cd2
commit 8a84c1b
Show file tree

Hide file tree

Showing 329 changed files with 3,448 additions and 1,652 deletions.
diff --git a/.DS_Store b/.DS_Store
diff --git a/.github/.DS_Store b/.github/.DS_Store
diff --git a/.github/images/.DS_Store b/.github/images/.DS_Store
diff --git a/cfg/buildprofiles.xml b/cfg/buildprofiles.xml
@@ -1,27 +1,22 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<buildprofiles>
+<buildprofiles xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/build-profiles.xsd"
+               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <variables>
         <web-root>https://ktor.io</web-root>
-        <web-community-path>Developer Community:http://www.jetbrains.net/devnet/community/idea/kb</web-community-path>
         <download-page>https://ktor.io/create/</download-page>
-        <config-showDownloadButton>false</config-showDownloadButton>
+        <showDownloadButton>false</showDownloadButton>
         <enable-browser-edits>true</enable-browser-edits>
         <browser-edits-url>https://github.com/ktorio/ktor-documentation/edit/main/</browser-edits-url>
         <search-scope/>
         <fallback-url/>
-        <help-app-version>3</help-app-version>
-        <config-feedbackRequireEmail>false</config-feedbackRequireEmail>
-        <config-disqus-id>jetbrains</config-disqus-id>
-        <config-disqus-show>false</config-disqus-show>
-        <config-feedback-url>https://forms-service.jetbrains.com/feedback</config-feedback-url>
-        <config-feedback-enabled>true</config-feedback-enabled>
-        <config-feedback-widget>true</config-feedback-widget>
-        <config-versions-switcher>https://raw.githubusercontent.com/ktorio/ktor-documentation/main/help-versions.json</config-versions-switcher>
-        <config-webmaster>[email protected]</config-webmaster>
-        <config-feedback-support>https://www.jetbrains.com/support/</config-feedback-support>
-        <config-sideblocks>true</config-sideblocks>
-        <config-productid>docs</config-productid>
-        <config-search-scopes-provider>https://data.services.jetbrains.com/search/</config-search-scopes-provider>
+        <feedbackRequireEmail>false</feedbackRequireEmail>
+        <feedback-url>https://forms-service.jetbrains.com/feedback</feedback-url>
+        <feedback-widget>true</feedback-widget>
+        <versions-switcher>https://raw.githubusercontent.com/ktorio/ktor-documentation/main/help-versions.json</versions-switcher>
+        <webmaster>[email protected]</webmaster>
+        <feedback-support>https://www.jetbrains.com/support/</feedback-support>
+        <sideblocks>true</sideblocks>
+        <search-scopes-provider>https://data.services.jetbrains.com/search/</search-scopes-provider>
         <noindex-content status="deprecated">true</noindex-content>
         <noindex-content status="eap">true</noindex-content>
         <noindex-content status="release">false</noindex-content>
@@ -31,12 +26,10 @@
         <og-twitter>@JetBrainsKtor</og-twitter>
         <og-image>https://raw.githubusercontent.com/ktorio/ktor-documentation/main/preview.jpg</og-image>
 
-        <config-algolia-api-key>8c2683cac2d71d547b55183297abb506</config-algolia-api-key>
-        <config-algolia-id>OHIV241QET</config-algolia-id>
-        <config-algolia-index>prod_JETBRAINSCOM_HELP</config-algolia-index>
-        <config-algolia-product-id>docs</config-algolia-product-id>
-        <config-algloia-product-version>2.1.0</config-algloia-product-version>
-
+        <algolia-api-key>8c2683cac2d71d547b55183297abb506</algolia-api-key>
+        <algolia-id>OHIV241QET</algolia-id>
+        <algolia-index>prod_JETBRAINSCOM_HELP</algolia-index>
+        <config-algloia-product-version>3.0.0</config-algloia-product-version>
         <analytics-head-script-file>google-analytics-code.html</analytics-head-script-file>
         <analytics-body-html-file>google-analytics-noscript.html</analytics-body-html-file>
 
@@ -51,7 +44,7 @@
         <primary-color>iris</primary-color>
     </variables>
 
-    <build-profile product="ktor"/>
+    <build-profile instance="ktor"/>
 
     <footer>
         <copyright>2000-2024 JetBrains s.r.o.</copyright>

diff --git a/codeSnippets/gradle.properties b/codeSnippets/gradle.properties
@@ -5,8 +5,8 @@ kotlin.native.binary.memoryModel = experimental
 # gradle configuration
 org.gradle.configureondemand = false
 # versions
-kotlin_version = 2.0.0
-ktor_version = 2.3.12
+kotlin_version = 2.0.20
+ktor_version = 3.0.0
 kotlinx_coroutines_version = 1.9.0
 kotlinx_serialization_version = 1.7.2
 kotlin_css_version = 1.0.0-pre.721

diff --git a/codeSnippets/settings.gradle.kts b/codeSnippets/settings.gradle.kts
@@ -44,7 +44,6 @@ module("snippets", "html")
 module("snippets", "html-templates")
 module("snippets", "jackson")
 module("snippets", "client-json")
-module("snippets", "locations")
 module("snippets", "dropwizard-metrics")
 module("snippets", "upload-file")
 module("snippets", "download-file")
@@ -55,6 +54,7 @@ module("snippets", "session-cookie-server")
 module("snippets", "session-header-server")
 module("snippets", "static-files")
 module("snippets", "static-resources")
+module("snippets", "static-zip")
 module("snippets", "timeout")
 module("snippets", "autohead")
 module("snippets", "autoreload-engine-main")
@@ -108,6 +108,7 @@ module("snippets", "logging")
 module("snippets", "call-id")
 module("snippets", "cors")
 module("snippets", "compression")
+module("snippets", "client-bom-remover")
 module("snippets", "client-content-encoding")
 module("snippets", "client-caching")
 module("snippets", "client-custom-plugin")
@@ -155,6 +156,9 @@ module("snippets", "custom-plugin-authorization")
 module("snippets", "client-configure-request")
 module("snippets", "request-validation")
 module("snippets", "data-conversion")
+module("snippets", "client-sse")
+module("snippets", "server-sse")
+module("snippets", "client-call-id")
 module("snippets", "tutorial-server-routing-and-requests")
 module("snippets", "tutorial-server-restful-api")
 module("snippets", "tutorial-server-websockets")

diff --git a/codeSnippets/snippets/auth-basic-hash-table/build.gradle.kts b/codeSnippets/snippets/auth-basic-hash-table/build.gradle.kts
@@ -22,6 +22,6 @@ dependencies {
     implementation("io.ktor:ktor-server-netty:$ktor_version")
     implementation("io.ktor:ktor-server-auth:$ktor_version")
     implementation("ch.qos.logback:logback-classic:$logback_version")
-    testImplementation("io.ktor:ktor-server-test-host:$ktor_version")
+    testImplementation("io.ktor:ktor-server-test-host-jvm:$ktor_version")
     testImplementation("org.jetbrains.kotlin:kotlin-test")
 }
diff --git a/codeSnippets/snippets/auth-basic-hash-table/src/test/kotlin/com/example/ApplicationTest.kt b/codeSnippets/snippets/auth-basic-hash-table/src/test/kotlin/com/example/ApplicationTest.kt
@@ -12,6 +12,9 @@ import kotlin.test.assertEquals
 class ApplicationTest {
     @Test
     fun testAuthRoute() = testApplication {
+        application {
+            main()
+        }
         val client = createClient {
             defaultRequest {
                 val credentials = Base64.getEncoder().encodeToString("admin:password".toByteArray())

diff --git a/codeSnippets/snippets/auth-basic/build.gradle.kts b/codeSnippets/snippets/auth-basic/build.gradle.kts
@@ -21,6 +21,5 @@ dependencies {
     implementation("io.ktor:ktor-server-netty:$ktor_version")
     implementation("io.ktor:ktor-server-auth:$ktor_version")
     implementation("ch.qos.logback:logback-classic:$logback_version")
-    testImplementation("io.ktor:ktor-server-test-host:$ktor_version")
-    testImplementation("org.jetbrains.kotlin:kotlin-test")
-}
+    testImplementation("io.ktor:ktor-server-test-host-jvm:$ktor_version")
+    testImplementation("org.jetbrains.kotlin:kotlin-test")}
diff --git a/codeSnippets/snippets/auth-basic/src/test/kotlin/authbasic/ApplicationTest.kt b/codeSnippets/snippets/auth-basic/src/test/kotlin/authbasic/ApplicationTest.kt
@@ -12,6 +12,9 @@ import kotlin.test.assertEquals
 class ApplicationTest {
     @Test
     fun testAuthRoute() = testApplication {
+        application {
+            main()
+        }
         val client = createClient {
             defaultRequest {
                 val credentials = Base64.getEncoder().encodeToString("jetbrains:foobar".toByteArray())

diff --git a/codeSnippets/snippets/auth-bearer/build.gradle.kts b/codeSnippets/snippets/auth-bearer/build.gradle.kts
@@ -22,6 +22,6 @@ dependencies {
     implementation("io.ktor:ktor-server-netty:$ktor_version")
     implementation("io.ktor:ktor-server-auth:$ktor_version")
     implementation("ch.qos.logback:logback-classic:$logback_version")
-    testImplementation("io.ktor:ktor-server-test-host:$ktor_version")
+    testImplementation("io.ktor:ktor-server-test-host-jvm:$ktor_version")
     testImplementation("org.jetbrains.kotlin:kotlin-test")
 }
diff --git a/codeSnippets/snippets/auth-bearer/src/test/kotlin/com/example/ApplicationTest.kt b/codeSnippets/snippets/auth-bearer/src/test/kotlin/com/example/ApplicationTest.kt
@@ -9,6 +9,9 @@ import kotlin.test.*
 class ApplicationTest {
     @Test
     fun testAuthRoute() = testApplication {
+        application {
+            main()
+        }
         val response = client.get("/") {
             header(HttpHeaders.Authorization, "Bearer abc123")
         }

diff --git a/codeSnippets/snippets/auth-digest/build.gradle.kts b/codeSnippets/snippets/auth-digest/build.gradle.kts
@@ -22,7 +22,11 @@ dependencies {
     implementation("io.ktor:ktor-server-netty:$ktor_version")
     implementation("io.ktor:ktor-server-auth:$ktor_version")
     implementation("ch.qos.logback:logback-classic:$logback_version")
-    testImplementation("io.ktor:ktor-server-test-host:$ktor_version")
+    testImplementation("io.ktor:ktor-server-test-host-jvm:$ktor_version")
     testImplementation("org.jetbrains.kotlin:kotlin-test")
     testImplementation("io.ktor:ktor-client-auth:$ktor_version")
 }
+
+kotlin {
+    jvmToolchain(11)
+}
diff --git a/codeSnippets/snippets/auth-digest/src/test/kotlin/authdigest/ApplicationTest.kt b/codeSnippets/snippets/auth-digest/src/test/kotlin/authdigest/ApplicationTest.kt
@@ -10,6 +10,9 @@ import kotlin.test.*
 class ApplicationTest {
     @Test
     fun testAuthRoute() = testApplication {
+        application {
+            main()
+        }
         val client = createClient {
             install(Auth) {
                 digest {

diff --git a/codeSnippets/snippets/auth-form-html-dsl/build.gradle.kts b/codeSnippets/snippets/auth-form-html-dsl/build.gradle.kts
@@ -23,6 +23,6 @@ dependencies {
     implementation("io.ktor:ktor-server-auth:$ktor_version")
     implementation("io.ktor:ktor-server-html-builder:$ktor_version")
     implementation("ch.qos.logback:logback-classic:$logback_version")
-    testImplementation("io.ktor:ktor-server-test-host:$ktor_version")
+    testImplementation("io.ktor:ktor-server-test-host-jvm:$ktor_version")
     testImplementation("org.jetbrains.kotlin:kotlin-test")
 }
diff --git a/codeSnippets/snippets/auth-form-html-dsl/src/test/kotlin/com/example/ApplicationTest.kt b/codeSnippets/snippets/auth-form-html-dsl/src/test/kotlin/com/example/ApplicationTest.kt
@@ -9,6 +9,9 @@ import kotlin.test.*
 class ApplicationTest {
     @Test
     fun testSuccessfulAuth() = testApplication {
+        application {
+            main()
+        }
         val loginResponse = client.post("/login") {
             header(HttpHeaders.ContentType, ContentType.Application.FormUrlEncoded.toString())
             setBody(listOf("username" to "jetbrains", "password" to "foobar").formUrlEncode())
@@ -18,6 +21,9 @@ class ApplicationTest {
 
     @Test
     fun testUnsuccessfulAuth() = testApplication {
+        application {
+            main()
+        }
         val loginResponse = client.post("/login") {
             header(HttpHeaders.ContentType, ContentType.Application.FormUrlEncoded.toString())
             setBody(listOf("username" to "jetbrains", "password" to "incorrect_pass").formUrlEncode())
@@ -27,6 +33,9 @@ class ApplicationTest {
 
     @Test
     fun testForm() = testApplication {
+        application {
+            main()
+        }
         val response = client.get("/login")
         assertEquals(
             """

diff --git a/codeSnippets/snippets/auth-form-session-nested/build.gradle.kts b/codeSnippets/snippets/auth-form-session-nested/build.gradle.kts
@@ -5,6 +5,7 @@ val logback_version: String by project
 plugins {
     application
     kotlin("jvm")
+    kotlin("plugin.serialization").version("2.0.0")
 }
 
 application {
@@ -23,7 +24,8 @@ dependencies {
     implementation("io.ktor:ktor-server-auth:$ktor_version")
     implementation("io.ktor:ktor-server-sessions:$ktor_version")
     implementation("io.ktor:ktor-server-html-builder:$ktor_version")
+    implementation("io.ktor:ktor-serialization-kotlinx-json:$ktor_version")
     implementation("ch.qos.logback:logback-classic:$logback_version")
-    testImplementation("io.ktor:ktor-server-test-host:$ktor_version")
+    testImplementation("io.ktor:ktor-server-test-host-jvm:$ktor_version")
     testImplementation("org.jetbrains.kotlin:kotlin-test")
 }
diff --git a/codeSnippets/snippets/auth-form-session-nested/src/main/kotlin/com/example/Application.kt b/codeSnippets/snippets/auth-form-session-nested/src/main/kotlin/com/example/Application.kt
@@ -7,7 +7,9 @@ import io.ktor.server.response.*
 import io.ktor.server.routing.*
 import io.ktor.server.sessions.*
 import kotlinx.html.*
+import kotlinx.serialization.Serializable
 
+@Serializable
 data class UserSession(val name: String, val count: Int) : Principal
 
 fun Application.main() {

diff --git a/codeSnippets/snippets/auth-form-session-nested/src/test/kotlin/ApplicationTest.kt b/codeSnippets/snippets/auth-form-session-nested/src/test/kotlin/ApplicationTest.kt
@@ -11,6 +11,9 @@ import kotlin.test.*
 class ApplicationTest {
     @Test
     fun testLoginProcess() = testApplication {
+        application {
+            main()
+        }
         val loginClient = createClient {
             install(HttpCookies)
         }

diff --git a/codeSnippets/snippets/auth-form-session/build.gradle.kts b/codeSnippets/snippets/auth-form-session/build.gradle.kts
@@ -5,6 +5,7 @@ val logback_version: String by project
 plugins {
     application
     kotlin("jvm")
+    kotlin("plugin.serialization").version("2.0.0")
 }
 
 application {
@@ -23,7 +24,8 @@ dependencies {
     implementation("io.ktor:ktor-server-auth:$ktor_version")
     implementation("io.ktor:ktor-server-sessions:$ktor_version")
     implementation("io.ktor:ktor-server-html-builder:$ktor_version")
+    implementation("io.ktor:ktor-serialization-kotlinx-json:$ktor_version")
     implementation("ch.qos.logback:logback-classic:$logback_version")
-    testImplementation("io.ktor:ktor-server-test-host:$ktor_version")
-    testImplementation("org.jetbrains.kotlin:kotlin-test")
+    testImplementation("io.ktor:ktor-server-test-host-jvm:$ktor_version")
+    testImplementation("org.jetbrains.kotlin:kotlin-test-junit")
 }
diff --git a/codeSnippets/snippets/auth-form-session/src/main/kotlin/com/example/Application.kt b/codeSnippets/snippets/auth-form-session/src/main/kotlin/com/example/Application.kt
@@ -7,7 +7,9 @@ import io.ktor.server.response.*
 import io.ktor.server.routing.*
 import io.ktor.server.sessions.*
 import kotlinx.html.*
+import kotlinx.serialization.Serializable
 
+@Serializable
 data class UserSession(val name: String, val count: Int) : Principal
 
 fun Application.main() {

diff --git a/codeSnippets/snippets/auth-form-session/src/test/kotlin/ApplicationTest.kt b/codeSnippets/snippets/auth-form-session/src/test/kotlin/ApplicationTest.kt
@@ -9,6 +9,9 @@ import kotlin.test.*
 class ApplicationTest {
     @Test
     fun testRequests() = testApplication {
+        application {
+            main()
+        }
         val client = createClient {
             install(HttpCookies)
         }

diff --git a/codeSnippets/snippets/auth-jwt-hs256/build.gradle.kts b/codeSnippets/snippets/auth-jwt-hs256/build.gradle.kts
@@ -27,7 +27,7 @@ dependencies {
     implementation("io.ktor:ktor-serialization-kotlinx-json:$ktor_version")
     implementation("io.ktor:ktor-server-config-yaml:$ktor_version")
     implementation("ch.qos.logback:logback-classic:$logback_version")
-    testImplementation("io.ktor:ktor-server-test-host:$ktor_version")
+    testImplementation("io.ktor:ktor-server-test-host-jvm:$ktor_version")
     testImplementation("org.jetbrains.kotlin:kotlin-test:$kotlin_version")
     testImplementation("io.ktor:ktor-client-content-negotiation:$ktor_version")
 }
diff --git a/codeSnippets/snippets/auth-jwt-hs256/src/main/kotlin/com/example/Application.kt b/codeSnippets/snippets/auth-jwt-hs256/src/main/kotlin/com/example/Application.kt
@@ -29,10 +29,10 @@ fun Application.main() {
         jwt("auth-jwt") {
             realm = myRealm
             verifier(JWT
-                .require(Algorithm.HMAC256(secret))
-                .withAudience(audience)
-                .withIssuer(issuer)
-                .build())
+                    .require(Algorithm.HMAC256(secret))
+                    .withAudience(audience)
+                    .withIssuer(issuer)
+                    .build())
             validate { credential ->
                 if (credential.payload.getClaim("username").asString() != "") {
                     JWTPrincipal(credential.payload)

diff --git a/...hs256/src/main/resources/application.conf → ...rc/main/resources/application-custom.conf b/...hs256/src/main/resources/application.conf → ...rc/main/resources/application-custom.conf
diff --git a/codeSnippets/snippets/auth-jwt-hs256/src/test/kotlin/com/example/ApplicationTest.kt b/codeSnippets/snippets/auth-jwt-hs256/src/test/kotlin/com/example/ApplicationTest.kt
@@ -6,13 +6,17 @@ import io.ktor.client.request.*
 import io.ktor.client.statement.*
 import io.ktor.http.*
 import io.ktor.serialization.kotlinx.json.*
+import io.ktor.server.config.*
 import io.ktor.server.testing.*
 import kotlinx.serialization.*
 import kotlin.test.*
 
 class ApplicationTest {
     @Test
     fun testHello() = testApplication {
+        environment {
+            config = ApplicationConfig("application-custom.conf")
+        }
         val client = createClient {
             install(ContentNegotiation) {
                 json()

diff --git a/codeSnippets/snippets/auth-oauth-google/build.gradle.kts b/codeSnippets/snippets/auth-oauth-google/build.gradle.kts
@@ -29,7 +29,7 @@ dependencies {
     implementation("io.ktor:ktor-client-content-negotiation:$ktor_version")
     implementation("io.ktor:ktor-serialization-kotlinx-json:$ktor_version")
     implementation("ch.qos.logback:logback-classic:$logback_version")
-    testImplementation("io.ktor:ktor-server-test-host:$ktor_version")
+    testImplementation("io.ktor:ktor-server-test-host-jvm:$ktor_version")
     testImplementation("org.jetbrains.kotlin:kotlin-test")
     testImplementation("io.ktor:ktor-server-content-negotiation:$ktor_version")
 }
diff --git a/...rc/main/kotlin/com/example/Application.kt → ...n/com/example/oauth/google/Application.kt b/...rc/main/kotlin/com/example/Application.kt → ...n/com/example/oauth/google/Application.kt
@@ -1,4 +1,4 @@
-package com.example
+package com.example.oauth.google
 
 import io.ktor.client.*
 import io.ktor.client.call.*
@@ -125,6 +125,7 @@ private suspend fun getSession(
     return userSession
 }
 
+@Serializable
 data class UserSession(val state: String, val token: String)
 
 @Serializable

diff --git a/codeSnippets/snippets/auth-oauth-google/src/test/kotlin/ApplicationTest.kt b/codeSnippets/snippets/auth-oauth-google/src/test/kotlin/ApplicationTest.kt
@@ -1,4 +1,4 @@
-package com.example
+package com.example.oauth.google
 
 import io.ktor.client.plugins.contentnegotiation.*
 import io.ktor.client.plugins.cookies.*

diff --git a/codeSnippets/snippets/autohead/build.gradle.kts b/codeSnippets/snippets/autohead/build.gradle.kts
@@ -22,6 +22,6 @@ dependencies {
     implementation("io.ktor:ktor-server-netty:$ktor_version")
     implementation("io.ktor:ktor-server-auto-head-response:$ktor_version")
     implementation("ch.qos.logback:logback-classic:$logback_version")
-    testImplementation("io.ktor:ktor-server-test-host:$ktor_version")
+    testImplementation("io.ktor:ktor-server-test-host-jvm:$ktor_version")
     testImplementation("org.jetbrains.kotlin:kotlin-test:$kotlin_version")
 }
diff --git a/codeSnippets/snippets/autohead/src/test/kotlin/AuthHeadTest.kt b/codeSnippets/snippets/autohead/src/test/kotlin/AuthHeadTest.kt
@@ -8,6 +8,9 @@ import kotlin.test.*
 class AuthHeadTest {
     @Test
     fun respondsSuccessfullyForHeadRequest() = testApplication {
+        application {
+            main()
+        }
         val headResponse = client.head("/home")
         assertEquals(HttpStatusCode.OK, headResponse.status)
     }

diff --git a/codeSnippets/snippets/autoreload-engine-main/build.gradle.kts b/codeSnippets/snippets/autoreload-engine-main/build.gradle.kts
@@ -25,5 +25,5 @@ dependencies {
     implementation("io.ktor:ktor-server-config-yaml:$ktor_version")
     testImplementation("junit:junit:$junit_version")
     testImplementation("com.typesafe:config:1.4.3")
-    testImplementation("io.ktor:ktor-server-test-host:$ktor_version")
+    testImplementation("io.ktor:ktor-server-test-host-jvm:$ktor_version")
 }