Skip to main content
Version: v0.25.0 (Latest)

Ktor Integration Plugin

The KotlinInjectPlugin bridges IDK's Metro DI system with Ktor's request pipeline. It is not an application-level service in its own right, but the foundation that all other IDK HTTP services run on. Every IDK HTTP service depends on this plugin being installed.

What It Does​

On every incoming request, the plugin runs a UserContextInterceptor before your route handlers:

  1. Resolves the tenant from the request via TenantResolver (default: reads the X-Tenant-ID header, falls back to "default")
  2. Resolves the principal from the request via PrincipalResolver (default: checks X-User-ID header, then Ktor auth plugin, falls back to "anonymous")
  3. Creates or retrieves the UserContextInstance for that tenant+principal pair
  4. Creates a SessionInstance scoped to this specific request
  5. Makes all session-scoped services available to route handlers through call.getSessionService<T>(), call.getUserService<T>(), and call.getAppService<T>()

All of this happens automatically. By the time your handler runs, the DI scopes are set up and every service is ready to use.

Auto-Discovery of Adapters​

When you call installUniversalHttpAdapters(), the plugin discovers all CommandBackedHttpAdapter instances contributed to the DI graph and mounts them as routes. This is how services register their endpoints without manual route wiring. Each adapter declares a mount point and a list of endpoint commands; the dispatcher indexes them and routes incoming requests by path and HTTP method.

Including in Your Server​

build.gradle.kts
dependencies {
    implementation("com.sphereon.idk:ktor-server-kotlin-inject:0.25.0")
}

Configuration​

install(KotlinInjectPlugin) {
    appGraph = myAppGraph
    tenantResolver = JwtTenantResolver()       // optional: custom tenant extraction
    principalResolver = JwtPrincipalResolver() // optional: custom principal extraction
}
OptionDefaultDescription
appGraph(required)Your root IDK AppGraph
tenantHeader"X-Tenant-ID"HTTP header for tenant ID extraction (used by default resolver)
principalHeader"X-User-ID"HTTP header for principal ID extraction (used by default resolver)
tenantResolverDefaultTenantResolverCustom strategy for resolving the tenant from a request
principalResolverDefaultPrincipalResolverCustom strategy for resolving the principal from a request

The plugin also integrates with the YAML configuration system on JVM. It registers property sources that load application.yml from the working directory, config directory, or classpath. These participate in the IDK configuration system at all three scope levels (app, tenant, principal).

See Ktor Integration for full configuration details, including custom resolvers, YAML scope layering, and route-level adapter mounting.

Next Steps​