Accelerates server-side development with type-safe REST, database and message-queue abstractions, built-in structured logging/OpenTelemetry tracing, dependency injection, config/context propagation, and functional Either-based error handling.
A comprehensive Kotlin multiplatform toolkit for building server applications with Ktor.
🏠 Homepage (under construction)
implementation("io.github.smyrgeorge:ktkit:x.y.z")
KtKit is a Kotlin multiplatform toolkit designed to speed up server-side application development with Ktor. It brings together several libraries into a cohesive set of tools that handle the repetitive aspects of backend development.
[!NOTE] Early Stage Project: KtKit is actively evolving. APIs may change between versions as we refine the abstractions based on real-world usage. Production use is possible but expect some breaking changes. Feedback and contributions are highly appreciated!
What it does (today):
Planned features:
ktkit)Application wrapper for Ktor server startup/shutdown, JSON setup, Koin DI, and routingAbstractRestHandler with typed request helpers, propagation, and error mapping[!WARNING] The
XRealNamePrincipalExtractorandXRealNameRestClientuse a base64-encoded JSON header (x-real-name) to identify the authenticated user. This mechanism is not safe to expose directly to the internet.
This pattern assumes a trusted reverse proxy or API gateway sits in front of your application and:
x-real-name header from client requestsx-real-name header with the authenticated user's information before forwardingIf your application is exposed directly to the internet without such a proxy, any client can forge the header and impersonate any user. Only use this extractor when your application runs behind a trusted infrastructure layer that controls this header.
ConfigPropertiesToml loads and deserializes TOML files into @Serializable data classes. It supports environment
variable interpolation (${VAR_NAME}), loading from resources or the filesystem, and merging a base config with an
override file (override values take precedence).
The load() method reads application.toml from resources as the base, then looks for an override in this order:
application.toml, config/application.toml, application.local.toml, config/application.local.toml.
// Define your config as a @Serializable data class
@Serializable
data class AppConfig(val server: ServerConfig, val database: DatabaseConfig)
@Serializable
data ( host: String, port: )
( url: String, maxConnections: )
# src/commonMain/resources/application.toml (base config)
[server]
host = "localhost"
port = 8080
[database]
url = "postgresql://${DB_HOST}/mydb"
maxConnections = 10
# config/application.local.toml (local override)
[database]
maxConnections = 50
// Auto-load with layered overrides
val config: AppConfig = ConfigPropertiesToml.load()
// Or load from a specific file
val config: AppConfig = ConfigPropertiesToml.loadFromFileSystem("path/to/config.toml")
// Or merge two files explicitly
val config: AppConfig = ConfigPropertiesToml.loadFromFileSystem(
base = "base.toml",
override = "override.toml"
)
ktkit-ktor-httpclient)A multiplatform REST client abstraction built on Ktor's HttpClient with functional error handling via Arrow's Raise.
HttpClientFactory for creating pre-configured HttpClient instances with timeouts, connection pooling, and JSON setupAbstractRestClient base class with typed HTTP methods (GET, POST, PUT, PATCH, DELETE, etc.)BearerRestClient (Bearer token auth) and XRealNameRestClient (X-Real-Name header auth)RestClientErrorSpec hierarchyktkit-sqlx4k)A coroutine-first SQL toolkit with compile-time query validations for Kotlin Multiplatform. PostgreSQL, MySQL/MariaDB, and SQLite supported.
DatabaseService helpers for error mapping and traced transactionsAuditableRepository hooks for createdAt/createdBy/updatedAt/updatedByAuditableDatabaseService interface for services with auditable entities and a save() extensionktkit-sqlx4k-pgmq)A lightweight message queue. Like AWS SQS and RSMQ but on Postgres.
Pgmq wrapper and AbstractPgmqEventHandler with trace/user propagationThe example module shows how Arrow's Raise and Kotlin context parameters keep service code compact while
preserving explicitness around errors and execution context:
class TestService(
override db: Driver,
repo: TestRepository,
) : AuditableDatabaseService<Test> {
log = Logger.of(::)
context(_: ExecContext, _: QueryExecutor)
: List<Test> = db { repo.findAll() }
context(_: ExecContext, _: Transaction)
: List<Test> {
log.info { }
findAll().also {
log.info { }
}
}
}
The execution context is a coroutine context element that also implements Arrow's Raise and log4k's tracing context:
class ExecContext(
val reqId: String,
val reqTs: Instant,
val principal: Principal,
// Only a part of the context is presented here.
// Check the documentation for more information.
) : Raise<ErrorSpec>, TracingContext by tracing, CoroutineContext.Element
This lets handlers and services raise domain errors, access tracing, and carry request metadata without threading
parameters manually. The context is propagated in two ways at once: via CoroutineContext and via context
parameters in function signatures.
Check the example application here.
./gradlew build
The project includes a docker-compose.yml for PostgreSQL:
docker-compose up -d
This is an open-source project. Contributions are welcome!
Check the repository for license information.
Yorgos S. (@smyrgeorge)
ExecContext/api/status/health and /api/status/metrics endpointsErrorSpec/ApiError) aligned with RFC 9457 conventionsJsonSupport utility for JSON column serialization with sqlx4k's ValueEncoder systemSurfaced from shared tags and platforms — no rankings paid for.