0
# Content Encoding
1

2
The Compression plugin supports multiple HTTP compression algorithms through the ContentEncoder interface, with built-in implementations for standard algorithms.
3

4
## Built-in Encoders
5

6
### GZip Encoding
7

8
```kotlin { .api }
9
fun CompressionConfig.gzip(block: CompressionEncoderBuilder.() -> Unit = {})
10
```
11

12
Configures gzip compression (RFC 1952) with default priority 1.0:
13

14
```kotlin
15
install(Compression) {
16
    gzip {
17
        priority = 0.9
18
        minimumSize(1024)
19
        matchContentType(ContentType.Text.Plain, ContentType.Application.Json)
20
    }
21
}
22
```
23

24
### Deflate Encoding  
25

26
```kotlin { .api }
27
fun CompressionConfig.deflate(block: CompressionEncoderBuilder.() -> Unit = {})
28
```
29

30
Configures deflate compression (RFC 1951) with default priority 0.9:
31

32
```kotlin
33
install(Compression) {
34
    deflate {
35
        priority = 0.8
36
        excludeContentType(ContentType.Image.Any)
37
    }
38
}
39
```
40

41
### Identity Encoding
42

43
```kotlin { .api }
44
fun CompressionConfig.identity(block: CompressionEncoderBuilder.() -> Unit = {})
45
```
46

47
Configures identity encoding (no compression) as a fallback option:
48

49
```kotlin
50
install(Compression) {
51
    identity {
52
        // Identity encoding typically used as fallback
53
        priority = 0.1
54
    }
55
}
56
```
57

58
## Encoder Configuration
59

60
```kotlin { .api }
61
class CompressionEncoderBuilder internal constructor(
62
    val encoder: ContentEncoder
63
) : ConditionsHolderBuilder {
64
    override val conditions: ArrayList<ApplicationCall.(OutgoingContent) -> Boolean> = arrayListOf()
65
    var priority: Double = 1.0
66
    
67
    internal fun buildConfig(): CompressionEncoderConfig
68
}
69
```
70

71
### Priority System
72

73
Encoders are selected based on client `Accept-Encoding` headers and configured priorities. Higher priority encoders are preferred when multiple options are available:
74

75
```kotlin
76
install(Compression) {
77
    gzip {
78
        priority = 1.0  // Highest priority
79
    }
80
    deflate {
81
        priority = 0.9  // Second choice
82
    }
83
    identity {
84
        priority = 0.1  // Fallback
85
    }
86
}
87
```
88

89
### Per-Encoder Conditions
90

91
Each encoder can have specific conditions that must be met for it to be used:
92

93
```kotlin
94
install(Compression) {
95
    gzip {
96
        // Only compress JSON responses larger than 500 bytes
97
        minimumSize(500)
98
        matchContentType(ContentType.Application.Json)
99
    }
100
    
101
    deflate {
102
        // Compress text content but exclude certain types
103
        matchContentType(ContentType.Text.Any)
104
        excludeContentType(ContentType.Text.EventStream)
105
        condition { _, content ->
106
            content.contentLength?.let { it > 100 } ?: true
107
        }
108
    }
109
}
110
```
111

112
## ContentEncoder Interface
113

114
The underlying encoder implementations from `io.ktor.util`:
115

116
```kotlin { .api }
117
interface Encoder {
118
    fun encode(source: ByteReadChannel, coroutineContext: CoroutineContext = EmptyCoroutineContext): ByteReadChannel
119
    fun encode(source: ByteWriteChannel, coroutineContext: CoroutineContext = EmptyCoroutineContext): ByteWriteChannel
120
    fun decode(source: ByteReadChannel, coroutineContext: CoroutineContext = EmptyCoroutineContext): ByteReadChannel
121
}
122

123
interface ContentEncoder : Encoder {
124
    val name: String
125
    fun predictCompressedLength(contentLength: Long): Long?
126
}
127

128
object GZipEncoder : ContentEncoder {
129
    override val name: String = "gzip"
130
}
131

132
object DeflateEncoder : ContentEncoder {
133
    override val name: String = "deflate"
134
}
135

136
object IdentityEncoder : ContentEncoder {
137
    override val name: String = "identity"
138
    override fun predictCompressedLength(contentLength: Long): Long = contentLength
139
}
140
```
141

142
## Content Negotiation
143

144
The plugin automatically handles HTTP content negotiation:
145

146
1. Reads client `Accept-Encoding` header
147
2. Matches available encoders with client preferences
148
3. Considers encoder priorities and quality values
149
4. Selects the best encoder that meets all conditions
150
5. Sets appropriate `Content-Encoding` response header
151

152
### Example Client Negotiation
153

154
```
155
Client sends: Accept-Encoding: gzip, deflate;q=0.8, *;q=0.1
156
Server response: Content-Encoding: gzip
157
```
158

159
The server will prefer gzip (quality 1.0) over deflate (quality 0.8) when both are available and meet the configured conditions.