Ktor server

Ktor has no dependency injection of its own, but both the application and every call carry typed attributes, which can hold any value. A module is just a value, so it is stored in the attributes of the scope it belongs to: the application for a module that lives as long as the server, and the call for a module that lives for one request.

This guide assumes a Ktor server in which Inara is set up as described in Setup.

The application module

Declare the module that holds everything that lives as long as the server:

@DIModule
interface AppModule {
    fun database(): Database
    fun userRepository(): UserRepository
}

Build it once, when the application starts, and keep it in the application’s attributes:

val AppModuleKey = AttributeKey<AppModule>("AppModule") (1)

val Application.appModule: AppModule get() = attributes[AppModuleKey] (2)

fun Application.module() {
    val appModule = AppModule(
        database = Binding.single { Database.open() },
        userRepository = Binding.single { UserRepository(database()) },
    )
    attributes.put(AppModuleKey, appModule) (3)

    routing {
        // ...
    }
}
1 The key is the only thing that ties the module to Ktor.
2 An extension property keeps the call sites short.
3 The module is built in module(), so it follows the application’s lifecycle, including the reload of a development server, which builds a fresh module with fresh single instances.

A resource that must be closed when the server stops is closed in the application’s ApplicationStopped event:

monitor.subscribe(ApplicationStopped) {
    appModule.database().close()
}

Building controllers

Keep the handlers' logic in plain classes, which know nothing about Ktor or Inara, and build them with @DIFactory:

class UsersController(
    private val userRepository: UserRepository, (1)
) {
    suspend fun list(): List<User> = userRepository.all()
    suspend fun find(id: UserId): User? = userRepository.find(id)
}

@DIFactory(builds = UsersController::class, from = AppModule::class)
object UsersControllerFactory
1 A regular constructor parameter, resolved by its type from AppModule.

The routes build the controller once, where they are declared, and delegate to it:

fun Application.module() {
    // ...

    routing {
        val users = UsersControllerFactory.UsersController(appModule) (1)

        get("/users") {
            call.respond(users.list())
        }
        get("/users/{id}") {
            val user = users.find(UserId(call.parameters["id"]!!))
                ?: return@get call.respond(HttpStatusCode.NotFound)
            call.respond(user)
        }
    }
}
1 Built when the routing is declared, not on every call: its dependencies are single instances anyway.

Since the controller does not depend on Inara, a test builds it with a fake repository, without any module or server.

Scoping a module to a call

A module can also live exactly as long as a call. This is the scope pattern, where the scope is one request.

Declare a module that composes the application module:

@DIModule(composed = true)
interface RequestModule : AppModule {
    val requestId: String
    fun auditLog(): AuditLog
}

val RequestModuleKey = AttributeKey<RequestModule>("RequestModule")

val ApplicationCall.requestModule: RequestModule get() = attributes[RequestModuleKey]

Then write a plugin that builds the module for every call, and stores it in the call’s attributes:

val RequestModulePlugin = createApplicationPlugin("RequestModule") {
    val appModule = application.appModule (1)

    onCall { call ->
        val requestId = call.request.headers["X-Request-Id"] ?: "unknown"

        call.attributes.put(
            RequestModuleKey,
            RequestModule(
                appModule = appModule, (2)
                requestId = Binding.value(requestId),
                auditLog = Binding.single { AuditLog(requestId, database()) }, (3)
            )
        )
    }
}

fun Application.module() {
    // ... the application module, as above

    install(RequestModulePlugin) (4)
}
1 The application module is read once, when the plugin is installed.
2 The request module reuses the application module: database() is the very same instance in every call.
3 One audit log per call, which reads a member of the application module.
4 Installed after the application module is stored, since the plugin reads it at installation.

The handlers read the module from the call:

get("/orders") {
    val auditLog = call.requestModule.auditLog()
    auditLog.record("orders listed")
    // ...
}

When the call ends, its attributes are dropped, and so is the request module: its own single instances are garbage collected with it, while the application module keeps its own.

A @DIFactory can build a class from the request module, for a class that needs members of both scopes. Build it in the handler, since it needs the call’s module:

class OrdersController(
    private val userRepository: UserRepository, (1)
    private val auditLog: AuditLog, (2)
) {
    // ...
}

@DIFactory(builds = OrdersController::class, from = RequestModule::class)
object OrdersControllerFactory

get("/orders") {
    val orders = OrdersControllerFactory.OrdersController(call.requestModule)
    // ...
}
1 Comes from the application module, through the request module.
2 Comes from the request module: it is a new one for every call.
A test can store a test module in the application’s attributes, before it installs the plugins. See Testing.