KTOR-8902 Add docs for replacing plugin config

codeSnippets/snippets/_misc_client/InstallOrReplacePlugin.kt

@@ -0,0 +1,8 @@
+import io.ktor.client.*
+import io.ktor.client.engine.cio.*
+
+val client = HttpClient(CIO) {
+    installOrReplace(ContentNegotiation) {
+        // ...
+    }
+}

topics/client-default-request.md

@@ -34,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.*
@@ -48,6 +48,30 @@ val client = HttpClient(CIO) {
 }
 ```
 
+### Replace existing configuration {id="default_request_replace"}
+
+If `DefaultRequest` has already been installed, you can replace its existing configuration in one of the following ways:
+
+- Use the `replace` parameter of `defaultRequest()`:
+
+```kotlin
+val client = HttpClient(CIO) {
+    defaultRequest(replace = true) {
+        // this: DefaultRequestBuilder
+    }
+}
+```
+
+- Use the generic `installOrReplace()` function:
+
+```kotlin
+val client = HttpClient(CIO) {
+    installOrReplace(DefaultRequest) {
+        // this: DefaultRequestBuilder
+    }
+}
+```
+
 ## Configure DefaultRequest {id="configure"}
 
 ### Base URL {id="url"}

topics/client-plugins.md

@@ -1,35 +1,60 @@
 [//]: # (title: Client plugins)
 
 <link-summary>
-Get acquainted with plugins that provide common functionality, for example, logging, serialization, authorization, etc.
+Learn how to use client plugins to add common functionality, such as logging, serialization, and authorization.
 </link-summary>
 
-Many applications require common functionality that is out of scope of the application logic. This could be things like [logging](client-logging.md),  [serialization](client-serialization.md), or [authorization](client-auth.md). All of these are provided in Ktor by means of what we call **Plugins**. 
-
+Many applications require common functionality that is not part of the core application logic, such as
+[logging](client-logging.md), [serialization](client-serialization.md), or [authorization](client-auth.md). In Ktor,
+this functionality is provided by client _plugins_.
 
 ## Add plugin dependency {id="plugin-dependency"}
-A plugin might require a separate [dependency](client-dependencies.md). For example, the [Logging](client-logging.md) plugin requires adding the `ktor-client-logging` artifact in the build script:
+
+Some plugins require an additional [dependency](client-dependencies.md). For example, to use the [Logging](client-logging.md) plugin, you need to add the
+`ktor-client-logging` artifact in your build script:
 
 <var name="artifact_name" value="ktor-client-logging"/>
 <include from="lib.topic" element-id="add_ktor_artifact"/>
 
-You can learn which dependencies you need from a topic for a required plugin.
-
+Each plugin’s documentation specifies any required dependencies.
 
 ## Install a plugin {id="install"}
-To install a plugin, you need to pass it to the `install` function inside a [client configuration block](client-create-and-configure.md#configure-client). For example, installing the `Logging` plugin looks as follows:
+
+To install a plugin, pass it to the `install` function inside a [client configuration block](client-create-and-configure.md#configure-client).
+
+For example, installing the `Logging` plugin looks as follows:
 
 ```kotlin
 ```
-{src="snippets/_misc_client/InstallLoggingPlugin.kt"}
+{src="snippets/_misc_client/InstallLoggingPlugin.kt" include-lines="1-7"}
+
+### Install or replace a plugin {id="install_or_replace"}
 
+In some cases, a plugin may already be installed — for example, by shared client configuration code. In such cases, you
+can replace its configuration using `installOrReplace()`:
+
+```kotlin
+```
+{src="snippets/_misc_client/InstallOrReplacePlugin.kt" include-symbol="client"}
+
+This function installs the plugin if it is not present or replaces its existing configuration if it has already been
+installed.
 
 ## Configure a plugin {id="configure_plugin"}
-You can configure a plugin inside the `install` block. For example, for the [Logging](client-logging.md) plugin, you can specify the logger, logging level, and condition for filtering log messages:
+
+Most plugins expose configuration options that can be set inside the `install` block.
+
+For example, the [Logging](client-logging.md) plugin allows you to specify the logger, logging level, and condition for filtering log
+messages:
+
 ```kotlin
 ```
-{src="snippets/client-logging/src/main/kotlin/com/example/Application.kt" include-lines="12-20"}
+{src="snippets/client-logging/src/main/kotlin/com/example/Application.kt" include-symbol="client"}
 
 
 ## Create a custom plugin {id="custom"}
-To learn how to create custom plugins, refer to [](client-custom-plugins.md).
+
+If the existing plugins do not meet your needs, you can create your own custom client plugins. Custom plugins allow you
+to intercept requests and responses and implement reusable behavior.
+
+To learn more, see [](client-custom-plugins.md).

topics/whats-new-340.md

@@ -288,3 +288,39 @@ val client = HttpClient(Apache5) {
 
 The new `configureConnectionManager {}` function keeps Ktor in control while allowing you to adjust parameters such as 
 maximum connections per route (`maxConnPerRoute`) and total maximum connections (`maxConnTotal`).
+
+
+### Plugin and default request configuration replacement
+
+Ktor client configuration now provides more control over replacing existing settings at runtime.
+
+#### Replace plugin configuration
+
+The new `installOrReplace()` function installs a client plugin or replaces its existing configuration if the plugin is
+already installed. This is useful when you need to reconfigure a plugin without manually removing it first.
+
+```kotlin
+val client = HttpClient {
+    installOrReplace(ContentNegotiation) {
+        json()
+    }
+}
+```
+
+In the above example, if `ContentNegotiation` is already installed, its configuration is replaced with the new one
+provided in the block.
+
+#### Replace default request configuration
+
+The `defaultRequest()` function now accepts an optional `replace` parameter (default is false). When set to `true`,
+the new configuration replaces any previously defined default request settings instead of being merged with them.
+
+```kotlin
+val client = HttpClient {
+    defaultRequest(replace = true) {
+        // Configure default request parameters
+    }
+}
+```
+
+This allows you to explicitly override earlier default request configuration when composing or reusing client setups.