HTTP server

The HTTP server module describes the incoming HTTP boundary of an application: accepting a request, parsing parameters, reading the body, selecting a handler, creating a response, telemetry, and interceptors. In Kora, controllers can be described declaratively with @HttpController and @HttpRoute, or handlers can be registered imperatively with HttpServerRequestHandler.

The declarative approach fits most APIs: the method signature describes the HTTP contract, and Kora creates the handler at compile time without using Reflection at runtime. The imperative approach is useful for low-level or dynamic routes where it is easier to process the request manually.

Request handling is synchronous. Every request is dispatched onto a virtual thread, so a handler may block: controller methods, interceptors and mappers all return their result directly and never return CompletionStage, Mono/Flux or a suspend function.

For a step-by-step walkthrough before the reference details, see HTTP Server and Advanced HTTP Server.

Dependency¶

Implementation is based on Undertow. Undertow is a lightweight open-source web server for Java applications. It is built on asynchronous and non-blocking I/O operations using NIO, which ensures high performance and low resource consumption.

implementation "io.koraframework:http-server-undertow"

@KoraApp
public interface Application extends UndertowPublicHttpServerModule { }

implementation("io.koraframework:http-server-undertow")

@KoraApp
interface Application : UndertowPublicHttpServerModule

UndertowPublicHttpServerModule starts two servers: the public one for application controllers and the system one for probes and metrics. If an application needs only the system server, connect UndertowSystemHttpServerModule instead.

Configuration¶

Basic HTTP server configuration parameters:

httpServer {
    port = 8080 //(1)!
    system.port = 8085 //(2)!
    maxRequestBodySize = "256MiB" //(3)!
    telemetry.logging.enabled = false //(4)!
}

httpServer:
  port: 8080 #(1)!
  system:
    port: 8085 #(2)!
  maxRequestBodySize: "256MiB" #(3)!
  telemetry:
    logging:
      enabled: false #(4)!

httpServer {
    port = 8080 //(1)!
    ignoreTrailingSlash = false //(2)!
    shutdownWait = "30s" //(3)!
    socketReadTimeout = "0s" //(4)!
    socketWriteTimeout = "0s" //(5)!
    socketKeepAliveEnabled = false //(6)!
    headerKeepAliveEnabled = false //(7)!
    headerServerNameEnabled = false //(8)!
    headerServerDateEnabled = true //(9)!
    maxRequestBodySize = "256MiB" //(10)!
    telemetry {
        logging {
            enabled = false //(11)!
            stacktrace = true //(12)!
            maskQueries = [ ] //(13)!
            maskHeaders = [ "authorization", "cookie", "set-cookie" ] //(14)!
            pathFull = false //(15)!
            maxRequestBodyLogSize = "2MiB" //(16)!
            maxResponseBodyLogSize = "2MiB" //(17)!
        }
        metrics {
            enabled = false //(18)!
            slo = [ 1, 10, 50, 100, 200, 500, 1000, 2000, 5000, 10000, 20000, 30000, 60000, 90000 ] //(19)!
            tags = { // (20)!
                "key1" = "value1"
                "key2" = "value2"
            }
        }
        tracing {
            enabled = true //(21)!
            tracePathFull = true //(22)!
            attributes = { // (23)!
                "key1" = "value1"
                "key2" = "value2"
            }
        }
    }
}

httpServer:
  port: 8080 #(1)!
  ignoreTrailingSlash: false #(2)!
  shutdownWait: "30s" #(3)!
  socketReadTimeout: "0s" #(4)!
  socketWriteTimeout: "0s" #(5)!
  socketKeepAliveEnabled: false #(6)!
  headerKeepAliveEnabled: false #(7)!
  headerServerNameEnabled: false #(8)!
  headerServerDateEnabled: true #(9)!
  maxRequestBodySize: "256MiB" #(10)!
  telemetry:
    logging:
      enabled: false #(11)!
      stacktrace: true #(12)!
      maskQueries: [ ] #(13)!
      maskHeaders: [ "authorization", "cookie", "set-cookie" ] #(14)!
      pathFull: false #(15)!
      maxRequestBodyLogSize: "2MiB" #(16)!
      maxResponseBodyLogSize: "2MiB" #(17)!
    metrics:
      enabled: false #(18)!
      slo: [ 1, 10, 50, 100, 200, 500, 1000, 2000, 5000, 10000, 20000, 30000, 60000, 90000 ] #(19)!
      tags: #(20)!
        key1: value1
        key2: value2
    tracing:
      enabled: true #(21)!
      tracePathFull: true #(22)!
      attributes: #(23)!
        key1: value1
        key2: value2

