KTOR-8902 Add docs for replacing plugin config

[vnikolova]

KTOR-8902

• add an entry in "What's new in Ktor 3.4.0`
• add a new subsection in client-plugins
• add a new subsection in client-default-request
• add a code example for installOrReplace

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Walkthrough

This PR introduces Ktor 3.4.0-EAP features including the HttpRequestLifecycle plugin for cancelling requests on client disconnect, respondHtmlFragment for partial HTML responses, OAuth provider fallback handling, token cache management, zstd compression support, and SSL trust store configuration. It adds a new server-http-request-lifecycle code snippet module and updates extensive documentation across client and server feature areas.

Changes

Cohort / File(s)	Summary
Build Configuration codeSnippets/gradle.properties, codeSnippets/settings.gradle.kts	Ktor version bumped to 3.4.0-eap-1477; new module added for server-http-request-lifecycle snippet.
Code Snippets - Client Configuration codeSnippets/snippets/_misc_client/InstallOrReplacePlugin.kt, codeSnippets/snippets/_misc_client/OkHttpConfig.kt	New HttpClient examples: InstallOrReplace pattern with ContentNegotiation and OkHttp duplex streaming configuration.
Code Snippets - OAuth codeSnippets/snippets/auth-oauth-google/src/main/kotlin/com/example/oauth/google/Application.kt	Added OAuth fallback error handling route and post-fallback redirect endpoint.
Code Snippets - HTML codeSnippets/snippets/html/src/main/kotlin/com/example/Application.kt	Added new /fragment route demonstrating respondHtmlFragment response with Created status.
Code Snippets - Server HTTP Request Lifecycle (New Module) codeSnippets/snippets/server-http-request-lifecycle/README.md, build.gradle.kts, src/main/kotlin/com/example/Application.kt, src/main/resources/application.conf, src/main/resources/logback.xml, src/test/kotlin/ApplicationTest.kt	New complete module demonstrating HttpRequestLifecycle plugin with /long-process route, cancellation handling, embedded server test, and configuration files.
Code Snippets - SSL Configuration codeSnippets/snippets/ssl-engine-main/src/main/resources/_application.yaml, src/main/resources/application.conf	Added trustStore, trustStorePassword, and enabledProtocols SSL configuration fields.
Project Navigation ktor.tree	Added TOC entry for server HTTP request lifecycle and corresponding What's New release note.
Documentation - Client Authentication topics/client-auth.md, topics/client-basic-auth.md, topics/client-bearer-auth.md	Added token caching documentation, cache control APIs (clearToken, clearAuthTokens, cacheTokens option), and authentication provider management.
Documentation - Client Core topics/client-default-request.md, topics/client-plugins.md, topics/client-responses.md	Updated defaultRequest DSL with replace parameter and installOrReplace pattern; added Headers.getSplitValues() API documentation.
Documentation - Server Features topics/server-compression.md, topics/server-html-dsl.md, topics/server-http-request-lifecycle.md, topics/server-oauth.md, topics/server-responses.md, topics/server-ssl.md	Added zstd compression, respondHtmlFragment, HttpRequestLifecycle plugin docs, OAuth fallback, HTML/response APIs, and SSL trust store configuration guidance.
Release Notes topics/whats-new-340.md	Comprehensive documentation of 3.4.0-EAP features: OAuth fallback, zstd, SSL, HTML fragments, HTTP lifecycle, token management, duplex streaming, and plugin replacement APIs.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~70 minutes

• HTTP request lifecycle implementation: Verify cancellation propagation, structured concurrency integration, and test coverage for client disconnect handling
• OAuth fallback error handling logic: Ensure fallback lambda receives correct exception types and response routing works as documented
• Documentation consistency: Cross-check code snippets in whats-new-340.md against actual implementation in multiple related topics
• New module completeness: Validate build.gradle.kts dependencies align with documentation examples and test setup correctly exercises the lifecycle plugin
• SSL and compression configuration examples: Confirm YAML/config syntax matches supported property names and type requirements

Possibly related PRs

• Fix Code Snippet Build #692 — Modifies codeSnippets/settings.gradle.kts module inclusions to add/remove snippet modules
• KTOR-8962 Update the Create a new Ktor project tutorial #708 — Changes module inclusions in settings.gradle.kts, including server-http-request-lifecycle module handling
• update: mention the Unix domain socket functionality in making requests #644 — Modifies topics/client-default-request.md with alternative defaultRequest configuration patterns

Suggested reviewers

• e5l
• Stexxe
• bjhham

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title accurately reflects the primary change: adding documentation for replacing plugin configuration, which aligns with the changeset's focus on documenting the installOrReplace feature.
Description check	✅ Passed	The PR description is directly related to the changeset, listing specific documentation additions (What's new entry, client-plugins subsection, client-default-request subsection, and installOrReplace code example).

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}