0
# Configuration
1

2
Comprehensive configuration options for the ContentEncoding plugin including operation modes, encoder settings, and quality value management.
3

4
## ContentEncodingConfig API
5

6
```kotlin { .api }
7
class ContentEncodingConfig {
8
    enum class Mode(internal val request: Boolean, internal val response: Boolean) {
9
        CompressRequest(true, false),
10
        DecompressResponse(false, true),
11
        All(true, true)
12
    }
13
    
14
    var mode: Mode
15
    
16
    /**
17
     * Installs the `gzip` encoder.
18
     * @param quality a priority value to use in the `Accept-Encoding` header.
19
     */
20
    fun gzip(quality: Float? = null): Unit
21
    
22
    /**
23
     * Installs the `deflate` encoder.
24
     * @param quality a priority value to use in the `Accept-Encoding` header.
25
     */
26
    fun deflate(quality: Float? = null): Unit
27
    
28
    /**
29
     * Installs the `identity` encoder.
30
     * @param quality a priority value to use in the `Accept-Encoding` header.
31
     */
32
    fun identity(quality: Float? = null): Unit
33
    
34
    /**
35
     * Installs a custom encoder.
36
     * @param encoder a custom encoder to use.
37
     * @param quality a priority value to use in the `Accept-Encoding` header.
38
     */
39
    fun customEncoder(encoder: ContentEncoder, quality: Float? = null): Unit
40
}
41
```
42

43
## Installation and Configuration
44

45
```kotlin { .api }
46
fun HttpClientConfig<*>.ContentEncoding(
47
    mode: ContentEncodingConfig.Mode = ContentEncodingConfig.Mode.DecompressResponse,
48
    block: ContentEncodingConfig.() -> Unit = {
49
        gzip()
50
        deflate()
51
        identity()
52
    }
53
): Unit
54
```
55

56
### Basic Configuration
57

58
```kotlin
59
import io.ktor.client.*
60
import io.ktor.client.plugins.compression.*
61

62
val client = HttpClient {
63
    install(ContentEncoding) {
64
        gzip()
65
        deflate()
66
        identity()
67
    }
68
}
69
```
70

71
### Advanced Configuration with Modes
72

73
```kotlin
74
val client = HttpClient {
75
    install(ContentEncoding) {
76
        mode = ContentEncodingConfig.Mode.All
77
        gzip(0.9f)
78
        deflate(0.8f)
79
        identity(0.1f)
80
    }
81
}
82
```
83

84
## Operation Modes
85

86
### DecompressResponse (Default)
87

88
Only decompresses incoming response bodies. Does not compress outgoing requests.
89

90
```kotlin
91
install(ContentEncoding) {
92
    mode = ContentEncodingConfig.Mode.DecompressResponse
93
    gzip()
94
    deflate()
95
}
96
```
97

98
**Behavior:**
99
- Sets `Accept-Encoding` header on outgoing requests
100
- Automatically decompresses response bodies based on `Content-Encoding` header
101
- Does not compress request bodies
102

103
**Use Cases:**
104
- Client applications consuming compressed APIs
105
- Bandwidth optimization for downloads
106
- Standard web client behavior
107

108
### CompressRequest
109

110
Only compresses outgoing request bodies. Does not decompress incoming responses.
111

112
```kotlin
113
install(ContentEncoding) {
114
    mode = ContentEncodingConfig.Mode.CompressRequest
115
    gzip()
116
    deflate()
117
}
118
```
119

120
**Behavior:**
121
- Compresses request bodies when explicitly requested via `compress()` function
122
- Does not set `Accept-Encoding` header
123
- Does not decompress response bodies
124

125
**Use Cases:**
126
- Upload-heavy applications
127
- API clients sending large payloads
128
- Bandwidth optimization for uploads only
129

130
### All (Bidirectional)
131

132
Both compresses outgoing requests and decompresses incoming responses.
133

134
```kotlin
135
install(ContentEncoding) {
136
    mode = ContentEncodingConfig.Mode.All
137
    gzip()
138
    deflate()
139
}
140
```
141

142
**Behavior:**
143
- Sets `Accept-Encoding` header on requests
144
- Decompresses response bodies automatically
145
- Compresses request bodies when requested
146
- Full bidirectional compression support
147

148
**Use Cases:**
149
- Full-featured API clients
150
- Applications with heavy upload and download requirements
151
- Maximum bandwidth optimization
152

153
## Quality Values
154

155
Quality values (q-values) specify preference order in the `Accept-Encoding` header, ranging from 0.0 to 1.0.
156

157
### Basic Quality Configuration
158

159
```kotlin
160
install(ContentEncoding) {
161
    gzip(0.9f)     // Highest preference
162
    deflate(0.8f)  // Medium preference  
163
    identity(0.1f) // Lowest preference (fallback)
164
}
165
```
166

167
**Generated Accept-Encoding Header:**
168
```
169
Accept-Encoding: gzip;q=0.9,deflate;q=0.8,identity;q=0.1
170
```
171