Module metrics are described in the Metrics Reference section.

System server¶

The system server is configured in its own httpServer.system section. SystemHttpServerConfig extends HttpServerConfig, so all options above are available there as well, plus the paths of the system endpoints:

httpServer.system {
    port = 8085 //(1)!
    metricsPath = "/metrics" //(2)!
    readinessPath = "/system/readiness" //(3)!
    livenessPath = "/system/liveness" //(4)!
    telemetry.tracing.enabled = false //(5)!
}

httpServer:
  system:
    port: 8085 #(1)!
    metricsPath: "/metrics" #(2)!
    readinessPath: "/system/readiness" #(3)!
    livenessPath: "/system/liveness" #(4)!
    telemetry:
      tracing:
        enabled: false #(5)!

Undertow¶

Undertow-specific transport settings live in a separate httpServer.undertow section and are shared by both servers, because they configure a single XnioWorker:

httpServer.undertow {
    ioThreads = 4 //(1)!
    threadKeepAliveTimeout = "60s" //(2)!
}

httpServer:
  undertow:
    ioThreads: 4 #(1)!
    threadKeepAliveTimeout: "60s" #(2)!

Request handling itself does not use a bounded blocking pool: each connection is dispatched to a virtual thread, so there are no blockingThreads or virtualThreadsEnabled options. The response body is written to the socket over NIO by the Undertow I/O threads. A body whose content is not already in memory is buffered on the request's virtual thread and sent in one piece while it fits into 64KiB; a larger one is streamed through a bounded pipe, so a large response is never held in memory as a whole.

For everything that has no configuration option, Kora provides Configurer<T> extension points. A Configurer<T> receives the object being built and returns the object to use:

@KoraApp
public interface Application extends UndertowPublicHttpServerModule {

    default Configurer<Undertow.Builder> undertowConfigurer() { //(1)!
        return builder -> builder.setServerOption(UndertowOptions.ENABLE_HTTP2, true);
    }

    default Configurer<XnioWorker.Builder> workerConfigurer() { //(2)!
        return builder -> builder.setWorkerName("my-worker");
    }
}

@KoraApp
interface Application : UndertowPublicHttpServerModule {

    fun undertowConfigurer(): Configurer<Undertow.Builder> = //(1)!
        Configurer { builder -> builder.setServerOption(UndertowOptions.ENABLE_HTTP2, true) }

    fun workerConfigurer(): Configurer<XnioWorker.Builder> = //(2)!
        Configurer { builder -> builder.setWorkerName("my-worker") }
}

An untagged Configurer<Undertow.Builder> applies to the public server. To configure the system server, mark the component with the @SystemApi tag.

Custom internal HTTP server¶

UndertowHttpServerFactoryModule creates an additional server with its own routes and configuration. Give the factory module and controller the same tag: generated handlers inherit that tag and are registered only on the matching server.

Place InternalHttpModule in the same compilation module as @KoraApp: @Module includes it automatically. Keep UndertowSystemHttpServerModule or UndertowPublicHttpServerModule on the application interface. UndertowSystemHttpServerModule provides shared Undertow components and the system server; an existing UndertowPublicHttpServerModule also keeps the public server running. Use the same http-server-undertow dependency.

@Module
public interface InternalHttpModule {
    interface InternalApi { }

    @FactoryModule
    @Tag(InternalApi.class)
    default UndertowHttpServerFactoryModule internalHttpApi() {
        return new UndertowHttpServerFactoryModule("kora-undertow-internal", "httpServer.internal");
    }
}

@Component
@HttpController
@Tag(InternalHttpModule.InternalApi.class)
public final class InternalHelloController {
    @HttpRoute(method = HttpMethod.GET, path = "/hello")
    public String hello() {
        return "Hello World";
    }
}

@Module
interface InternalHttpModule {
    interface InternalApi

    @FactoryModule
    @Tag(InternalApi::class)
    fun internalHttpApi(): UndertowHttpServerFactoryModule =
        UndertowHttpServerFactoryModule("kora-undertow-internal", "httpServer.internal")
}

@Component
@HttpController
@Tag(InternalHttpModule.InternalApi::class)
class InternalHelloController {
    @HttpRoute(method = HttpMethod.GET, path = "/hello")
    fun hello(): String = "Hello World"
}

