0
# Compression & Encoding
1

2
Content encoding and compression utilities including GZip and Deflate support. Provides efficient compression and decompression capabilities for web content and data processing with coroutine support.
3

4
## Capabilities
5

6
### Encoder Interface
7

8
Base interface for content encoding and decoding operations with coroutine context support.
9

10
```kotlin { .api }
11
/**
12
 * Content encoder interface supporting both encoding and decoding operations
13
 */
14
interface Encoder {
15
    /** Launch coroutine to encode source bytes */
16
    fun encode(
17
        source: ByteReadChannel,
18
        coroutineContext: CoroutineContext = EmptyCoroutineContext
19
    ): ByteReadChannel
20
    
21
    /** Launch coroutine to encode source bytes for writing */
22
    fun encode(
23
        source: ByteWriteChannel,
24
        coroutineContext: CoroutineContext = EmptyCoroutineContext
25
    ): ByteWriteChannel
26
    
27
    /** Launch coroutine to decode source bytes */
28
    fun decode(
29
        source: ByteReadChannel,
30
        coroutineContext: CoroutineContext = EmptyCoroutineContext
31
    ): ByteReadChannel
32
}
33
```
34

35
**Usage Examples:**
36

37
```kotlin
38
import io.ktor.util.*
39
import kotlin.coroutines.EmptyCoroutineContext
40

41
// Use identity encoder (no-op)
42
val sourceChannel: ByteReadChannel = // ... source data
43
val encoded = Identity.encode(sourceChannel, EmptyCoroutineContext)
44
val decoded = Identity.decode(encoded, EmptyCoroutineContext)
45

46
// Custom encoder implementation
47
class CustomEncoder : Encoder {
48
    override fun encode(
49
        source: ByteReadChannel,
50
        coroutineContext: CoroutineContext
51
    ): ByteReadChannel {
52
        // Custom encoding logic
53
        return source
54
    }
55
    
56
    override fun encode(
57
        source: ByteWriteChannel,
58
        coroutineContext: CoroutineContext
59
    ): ByteWriteChannel {
60
        // Custom encoding for write channel
61
        return source
62
    }
63
    
64
    override fun decode(
65
        source: ByteReadChannel,
66
        coroutineContext: CoroutineContext
67
    ): ByteReadChannel {
68
        // Custom decoding logic
69
        return source
70
    }
71
}
72
```
73

74
### ContentEncoder Interface
75

76
Interface for content encoders with HTTP header naming support and compression prediction.
77

78
```kotlin { .api }
79
/**
80
 * A request/response content encoder with HTTP header support
81
 */
82
interface ContentEncoder : Encoder {
83
    /** Encoder identifier to use in HTTP headers */
84
    val name: String
85
    
86
    /** Provides estimation for compressed length or null if impossible */
87
    fun predictCompressedLength(contentLength: Long): Long?
88
}
89
```
90

91
**Usage Examples:**
92

93
```kotlin
94
import io.ktor.util.*
95

96
// Use built-in identity encoder
97
val identityEncoder: ContentEncoder = IdentityEncoder
98
println("Encoder name: ${identityEncoder.name}") // "identity"
99

100
// Check compression prediction
101
val originalSize = 1024L
102
val predictedSize = identityEncoder.predictCompressedLength(originalSize)
103
println("Predicted size: $predictedSize") // 1024 (no compression)
104

105
// Use encoder
106
val sourceChannel: ByteReadChannel = // ... source data
107
val processed = identityEncoder.encode(sourceChannel)
108
```
109

110
### Built-in Content Encoders
111

112
Platform-specific implementations of compression algorithms (expect/actual pattern).
113

