Neton

High-performance Kotlin/Native Web Framework

Native-first, zero reflection, compile-time code generation, structured logging, engineering-grade DSL

中文文档

Neton is a production-ready, engineering-focused web framework that differs from traditional JVM frameworks (Spring Boot, Ktor):

• Native-first: Compiles to native executables with fast startup and low resource usage
• Zero reflection: All routes/tables/fields are generated at compile time via KSP
• Unified configuration: TOML-based config with priority: CLI/ENV > environment conf > defaults
• Structured logging: Built-in multi-sink, async writing, WARN/ERROR guaranteed delivery
• Security: JWT authentication with composable Guard/Authenticator
• Clear database semantics: Entity (data class) + Table (single-table CRUD) + Logic (business aggregation)
• Contract tests: Core behaviors locked down via contract tests

neton-database has no macosX64 target because its driver, sqlx4k, publishes no macosX64 artifact. Every other module builds on Intel Macs; database work needs Apple Silicon, Linux or Windows.

implementation("com.netonstream:neton:1.0.0-beta1")

neton brings in neton-core, neton-logging, neton-http and neton-routing — enough for a running service — and pins every other module to the same release, so optional modules are added without a version:

implementation("com.netonstream:neton-database")
implementation("com.netonstream:neton-redis")

Projects that only want the version constraints can use implementation(platform("com.netonstream:neton-bom:1.0.0-beta1")).

Neton.run(args) {

    http {
        port = 8080
    }

    routing {
        get("/") {
            "Hello Neton!"
        }
    }
}

• Works without reflection or KSP
• Coexists with auto-generated routes
• Supports middleware and Guards

Neton uses a TOML-based configuration system.
All modules (http/logging/database/redis/routing) are loaded through a unified ConfigLoader.

# application.conf

[application]
name = "Neton App"
debug = true

[server]
port = 8080
host = "0.0.0.0"

[logging]
level = "INFO"

[[logging.sinks]]
name = "all"
file = "logs/all.log"
levels = "ALL"

neton-http uses Ktor by default and does not know about Hyper. Applications that need Hyper add the external neton-http-hyper4k adapter and pass its constructor to the HTTP component:

Neton.run(args) {
    http(::Hyper4kHttpAdapter) { port = 8080 }
}

The default http { } overload selects Ktor. Adapter selection is compile-time application code, not an application.conf setting or a runtime registry.

Built-in structured logging:

• Multi-sink support
• Async writing (debug/info may drop, warn/error guaranteed)
• Auto-injected traceId/spanId

Output example (JSON):

{
  "ts": "2026-02-13T10:21:33.123Z",
  "level": "INFO",
  "service": "neton-app",
  "traceId": "abc123",
  "msg": "http.request",
  "method": "GET",
  "path": "/",
  "status": 200,
  "latencyMs": 5
}

Neton provides a built-in JWT authentication/authorization system:

@Get("/profile")
fun profile(@CurrentUser user: User): User {
    return user
}

• Built-in Guard/Authenticator mechanism
• Stable JWT primary path
• Composable security DSL

SessionAuth / BasicAuth are experimental in v1

Table (Single-table CRUD)

KSP auto-generates single-table operations:

UserTable.get(id)
UserTable.query { where { ColumnRef("status") eq id } }.list()
UserTable.destroy(id)

Logic (Business aggregation)

class UserLogic(private val db: DbContext = dbContext()) : DbContext by db {
    suspend fun getWithRoles(id: Long): UserWithRoles? { ... }
}

Principles:

• Controller → Logic → Table → Model (frozen layering)
• Table = single-table CRUD (KSP generated)
• Logic = business aggregation (multi-table joins / transactions / domain)

Organize routes by group:

routing {
    group("admin") {
        get("/dashboard") { ... }
    }
}

The framework mounts paths under the group prefix and automatically applies the corresponding Guard/Authenticator.

Core behaviors are locked down via contract tests:

# macOS ARM64
./gradlew :examples:helloworld:linkDebugExecutableMacosArm64
cd examples/helloworld && ./build/bin/macosArm64/debugExecutable/helloworld.kexe

# Linux x64
./gradlew :examples:helloworld:linkDebugExecutableLinuxX64

# Linux ARM64
./gradlew :examples:helloworld:linkDebugExecutableLinuxArm64

# Windows x64
./gradlew :examples:helloworld:linkDebugExecutableMingwX64

Linux executables can be built on macOS when a Linux GCC cross toolchain is available. The default executable names are provided by Homebrew's macos-cross-toolchains packages:

brew tap messense/macos-cross-toolchains
brew install x86_64-unknown-linux-gnu aarch64-unknown-linux-gnu

Custom toolchain paths can be supplied through NETON_LINUX_X64_CC, NETON_LINUX_X64_AR, NETON_LINUX_ARM64_CC, and NETON_LINUX_ARM64_AR, or the corresponding Gradle properties neton.linuxX64.cc, neton.linuxX64.ar, neton.linuxArm64.cc, and neton.linuxArm64.ar.

Cross-compilation verifies linking only. Run the produced executable and runtime smoke tests on the target Linux architecture before release.

Windows builds use the MinGW GCC toolchain distributed with Kotlin/Native for the small native lifecycle bridge. Custom tools can be selected with NETON_MINGW_X64_CC and NETON_MINGW_X64_AR, or the corresponding Gradle properties neton.mingwX64.cc and neton.mingwX64.ar.

Visit: http://localhost:8080/

Response:

Hello Neton!

• Startup time: Measured from process start to HTTP port listening
• Varies by build mode (Debug/Release), hardware, and I/O conditions

Apache 2.0 License

Issues and PRs are welcome.
Check the examples/ directory to get started.

Neton is built on top of these excellent open-source projects:

Thanks to all the authors and contributors of these projects!