or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

coroutine-integration.mdengine-implementation.mdindex.mdplatform-optimization.mdrequest-response.mdserver-configuration.mdstandalone-server.md
tile.json

tessl/maven-io-ktor--ktor-server-netty-jvm

Netty-based HTTP server engine for Ktor framework providing high-performance asynchronous server capabilities

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.ktor/ktor-server-netty@3.2.x

To install, run

npx @tessl/cli install tessl/maven-io-ktor--ktor-server-netty-jvm@3.2.0

index.mddocs/

Ktor Server Netty

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.

Package Information

  • Package Name: io.ktor:ktor-server-netty
  • Package Type: maven
  • Language: Kotlin
  • Installation: implementation("io.ktor:ktor-server-netty:3.2.0") (Gradle)

Core Imports

import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.engine.*
import io.ktor.events.*                      // For Events parameter
import io.netty.bootstrap.ServerBootstrap    // For bootstrap configuration
import io.netty.channel.ChannelPipeline      // For pipeline configuration

Basic Usage

import io.ktor.server.application.*
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.response.*
import io.ktor.server.routing.*

fun main() {
    // Create and start embedded server
    embeddedServer(Netty, port = 8080) {
        routing {
            get("/") {
                call.respondText("Hello from Ktor Netty!")
            }
        }
    }.start(wait = true)
}

Architecture

Ktor Server Netty is built around several key components:

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

Capabilities

Server Creation and Configuration

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

object Netty : ApplicationEngineFactory<NettyApplicationEngine, NettyApplicationEngine.Configuration> {
    fun configuration(
        configure: NettyApplicationEngine.Configuration.() -> Unit
    ): NettyApplicationEngine.Configuration
    
    fun create(
        environment: ApplicationEnvironment,
        monitor: Events,
        developmentMode: Boolean,
        configuration: NettyApplicationEngine.Configuration,
        applicationProvider: () -> Application
    ): NettyApplicationEngine
}

Server Creation and Configuration

Standalone Server Execution

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

object EngineMain {
    @JvmStatic
    fun main(args: Array<String>)
    
    fun createServer(
        args: Array<String>
    ): EmbeddedServer<NettyApplicationEngine, NettyApplicationEngine.Configuration>
}

Standalone Server Execution

Engine Implementation

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

class NettyApplicationEngine(
    environment: ApplicationEnvironment,
    monitor: Events,
    developmentMode: Boolean,
    val configuration: Configuration,
    applicationProvider: () -> Application
) : BaseApplicationEngine(environment, monitor, developmentMode) {
    fun start(wait: Boolean): NettyApplicationEngine
    fun stop(gracePeriodMillis: Long, timeoutMillis: Long)
}

Engine Implementation

Request and Response Handling

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

abstract class NettyApplicationCall(
    application: Application,
    public val context: ChannelHandlerContext,
    private val requestMessage: Any,
) : BaseApplicationCall(application)

abstract class NettyApplicationRequest(
    call: PipelineCall,
    override val coroutineContext: CoroutineContext,
    public val context: ChannelHandlerContext,
    private val requestBodyChannel: ByteReadChannel,
    protected val uri: String,
    internal val keepAlive: Boolean
) : BaseApplicationRequest(call), CoroutineScope

abstract class NettyApplicationResponse(
    call: NettyApplicationCall,
    protected val context: ChannelHandlerContext,
    protected val engineContext: CoroutineContext,
    protected val userContext: CoroutineContext
) : BaseApplicationResponse(call)

Request and Response Handling

Platform Optimization

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

class EventLoopGroupProxy(
    val channel: KClass<out ServerSocketChannel>,
    group: EventLoopGroup
) : EventLoopGroup by group {
    companion object {
        fun create(parallelism: Int): EventLoopGroupProxy
    }
}

Platform Optimization

Coroutine Integration

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

suspend fun <T> Future<T>.suspendAwait(): T
suspend fun <T> Future<T>.suspendWriteAwait(): T
suspend fun <T> Future<T>.suspendAwait(
    exception: (Throwable, Continuation<T>) -> Unit
): T

Coroutine Integration

Types

class NettyApplicationEngine.Configuration : BaseApplicationEngine.Configuration() {
    // Inherited from BaseApplicationEngine.Configuration
    var connectionGroupSize: Int
    var workerGroupSize: Int
    var callGroupSize: Int
    
    // Netty-specific configuration
    var runningLimit: Int
    var shareWorkGroup: Boolean
    var configureBootstrap: ServerBootstrap.() -> Unit
    var responseWriteTimeoutSeconds: Int
    var requestReadTimeoutSeconds: Int
    var tcpKeepAlive: Boolean
    var maxInitialLineLength: Int
    var maxHeaderSize: Int
    var maxChunkSize: Int
    var enableHttp2: Boolean
    var httpServerCodec: () -> HttpServerCodec
    var channelPipelineConfig: ChannelPipeline.() -> Unit
}