Kora Di Compile

Kora DI Compile — Compile-Time Dependency Injection

Kora sub-skill — obey the kora-v2 meta rules on every task: R0 ground the workspace on Kora 2.0 refs before starting (framework source at tag 2.0.0.RC1 + kora-examples at migration/2.0; kora-docs is 1.x only) · R1 read this sub-skill before writing code · R2 Kora 2.0 APIs only — no Spring/Micronaut/Quarkus, no Kora 1.x APIs, no invented annotations or config keys · R3 journal any incorrect Kora usage. Add comments/Javadoc only if asked.

Kora wires the whole container at compile time. The annotation processor (Java) or symbol processor (Kotlin) reads your @KoraApp interface, resolves every dependency, and emits a plain Java/Kotlin class that constructs the graph. There is no reflection, no classpath scanning and no runtime proxying: an unresolvable dependency is a compile error, not a startup failure.

Read this skill when: bootstrapping @KoraApp, registering components with @Component / @Module / @FactoryModule, splitting a build with @KoraSubmodule, disambiguating with @Tag, gating components with @Conditional, or decoding a graph build failure.

Scope boundary. This skill covers everything the processor decides: declaration, discovery, resolution and the compile errors it emits. What the graph does once it is running — init()/release() ordering, refresh, GraphInterceptor — belongs to kora-di-runtime.

Quick Start

Task Progress:
- [ ] 1. Add the kora-bom platform + annotation-processors (Java) / symbol-processors (KSP)
- [ ] 2. Create the @KoraApp interface and its main() entry point
- [ ] 3. extends the external modules you need (HoconConfigModule, LogbackModule, …)
- [ ] 4. Register your own types with @Component / @Module factory methods
- [ ] 5. ./gradlew classes and read the generated <App>Graph

1. Build Setup

Java

configurations {
    koraBom
    annotationProcessor.extendsFrom(koraBom)
    implementation.extendsFrom(koraBom)
    testAnnotationProcessor.extendsFrom(koraBom)
}

dependencies {
    koraBom platform("io.koraframework:kora-bom:$koraVersion")   // koraVersion=2.0.0.RC1
    annotationProcessor "io.koraframework:annotation-processors"
    testAnnotationProcessor "io.koraframework:annotation-processors"
}

java { toolchain { languageVersion = JavaLanguageVersion.of(25) } }
application { mainClass = "com.example.Application" }

Kotlin

plugins {
    kotlin("jvm") version "2.4.10"
    id("com.google.devtools.ksp") version "2.3.11"
}

dependencies {
    implementation(platform("io.koraframework:kora-bom:$koraVersion"))
    ksp("io.koraframework:symbol-processors:$koraVersion")        // explicit version required
    kspTest("io.koraframework:symbol-processors:$koraVersion")
}

kotlin {
    jvmToolchain(25)
    sourceSets.main { kotlin.srcDir("build/generated/ksp/main/kotlin") }
    sourceSets.test { kotlin.srcDir("build/generated/ksp/test/kotlin") }
}

application { mainClass.set("com.example.ApplicationKt") }   // not "…Application"

ksp is not covered by the BOM platform, so symbol-processors needs its own version. Every Gradle module declaring @KoraApp, @KoraSubmodule, @Module or @Component needs the processor on its own compile classpath — otherwise nothing is generated and the only symptom is cannot find symbol: ApplicationGraph.

Full templates: build.gradle.template, build.gradle.kts.template.

2. Application Bootstrap

package com.example;

import io.koraframework.application.graph.KoraApplication;
import io.koraframework.common.annotation.KoraApp;
import io.koraframework.config.hocon.HoconConfigModule;
import io.koraframework.logging.logback.LogbackModule;

@KoraApp
public interface Application extends HoconConfigModule, LogbackModule {

    static void main(String[] args) {
        KoraApplication.run(ApplicationGraph::graph);
    }
}

// same imports; a top-level main() compiles into com.example.ApplicationKt
@KoraApp
interface Application : HoconConfigModule, LogbackModule

fun main() {
    KoraApplication.run(ApplicationGraph::graph)
}

ApplicationGraph is generated into your own package — never import it from io.koraframework.*. The class name is always <KoraAppSimpleName>Graph.

Key rules: @KoraApp only on an interface · one graph per runnable application · external modules need extends · local @Module interfaces are discovered automatically.

→ @KoraApp Reference

3. Component Registration

@Component — constructor injection

@Component
public final class UserService {
    private final UserRepository repository;

    public UserService(UserRepository repository) {   // exactly one public constructor
        this.repository = repository;
    }
}

@Module — factory methods

@Module
public interface StorageModule {

    default Storage storage(StorageConfig config) {
        return new TempFileStorage(config);
    }
}

