HTTP сервер

Модуль HTTP-сервера описывает входящую HTTP-границу приложения: прием запроса, разбор параметров, чтение тела, выбор обработчика, формирование ответа, телеметрию и перехватчики. В Kora можно описывать контроллеры декларативно через @HttpController и @HttpRoute, либо регистрировать обработчики императивно через HttpServerRequestHandler.

Декларативный подход подходит для большинства API: сигнатура метода описывает HTTP-контракт, а Kora во время компиляции создает обработчик без использования Reflection в рантайме. Императивный подход полезен для низкоуровневых или динамических маршрутов, где запрос удобнее обрабатывать вручную.

Обработка запросов синхронная. Каждый запрос выполняется на виртуальном потоке, поэтому обработчик может блокироваться: методы контроллеров, перехватчики и мапперы возвращают результат напрямую и никогда не возвращают CompletionStage, Mono/Flux или suspend-функцию.

Если нужен пошаговый разбор перед справочным описанием, смотрите HTTP-сервер и продвинутый HTTP-сервер.

Подключение¶

Реализация основана на Undertow. Undertow — это легковесный веб-сервер с открытым исходным кодом для Java-приложений. Он построен на асинхронных и неблокирующих операциях ввода-вывода с использованием NIO, что обеспечивает высокую производительность и низкое потребление ресурсов.

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

@KoraApp
public interface Application extends UndertowPublicHttpServerModule { }

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

@KoraApp
interface Application : UndertowPublicHttpServerModule

UndertowPublicHttpServerModule поднимает два сервера: публичный для контроллеров приложения и системный для проб и метрик. Если приложению нужен только системный сервер, подключите UndertowSystemHttpServerModule.

Конфигурация¶

Основные параметры конфигурации HTTP-сервера:

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

Метрики модуля описаны в разделе Справочник метрик.

Системный сервер¶

Системный сервер настраивается в собственной секции httpServer.system. SystemHttpServerConfig наследует HttpServerConfig, поэтому там доступны все перечисленные выше опции, плюс пути системных эндпоинтов:

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 вынесены в отдельную секцию httpServer.undertow и общие для обоих серверов, поскольку настраивают единый XnioWorker:

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

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

Сама обработка запроса не использует ограниченный пул блокирующих потоков: каждое соединение обслуживается виртуальным потоком, поэтому опций blockingThreads и virtualThreadsEnabled больше нет. Тело ответа записывается в сокет через NIO потоками ввода-вывода Undertow. Тело, содержимое которого еще не находится в памяти, буферизуется на виртуальном потоке запроса и отправляется целиком, пока укладывается в 64KiB; большее тело передается потоком через ограниченный канал, поэтому большой ответ никогда не держится в памяти полностью.

Для всего, что не вынесено в конфигурацию, Kora предоставляет точки расширения Configurer<T>. Configurer<T> получает собираемый объект и возвращает тот, который будет использован:

@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") }
}

Configurer<Undertow.Builder> без тега применяется к публичному серверу. Чтобы настроить системный сервер, пометьте компонент тегом @SystemApi.

Собственный внутренний HTTP-сервер¶

UndertowHttpServerFactoryModule позволяет поднять дополнительный сервер со своими маршрутами и конфигурацией. Пометьте фабричный модуль и контроллер одним тегом: сгенерированные обработчики получат этот тег и попадут только на соответствующий сервер.

Разместите InternalHttpModule в том же модуле компиляции, что и @KoraApp: @Module подключает его автоматически. В интерфейсе приложения сохраните UndertowSystemHttpServerModule или UndertowPublicHttpServerModule. UndertowSystemHttpServerModule предоставляет общие компоненты Undertow и системный сервер; если уже подключён UndertowPublicHttpServerModule, публичный сервер также продолжит работать. Используется та же зависимость http-server-undertow.

@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"
}

Первый аргумент фабрики — имя сервера для потоков и телеметрии, второй — путь к секции HttpServerConfig. В конфигурации приложения задайте httpServer.internal.port, например 8086; остальные настройки этого сервера также задаются в httpServer.internal.

GET http://localhost:8086/hello вернёт Hello World. Общие транспортные настройки остаются в httpServer.undertow. Для перехватчиков HttpServerInterceptor и Configurer<Undertow.Builder> внутреннего сервера используйте тот же тег InternalApi. Тег разделяет маршруты; доступ к порту ограничивается настройками сети. Аналогичный пример с OpenAPI — в OpenAPI management.