114
```kotlin { .api }
115
/**
116
 * Identity encoder that doesn't modify content
117
 */
118
object IdentityEncoder : ContentEncoder {
119
    override val name: String
120
    override fun predictCompressedLength(contentLength: Long): Long
121
    
122
    override fun encode(
123
        source: ByteReadChannel,
124
        coroutineContext: CoroutineContext
125
    ): ByteReadChannel
126
    
127
    override fun encode(
128
        source: ByteWriteChannel,
129
        coroutineContext: CoroutineContext
130
    ): ByteWriteChannel
131
    
132
    override fun decode(
133
        source: ByteReadChannel,
134
        coroutineContext: CoroutineContext
135
    ): ByteReadChannel
136
}
137

138
/**
139
 * GZip content encoder (expect/actual implementation)
140
 */
141
object GZipEncoder : ContentEncoder {
142
    override val name: String
143
    
144
    override fun encode(
145
        source: ByteReadChannel,
146
        coroutineContext: CoroutineContext
147
    ): ByteReadChannel
148
    
149
    override fun encode(
150
        source: ByteWriteChannel,
151
        coroutineContext: CoroutineContext
152
    ): ByteWriteChannel
153
    
154
    override fun decode(
155
        source: ByteReadChannel,
156
        coroutineContext: CoroutineContext
157
    ): ByteReadChannel
158
}
159

160
/**
161
 * Deflate content encoder (expect/actual implementation)
162
 */
163
object DeflateEncoder : ContentEncoder {
164
    override val name: String
165
    
166
    override fun encode(
167
        source: ByteReadChannel,
168
        coroutineContext: CoroutineContext
169
    ): ByteReadChannel
170
    
171
    override fun encode(
172
        source: ByteWriteChannel,
173
        coroutineContext: CoroutineContext
174
    ): ByteWriteChannel
175
    
176
    override fun decode(
177
        source: ByteReadChannel,
178
        coroutineContext: CoroutineContext
179
    ): ByteReadChannel
180
}
181

182
/**
183
 * Empty encoder that doesn't modify content
184
 */
185
object Identity : Encoder {
186
    override fun encode(
187
        source: ByteReadChannel,
188
        coroutineContext: CoroutineContext
189
    ): ByteReadChannel
190
    
191
    override fun encode(
192
        source: ByteWriteChannel,
193
        coroutineContext: CoroutineContext
194
    ): ByteWriteChannel
195
    
196
    override fun decode(
197
        source: ByteReadChannel,
198
        coroutineContext: CoroutineContext
199
    ): ByteReadChannel
200
}
201
```
202

203
**Usage Examples:**
204

205
```kotlin
206
import io.ktor.util.*
207
import kotlin.coroutines.EmptyCoroutineContext
208

209
// GZip compression
210
val originalData: ByteReadChannel = // ... source data
211
val gzipCompressed = GZipEncoder.encode(originalData, EmptyCoroutineContext)
212
val gzipDecompressed = GZipEncoder.decode(gzipCompressed, EmptyCoroutineContext)
213

214
// Deflate compression
215
val deflateCompressed = DeflateEncoder.encode(originalData, EmptyCoroutineContext)
216
val deflateDecompressed = DeflateEncoder.decode(deflateCompressed, EmptyCoroutineContext)
217

218
// Use in HTTP context
219
val responseData = "Large response content...".toByteArray()
220
val responseChannel = ByteReadChannel(responseData)
221

222
val encodedResponse = when (acceptedEncodings.contains("gzip")) {
223
    true -> {
224
        headers["Content-Encoding"] = GZipEncoder.name // "gzip"
225
        GZipEncoder.encode(responseChannel)
226
    }
227
    false -> {
228
        headers["Content-Encoding"] = IdentityEncoder.name // "identity"
229
        IdentityEncoder.encode(responseChannel)
230
    }
231
}
232
```
233

234
## Implementation Notes
235

236
- **Platform Support**: The Encoder and ContentEncoder interfaces are available on all platforms (Common)
237
- **Expect/Actual Pattern**: GZipEncoder and DeflateEncoder have platform-specific implementations
238
- **Coroutine Context**: All encoding/decoding operations support optional coroutine context for structured concurrency
239
- **HTTP Integration**: ContentEncoder interface is designed for HTTP content encoding headers
240
- **Built-in Encoders**: 
241
  - `Identity` - No-op encoder for compatibility
242
  - `IdentityEncoder` - Named content encoder for HTTP "identity" encoding
243
  - `GZipEncoder` - Platform-specific GZip compression
244
  - `DeflateEncoder` - Platform-specific Deflate compression