The first factory argument names the server for threads and telemetry; the second specifies the HttpServerConfig section. Set httpServer.internal.port in the application configuration, for example to 8086; other settings for this server also belong under httpServer.internal.

GET http://localhost:8086/hello returns Hello World. Shared transport settings remain under httpServer.undertow. Use the same InternalApi tag for internal server HttpServerInterceptor and Configurer<Undertow.Builder> components. The tag separates routes; network settings restrict access to the port. See OpenAPI management for a similar OpenAPI example.

SomeController declarative¶

The @HttpController annotation should be used to create a controller, and the @Component annotation should be used to register it as a dependency. The @HttpRoute annotation is responsible for specifying the HTTP path and method for a particular handler method.

@Component //(1)!
@HttpController //(2)!
public final class SomeController {

    //(3)!
    @HttpRoute(method = HttpMethod.POST,  //(4)!
               path = "/hello/world")  //(5)!
    public String helloWorld() {
        return "Hello World";
    }
}

@Component //(1)!
@HttpController //(2)!
class SomeController {

    //(3)!
    @HttpRoute(method = HttpMethod.POST,  //(4)!
               path = "/hello/world") //(5)!
    fun helloWorld(): String {
        return "Hello World"
    }
}

HttpRoute.method() is a String, and HttpMethod is a set of constants (GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE, PATCH, QUERY), so a non-standard method can be written as a literal: @HttpRoute(method = "PURGE", path = "/cache").

Routing¶

@HttpRoute matches a request by its method (an HTTP method from HttpMethod) and its path. The path is a template that must start with / and may contain one or more {name} segments — each is a path parameter bound with @Path:

• /users — a static path
• /users/{id} — one path parameter
• /users/{userId}/orders/{orderId} — several path parameters, including in the middle of the path

A path parameter always matches exactly one path segment; a value never spans a /.

Trailing slash. By default the match is exact, so /users and /users/ are different routes — a request to /users/ against a /users route returns 404. To treat them as the same route, enable httpServer.ignoreTrailingSlash (see Configuration):

httpServer {
    ignoreTrailingSlash = true
}

httpServer:
  ignoreTrailingSlash: true

Method matching. A path served with a method that has no matching route returns 405 Method Not Allowed; an unknown path returns 404 Not Found. The matched template is available at runtime as HttpServerRequest.route() and is used as the low-cardinality path label in metrics and tracing (see Telemetry).

Request¶

This section describes how an HTTP request is converted into controller method arguments. Special annotations are used for request parts, and the request body is passed as an argument without such an annotation.

String parameter conversion¶

Values from paths, query parameters, headers, and cookie arrive as strings. Kora uses HttpServerParameterReader<T> to convert a string into the target type:

public interface HttpServerParameterReader<T> {
    T read(String string);
}

HttpServerParameterReader<T> is looked up as a graph component by the exact parameter type. If the parameter is declared as List<T> or Set<T>, the converter is applied to every value separately.

String, Boolean, Integer, Long, Double and UUID are parsed by the generated handler itself and need no converter. Out of the box Kora also provides converters for Float, BigInteger, BigDecimal, Duration, LocalDate, LocalTime, LocalDateTime, OffsetTime, OffsetDateTime, ZonedDateTime, and any enum. For enum, the default mapping uses the value name via Enum.name(). If a value cannot be converted, the request is completed with a 400 response through HttpServerResponseException.

public record UserId(long value) {}

@Module
public interface UserIdModule {

    default HttpServerParameterReader<UserId> userIdParameterReader() {
        return HttpServerParameterReader.of(
            value -> new UserId(Long.parseLong(value)),
            value -> "Invalid user id: " + value
        );
    }
}

data class UserId(val value: Long)

@Module
interface UserIdModule {

    fun userIdParameterReader(): HttpServerParameterReader<UserId> {
        return HttpServerParameterReader.of(
            { value -> UserId(value.toLong()) },
            { value -> "Invalid user id: $value" }
        )
    }
}

After registering the converter, the custom type can be used in controller parameters:

@HttpRoute(method = HttpMethod.GET, path = "/users/{id}")
public User get(@Path("id") UserId id) {
    return userService.get(id);
}

Path parameter¶

@Path - denotes the value of the request path part, the parameter itself is specified in {path} in the path and the name of the parameter is specified in value or defaults to the name of the method argument. The value is converted through HttpServerParameterReader<T>, so both built-in and custom types can be used.

@Component
@HttpController
public final class SomeController {

    @HttpRoute(method = HttpMethod.POST, path = "/hello/{pathName}")
    public String helloWorld(@Path("pathName") String pathValue) {
        return "Hello World";
    }
}