SomeController декларативный¶

Для создания контроллера используется аннотация @HttpController, а для регистрации его как зависимости — аннотация @Component. Аннотация @HttpRoute отвечает за указание HTTP-пути и метода для конкретного метода-обработчика.

@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() имеет тип String, а HttpMethod — это набор констант (GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE, PATCH, QUERY), поэтому нестандартный метод можно указать литералом: @HttpRoute(method = "PURGE", path = "/cache").

Маршрутизация¶

@HttpRoute сопоставляет запрос по его method (HTTP-метод из HttpMethod) и path. path — это шаблон, который должен начинаться с / и может содержать один или несколько сегментов {name} — каждый является параметром пути, связываемым через @Path:

• /users — статический путь
• /users/{id} — один параметр пути
• /users/{userId}/orders/{orderId} — несколько параметров пути, в том числе в середине пути

Параметр пути всегда соответствует ровно одному сегменту пути; значение никогда не охватывает /.

Завершающий слеш. По умолчанию сопоставление точное, поэтому /users и /users/ — это разные маршруты: запрос к /users/ при маршруте /users вернёт 404. Чтобы считать их одним маршрутом, включите httpServer.ignoreTrailingSlash (см. Конфигурация):

httpServer {
    ignoreTrailingSlash = true
}

httpServer:
  ignoreTrailingSlash: true

Сопоставление метода. Путь, обслуживаемый методом без подходящего маршрута, вернёт 405 Method Not Allowed; неизвестный путь вернёт 404 Not Found. Сопоставленный шаблон доступен во время выполнения как HttpServerRequest.route() и используется как метка пути с низкой кардинальностью в метриках и трассировке (см. Телеметрия).

Запрос¶

В этом разделе описано, как HTTP запрос превращается в аргументы метода контроллера. Для частей запроса используются специальные аннотации, а тело запроса передается аргументом без такой аннотации.

Конвертация строковых параметров¶

Значения из пути, параметров запроса, заголовков и cookie приходят строками. Для преобразования строки в целевой тип Kora использует HttpServerParameterReader<T>:

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

HttpServerParameterReader<T> ищется как компонент графа по точному типу параметра. Если параметр объявлен как List<T> или Set<T>, конвертер применяется к каждому значению по отдельности.

String, Boolean, Integer, Long, Double и UUID разбираются самим сгенерированным обработчиком и конвертера не требуют. Из коробки Kora также предоставляет конвертеры для Float, BigInteger, BigDecimal, Duration, LocalDate, LocalTime, LocalDateTime, OffsetTime, OffsetDateTime, ZonedDateTime и любого enum. Для enum по умолчанию используется имя значения через Enum.name(). Если значение не удалось сконвертировать, запрос завершается ответом 400 через 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" }
        )
    }
}

После регистрации конвертера пользовательский тип можно использовать в параметрах контроллера:

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

Параметр пути¶

@Path — обозначает значение части пути запроса, сам параметр указывается в пути как {path}, а имя параметра задается в value либо по умолчанию равно имени аргумента метода. Значение преобразуется через HttpServerParameterReader<T>, поэтому доступны как встроенные, так и пользовательские типы.

@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";
    }
}

Параметр пути всегда обязателен: если указанное в @Path имя отсутствует в шаблоне маршрута, компиляция завершается ошибкой Path parameter '...' is not present in the request mapping path.

Параметр запроса¶

@Query — значение параметра запроса, имя параметра задается в value либо по умолчанию равно имени аргумента метода. Поддерживаются одиночные значения, List<T> и Set<T>. List<T> сохраняет все значения параметра, а Set<T> убирает дубликаты и сохраняет порядок первого вхождения.

@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";
    }
}

Параметр без значения (/hello/world?queryName) считается отсутствующим: обязательный параметр приведет к ответу 400 с сообщением Query parameter 'queryName' is required.

Заголовок запроса¶

@Header — значение заголовка запроса, имя параметра задается в value либо по умолчанию равно имени аргумента метода. Поддерживаются одиночные значения, List<T> и Set<T>. List<T> и Set<T> используют все значения заголовка.

@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";
    }
}

Тело запроса¶

Для указания тела запроса используется аргумент метода без специальных аннотаций. По умолчанию поддерживаются byte[], ByteBuffer, String, InputStream, HttpBodyInput, FormUrlEncoded, FormMultipart, а также пользовательские типы через HttpServerRequestMapper<T>.

