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

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

—

Pending

Overview

Eval results

Files

Platform Optimization

Name: tessl/maven-io-ktor--ktor-server-netty-jvm
Author: tessl

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

Capabilities

EventLoopGroupProxy

Wrapper class that transparently selects optimal EventLoopGroup implementations based on the current platform, maximizing network performance.

/**
 * Transparently allows for the creation of EventLoopGroups utilizing the optimal implementation for
 * a given operating system, subject to availability, or falling back to NioEventLoopGroup if none is available
 */
class EventLoopGroupProxy(
    val channel: KClass<out ServerSocketChannel>,
    group: EventLoopGroup
) : EventLoopGroup by group {
    
    /**
     * Server socket channel class used by this event loop group
     */
    val channel: KClass<out ServerSocketChannel>
    
    companion object {
        /**
         * Create optimal EventLoopGroup for the current platform
         * @param parallelism Number of threads in the event loop group
         * @return EventLoopGroupProxy with optimal implementation for current OS
         */
        fun create(parallelism: Int): EventLoopGroupProxy
    }
}

Platform Selection Logic:

The EventLoopGroupProxy automatically selects the best implementation based on availability:

macOS: KQueueEventLoopGroup with KQueueServerSocketChannel (native kqueue)
Linux: EpollEventLoopGroup with EpollServerSocketChannel (native epoll)
Fallback: NioEventLoopGroup with NioServerSocketChannel (cross-platform NIO)

Usage Examples:

import io.ktor.server.netty.*

// Automatic platform optimization
val eventLoopGroup = EventLoopGroupProxy.create(parallelism = 8)

// The proxy automatically selects:
// - macOS: KQueueEventLoopGroup + KQueueServerSocketChannel
// - Linux: EpollEventLoopGroup + EpollServerSocketChannel  
// - Others: NioEventLoopGroup + NioServerSocketChannel

println("Selected channel type: ${eventLoopGroup.channel}")

// Use in server configuration
val configuration = NettyApplicationEngine.Configuration().apply {
    configureBootstrap = {
        // The engine will automatically use the optimal channel class
        // No manual configuration needed
    }
}

Platform Channel Selection

Utility function that determines the optimal ServerSocketChannel implementation for the current platform.

/**
 * Get optimal ServerSocketChannel class for the current platform
 * @return KClass of the most suitable ServerSocketChannel implementation
 */
internal fun getChannelClass(): KClass<out ServerSocketChannel>

Platform Mapping:

macOS: KQueueServerSocketChannel::class (native kqueue I/O)
Linux: EpollServerSocketChannel::class (native epoll I/O)
Windows/Other: NioServerSocketChannel::class (standard NIO)

Performance Characteristics

Each platform-optimized implementation provides different performance characteristics:

KQueue (macOS):

Native kqueue-based I/O
Optimal for macOS systems
Low CPU overhead for connection management
Excellent scalability for concurrent connections

Epoll (Linux):

Native epoll-based I/O
Optimal for Linux systems
Superior performance for high-throughput scenarios
Efficient handling of large numbers of file descriptors

NIO (Cross-platform):

Java NIO-based implementation
Works on all platforms
Reasonable performance for most use cases
Fallback when native implementations unavailable

Automatic Detection and Fallback

The system automatically detects platform capabilities and falls back gracefully:

// Detection logic (internal)
val eventLoopGroup = when {
    KQueue.isAvailable() -> {
        println("Using native KQueue transport (macOS)")
        EventLoopGroupProxy(
            KQueueServerSocketChannel::class,
            KQueueEventLoopGroup(parallelism, threadFactory)
        )
    }
    
    Epoll.isAvailable() -> {
        println("Using native Epoll transport (Linux)")
        EventLoopGroupProxy(
            EpollServerSocketChannel::class,
            EpollEventLoopGroup(parallelism, threadFactory)
        )
    }
    
    else -> {
        println("Using NIO transport (cross-platform)")
        EventLoopGroupProxy(
            NioServerSocketChannel::class,
            NioEventLoopGroup(parallelism, threadFactory)
        )
    }
}

Thread Pool Configuration

The EventLoopGroupProxy creates event loop groups with proper thread naming and daemon thread configuration:

// Example of internal thread factory usage
val threadFactory = DefaultThreadFactory(EventLoopGroupProxy::class.java, true)

// Thread naming pattern: "EventLoopGroupProxy-<number>"
// Daemon threads: true (won't prevent JVM shutdown)

Resource Management

EventLoopGroupProxy properly implements the EventLoopGroup interface with delegation, ensuring proper resource cleanup:

// Proper shutdown in server lifecycle
try {
    // Server operations
} finally {
    // Graceful shutdown with timeout
    eventLoopGroup.shutdownGracefully(
        quietPeriod = 1000,     // 1 second quiet period
        timeout = 5000,         // 5 second timeout
        unit = TimeUnit.MILLISECONDS
    ).await()
}

Integration with Netty Configuration

The platform optimization integrates seamlessly with custom Netty bootstrap configuration:

val configuration = NettyApplicationEngine.Configuration().apply {
    configureBootstrap = {
        // Platform-optimized channel class is automatically selected
        // Additional options can be configured as needed
        
        option(ChannelOption.SO_BACKLOG, 1024)
        option(ChannelOption.SO_REUSEADDR, true)
        
        childOption(ChannelOption.TCP_NODELAY, true)
        childOption(ChannelOption.SO_KEEPALIVE, true)
        
        // Platform-specific optimizations
        when {
            Epoll.isAvailable() -> {
                childOption(EpollChannelOption.TCP_KEEPCNT, 5)
                childOption(EpollChannelOption.TCP_KEEPIDLE, 300)
                childOption(EpollChannelOption.TCP_KEEPINTVL, 60)
            }
        }
    }
}

Performance Monitoring

Access to platform-specific performance metrics and monitoring:

// Check which transport is being used
fun getTransportInfo(eventLoopGroup: EventLoopGroupProxy): String {
    return when (eventLoopGroup.channel) {
        KQueueServerSocketChannel::class -> "KQueue (native macOS)"
        EpollServerSocketChannel::class -> "Epoll (native Linux)"
        NioServerSocketChannel::class -> "NIO (cross-platform)"
        else -> "Unknown transport"
    }
}

// Usage in monitoring/health checks
get("/transport-info") {
    val transportInfo = getTransportInfo(eventLoopGroup)
    call.respondText("Transport: $transportInfo")
}

Install with Tessl CLI

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

docs

coroutine-integration.md

engine-implementation.md

index.md

platform-optimization.md

request-response.md

server-configuration.md

standalone-server.md

tile.json

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