@Component
@HttpController
class SomeController {

    @HttpRoute(method = HttpMethod.POST, path = "/hello/{pathName}")
    fun helloWorld(
        @Path("pathName") pathValue: String
    ): String {
        return "Hello World";
    }
}

A path parameter is always required: if the name in @Path is absent from the route template, compilation fails with Path parameter '...' is not present in the request mapping path.

Query parameter¶

@Query - value of the query parameter, the name of the parameter is specified in value or is equal to the name of the method argument by default. Single values, List<T>, and Set<T> are supported. List<T> keeps all parameter values, while Set<T> removes duplicates and preserves the order of first occurrence.

@Component
@HttpController
public final class SomeController {

    @HttpRoute(method = HttpMethod.POST, path = "/hello/world")
    public String helloWorld(@Query("queryName") String queryValue,
                             @Query("queryNameList") List<String> queryValues) {
        return "Hello World";
    }
}

@Component
@HttpController
class SomeController {

    @HttpRoute(method = HttpMethod.POST, path = "/hello/world")
    fun helloWorld(
        @Query("queryName") queryValue: String,
        @Query("queryNameList") queryValues: List<String>
    ): String {
        return "Hello World";
    }
}

A query parameter present without a value (/hello/world?queryName) counts as missing: a required parameter is answered with 400 and the message Query parameter 'queryName' is required.

Request header¶

@Header - value of request header, the parameter name is specified in value or defaults to the method argument name. Single values, List<T>, and Set<T> are supported. List<T> and Set<T> use all values of the header.

@Component
@HttpController
public final class SomeController {

    @HttpRoute(method = HttpMethod.POST, path = "/hello/world")
    public String helloWorld(@Header("headerName") String headerValue,
                             @Header("headerNameList") List<String> headerValues) {
        return "Hello World";
    }
}

@Component
@HttpController
class SomeController {

    @HttpRoute(method = HttpMethod.POST, path = "/hello/world")
    fun helloWorld(
        @Header("headerName") headerValue: String,
        @Header("headerNameList") headerValues: List<String>
    ): String {
        return "Hello World";
    }
}

Request body¶

Specifying the request body requires using a method argument without special annotations. By default, byte[], ByteBuffer, String, InputStream, HttpBodyInput, FormUrlEncoded, FormMultipart, and custom types through HttpServerRequestMapper<T> are supported.

InputStream and HttpBodyInput give access to the body without buffering it in memory, which is useful for large uploads.

JSON¶

In request body should be treated as JSON, than it must be annotated via @Json tag to require handler for injection with JsonReader<T>.

@Component
@HttpController
public final class SomeController {

    @Json
    public record Request(String name) {}

    @HttpRoute(method = HttpMethod.POST, path = "/hello/world")
    public String helloWorld(@Json Request body) { //(1)!
        return "Hello World";
    }
}

@Component
@HttpController
class SomeController {

    @Json
    data class Request(val name: String)

    @HttpRoute(method = HttpMethod.POST, path = "/hello/world")
    fun helloWorld(@Json body: Request): String { //(1)!
        return "Hello World"
    }
}

The JSON module is required.

Form UrlEncoded¶

Declare a FormUrlEncoded (from io.koraframework.http.common.form) argument to accept a request with the application/x-www-form-urlencoded content type (form data). No @Json or @Mapping annotation is needed — Kora has a built-in reader for this type.

FormUrlEncoded is iterable and provides:

• get(String name) — returns the FormUrlEncoded.FormPart with that name, or null
• FormPart.name() — the field name
• FormPart.values() — all values of that field (a field may be repeated in the form)

@Component
@HttpController
public final class SomeController {

    @HttpRoute(method = HttpMethod.POST, path = "/form/encoded")
    public String handle(FormUrlEncoded body) {
        FormUrlEncoded.FormPart name = body.get("name"); //(1)!
        String firstName = (name != null) ? name.values().get(0) : null;
        return "Hello " + firstName;
    }
}

@Component
@HttpController
class SomeController {

    @HttpRoute(method = HttpMethod.POST, path = "/form/encoded")
    fun handle(body: FormUrlEncoded): String {
        val name = body.get("name") //(1)!
        val firstName = name?.values()?.firstOrNull()
        return "Hello $firstName"
    }
}

Form Multipart¶

Declare a FormMultipart (from io.koraframework.http.common.form) argument to accept a multipart/form-data request (binary form), typically used for file uploads. No @Json or @Mapping annotation is needed.