172
### Quality Value Rules
173

174
```kotlin
175
install(ContentEncoding) {
176
    // Valid quality values (0.0 to 1.0)
177
    gzip(1.0f)     // Maximum preference
178
    deflate(0.5f)  // Medium preference
179
    identity(0.0f) // Minimum preference
180
    
181
    // No quality value = included without q-value
182
    gzip()         // Equivalent to highest preference
183
}
184
```
185

186
**Validation:**
187
- Quality values must be between 0.0 and 1.0 (inclusive)
188
- Invalid quality values throw `IllegalArgumentException`
189
- Null quality values omit the q-parameter in headers
190

191
### Dynamic Quality Configuration
192

193
```kotlin
194
val highBandwidth = true
195

196
install(ContentEncoding) {
197
    if (highBandwidth) {
198
        gzip(0.9f)
199
        deflate(0.8f)
200
    } else {
201
        identity(1.0f)  // Prefer no compression on low bandwidth
202
    }
203
}
204
```
205

206
## Custom Encoder Registration
207

208
```kotlin { .api }
209
fun customEncoder(encoder: ContentEncoder, quality: Float? = null): Unit
210
```
211

212
### Adding Custom Encoders
213

214
```kotlin
215
class BrotliEncoder : ContentEncoder {
216
    override val name: String = "br"
217
    
218
    override fun encode(
219
        source: ByteReadChannel,
220
        coroutineContext: CoroutineContext
221
    ): ByteReadChannel {
222
        // Brotli compression implementation
223
        TODO("Implement Brotli compression")
224
    }
225
    
226
    override fun decode(
227
        source: ByteReadChannel,
228
        coroutineContext: CoroutineContext
229
    ): ByteReadChannel {
230
        // Brotli decompression implementation
231
        TODO("Implement Brotli decompression")
232
    }
233
    
234
    override fun predictCompressedLength(contentLength: Long): Long? {
235
        return (contentLength * 0.7).toLong() // Estimate 30% compression
236
    }
237
}
238

239
// Register custom encoder
240
install(ContentEncoding) {
241
    customEncoder(BrotliEncoder(), 0.95f)
242
    gzip(0.9f)
243
    deflate(0.8f)
244
}
245
```
246

247
### Encoder Management
248

249
```kotlin
250
install(ContentEncoding) {
251
    // Add encoders
252
    gzip(0.9f)
253
    deflate(0.8f)
254
    
255
    // Remove encoder (by re-adding with null quality)
256
    gzip(null)  // Removes gzip encoder
257
    
258
    // Re-add with different quality
259
    gzip(0.5f)  // Adds gzip back with lower priority
260
}
261
```
262

263
## Configuration Validation
264

265
### Quality Value Validation
266

267
```kotlin
268
install(ContentEncoding) {
269
    try {
270
        gzip(1.5f)  // Invalid: > 1.0
271
    } catch (e: IllegalArgumentException) {
272
        println("Invalid quality value: ${e.message}")
273
    }
274
    
275
    try {
276
        deflate(-0.1f)  // Invalid: < 0.0
277
    } catch (e: IllegalArgumentException) {
278
        println("Invalid quality value: ${e.message}")
279
    }
280
}
281
```
282

283
### Encoder Validation
284

285
```kotlin
286
class InvalidEncoder : ContentEncoder {
287
    override val name: String = ""  // Invalid: empty name
288
    // ... rest of implementation
289
}
290

291
install(ContentEncoding) {
292
    try {
293
        customEncoder(InvalidEncoder())
294
    } catch (e: IllegalArgumentException) {
295
        println("Invalid encoder: ${e.message}")
296
    }
297
}
298
```
299

300
## Configuration Examples
301

302
### Minimal Configuration
303

304
```kotlin
305
val client = HttpClient {
306
    install(ContentEncoding)  // Uses defaults: DecompressResponse mode with gzip, deflate, identity
307
}
308
```
309

310
### Compression-Only Client
311

312
```kotlin
313
val uploadClient = HttpClient {
314
    install(ContentEncoding) {
315
        mode = ContentEncodingConfig.Mode.CompressRequest
316
        gzip()
317
    }
318
}
319
```
320

321
### High-Performance Configuration
322

323
```kotlin
324
val performanceClient = HttpClient {
325
    install(ContentEncoding) {
326
        mode = ContentEncodingConfig.Mode.All
327
        gzip(1.0f)      // Prefer gzip for best compression
328
        deflate(0.8f)   // Fallback to deflate
329
        identity(0.1f)  // Last resort: no compression
330
    }
331
}
332
```
333

334
### Development/Debug Configuration
335

336
```kotlin
337
val debugClient = HttpClient {
338
    install(ContentEncoding) {
339
        mode = ContentEncodingConfig.Mode.DecompressResponse
340
        identity(1.0f)  // Prefer uncompressed for easier debugging
341
        gzip(0.5f)      // Allow compression if server insists
342
    }
343
}
344
```