InputStream и HttpBodyInput дают доступ к телу без буферизации его в памяти, что удобно для больших загрузок.

JSON¶

Для указания, что тело является JSON и для него требуется внедрить JsonReader<T>, используется аннотация @Json:

@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"
    }
}

Требуется модуль JSON.

Form UrlEncoded¶

Объявите аргумент FormUrlEncoded (из io.koraframework.http.common.form), чтобы принять запрос с типом содержимого application/x-www-form-urlencoded (форма данных). Аннотации @Json или @Mapping не требуются — для этого типа в Kora есть встроенный reader.

FormUrlEncoded итерируем и предоставляет:

• get(String name) — возвращает FormUrlEncoded.FormPart с таким именем, либо null
• FormPart.name() — имя поля
• FormPart.values() — все значения поля (поле может повторяться в форме)

@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¶

Объявите аргумент FormMultipart (из io.koraframework.http.common.form), чтобы принять запрос multipart/form-data (бинарная форма), обычно используется для загрузки файлов. Аннотации @Json или @Mapping не требуются.

FormMultipart.parts() возвращает список частей. FormMultipart.FormPart — sealed-интерфейс с подтипами MultipartData, MultipartFile и MultipartFileStream, но сервер читает запрос в память целиком и отдает каждую часть, включая текстовые поля, как MultipartFile: name(), fileName(), contentType() и content() (byte[]). MultipartData и MultipartFileStream используются при отправке формы, например HTTP-клиентом.

@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 либо по умолчанию равно имени аргумента метода. Значение можно получить как String, как тип Cookie с именем, значением и атрибутами, либо как другой тип через 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";
    }
}

Пользовательский параметр¶

Если аргумент метода нужно собрать из запроса вручную, используется интерфейс HttpServerRequestMapper<T>. Это удобно для пользовательского контекста, авторизации, сложной валидации заголовков или сразу нескольких частей запроса:

@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)

Исключение, выброшенное маппером, превращается в ответ 400, если только оно само не является HttpServerResponse, поэтому маппер — еще и удобное место, чтобы отклонить некорректный запрос с точным статус-кодом.

Полный запрос¶

Метод контроллера может принимать сам HttpServerRequest, когда обработчику нужен исходный запрос:

@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 также предоставляет host(), scheme(), method(), path(), pathTemplate(), cookies() и body().

Обязательные параметры¶

Необязательные параметры¶

@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"
    }
}

Ответ¶

По умолчанию можно использовать стандартные типы возвращаемых значений: byte[], ByteBuffer, String, HttpBodyOutput. Они обрабатываются со статусом 200 и соответствующим заголовком типа содержимого ответа. Метод с типом void также отвечает 200 с пустым телом.

Если статус, заголовки или тело нужно указать вручную, метод может возвращать HttpServerResponse. Основной контракт HttpServerResponse состоит из кода ответа, заголовков и опционального тела:

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 предоставляет фабричные методы empty(), plaintext(...), json(...), octetStream(...) и of(contentType, ...). Для потокового ответа используйте HttpBodyOutput.of(contentType, InputStream) либо HttpBodyOutput.of(contentType, os -> ...).

Потоковая передача через InputStream¶

Верните HttpBodyOutput.of(contentType, inputStream), чтобы отправить тело без чтения всего файла в массив байтов. Откройте поток в контроллере и передайте владение телу ответа: сервер закрывает его после обработки ответа, в том числе при ошибке записи. Не закрывайте возвращаемый поток через try-with-resources / use в контроллере — иначе сервер получит уже закрытый поток.

@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))
}

Импортируйте HttpBodyOutput из io.koraframework.http.common.body. Фиксированный путь к файлу на сервере в примере не зависит от пользовательского ввода. Если точная длина известна и содержимое не меняется во время передачи, используйте of(contentType, length, stream) или octetStream(length, stream); иначе оставьте длину неизвестной (-1). HTTP/1.1 может передавать тело по частям, а HTTP/2 — в собственных кадрах данных.

Undertow буферизует небольшое тело до 64KiB, а для больших использует канал с ограниченным буфером: скорость записи в сокет ограничивает скорость чтения источника. Чтение InputStream выполняется блокирующим кодом на виртуальном потоке запроса. Разрыв соединения с клиентом приводит к ошибке записи, но не гарантирует немедленную остановку произвольного блокирующего чтения — задавайте ограничение времени чтения источника. После отправки заголовков ошибку чтения или записи уже нельзя заменить JSON-ответом. Сервер передаёт поток байтов, а не формирует события SSE.

