0
# Ktor Server Compression
1

2
Ktor Server Compression is a server-side plugin for the Ktor framework that provides comprehensive HTTP response compression and request decompression capabilities. It supports multiple compression algorithms including gzip, deflate, and identity encoding, with intelligent content negotiation and configurable compression criteria.
3

4
## Package Information
5

6
- **Package Name**: io.ktor:ktor-server-compression-jvm
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Installation**: Add to `build.gradle.kts`:
10

11
```kotlin
12
implementation("io.ktor:ktor-server-compression-jvm:3.2.0")
13
```
14

15
## Core Imports
16

17
```kotlin
18
import io.ktor.server.plugins.compression.*
19
import io.ktor.server.application.*
20
import io.ktor.server.http.content.*  // For suppression functions
21
import io.ktor.util.*  // For ContentEncoder types
22
```
23

24
## Basic Usage
25

26
```kotlin
27
import io.ktor.server.application.*
28
import io.ktor.server.plugins.compression.*
29
import io.ktor.server.response.*
30
import io.ktor.server.routing.*
31

32
fun Application.module() {
33
    // Install with default configuration (gzip, deflate, identity)
34
    install(Compression)
35
    
36
    routing {
37
        get("/") {
38
            call.respondText("This response will be compressed if client supports it")
39
        }
40
    }
41
}
42
```
43

44
## Architecture
45

46
The compression plugin operates at the Ktor pipeline level, intercepting outgoing responses for compression and incoming requests for decompression. It uses a priority-based encoder selection system that respects client `Accept-Encoding` headers and applies configurable conditions to determine when compression should occur.
47

48
Key components:
49
- **Compression Plugin**: Main plugin entry point with dual-mode operation
50
- **Configuration System**: Fluent DSL for setting up encoders and conditions  
51
- **Content Encoders**: Pluggable compression algorithm implementations
52
- **Suppression System**: Fine-grained control to disable compression per request
53

54
## Capabilities
55

56
### Plugin Installation and Configuration
57

58
Install the Compression plugin with customizable encoding algorithms and operational modes.
59

60
```kotlin { .api }
61
val Compression: RouteScopedPlugin<CompressionConfig>
62

63
fun Application.install(plugin: RouteScopedPlugin<CompressionConfig>, configure: CompressionConfig.() -> Unit = {})
64
```
65

66
[Plugin Configuration](./configuration.md)
67

68
### Content Encoding
69

70
Built-in support for standard HTTP compression algorithms with configurable priority and conditions.
71

72
```kotlin { .api }
73
fun CompressionConfig.gzip(block: CompressionEncoderBuilder.() -> Unit = {})
74
fun CompressionConfig.deflate(block: CompressionEncoderBuilder.() -> Unit = {})  
75
fun CompressionConfig.identity(block: CompressionEncoderBuilder.() -> Unit = {})
76
```
77

78
[Content Encoding](./encoding.md)
79

80
### Compression Conditions
81

82
Configure when compression should be applied based on content type, size, and custom predicates.
83

84
```kotlin { .api }
85
fun ConditionsHolderBuilder.condition(predicate: ApplicationCall.(OutgoingContent) -> Boolean)
86
fun ConditionsHolderBuilder.minimumSize(minSize: Long)
87
fun ConditionsHolderBuilder.matchContentType(vararg mimeTypes: ContentType)
88
fun ConditionsHolderBuilder.excludeContentType(vararg mimeTypes: ContentType)
89
```
90

91
[Compression Conditions](./conditions.md)
92

93
### Request Decompression
94

95
Automatic decompression of compressed request bodies with decoder tracking.
96

97
```kotlin { .api }
98
val ApplicationRequest.appliedDecoders: List<String>
99
```
100

101
[Request Decompression](./decompression.md)
102

103
### Compression Control
104

105
Runtime control to suppress compression or decompression on a per-request basis.
106

107
```kotlin { .api }
108
fun ApplicationCall.suppressCompression()
109
fun ApplicationCall.suppressDecompression()
110
val ApplicationCall.isCompressionSuppressed: Boolean
111
val ApplicationCall.isDecompressionSuppressed: Boolean
112
```
113

114
[Compression Control](./control.md)
115

116
## Core Types
117

118
```kotlin { .api }
119
data class CompressionConfig(
120
    var mode: Mode = Mode.All,
121
    val encoders: MutableMap<String, CompressionEncoderBuilder> = hashMapOf(),
122
    val conditions: MutableList<ApplicationCall.(OutgoingContent) -> Boolean> = arrayListOf()
123
)
124

125
enum class CompressionConfig.Mode(
126
    internal val request: Boolean, 
127
    internal val response: Boolean
128
) {
129
    CompressResponse(false, true),
130
    DecompressRequest(true, false),
131
    All(true, true)
132
}
133

134
data class CompressionEncoderConfig(
135
    val encoder: ContentEncoder,
136
    val conditions: List<ApplicationCall.(OutgoingContent) -> Boolean>,
137
    val priority: Double
138
)
139

140
class CompressionEncoderBuilder(
141
    val encoder: ContentEncoder
142
) : ConditionsHolderBuilder {
143
    val conditions: ArrayList<ApplicationCall.(OutgoingContent) -> Boolean>
144
    var priority: Double = 1.0
145
}
146

147
interface ConditionsHolderBuilder {
148
    val conditions: MutableList<ApplicationCall.(OutgoingContent) -> Boolean>
149
}
150
```