FormMultipart.parts() returns the list of parts. FormMultipart.FormPart is a sealed interface with the subtypes MultipartData, MultipartFile and MultipartFileStream, but the server reads the whole request into memory and delivers every part, text fields included, as MultipartFile: name(), fileName(), contentType() and content() (byte[]). MultipartData and MultipartFileStream are used when a form is sent, for example by an HTTP client.

@Component
@HttpController
public final class SomeController {

    @HttpRoute(method = HttpMethod.POST, path = "/form/multipart")
    public String handle(FormMultipart body) {
        for (FormMultipart.FormPart part : body.parts()) {
            if (part instanceof FormMultipart.FormPart.MultipartFile file) { //(1)!
                String name = file.name();
                String fileName = file.fileName(); //(2)!
                String contentType = file.contentType();
                byte[] content = file.content();
            }
        }
        return "OK";
    }
}

@Component
@HttpController
class SomeController {

    @HttpRoute(method = HttpMethod.POST, path = "/form/multipart")
    fun handle(body: FormMultipart): String {
        for (part in body.parts()) {
            if (part is FormMultipart.FormPart.MultipartFile) { //(1)!
                val name = part.name()
                val fileName = part.fileName() //(2)!
                val contentType = part.contentType()
                val content = part.content()
            }
        }
        return "OK"
    }
}

Cookie¶

@Cookie - Cookie value, the parameter name is specified in value or defaults to the method argument name. The value can be received as String, as a Cookie type with name, value, and attributes, or as another type through HttpServerParameterReader<T>.

@Component
@HttpController
public final class SomeController {

    @HttpRoute(method = HttpMethod.POST, path = "/hello/world")
    public String helloWorld(@Cookie("cookieName") String cookieValue) {
        return "Hello World";
    }
}

@Component
@HttpController
class SomeController {

    @HttpRoute(method = HttpMethod.POST, path = "/hello/world")
    fun helloWorld(
        @Cookie("cookieName") cookieValue: String
    ): String {
        return "Hello World";
    }
}

Custom parameter¶

If a method argument needs to be assembled from the request manually, use the HttpServerRequestMapper<T> interface. This is useful for user context, authorization, complex header validation, or several request parts at once:

@Component
@HttpController
public final class SomeController {

    public record UserContext(String userId, String traceId) {}

    @Component //(1)!
    public static final class RequestMapper implements HttpServerRequestMapper<UserContext> {

        @Override
        public UserContext apply(HttpServerRequest request) {
            return new UserContext(request.headers().getFirst("x-user-id"), request.headers().getFirst("x-trace-id"));
        }
    }

    @HttpRoute(method = HttpMethod.POST, path = "/hello/world")
    public String get(@Mapping(RequestMapper.class) UserContext context) {
        return "Hello World";
    }
}

@Component
@HttpController
class SomeController {

    data class UserContext(val userId: String?, val traceId: String?)

    @Component //(1)!
    class RequestMapper : HttpServerRequestMapper<UserContext> {

        override fun apply(request: HttpServerRequest): UserContext {
            return UserContext(
                request.headers().getFirst("x-user-id"),
                request.headers().getFirst("x-trace-id")
            )
        }
    }

    @HttpRoute(method = HttpMethod.POST, path = "/hello/world")
    fun get(@Mapping(RequestMapper::class) context: UserContext): String {
        return "Hello World"
    }
}

No component found for dependency:
  SomeController.RequestMapper (no tags)

An exception thrown by a mapper is turned into a 400 response unless it is itself an HttpServerResponse, so a mapper is also a convenient place to reject a malformed request with an exact status code.

Full request¶

A controller method can accept HttpServerRequest itself when the handler needs the raw request:

@Component
@HttpController
public final class SomeController {

    @HttpRoute(method = HttpMethod.GET, path = "/request")
    public HttpServerResponse get(HttpServerRequest request) {
        var header = request.headers().getFirst("header"); //(1)!
        var query = request.queryParams().get("query"); //(2)!
        var path = request.pathParams().get("path"); //(3)!
        return HttpServerResponse.of(200, HttpBody.plaintext(request.path()));
    }
}

@Component
@HttpController
class SomeController {

    @HttpRoute(method = HttpMethod.GET, path = "/request")
    fun get(request: HttpServerRequest): HttpServerResponse {
        val header = request.headers().getFirst("header") //(1)!
        val query = request.queryParams()["query"] //(2)!
        val path = request.pathParams()["path"] //(3)!
        return HttpServerResponse.of(200, HttpBody.plaintext(request.path()))
    }
}

