Kora HTTP Server

Kora HTTP Server

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.

Handlers are generated at compile time. For each @HttpController the processor emits a <Controller>Module @Module interface with one HttpServerRequestHandler factory method per @HttpRoute, which the DI graph assembles into an HttpServerRouter. Nothing is reflective, and nothing is discovered at runtime — a route that does not compile does not exist.

Migrating from Kora 1.x — read this first

Five changes cause silent or confusing failures. Each is covered in depth in the linked reference.

Every framework package moved from ru.tinkoff.kora.* to io.koraframework.*, and the HTTP packages were also re-split — a blind group rename leaves imports that do not resolve. See Controller & Routing.

Quick start

1. Dependencies (Java)

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

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

    implementation "io.koraframework:http-server-undertow"
    implementation "io.koraframework:json-common"
    implementation "io.koraframework:config-hocon"
    implementation "io.koraframework:logging-logback"
}

Kotlin replaces the processor with KSP:

implementation(platform("io.koraframework:kora-bom:${property("koraVersion")}"))
ksp("io.koraframework:symbol-processors:${property("koraVersion")}")
implementation("io.koraframework:http-server-undertow")

Java 25 is the floor — Kora 2.0 artifacts are class-file 69. Artifacts other than the BOM are never versioned individually.

2. Application graph

@KoraApp
public interface Application extends
        HoconConfigModule,
        LogbackModule,
        JsonModule,
        UndertowPublicHttpServerModule {

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

UndertowPublicHttpServerModule extends UndertowSystemHttpServerModule, so plugging in the public module starts both servers: the application server on httpServer.port and the system server (readiness, liveness, metrics) on httpServer.system.port. UndertowHttpServerModule from 1.x no longer exists.

3. Controller

@Component
@HttpController
public final class HelloController {

    @HttpRoute(method = HttpMethod.GET, path = "/hello/{name}")
    public String hello(@Path String name) {
        return "Hello " + name;   // 200 OK, text/plain
    }
}

@HttpController optionally takes a path prefix (String value() default ""), prepended to every @HttpRoute path in the class. Leave it off and each route carries its full path.

4. Config (application.conf)

httpServer {
  port = 8080
  system.port = 8085
  telemetry.logging.enabled = true   # off by default
}

CRUD controller

JSON needs @Json on the method and on the body parameter. Optional inputs are @Nullable (Java, JSpecify) or a nullable type (Kotlin).

@Component
@HttpController
public final class UserController {

    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    @HttpRoute(method = HttpMethod.GET, path = "/users/{userId}")
    @Json
    public UserResponse getUser(@Path String userId) {
        return userService.findById(userId)
                .orElseThrow(() -> HttpServerResponseException.of(404, "User not found: " + userId));
    }

    @HttpRoute(method = HttpMethod.GET, path = "/users")
    @Json
    public List<UserResponse> listUsers(@Nullable @Query Integer page,
                                        @Nullable @Query Integer size) {
        return userService.findAll(page == null ? 0 : page, size == null ? 10 : size);
    }

    @HttpRoute(method = HttpMethod.POST, path = "/users")
    @Json
    public HttpResponseEntity<UserResponse> createUser(@Json UserRequest request) {
        var created = userService.create(request);
        return HttpResponseEntity.of(201, HttpHeaders.of("Location", "/users/" + created.id()), created);
    }

    @HttpRoute(method = HttpMethod.DELETE, path = "/users/{userId}")
    public void deleteUser(@Path String userId) {
        userService.delete(userId);   // void -> 200 with an empty body, no mapper needed
    }
}

DTOs are plain records annotated @Json: UserRequest(String email, String name), UserResponse(String id, String email, String name).

Key annotations

HttpMethod (io.koraframework.http.common.HttpMethod) is a holder of String constants, not an enum: GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE, PATCH, QUERY. @HttpRoute(method = ...) takes a String, so method = "GET" is equally valid.

Response types

return HttpResponseEntity.of(201, HttpHeaders.of("Location", "/users/" + id), user);
return HttpServerResponse.of(200, HttpHeaders.of("X-Trace", traceId), HttpBody.plaintext("OK"));
return HttpServerResponse.of(204);

Reactive and suspending handlers are gone. http-server-common ships no response mapper for Mono/Flux/CompletionStage, and the Kotlin processor rejects suspend with Suspend methods are not supported by the HTTP server controller generator. Run concurrent work inside a synchronous handler with StructuredTaskScope.

See Response Types for HttpBody, HttpHeaders and custom HttpServerResponseMapper (including the Kotlin nullability rule).

Error handling

Throw HttpServerResponseException.of(code, message) to short-circuit a handler. HttpServerResponseException is itself an HttpServerResponse, so an interceptor can simply return it. There is no @ControllerAdvice equivalent — centralized error translation is an interceptor concern.

return userService.find(id)
    .orElseThrow(() -> HttpServerResponseException.of(404, "Not found: " + id));

See Error Handling for the global error interceptor.

Interceptors

public interface HttpServerInterceptor {
    HttpServerResponse intercept(HttpServerRequest request, InterceptChain chain) throws Exception;

    interface InterceptChain {
        HttpServerResponse process(HttpServerRequest request) throws Exception;
    }
}

Synchronous, one request argument, throws Exception — so a plain try/catch around chain.process(request) is the way to handle downstream errors.

@Tag(HttpServer.class)   // io.koraframework.http.server.common.HttpServer
@Component
public final class LoggingInterceptor implements HttpServerInterceptor {

    private static final Logger log = LoggerFactory.getLogger(LoggingInterceptor.class);

    @Override
    public HttpServerResponse intercept(HttpServerRequest request, InterceptChain chain) throws Exception {
        long started = System.nanoTime();
        HttpServerResponse response = chain.process(request);
        log.info("{} {} -> {} ({} ms)", request.method(), request.path(), response.code(),
                (System.nanoTime() - started) / 1_000_000);
        return response;
    }
}

Server-scoped interceptors are sorted by simple class name, not by declaration order, and they never run on the system server. See Interceptors.

Configuration

httpServer {
  port = 8080
  ignoreTrailingSlash = false
  shutdownWait = "30s"
  maxRequestBodySize = "256MiB"

  telemetry {
    logging.enabled = true    # default false
    metrics.enabled = true    # default false
    tracing.enabled = true    # default true (but false under httpServer.system)
  }

  system {
    port = 8085
    metricsPath   = "/metrics"
    readinessPath = "/system/readiness"
    livenessPath  = "/system/liveness"
  }

  undertow {
    ioThreads = 4             # transport tuning lives in its own section
  }
}

telemetry.logging.enabled and telemetry.metrics.enabled default to false everywhere — an example that claims to demonstrate them must switch them on. See Configuration for every key that actually exists.

References

Assets

scripts/validate_controller.py statically checks a controller or interceptor file for the regressions above (--json for machine output, --help for usage).

Pitfalls

Evals

Self-check rubric: evals/evals.json.