Kora Framework

Kora is a modular framework that provides high-performance implementations for various service tasks. You should only include the modules required for your specific service to keep it lightweight.

Key modules include:

• HTTP: Includes an HTTP server, a declarative HTTP client, request mapping, interceptors, and service endpoints. Supports strictly typed code generation from OpenAPI and a SOAP client.
• Data: SQL-first repositories with compile-time @Query validation. Supports JDBC, R2DBC, Vert.x, and Cassandra. Includes column macros, generated converters, batch queries, and migrations.
• Messaging & RPC: Kafka consumers/producers, gRPC server and client, and an S3 client.
• Aspects: Compile-time generation for resilience (@Retry, @Timeout, @CircuitBreaker, @Fallback), caching (Caffeine / Redis), validation, and scheduling (no runtime proxies).
• Core: Compile-time dependency injection, typed configuration (HOCON / YAML), reflection-free JSON, and concurrency using virtual threads.
• Observability: Built-in support for metrics, tracing, structured logging, and probes following the OpenTelemetry standard.

Kora is a cloud-oriented server-side framework for Java and Kotlin designed for simplicity, transparency, and high performance. Unlike traditional frameworks that rely on runtime reflection, dynamic proxies, or classpath scanning, Kora uses annotation processing (Java) or KSP (Kotlin) to generate plain, readable Java/Kotlin code during the compilation phase.

Key characteristics include:

• Compile-time safety: Dependency graphs, HTTP routing, and repository implementations are validated during compilation. Errors like missing dependencies or invalid SQL placeholders result in compiler errors rather than runtime exceptions.
• High Performance: Since code is generated upfront, there is no Reflection API overhead at runtime, leading to TechEmpower-level performance.
• Fast Startup: The dependency container is built at compile-time, allowing services to start in seconds, which is ideal for horizontal scaling and rolling deployments.
• Transparency: The generated code is human-readable and can be inspected or debugged using standard tools.

The updater supports inline versions in the catalog, formatted as:

logback-classic = { module = "ch.qos.logback:logback-classic", version = "1.5.18" }

Important Considerations:

• Reporting: Inline dependencies are reported as inline:<lineNumber> because they lack a stable version key.
• Policy: While you can apply policies to inline versions using quoted keys (e.g., "inline:42" = "patch"), this is fragile because line numbers change when the file is edited.
• Best Practice: If an inline dependency requires a permanent version policy, move its version into the [versions] section and use a version.ref in the [libraries] section.

# Recommended way to handle dependencies requiring policies
[versions]
logback = "1.5.18"

[libraries]
logback-classic = { module = "ch.qos.logback:logback-classic", version.ref = "logback" }

[version-levels]
logback = "patch"

Use the @KoraAppTest annotation to spin up a real application graph for testing. Kora automatically prunes the graph to include only the declared @TestComponent nodes and their dependencies, ensuring you test exactly what is wired without unnecessary overhead.

You can use @Mock alongside @TestComponent to replace specific nodes in the graph with mocks (e.g., using Mockito). This approach supports component tests, integration tests using Testcontainers, and black-box tests against a built service.

@KoraAppTest(Application.class)
class PetServiceTests {

    @Mock
    @TestComponent
    private PetRepository petRepository;   // replace node with a mock

    @TestComponent
    private PetService petService;         // inject any node from the graph

    @Test
    void findByID() {
        Mockito.when(petRepository.findById(1)).thenReturn(Optional.of(pet));
        assertTrue(petService.findByID(1).isPresent());
    }
}