HttpServerRequest also exposes host(), scheme(), method(), path(), pathTemplate(), cookies() and body().

Required parameters¶

Optional parameters¶

@Component
@HttpController
public final class SomeController {

    @HttpRoute(method = HttpMethod.POST, path = "/hello/world")
    public String helloWorld(@Nullable @Query("queryName") String queryValue) { //(1)!
        return "Hello World";
    }
}

@Component
@HttpController
class SomeController {

    @HttpRoute(method = HttpMethod.POST, path = "/hello/world")
    fun helloWorld(@Query("queryName") queryValue: String?): String {
        return "Hello World"
    }
}

Response¶

By default, standard return value types can be used: byte[], ByteBuffer, String, HttpBodyOutput. They are processed with status 200 and the corresponding response content type header. A void method also answers with 200 and an empty body.

If the status, headers, or body must be specified manually, the method can return HttpServerResponse. The main HttpServerResponse contract consists of a response code, headers, and an optional body:

public interface HttpServerResponse {
    int code();
    HttpHeaders headers();
    @Nullable
    HttpBodyOutput body();
}

@Component
@HttpController
public final class SomeController {

    @HttpRoute(method = HttpMethod.POST, path = "/hello/world")
    public HttpServerResponse helloWorld() {
        return HttpServerResponse.of(
                200, //(1)!
                HttpHeaders.of("headerName", "headerValue"), //(2)!
                HttpBody.plaintext("Hello World") //(3)!
        );
    }
}

@Component
@HttpController
class SomeController {

    @HttpRoute(method = HttpMethod.POST, path = "/hello/world")
    fun helloWorld(): HttpServerResponse {
        return HttpServerResponse.of(
            200, //(1)!
            HttpHeaders.of("headerName", "headerValue"), //(2)!
            HttpBody.plaintext("Hello World") //(3)!
        )
    }
}

HttpBody provides the factory methods empty(), plaintext(...), json(...), octetStream(...) and of(contentType, ...). For a streaming response use HttpBodyOutput.of(contentType, InputStream) or HttpBodyOutput.of(contentType, os -> ...).

Streaming with InputStream¶

Return HttpBodyOutput.of(contentType, inputStream) to send a body without loading the whole file into a byte array. Open the stream in the controller and transfer ownership to the response body: the server closes it after response processing, including write failures. Do not wrap the returned stream in a controller-level try-with-resources / use, because that would close it before the server reads it.

@HttpRoute(method = HttpMethod.GET, path = "/report")
public HttpServerResponse report() throws java.io.IOException {
    var path = java.nio.file.Path.of("/data/report.csv");
    var stream = java.nio.file.Files.newInputStream(path);
    return HttpServerResponse.of(200, HttpBodyOutput.of("text/csv", stream));
}

@HttpRoute(method = HttpMethod.GET, path = "/report")
fun report(): HttpServerResponse {
    val path = java.nio.file.Path.of("/data/report.csv")
    val stream = java.nio.file.Files.newInputStream(path)
    return HttpServerResponse.of(200, HttpBodyOutput.of("text/csv", stream))
}

Import HttpBodyOutput from io.koraframework.http.common.body. The fixed server-side path keeps this example independent of user-provided filenames. If the exact length is known and the content cannot change during transfer, use of(contentType, length, stream) or octetStream(length, stream); otherwise leave it unknown (-1). HTTP/1.1 can then use chunked framing; HTTP/2 uses its own data frames.

Undertow buffers a small unknown body up to 64KiB; larger bodies use a bounded pipe and socket backpressure paces the producer. Reading an InputStream is blocking work on the request virtual thread. A disconnected client causes writing to fail; it does not guarantee that a custom blocking stream will immediately stop reading, so configure source read timeouts too. If headers are already sent, a read/write failure cannot be replaced with a JSON error response. This is byte streaming, not SSE event framing.

JSON¶

If the response should be returned as JSON, use the @Json annotation on the method. Kora will find or create JsonWriter<T> for the response type:

@Component
@HttpController
public final class SomeController {

    @Json
    public record Response(String greeting) {}

    @Json //(1)!
    @HttpRoute(method = HttpMethod.POST, path = "/hello/world")
    public Response helloWorld() {
        return new Response("Hello World");
    }
}

@Component
@HttpController
class SomeController {

    @Json
    data class Response(val greeting: String)