JSON¶

Если предполагается отвечать в формате JSON и для него требуется обработчик с JsonWriter<T>, для этого требуется использовать аннотацию @Json над методом.

@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")
    }
}

Требуется модуль JSON.

Сущность ответа¶

Если тело, заголовки и статус-код ответа нужно вернуть вместе, используется HttpResponseEntity<T> — обертка над телом ответа.

Ниже пример, аналогичный примеру с JSON, но с оберткой HttpResponseEntity:

@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). Заголовок content-type, заданный в сущности, имеет приоритет над тем, который сформировал нижележащий маппер.

Ответ исключением¶

Если обработку нужно прервать и сразу вернуть ошибку, выбрасывается HttpServerResponseException. Он одновременно является исключением и HttpServerResponse, поэтому его можно бросить из контроллера, сервиса или конвертера параметров.

Фабричные методы HttpServerResponseException.of(...) позволяют указать статус-код, текст ответа, причину и заголовки. Тело ответа записывается как 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"
    }
}

Пользовательский ответ¶

Если ответ нужно формировать особым образом, используется интерфейс HttpServerResponseMapper<T>. Он получает исходный HttpServerRequest и результат метода контроллера, а возвращает готовый 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")
    }
}

Маршруты¶

Маршрут складывается из префикса пути @HttpController и пути @HttpRoute:

@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"
}

Правила сопоставления маршрутов:

• Параметр пути {name} соответствует одному сегменту пути.
• Шаблон * допустим один раз и только в последнем сегменте: /files/*, /files/*.js, /files/file-*.txt, /tenant/{id}/report-*.json. Все остальное (/foo/*/bar, /foo/**, /foo/a*b*c, /foo/{*}) не компилируется с ошибкой HTTP server route path is invalid.
• Два обработчика с эквивалентными шаблонами для одного метода приводят к падению сервера на старте с сообщением Cannot add path template ..., matcher already contains an equivalent pattern ....
• Неизвестный путь отвечает 404; известный путь с неподдерживаемым методом отвечает 405 и заголовком Allow со списком зарегистрированных методов.
• При httpServer.ignoreTrailingSlash = true для каждого маршрута без шаблона регистрируется дополнительный вариант, поэтому /my/path и /my/path/ попадают в один обработчик.

Сигнатуры¶

Доступные из коробки сигнатуры декларативных методов-обработчиков HTTP:

Перехватчики¶

Перехватчики позволяют изменить поведение или добавить общую логику вокруг обработки запроса. Используется интерфейс HttpServerInterceptor:

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

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

Перехватчик получает HttpServerRequest и цепочку дальнейшей обработки. Чтобы передать запрос дальше, вызывается chain.process(request). Если перехватчик сам возвращает ответ, обработчик контроллера не вызывается. Поскольку вызов синхронный, исключение из глубины цепочки перехватывается обычным try/catch.

Перехватчики можно применять:

• К конкретным методам контроллера — @InterceptWith на методе
• Ко всему контроллеру — @InterceptWith на классе
• Сразу ко всем контроллерам — зарегистрировать компонент перехватчика с тегом @Tag(HttpServer.class); глобальных перехватчиков может быть несколько

@InterceptWith — повторяемая аннотация, при этом перехватчики, объявленные на классе, выполняются раньше объявленных на методе. Глобальные перехватчики применяются в детерминированном порядке, отсортированном по простому имени класса перехватчика.

Порядок выполнения:

Перехватчики, объявленные через @InterceptWith, выполняются в порядке объявления (сверху вниз): перехватчики уровня контроллера оборачивают перехватчики уровня метода, а в пределах одной цели порядок соответствует порядку аннотаций. Каждый перехватчик может изменить запрос перед chain.process(...), прервать цепочку, вернув ответ без её вызова, либо обработать результат/исключение после.

Глобальные перехватчики, зарегистрированные через @Tag(HttpServerModule.class), не имеют гарантированного порядка между собой. Если требуется строгий порядок между глобальными обработчиками (например, авторизация должна выполняться до обработки ошибок), не регистрируйте несколько глобальных перехватчиков — реализуйте один глобальный перехватчик, который вызывает нужные шаги в требуемом порядке внутри себя.

@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"
    }
}