0
# Ktor Server Netty
1

2
Ktor Server Netty is a high-performance, Netty-based HTTP server engine for the Ktor framework. It provides asynchronous, non-blocking server capabilities with support for HTTP/1.1, HTTP/2, WebSockets, and SSL/TLS. The engine leverages Netty's robust networking capabilities to handle concurrent connections efficiently, making it ideal for building scalable microservices, web applications, and API servers.
3

4
## Package Information
5

6
- **Package Name**: io.ktor:ktor-server-netty
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Installation**: `implementation("io.ktor:ktor-server-netty:3.2.0")` (Gradle)
10

11
## Core Imports
12

13
```kotlin
14
import io.ktor.server.netty.*
15
import io.ktor.server.application.*
16
import io.ktor.server.engine.*
17
import io.ktor.events.*                      // For Events parameter
18
import io.netty.bootstrap.ServerBootstrap    // For bootstrap configuration
19
import io.netty.channel.ChannelPipeline      // For pipeline configuration
20
```
21

22
## Basic Usage
23

24
```kotlin
25
import io.ktor.server.application.*
26
import io.ktor.server.engine.*
27
import io.ktor.server.netty.*
28
import io.ktor.server.response.*
29
import io.ktor.server.routing.*
30

31
fun main() {
32
    // Create and start embedded server
33
    embeddedServer(Netty, port = 8080) {
34
        routing {
35
            get("/") {
36
                call.respondText("Hello from Ktor Netty!")
37
            }
38
        }
39
    }.start(wait = true)
40
}
41
```
42

43
## Architecture
44

45
Ktor Server Netty is built around several key components:
46

47
- **Application Engine Factory**: The `Netty` object serves as the factory for creating NettyApplicationEngine instances
48
- **Engine Configuration**: Comprehensive configuration options for fine-tuning server behavior, performance, and protocol support
49
- **Channel Management**: EventLoopGroup proxies that automatically select optimal implementations (Epoll, KQueue, NIO) based on the platform
50
- **Request/Response Processing**: Abstract base classes for handling HTTP requests and responses with Netty integration
51
- **Coroutine Integration**: Extension functions for seamless integration between Netty's Future-based API and Kotlin coroutines
52

53
## Capabilities
54

55
### Server Creation and Configuration
56

57
Primary entry points for creating and configuring Netty-based HTTP servers with comprehensive options for performance tuning and protocol support.
58

59
```kotlin { .api }
60
object Netty : ApplicationEngineFactory<NettyApplicationEngine, NettyApplicationEngine.Configuration> {
61
    fun configuration(
62
        configure: NettyApplicationEngine.Configuration.() -> Unit
63
    ): NettyApplicationEngine.Configuration
64
    
65
    fun create(
66
        environment: ApplicationEnvironment,
67
        monitor: Events,
68
        developmentMode: Boolean,
69
        configuration: NettyApplicationEngine.Configuration,
70
        applicationProvider: () -> Application
71
    ): NettyApplicationEngine
72
}
73
```
74

75
[Server Creation and Configuration](./server-configuration.md)
76

77
### Standalone Server Execution
78

79
Main entry point for running standalone Ktor Netty servers from command line or application main functions.
80

81
```kotlin { .api }
82
object EngineMain {
83
    @JvmStatic
84
    fun main(args: Array<String>)
85
    
86
    fun createServer(
87
        args: Array<String>
88
    ): EmbeddedServer<NettyApplicationEngine, NettyApplicationEngine.Configuration>
89
}
90
```
91

92
[Standalone Server Execution](./standalone-server.md)
93

94
### Engine Implementation
95

96
Core server engine implementation providing lifecycle management, connection handling, and integration with Ktor's application pipeline.
97

98
```kotlin { .api }
99
class NettyApplicationEngine(
100
    environment: ApplicationEnvironment,
101
    monitor: Events,
102
    developmentMode: Boolean,
103
    val configuration: Configuration,
104
    applicationProvider: () -> Application
105
) : BaseApplicationEngine(environment, monitor, developmentMode) {
106
    fun start(wait: Boolean): NettyApplicationEngine
107
    fun stop(gracePeriodMillis: Long, timeoutMillis: Long)
108
}
109
```
110

111
[Engine Implementation](./engine-implementation.md)
112

113
### Request and Response Handling
114

115
Abstract base classes for HTTP request and response processing with Netty channel integration and coroutine support.
116

117
```kotlin { .api }
118
abstract class NettyApplicationCall(
119
    application: Application,
120
    public val context: ChannelHandlerContext,
121
    private val requestMessage: Any,
122
) : BaseApplicationCall(application)
123

124
abstract class NettyApplicationRequest(
125
    call: PipelineCall,
126
    override val coroutineContext: CoroutineContext,
127
    public val context: ChannelHandlerContext,
128
    private val requestBodyChannel: ByteReadChannel,
129
    protected val uri: String,
130
    internal val keepAlive: Boolean
131
) : BaseApplicationRequest(call), CoroutineScope
132

133
abstract class NettyApplicationResponse(
134
    call: NettyApplicationCall,
135
    protected val context: ChannelHandlerContext,
136
    protected val engineContext: CoroutineContext,
137
    protected val userContext: CoroutineContext
138
) : BaseApplicationResponse(call)
139
```
140

141
[Request and Response Handling](./request-response.md)
142

143
### Platform Optimization
144

145
Platform-optimized networking components that automatically select the best EventLoopGroup and Channel implementations for the current operating system.
146

147
```kotlin { .api }
148
class EventLoopGroupProxy(
149
    val channel: KClass<out ServerSocketChannel>,
150
    group: EventLoopGroup
151
) : EventLoopGroup by group {
152
    companion object {
153
        fun create(parallelism: Int): EventLoopGroupProxy
154
    }
155
}
156
```
157

158
[Platform Optimization](./platform-optimization.md)
159

160
### Coroutine Integration
161

162
Extension functions for seamless integration between Netty's Future-based asynchronous API and Kotlin coroutines.
163

164
```kotlin { .api }
165
suspend fun <T> Future<T>.suspendAwait(): T
166
suspend fun <T> Future<T>.suspendWriteAwait(): T
167
suspend fun <T> Future<T>.suspendAwait(
168
    exception: (Throwable, Continuation<T>) -> Unit
169
): T
170
```
171

172
[Coroutine Integration](./coroutine-integration.md)
173

174
## Types
175

176
```kotlin { .api }
177
class NettyApplicationEngine.Configuration : BaseApplicationEngine.Configuration() {
178
    // Inherited from BaseApplicationEngine.Configuration
179
    var connectionGroupSize: Int
180
    var workerGroupSize: Int
181
    var callGroupSize: Int
182
    
183
    // Netty-specific configuration
184
    var runningLimit: Int
185
    var shareWorkGroup: Boolean
186
    var configureBootstrap: ServerBootstrap.() -> Unit
187
    var responseWriteTimeoutSeconds: Int
188
    var requestReadTimeoutSeconds: Int
189
    var tcpKeepAlive: Boolean
190
    var maxInitialLineLength: Int
191
    var maxHeaderSize: Int
192
    var maxChunkSize: Int
193
    var enableHttp2: Boolean
194
    var httpServerCodec: () -> HttpServerCodec
195
    var channelPipelineConfig: ChannelPipeline.() -> Unit
196
}
197
```