    @Json //(1)!
    @HttpRoute(method = HttpMethod.POST, path = "/hello/world")
    fun helloWorld(): Response {
        return Response("Hello World")
    }
}

The JSON module is required.

Response entity¶

If the body, headers, and response status code should be returned together, use HttpResponseEntity<T>, a wrapper around the response body.

Below is an example similar to the JSON example with the HttpResponseEntity wrapper:

@Component
@HttpController
public final class SomeController {

    @Json
    public record Response(String greeting) {}

    @Json
    @HttpRoute(method = HttpMethod.POST, path = "/hello/world")
    public HttpResponseEntity<Response> helloWorld() {
        return HttpResponseEntity.of(200, HttpHeaders.of("myHeader", "12345"), new Response("Hello World"));
    }
}

@Component
@HttpController
class SomeController {

    @Json
    data class Response(val greeting: String)

    @Json
    @HttpRoute(method = HttpMethod.POST, path = "/hello/world")
    fun helloWorld(): HttpResponseEntity<Response> {
        return HttpResponseEntity.of(200, HttpHeaders.of("myHeader", "12345"), Response("Hello World"));
    }
}

HttpResponseEntity.of(code, body) is available when only the status code has to be overridden. The content-type set on the entity headers wins over the one produced by the underlying mapper.

Respond exception¶

If processing should be interrupted and an error should be returned immediately, throw HttpServerResponseException. It is both an exception and an HttpServerResponse, so it can be thrown from a controller, service, or parameter converter.

The HttpServerResponseException.of(...) factory methods allow specifying the status code, response text, cause, and headers. The response body is written as text/plain;charset=utf-8.

@Component
@HttpController
public final class SomeController {

    @HttpRoute(method = HttpMethod.POST, path = "/hello/{pathName}")
    public String helloWorld(@Path("pathName") String pathValue) {
        if("null".equals(pathValue)) {
            throw HttpServerResponseException.of(400, "Bad request");
        }
        return "OK";
    }
}

@Component
@HttpController
class SomeController {

    @HttpRoute(method = HttpMethod.POST, path = "/hello/{pathName}")
    fun helloWorld(@Path("pathName") pathValue: String): String {
        if ("null" == pathValue) {
            throw HttpServerResponseException.of(400, "Bad request")
        }
        return "OK"
    }
}

Custom response¶

If the response needs to be created in a custom way, use the HttpServerResponseMapper<T> interface. It receives the original HttpServerRequest and the controller method result, and returns a ready HttpServerResponse:

@Component
@HttpController
public final class SomeController {

    public record HelloWorldResponse(String greeting, String name) {}

    @Component //(1)!
    public static final class ResponseMapper implements HttpServerResponseMapper<HelloWorldResponse> {

        @Override
        public HttpServerResponse apply(HttpServerRequest request, HelloWorldResponse result) {
            return HttpServerResponse.of(200, HttpBody.plaintext(result.greeting() + " - " + result.name()));
        }
    }

    @Mapping(ResponseMapper.class)
    @HttpRoute(method = HttpMethod.POST, path = "/hello/world")
    public HelloWorldResponse helloWorld() {
        return new HelloWorldResponse("Hello World", "Bob");
    }
}

@Component
@HttpController
class SomeController {

    data class HelloWorldResponse(val greeting: String, val name: String)

    @Component //(1)!
    class ResponseMapper : HttpServerResponseMapper<HelloWorldResponse> {

        override fun apply(request: HttpServerRequest, result: HelloWorldResponse?): HttpServerResponse { //(2)!
            requireNotNull(result)
            return HttpServerResponse.of(200, HttpBody.plaintext("${result.greeting} - ${result.name}"))
        }
    }

    @Mapping(ResponseMapper::class)
    @HttpRoute(method = HttpMethod.POST, path = "/hello/world")
    fun helloWorld(): HelloWorldResponse {
        return HelloWorldResponse("Hello World", "Bob")
    }
}

Routes¶

A route is the concatenation of the @HttpController path prefix and the @HttpRoute path:

@Component
@HttpController("/api/v1") //(1)!
public final class SomeController {

    @HttpRoute(method = HttpMethod.GET, path = "/pets/{id}") //(2)!
    public String get(@Path long id) {
        return "OK";
    }

    @HttpRoute(method = HttpMethod.GET, path = "/files/*") //(3)!
    public String file() {
        return "OK";
    }
}

@Component
@HttpController("/api/v1") //(1)!
class SomeController {

    @HttpRoute(method = HttpMethod.GET, path = "/pets/{id}") //(2)!
    fun get(@Path id: Long): String = "OK"