@Module and @KoraApp accept interfaces only; providers are default methods (Kotlin: bodied interface functions). A provider must return a reference type and must not return null unless the consumer's parameter is @Nullable.

→ Component Registration Reference · Component Factories Reference

4. Module Discovery — when extends is required

The processor auto-collects every @Module interface it compiles in this Gradle module. Anything already on the classpath as bytecode was never seen by the processor and must be pulled in explicitly.

→ Module Auto-Discovery Reference

5. Multi-Module Projects

// pet-api/  — the domain subproject
@KoraSubmodule
public interface PetModule extends CommonModule, JdbcDatabaseModule { }

// app/      — the assembly subproject
@KoraApp
public interface Application extends PetModule, HoconConfigModule, LogbackModule {
    static void main(String[] args) { KoraApplication.run(ApplicationGraph::graph); }
}

@KoraSubmodule makes the processor emit <Name>SubmoduleImpl next to the interface, carrying every @Component and @Module provider compiled in that subproject. The processor must run in the subproject too, or the @KoraApp build fails with "Kora submodule was not generated yet".

→ @KoraSubmodule Reference

6. Disambiguation with @Tag

A tag is any class used as a marker. Matching is exact, with one wildcard:

public final class RedisTag { private RedisTag() {} }

@Tag(RedisTag.class) @Component
public final class RedisCache implements Cache { }

public UserService(@Tag(RedisTag.class) Cache cache) { }

→ Tags & Collections Reference

7. Collection, Lazy and Optional Dependencies

@Component
public final class NotificationService {
    public NotificationService(@Tag(Tag.Any.class) All<Notifier> notifiers,
                               ValueOf<AuditLog> audit,
                               @Nullable SmsProvider sms) { }
}

Java nullability is JSpecify (org.jspecify.annotations.Nullable, type-use). Kotlin expresses it as T? — never carry JSpecify annotations into Kotlin.

8. Graph Roots

Nothing is instantiated unless it is a @Root or a transitive dependency of one. A component whose only job is a side effect at startup will be pruned without @Root.

import io.koraframework.common.annotation.Root;

@Root @Component
public final class CacheWarmer implements Lifecycle {
    public void init() { /* runs at startup */ }
    public void release() { }
}

@Root also applies to a @Module provider method. @Root lives in io.koraframework.common.annotation — the same package as everything else in 2.0.

→ Graph Roots & Lifecycle Reference · runtime init/release semantics: kora-di-runtime

9. Conditional Components (new in 2.0)

@Conditional(tag = X.class) gates a component on a GraphCondition published under @Tag(X.class). Candidates are all compiled; exactly one must match when the graph initialises.

@Component
@Conditional(tag = RedisEnabled.class)
public final class RedisCache implements Cache { }

→ Conditional Components Reference

10. Graph Build Failures

The 2.0 processor prints a diagnosis, a resolution path and a Fix: list. Match on the first line:

A No component found error also lists same-type-different-tag candidates under Note: — read that section first; a forgotten or mismatched @Tag is the usual cause.

11. Debugging

# Java — generated graph
ls build/generated/sources/annotationProcessor/java/main/

# Kotlin — generated graph
ls build/generated/ksp/main/kotlin/

Raise processor verbosity (Java annotation processor only) by adding the koraLogLevel compiler argument; the processor also writes a full log under build/kora/log/:

compileJava { options.compilerArgs += ["-AkoraLogLevel=DEBUG"] }

After renaming a package or migrating from 1.x, stale generated sources produce phantom errors that point at classes you have already deleted. Rebuild the generated tree — never hand-edit it:

./gradlew clean classes --no-build-cache

12. Removed in Kora 2.0

• Context does not exist anywhere in the framework. A component or provider that takes a Kora Context parameter will not compile.
• Component contracts are synchronous, executed on virtual threads. CompletionStage, Reactor Mono/Flux and Kotlin suspend are no longer Kora contracts.
• ru.tinkoff.kora.* is gone; DI annotations moved from ru.tinkoff.kora.common to io.koraframework.common.annotation. @Root was already in …common.annotation under 1.x — it only changed group.
• ru.tinkoff.kora:kora-parent is replaced by io.koraframework:kora-bom.

References

Assets

Templates in assets/: Application.java.template, Application.kt.template, Component.java.template, Module.java.template, KoraSubmodule.java.template, build.gradle.template, build.gradle.kts.template, settings.gradle.template, gradle.properties.template, gradle-wrapper.properties.template, application.conf.template, application.yaml.template, plus QUICK_REFERENCE.md.

python3 scripts/generate_project.py --name my-app --package com.example --dry-run
python3 scripts/generate_project.py --name my-app --package com.example --lang kotlin
python3 scripts/validate_gradle.py --file build.gradle