    @HttpRoute(method = HttpMethod.GET, path = "/files/*") //(3)!
    fun file(): String = "OK"
}

Route matching rules:

• A path parameter {name} matches a single path segment.
• A wildcard * is allowed once and only in the final segment: /files/*, /files/*.js, /files/file-*.txt, /tenant/{id}/report-*.json. Anything else (/foo/*/bar, /foo/**, /foo/a*b*c, /foo/{*}) fails compilation with HTTP server route path is invalid.
• Two handlers with equivalent templates for the same method make the server fail on start with Cannot add path template ..., matcher already contains an equivalent pattern ....
• An unknown path answers 404; a known path requested with an unsupported method answers 405 with the Allow header listing the registered methods.
• With httpServer.ignoreTrailingSlash = true an additional variant of every non-wildcard route is registered, so /my/path and /my/path/ hit the same handler.

Signatures¶

Available signatures for declarative HTTP handler methods out of the box:

Interceptors¶

Interceptors can be created to change behavior or add shared logic around request processing. Use the HttpServerInterceptor interface:

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

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

An interceptor receives the HttpServerRequest and the chain of further processing. To pass the request further, call chain.process(request). If the interceptor returns a response itself, the controller handler is not called. Because the call is synchronous, an exception thrown further down the chain is simply caught with try/catch.

Interceptors can be used on:

• Specific controller methods — @InterceptWith on the method
• Entire controller — @InterceptWith on the class
• All controllers at once — register the interceptor component with the @Tag(HttpServer.class) tag; there can be several global interceptors

@InterceptWith is repeatable, and interceptors declared on the class run before those declared on the method. Global interceptors are applied in a deterministic order sorted by the interceptor class simple name.

Execution order:

Interceptors declared with @InterceptWith run in the order they are declared (top to bottom): controller-level interceptors wrap method-level ones, and within the same target the order follows the annotation order. Each interceptor may modify the request before chain.process(...), short-circuit by returning a response without calling the chain, or handle the result/exception afterwards.

Global interceptors registered with @Tag(HttpServerModule.class) have no guaranteed order between each other. If a strict order across global concerns is required (for example authorization must run before error mapping), do not register several global interceptors — implement a single global interceptor that invokes the concerns in the required order internally.

@Component
@HttpController
@InterceptWith(SomeController.ControllerInterceptor.class) //(1)!
public final class SomeController {

    @Component
    public static final class ControllerInterceptor implements HttpServerInterceptor {

        @Override
        public HttpServerResponse intercept(HttpServerRequest request, InterceptChain chain) throws Exception {
            return chain.process(request);
        }
    }

    @Component
    public static final class MethodInterceptor implements HttpServerInterceptor {

        @Override
        public HttpServerResponse intercept(HttpServerRequest request, InterceptChain chain) throws Exception {
            return chain.process(request);
        }
    }

    @Tag(HttpServer.class) //(2)!
    @Component
    public static final class ServerInterceptor implements HttpServerInterceptor {

        @Override
        public HttpServerResponse intercept(HttpServerRequest request, InterceptChain chain) throws Exception {
            return chain.process(request);
        }
    }

    @InterceptWith(MethodInterceptor.class) //(3)!
    @HttpRoute(method = HttpMethod.POST, path = "/intercepted")
    public String helloWorld() {
        return "Hello World";
    }
}

@Component
@HttpController
@InterceptWith(SomeController.ControllerInterceptor::class) //(1)!
class SomeController {

    @Component
    class ControllerInterceptor : HttpServerInterceptor {

        override fun intercept(request: HttpServerRequest, chain: HttpServerInterceptor.InterceptChain): HttpServerResponse {
            return chain.process(request)
        }
    }

    @Component
    class MethodInterceptor : HttpServerInterceptor {

        override fun intercept(request: HttpServerRequest, chain: HttpServerInterceptor.InterceptChain): HttpServerResponse {
            return chain.process(request)
        }
    }

    @Tag(HttpServer::class) //(2)!
    @Component
    class ServerInterceptor : HttpServerInterceptor {

        override fun intercept(request: HttpServerRequest, chain: HttpServerInterceptor.InterceptChain): HttpServerResponse {
            return chain.process(request)
        }
    }

    @InterceptWith(MethodInterceptor::class) //(3)!
    @HttpRoute(method = HttpMethod.POST, path = "/intercepted")
    fun helloWorld(): String {
        return "Hello World"
    }
}