バージョン:

HTTP Reference

このドキュメントでは、Quarkusで利用可能なさまざまなHTTP機能について説明します。

Eclipse Vert.xは、基本的なHTTPレイヤーを提供します。 Servletのサポートのために、QuarkusはVert.xの上で動作するカスタマイズされたUndertowバージョンを使用し、Jakarta RESTのサポートはRESTEasyを通じて提供されます。

Undertowがある場合、RESTEasyはServletフィルタとして機能します。 Undertowがない場合、RESTEasyはServletを介さずにVert.x上で直接動作します。

1. 静的リソースの提供

Quarkus を Web アプリケーションに使用する場合は、Web 向け Quarkus ガイドを参照してください。

1.1. アプリケーションjarから

アプリケーションjarから静的リソースを提供するには、それらをアプリケーションの META-INF/resources ディレクトリに配置する必要があります。この場所は、Servlet仕様で定義されている jar ファイルのリソースの標準的な場所として選択されています。QuarkusはServletなしで使用できますが、この規約に従って、リソースをこの場所に配置する既存のコードを正しく機能させることができます。

1.2. webjars や mvnpm などの Web 依存関係から

WebJars、https://mvnpm.org[mvnpm]、https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap[importmaps] の使用方法の詳細は、Web 依存関係ロケーターガイドを参照してください。

1.3. ローカルディレクトリから

Vert.xルーターに追加ルートをインストールすることで、静的リソースをローカルディレクトリから提供できます。

例えば、 http://localhost:8080/static/ でカレントパスから相対的に、 static/ ディレクトリからリソースを提供するには、以下のルートをインストールします：

package org.acme;

import io.quarkus.runtime.StartupEvent;
import io.vertx.ext.web.Router;
import io.vertx.ext.web.handler.StaticHandler;
import jakarta.enterprise.event.Observes;


public class StaticResources {

    void installRoute(@Observes StartupEvent startupEvent, Router router) {
        router.route()
                .path("/static/*")
                .handler(StaticHandler.create("static/"));
    }
}

1.4. ローカルファイルシステムの静的リソース

Serving static resources from a local filesystem directory is enabled when quarkus.http.static-dir.path is set. The quarkus.http.static-dir.enabled property can be used to explicitly disable this feature.

Quarkus は、アプリケーション JAR や Java リソースの外部にあるローカルファイルシステムのディレクトリーから静的ファイルを提供できます。これは quarkus.http.static-dir.* プロパティーを介して設定されます。

static/ ディレクトリーの内容を公開するには、以下のようにします。

quarkus.http.static-dir.path=static

デフォルトでは、静的ファイルは /static エンドポイントの下で公開されます。

この設定では、 static/picture.jpg にあるファイルは http://localhost:8080/static/picture.jpg で利用可能になります。

デフォルトのエンドポイントを変更するには、以下のようにします。

quarkus.http.static-dir.endpoint=/

この設定では、 static/picture.jpg にあるファイルは http://localhost:8080/picture.jpg で利用可能になります。

quarkus.http.static-dir.endpoint の値には * や .. を含めることはできず、末尾のスラッシュを避けるために正規化されます。同様に、 quarkus.http.static-dir.path は .. を含まない相対パスである必要があります。Quarkus はビルド時にこれらの値を検証します。

この機能は、開発環境と本番環境の両方で使用できます。

1.5. HTTP圧縮

静的リソースのレスポンスボディは、デフォルトでは圧縮されません。 HTTP 圧縮のサポートは quarkus.http.enable-compression=true によって有効にすることができます。圧縮サポートが有効な場合、リソースのファイル名から得られる Content-Type ヘッダーが quarkus.http.compress-media-types で設定された圧縮メディアタイプであれば、レスポンスボディは圧縮されます。

By default, the following list of media types is compressed: text/html, text/plain, text/xml, text/css, text/javascript, application/javascript, application/json, application/graphql+json and application/xhtml+xml.

If the client does not indicate its support for HTTP compression in a request header, e.g. Accept-Encoding: deflate, gzip, br, then the response body is not compressed.

Brotli compression is not available by default. You can enable it by setting quarkus.http.compressors=deflate,gzip,br. In case of building native image, it adds around 1MB to your executable size.

1.6. その他の設定

さらに、静的リソースのインデックスページをデフォルトの index.html から変更すること、隠しファイル（ドットファイルなど）を提供しないことを示すこと、範囲要求を無効にすること、キャッシュ対応（ヘッダーのキャッシュ、ファイルのプロパティのキャッシュなど）を設定することができます。

ビルド時に固定される設定プロパティ - それ以外の設定プロパティは実行時に上書き可能

Configuration property	タイプ	デフォルト
`quarkus.http.static-resources.index-page` Set the index page when serving static resources. Environment variable: `QUARKUS_HTTP_STATIC_RESOURCES_INDEX_PAGE` Show more	string	`index.html`
`quarkus.http.static-resources.include-hidden` Set whether hidden files should be served. Environment variable: `QUARKUS_HTTP_STATIC_RESOURCES_INCLUDE_HIDDEN` Show more	boolean	`true`
`quarkus.http.static-resources.enable-range-support` Set whether range requests (resumable downloads; media streaming) should be enabled. Environment variable: `QUARKUS_HTTP_STATIC_RESOURCES_ENABLE_RANGE_SUPPORT` Show more	boolean	`true`
`quarkus.http.static-resources.caching-enabled` Set whether cache handling is enabled. Environment variable: `QUARKUS_HTTP_STATIC_RESOURCES_CACHING_ENABLED` Show more	boolean	`true`
`quarkus.http.static-resources.cache-entry-timeout` Set the cache entry timeout. The default is `30` seconds. Environment variable: `QUARKUS_HTTP_STATIC_RESOURCES_CACHE_ENTRY_TIMEOUT` Show more	Duration	`30S`
`quarkus.http.static-resources.max-age` Set value for max age in caching headers. The default is `24` hours. Environment variable: `QUARKUS_HTTP_STATIC_RESOURCES_MAX_AGE` Show more	Duration	`24H`
`quarkus.http.static-resources.max-cache-size` Set the max cache size. Environment variable: `QUARKUS_HTTP_STATIC_RESOURCES_MAX_CACHE_SIZE` Show more	int	`10000`
`quarkus.http.static-resources.content-encoding` Content encoding for text related files Environment variable: `QUARKUS_HTTP_STATIC_RESOURCES_CONTENT_ENCODING` Show more	Charset	`UTF-8`

Configuration property

タイプ

デフォルト

quarkus.http.static-resources.index-page

Set the index page when serving static resources.

Environment variable: QUARKUS_HTTP_STATIC_RESOURCES_INDEX_PAGE

string

index.html

quarkus.http.static-resources.include-hidden

Set whether hidden files should be served.

Environment variable: QUARKUS_HTTP_STATIC_RESOURCES_INCLUDE_HIDDEN

boolean

true

quarkus.http.static-resources.enable-range-support

Set whether range requests (resumable downloads; media streaming) should be enabled.

Environment variable: QUARKUS_HTTP_STATIC_RESOURCES_ENABLE_RANGE_SUPPORT

boolean

true

quarkus.http.static-resources.caching-enabled

Set whether cache handling is enabled.

Environment variable: QUARKUS_HTTP_STATIC_RESOURCES_CACHING_ENABLED

boolean

true

quarkus.http.static-resources.cache-entry-timeout

Set the cache entry timeout. The default is 30 seconds.

Environment variable: QUARKUS_HTTP_STATIC_RESOURCES_CACHE_ENTRY_TIMEOUT

Duration

30S

quarkus.http.static-resources.max-age

Set value for max age in caching headers. The default is 24 hours.

Environment variable: QUARKUS_HTTP_STATIC_RESOURCES_MAX_AGE

Duration

24H

quarkus.http.static-resources.max-cache-size

Set the max cache size.

Environment variable: QUARKUS_HTTP_STATIC_RESOURCES_MAX_CACHE_SIZE

int

10000

quarkus.http.static-resources.content-encoding

Content encoding for text related files

Environment variable: QUARKUS_HTTP_STATIC_RESOURCES_CONTENT_ENCODING

Charset

UTF-8

期間フォーマットについて

期間の値を書くには、標準の java.time.Duration フォーマットを使います。詳細は Duration#parse() Java API documentation を参照してください。

数字で始まる簡略化した書式を使うこともできます:

数値のみの場合は、秒単位の時間を表します。
数値の後に ms が続く場合は、ミリ秒単位の時間を表します。

その他の場合は、簡略化されたフォーマットが解析のために java.time.Duration フォーマットに変換されます：

数値の後に h 、 m 、 s が続く場合は、その前に PT が付けられます。
数値の後に d が続く場合は、その前に P が付けられます。

2. コンテキストパスの設定

デフォルトでは、 Quarkus はルートコンテキストの下からコンテンツを提供します。これを変更したい場合は、 quarkus.http.root-path 設定キーを使用してコンテキストパスを設定することができます。

Servlet を使用している場合は、quarkus.servlet.context-path を通して Servlet のコンテキストパスを制御することができます。この項目は、上記の http ルートに相対的で、Servlet と、Servlet の上で実行されるものにのみ影響します。多くのアプリケーションでは、Quarkus が提供するすべてのサービスに影響するため、HTTP ルートを使用することをお勧めします。

両方を指定した場合、サーブレット以外のすべてのウェブエンドポイントは quarkus.http.root-path からの相対的なものになり、サーブレットは {quarkus.http.root-path}/{quarkus.servlet.context-path} からの相対的なものになります。

テストに REST Assured を使用し、quarkus.http.root-path が設定されている場合、Quarkus は自動的に Quarkus テストで使用するためのベース URL を設定します。そのため、テストの URL はルートパスには含めないでください。

一般に、ウェブコンテンツのパス設定は、 quarkus.http.root-path ( デフォルトでは / ) からの相対パスとして解釈されます。

このコンテキストルート内のパスを指定するには、スラッシュで始まらない相対パスを使用します。
URIを明示的に指定し、 quarkus.http.root-path の値にかかわらず常に同じになるようにしたい場合は、スラッシュで始まる絶対パスを使用します。

例として、エクステンションが service というパスを設定した場合、そのエンドポイントは ${quarkus.http.root-path}/service から提供されます。そのパスの設定を /service に変更した場合、そのエンドポイントは /service から提供されるようになります。

Quarkus のパス解決に関するブログ記事では、ユーザー定義パスとエクステンション定義パスの両方に対するパス解決の仕組みについて詳しく説明しています。

マネジメントインターフェース

quarkus.http.root-path は、メインの HTTP サーバーにのみ使用されます。マネジメントインターフェイスを有効にした場合（ quarkus.management.enabled=true プロパティを使用）、マネジメントインターフェイスのルートパスは、次のように設定できます: quarkus.management.root-path 。

詳しくは、マネジメントインターフェイスのリファレンスを参照してください。

3. TLS/SSLによる安全な接続のサポート

Quarkusで安全な接続をサポートするには、証明書と関連するキーファイルを提供するか、キーストアを提供する必要があります。

いずれの場合も、パスワードを提供する必要があります。提供方法の詳細については、提供方法に関する段落を参照してください。

ネイティブ実行可能ファイルでの TLS/SSL サポートを有効にするには、ネイティブ実行可能ファイルでの SSL の使用ガイドを参照してください。

3.1. TLS 集中設定の使用

Quarkus は、サーバーの TLS コンテキストを設定するために使用できる TLS 集中設定を提供します。 HTTPS を設定することが推奨される方法です。

HTTPS を使用するために HTTP サーバーを設定するには、次の設定を使用できます。

quarkus.tls.key-store.pem.0.cert=server.crt
quarkus.tls.key-store.pem.0.key=server.key
quarkus.http.insecure-requests=disabled # Reject HTTP requests

p12 (PKCS12) キーストアを使用するには、次の設定を適用します。

quarkus.tls.key-store.p12.path=server-keystore.p12
quarkus.tls.key-store.p12.password=secret
quarkus.http.insecure-requests=disabled # Reject HTTP requests

デフォルト設定の代わりに、名前付き設定を使用できます。

quarkus.tls.https.key-store.p12.path=server-keystore.p12
quarkus.tls.https.key-store.p12.password=secret
quarkus.http.insecure-requests=disabled
quarkus.http.tls-configuration-name=https

3.2. HTTP サーバーの直接設定

TLS レジストリーを使用しない場合は、HTTP サーバーを直接設定できます。

証明書がキーストアにロードされていない場合は、以下のプロパティーを使用して直接提供することができます。Quarkus はまず、与えられたファイルをリソースとしてロードしようとし、ファイルシステムをフォールバックとして使用します。証明書/キーペアは、起動時に新しく作成されたキーストアにロードされます。

application.properties は次のようになります。

quarkus.http.ssl.certificate.files=/path/to/certificate
quarkus.http.ssl.certificate.key-files=/path/to/key

別の解決策としては、すでに証明書付きのデフォルトのエントリーを含むキーストアを直接提供する方法もあります。少なくともファイルとパスワードを提供する必要があります。

証明書とキーファイルの組み合わせと同様に、 Quarkus はまず、ファイルシステムからの読み込みを試みる前に、指定されたパスをリソースとして解決しようとします。

次のプロパティーを application.properties に追加します。

quarkus.http.ssl.certificate.key-store-file=/path/to/keystore

オプションのヒントとして、キーストアのタイプをオプションの1つとして指定できます。タイプが指定されていない場合、Quarkusはファイルの拡張子から推測しようとします。

quarkus.http.ssl.certificate.key-store-file-type=[one of JKS, JCEKS, P12, PKCS12, PFX]

前述のいずれのシナリオでも、キーストアを作成/ロードするためにパスワードを指定する必要があります。パスワードは、以下のプロパティーを使用して application.properties で (プレーンテキストで) 設定できます。

quarkus.http.ssl.certificate.key-store-password=your-password

しかし、設定ファイルでパスワードをプレーンテキストとして提供する代わりに (これは悪い習慣と考えられています)、環境変数 QUARKUS_HTTP_SSL_CERTIFICATE_KEY_STORE_PASSWORD として ( MicroProfile config を使用して) パスワードを提供することができます。これは、 Kubernetes secrets と連動します。

注意：Quarkusの以前のバージョン（0.16以前）との互換性を保つため、デフォルトのパスワードは "password "に設定されています。そのため、必須パラメータではありません！

3.3. HTTP ポートの設定

デフォルトでは、Quarkusは、SSLで保護された接続にポート8443を、テストの実行時にはポート8444をリッスンします。

これらのポートは、 application.properties のプロパティ quarkus.http.ssl-port と quarkus.http.test-ssl-port で設定することができます。

3.4. HTTP ポートの無効化

HTTP ポートを無効にして、セキュアなリクエストのみをサポートすることも可能です。これは application.properties の quarkus.http.insecure-requests プロパティーで行います。3 つの値を利用できます。

enabled: デフォルトでは、 HTTP は通常通りに動作します。
redirect: HTTP リクエストは HTTPS ポートにリダイレクトされます。
disabled: HTTP ポートは開放されません。

if you use redirect or disabled and have not added an SSL certificate or keystore, your server will not start!

3.5. 証明書の再読込

きーストア、トラスト・ストア、および証明書ファイルは、定期的にリロードできます。 quarkus.http.ssl.certificate.reload-period プロパティを設定して、証明書をリロードする間隔を指定します：

quarkus.http.ssl.certificate.files=/mount/certs/tls.crt
quarkus.http.ssl.certificate.key-files=/mount/certs/tls.key
quarkus.http.ssl.certificate.reload-period=1h

ファイルは最初に読み込まれたのと同じ場所から再読み込みされます。内容に変更がない場合、リロードは失敗します。リロードに失敗した場合、サーバは以前の証明書を使い続けます。

3.6. クライアントの再ネゴシエーションの防止

詳細は、クライアントの再ネゴシエーションの防止を参照してください。

4. 追加の HTTP ヘッダー

すべてのレスポンスに HTTP ヘッダーを送信するようにするには、以下のプロパティーを追加します。

quarkus.http.header."X-Content-Type-Options".value=nosniff

これにより、アプリケーション内の任意のリソースに対して実行されるリクエストのレスポンスに、 X-Content-Type-Options: nosniff HTTP ヘッダーが含まれます。

また、ヘッダーを適用する必要がある path パターンと HTTP methods を指定することもできます。

quarkus.http.header.Pragma.value=no-cache
quarkus.http.header.Pragma.path=/headers/pragma
quarkus.http.header.Pragma.methods=GET,HEAD

これにより、 /headers/pragma リソースが GET または HEAD メソッドで呼び出された場合にのみ、 Pragma ヘッダーが適用されます。

ビルド時に固定される設定プロパティ - それ以外の設定プロパティは実行時に上書き可能

Configuration property	タイプ	デフォルト
`quarkus.http.header."header".path` The path this header should be applied Environment variable: `QUARKUS_HTTP_HEADER__HEADER__PATH` Show more	string	`/*`
`quarkus.http.header."header".value` The value for this header configuration Environment variable: `QUARKUS_HTTP_HEADER__HEADER__VALUE` Show more	string	required
`quarkus.http.header."header".methods` The HTTP methods for this header configuration. If no HTTP methods are specified, the header will be always added. Environment variable: `QUARKUS_HTTP_HEADER__HEADER__METHODS` Show more	文字列のリスト

Configuration property

タイプ

デフォルト

quarkus.http.header."header".path

The path this header should be applied

Environment variable: QUARKUS_HTTP_HEADER__HEADER__PATH

string

/*

quarkus.http.header."header".value

The value for this header configuration

Environment variable: QUARKUS_HTTP_HEADER__HEADER__VALUE

string

required

quarkus.http.header."header".methods

The HTTP methods for this header configuration.

If no HTTP methods are specified, the header will be always added.

Environment variable: QUARKUS_HTTP_HEADER__HEADER__METHODS

文字列のリスト

4.1. パスごとの追加の HTTP ヘッダー

パスによって異なるヘッダー値が必要な場合は、以下のように設定することができます。

quarkus.http.filter.index.header."Cache-Control"=none
quarkus.http.filter.index.matches=/index.html

これにより、 /index.html が呼び出されたときに、 Cache-Control のヘッダに none が設定されます。

The index after quarkus.http.filter in the key is used for grouping and (as an example) can be named as you like.

パスには正規表現を使用でき、また HTTP ヘッダーが設定される HTTP メソッドを指定することもできます。

quarkus.http.filter.static.header."Cache-Control"=max-age=31536000
quarkus.http.filter.static.methods=GET,HEAD
quarkus.http.filter.static.matches=/static/.*

設定でパスが重複している場合、順序を指定することができます ( 値の大きい方が優先されます ) 。例えば、以下のような設定を持つ場合を考えます。

quarkus.http.filter.just-order.order=10
quarkus.http.filter.just-order.header."Cache-Control"=max-age=5000
quarkus.http.filter.just-order.matches=/paths/order

quarkus.http.filter.any-order.order=11
quarkus.http.filter.any-order.header."Cache-Control"=max-age=1
quarkus.http.filter.any-order.matches=/paths/order.*

/paths/order が要求されたときに Cache-Control: max-age=1 ヘッダを含めます。

ビルド時に固定される設定プロパティ - それ以外の設定プロパティは実行時に上書き可能

Configuration property	タイプ	デフォルト
`quarkus.http.filter."filter".matches` A regular expression for the paths matching this configuration Environment variable: `QUARKUS_HTTP_FILTER__FILTER__MATCHES` Show more	string	required
`quarkus.http.filter."filter".header."header-name"` Additional HTTP Headers always sent in the response Environment variable: `QUARKUS_HTTP_FILTER__FILTER__HEADER__HEADER_NAME_` Show more	Map<String,String>
`quarkus.http.filter."filter".methods` The HTTP methods for this path configuration Environment variable: `QUARKUS_HTTP_FILTER__FILTER__METHODS` Show more	文字列のリスト
`quarkus.http.filter."filter".order` Order in which this path config is applied. Higher priority takes precedence Environment variable: `QUARKUS_HTTP_FILTER__FILTER__ORDER` Show more	int

Configuration property

タイプ

デフォルト

quarkus.http.filter."filter".matches

A regular expression for the paths matching this configuration

Environment variable: QUARKUS_HTTP_FILTER__FILTER__MATCHES

string

required

quarkus.http.filter."filter".header."header-name"

Additional HTTP Headers always sent in the response

Environment variable: QUARKUS_HTTP_FILTER__FILTER__HEADER__HEADER_NAME_

Map<String,String>

quarkus.http.filter."filter".methods

The HTTP methods for this path configuration

Environment variable: QUARKUS_HTTP_FILTER__FILTER__METHODS

文字列のリスト

quarkus.http.filter."filter".order

Order in which this path config is applied. Higher priority takes precedence

Environment variable: QUARKUS_HTTP_FILTER__FILTER__ORDER

int

5. Vert.xにおける 100-continue のサポート

100-continue をサポートするには、 quarkus.http.handle-100-continue-automatically オプションを明示的に有効にする必要があります。詳細については、 100-continue と関連する Vert.x ドキュメントを参照してください。

quarkus.http.handle-100-continue-automatically=true

6. HTTP/2 サポート

HTTP/2はデフォルトで有効になっており、SSLが使用されている場合はブラウザで使用されます。 SSL が使用されていない場合でも、クリアテキストアップグレードによる HTTP/2 はサポートされており、ブラウザ以外のクライアントで使用される可能性があります。

HTTP/2 を無効にしたい場合は、以下を設定します。

quarkus.http.http2=false

いくつかの設定属性はHTTP/2に固有であることに注意してください。例えば、最大ヘッダーリストサイズ (~ヘッダー) を設定するには、 quarkus.http.limits.max-header-list-size 属性を設定する必要があります。また、 quarkus.http.http2-push-enabled を使用して、HTTP/2プッシュを有効または無効にすることもできます。

7. ランダムポートでの待ち受け

ポートを指定したくない場合は、 quarkus.http.port=0 または quarkus.http.test-port=0 を設定できます。OS によってランダムな空きポートが選択され、コンソールにログメッセージが表示されます。

実際のポートを取得するには、 io.quarkus.vertx.http.HttpServer API を使用します。これは CDI Bean としてアプリケーションコードにインジェクションできます。

import jakarta.inject.Singleton;
import io.quarkus.vertx.http.HttpServer;

@Singleton
public class MyService  {
    @Inject
    HttpServer httpServer;

    public void connectToServer() {
        int port = httpServer.getPort();
    }
}

または、フィールドまたはテストパラメーターとして、あらゆる種類のテストにインジェクションできます。

import org.junit.jupiter.api.Test;
import io.quarkus.test.junit.QuarkusTest;
import io.quarkus.vertx.http.HttpServer;

@QuarkusTest
class HttpServerTest {
    HttpServer httpServer;

    @Test
    void connectToServer(HttpServer httpServer) {
        int port = httpServer.getPort();
    }
}

Quarkus がサービスを提供している URI を取得するには、 HttpServer#getLocalBaseUri() を使用します。テストでは、 @TestHTTPResource を使用して URI を直接インジェクションできます。

@TestHTTPResource
URL testUrl;

REST Assured のように、実際の HTTP ポートを必要とするすべての Quarkus コンポーネントは、実際のポートで自動的に更新されます。

8. CORS フィルター

Quarkusアプリケーションを別のドメインで実行されている別のアプリケーションからアクセスできるようにするには、クロスオリジンリソース共有（CORS）を設定する必要があります。 Quarkusが提供するCORSフィルターの詳細については、クロスオリジンリソース共有ガイドのQuarkus CORSフィルターのセクションを参照してください。

9. HTTP Host header validation

Quarkus can validate the HTTP Host header on incoming requests to protect against DNS rebinding attacks and host header poisoning.

When quarkus.http.host is set to a localhost name (localhost, 127.0.0.1, or [::1]), host validation is automatically enabled in dev and production modes. Only requests whose Host header matches one of the known localhost names are accepted; all others receive a 400 Bad Request response.

This automatic behavior is a change from previous Quarkus versions, where no Host header validation was performed. If your application runs behind a reverse proxy that rewrites the Host header, you may need to either:

configure the allowed hosts explicitly with quarkus.http.host-validation.allowed-hosts, or
disable the automatic validation with quarkus.http.host-validation.require-localhost=false.

9.1. Configuring allowed hosts

To restrict requests to a specific set of host names, use allowed-hosts:

quarkus.http.host-validation.allowed-hosts=example.com,api.example.com

The check is case-insensitive and only validates the host name, not the port.

9.2. Requiring localhost only

To explicitly require that only localhost names are accepted:

quarkus.http.host-validation.require-localhost=true

To disable automatic localhost validation when the server is bound to a localhost address:

quarkus.http.host-validation.require-localhost=false

allowed-hosts and require-localhost are mutually exclusive. Setting both results in a configuration error.

9.3. Reverse proxy considerations

When running behind a reverse proxy, enable proxy header forwarding so that Quarkus validates the forwarded host instead of the proxy’s internal host name:

quarkus.http.proxy.proxy-address-forwarding=true
quarkus.http.proxy.allow-forwarded=true
quarkus.http.host-validation.allowed-hosts=public-api.example.com

This works with both the standard Forwarded header and the X-Forwarded-Host header.

ビルド時に固定される設定プロパティ - それ以外の設定プロパティは実行時に上書き可能

Configuration property	タイプ	デフォルト
`quarkus.http.host-validation.require-localhost` Require that HTTP Host authority can only contain valid localhost names such as "localhost", "127.0.0.1" or "[::1]". This requirement is enforced in production and dev modes, when neither this nor the `allowed-hosts()` properties are configured and the "quarkus.http.host" property has a valid localhost name. Set this property to `false` if it is not required. Note this property is mutually exclusive with the `allowed-hosts()` property. Environment variable: `QUARKUS_HTTP_HOST_VALIDATION_REQUIRE_LOCALHOST` Show more	boolean
`quarkus.http.host-validation.allowed-hosts` Allowed hosts. A comma-separated set of hosts, for example: "localhost", "quarkus.io". Note this property is mutually exclusive with the `require-localhost()` property. Environment variable: `QUARKUS_HTTP_HOST_VALIDATION_ALLOWED_HOSTS` Show more	文字列のリスト

Configuration property

タイプ

デフォルト

quarkus.http.host-validation.require-localhost

Require that HTTP Host authority can only contain valid localhost names such as "localhost", "127.0.0.1" or "[::1]".

This requirement is enforced in production and dev modes, when neither this nor the allowed-hosts() properties are configured and the "quarkus.http.host" property has a valid localhost name. Set this property to false if it is not required.

Note this property is mutually exclusive with the allowed-hosts() property.

Environment variable: QUARKUS_HTTP_HOST_VALIDATION_REQUIRE_LOCALHOST

boolean

quarkus.http.host-validation.allowed-hosts

Allowed hosts.

A comma-separated set of hosts, for example: "localhost", "quarkus.io".

Note this property is mutually exclusive with the require-localhost() property.

Environment variable: QUARKUS_HTTP_HOST_VALIDATION_ALLOWED_HOSTS

文字列のリスト

10. HTTP 制限の設定

ビルド時に固定される設定プロパティ - それ以外の設定プロパティは実行時に上書き可能

Configuration property	タイプ	デフォルト
`quarkus.http.limits.max-header-size` The maximum length of all headers, up to `Integer.MAX_VALUE` bytes. Environment variable: `QUARKUS_HTTP_LIMITS_MAX_HEADER_SIZE` Show more	MemorySize	`20K`
`quarkus.http.limits.max-body-size` The maximum size of a request body, up to `Long.MAX_VALUE` bytes. Environment variable: `QUARKUS_HTTP_LIMITS_MAX_BODY_SIZE` Show more	MemorySize	`10240K`
`quarkus.http.limits.max-chunk-size` The max HTTP chunk size, up to `Integer.MAX_VALUE` bytes. Environment variable: `QUARKUS_HTTP_LIMITS_MAX_CHUNK_SIZE` Show more	MemorySize	`8192`
`quarkus.http.limits.max-initial-line-length` The maximum length of the initial line (e.g. `"GET / HTTP/1.0"`). Environment variable: `QUARKUS_HTTP_LIMITS_MAX_INITIAL_LINE_LENGTH` Show more	int	`4096`
`quarkus.http.limits.max-form-attribute-size` The maximum length of a form attribute, up to `Integer.MAX_VALUE` bytes. Environment variable: `QUARKUS_HTTP_LIMITS_MAX_FORM_ATTRIBUTE_SIZE` Show more	MemorySize	`2048`
`quarkus.http.limits.max-form-fields` Set the maximum number of fields of a form. Set to `-1` to allow unlimited number of attributes. Environment variable: `QUARKUS_HTTP_LIMITS_MAX_FORM_FIELDS` Show more	int	`256`
`quarkus.http.limits.max-form-buffered-bytes` Set the maximum number of bytes a server can buffer when decoding a form. Set to `-1` to allow unlimited length, up to `Integer.MAX_VALUE` bytes. Environment variable: `QUARKUS_HTTP_LIMITS_MAX_FORM_BUFFERED_BYTES` Show more	MemorySize	`1K`
`quarkus.http.limits.max-parameters` The maximum number of HTTP request parameters permitted for incoming requests. If a client sends more than this number of parameters in a request, the connection is closed. Environment variable: `QUARKUS_HTTP_LIMITS_MAX_PARAMETERS` Show more	int	`1000`
`quarkus.http.limits.max-multipart-part-header-size` The maximum size of the headers section within a single MIME part of a `multipart/form-data` request. This limits the combined size of all header names and values for each individual part (e.g., the Content-Disposition and Content-Type headers), not the HTTP request headers. If a part’s headers exceed this limit, the request is rejected with HTTP 413. Environment variable: `QUARKUS_HTTP_LIMITS_MAX_MULTIPART_PART_HEADER_SIZE` Show more	MemorySize	`32K`
`quarkus.http.limits.max-multipart-header-count` The maximum number of headers allowed within a single MIME part of a `multipart/form-data` request. If a part contains more headers than this limit, the request is rejected with HTTP 413. Environment variable: `QUARKUS_HTTP_LIMITS_MAX_MULTIPART_HEADER_COUNT` Show more	int	`40`
`quarkus.http.limits.max-connections` The maximum number of connections that are allowed at any one time. If this is set it is recommended to set a short idle timeout. Environment variable: `QUARKUS_HTTP_LIMITS_MAX_CONNECTIONS` Show more	int
`quarkus.http.limits.header-table-size` Set the SETTINGS_HEADER_TABLE_SIZE HTTP/2 setting. Allows the sender to inform the remote endpoint of the maximum size of the header compression table used to decode header blocks, in octets. The encoder can select any size equal to or less than this value by using signaling specific to the header compression format inside a header block. The initial value is `4,096` octets. Environment variable: `QUARKUS_HTTP_LIMITS_HEADER_TABLE_SIZE` Show more	long
`quarkus.http.limits.max-concurrent-streams` Set SETTINGS_MAX_CONCURRENT_STREAMS HTTP/2 setting. Indicates the maximum number of concurrent streams that the sender will allow. This limit is directional: it applies to the number of streams that the sender permits the receiver to create. Initially, there is no limit to this value. It is recommended that this value be no smaller than 100, to not unnecessarily limit parallelism. Environment variable: `QUARKUS_HTTP_LIMITS_MAX_CONCURRENT_STREAMS` Show more	long
`quarkus.http.limits.max-frame-size` Set the SETTINGS_MAX_FRAME_SIZE HTTP/2 setting. Indicates the size of the largest frame payload that the sender is willing to receive, in octets. The initial value is `2^14` (16,384) octets. Environment variable: `QUARKUS_HTTP_LIMITS_MAX_FRAME_SIZE` Show more	int
`quarkus.http.limits.max-header-list-size` Set the SETTINGS_MAX_HEADER_LIST_SIZE HTTP/2 setting. This advisory setting informs a peer of the maximum size of header list that the sender is prepared to accept, in octets. The value is based on the uncompressed size of header fields, including the length of the name and value in octets plus an overhead of 32 octets for each header field. The default value is `8192` Environment variable: `QUARKUS_HTTP_LIMITS_MAX_HEADER_LIST_SIZE` Show more	long
`quarkus.http.limits.rst-flood-max-rst-frame-per-window` Set the max number of RST frame allowed per time window, this is used to prevent HTTP/2 RST frame flood DDOS attacks. The default value is `200`, setting zero or a negative value, disables flood protection. Environment variable: `QUARKUS_HTTP_LIMITS_RST_FLOOD_MAX_RST_FRAME_PER_WINDOW` Show more	int
`quarkus.http.limits.rst-flood-window-duration` Set the duration of the time window when checking the max number of RST frames, this is used to prevent HTTP/2 RST frame flood DDOS attacks.. The default value is `30 s`, setting zero or a negative value, disables flood protection. Environment variable: `QUARKUS_HTTP_LIMITS_RST_FLOOD_WINDOW_DURATION` Show more	Duration

Configuration property

タイプ

デフォルト

quarkus.http.limits.max-header-size

The maximum length of all headers, up to Integer.MAX_VALUE bytes.

Environment variable: QUARKUS_HTTP_LIMITS_MAX_HEADER_SIZE

MemorySize

20K

quarkus.http.limits.max-body-size

The maximum size of a request body, up to Long.MAX_VALUE bytes.

Environment variable: QUARKUS_HTTP_LIMITS_MAX_BODY_SIZE

MemorySize

10240K

quarkus.http.limits.max-chunk-size

The max HTTP chunk size, up to Integer.MAX_VALUE bytes.

Environment variable: QUARKUS_HTTP_LIMITS_MAX_CHUNK_SIZE

MemorySize

8192

quarkus.http.limits.max-initial-line-length

The maximum length of the initial line (e.g. "GET / HTTP/1.0").

Environment variable: QUARKUS_HTTP_LIMITS_MAX_INITIAL_LINE_LENGTH

int

4096

quarkus.http.limits.max-form-attribute-size

The maximum length of a form attribute, up to Integer.MAX_VALUE bytes.

Environment variable: QUARKUS_HTTP_LIMITS_MAX_FORM_ATTRIBUTE_SIZE

MemorySize

2048

quarkus.http.limits.max-form-fields

Set the maximum number of fields of a form. Set to -1 to allow unlimited number of attributes.

Environment variable: QUARKUS_HTTP_LIMITS_MAX_FORM_FIELDS

int

256

quarkus.http.limits.max-form-buffered-bytes

Set the maximum number of bytes a server can buffer when decoding a form. Set to -1 to allow unlimited length, up to Integer.MAX_VALUE bytes.

Environment variable: QUARKUS_HTTP_LIMITS_MAX_FORM_BUFFERED_BYTES

MemorySize

1K

quarkus.http.limits.max-parameters

The maximum number of HTTP request parameters permitted for incoming requests.

If a client sends more than this number of parameters in a request, the connection is closed.

Environment variable: QUARKUS_HTTP_LIMITS_MAX_PARAMETERS

int

1000

quarkus.http.limits.max-multipart-part-header-size

The maximum size of the headers section within a single MIME part of a multipart/form-data request. This limits the combined size of all header names and values for each individual part (e.g., the Content-Disposition and Content-Type headers), not the HTTP request headers.

If a part’s headers exceed this limit, the request is rejected with HTTP 413.

Environment variable: QUARKUS_HTTP_LIMITS_MAX_MULTIPART_PART_HEADER_SIZE

MemorySize

32K

quarkus.http.limits.max-multipart-header-count

The maximum number of headers allowed within a single MIME part of a multipart/form-data request.

If a part contains more headers than this limit, the request is rejected with HTTP 413.

Environment variable: QUARKUS_HTTP_LIMITS_MAX_MULTIPART_HEADER_COUNT

int

40

quarkus.http.limits.max-connections

The maximum number of connections that are allowed at any one time. If this is set it is recommended to set a short idle timeout.

Environment variable: QUARKUS_HTTP_LIMITS_MAX_CONNECTIONS

int

quarkus.http.limits.header-table-size

Set the SETTINGS_HEADER_TABLE_SIZE HTTP/2 setting.

Allows the sender to inform the remote endpoint of the maximum size of the header compression table used to decode header blocks, in octets. The encoder can select any size equal to or less than this value by using signaling specific to the header compression format inside a header block. The initial value is 4,096 octets.

Environment variable: QUARKUS_HTTP_LIMITS_HEADER_TABLE_SIZE

long

quarkus.http.limits.max-concurrent-streams

Set SETTINGS_MAX_CONCURRENT_STREAMS HTTP/2 setting.

Indicates the maximum number of concurrent streams that the sender will allow. This limit is directional: it applies to the number of streams that the sender permits the receiver to create. Initially, there is no limit to this value. It is recommended that this value be no smaller than 100, to not unnecessarily limit parallelism.

Environment variable: QUARKUS_HTTP_LIMITS_MAX_CONCURRENT_STREAMS

long

quarkus.http.limits.max-frame-size

Set the SETTINGS_MAX_FRAME_SIZE HTTP/2 setting. Indicates the size of the largest frame payload that the sender is willing to receive, in octets. The initial value is 2^14 (16,384) octets.

Environment variable: QUARKUS_HTTP_LIMITS_MAX_FRAME_SIZE

int

quarkus.http.limits.max-header-list-size

Set the SETTINGS_MAX_HEADER_LIST_SIZE HTTP/2 setting. This advisory setting informs a peer of the maximum size of header list that the sender is prepared to accept, in octets. The value is based on the uncompressed size of header fields, including the length of the name and value in octets plus an overhead of 32 octets for each header field. The default value is 8192

Environment variable: QUARKUS_HTTP_LIMITS_MAX_HEADER_LIST_SIZE

long

quarkus.http.limits.rst-flood-max-rst-frame-per-window

Set the max number of RST frame allowed per time window, this is used to prevent HTTP/2 RST frame flood DDOS attacks. The default value is 200, setting zero or a negative value, disables flood protection.

Environment variable: QUARKUS_HTTP_LIMITS_RST_FLOOD_MAX_RST_FRAME_PER_WINDOW

int

quarkus.http.limits.rst-flood-window-duration

Set the duration of the time window when checking the max number of RST frames, this is used to prevent HTTP/2 RST frame flood DDOS attacks.. The default value is 30 s, setting zero or a negative value, disables flood protection.

Environment variable: QUARKUS_HTTP_LIMITS_RST_FLOOD_WINDOW_DURATION

Duration

期間フォーマットについて

期間の値を書くには、標準の java.time.Duration フォーマットを使います。詳細は Duration#parse() Java API documentation を参照してください。

数字で始まる簡略化した書式を使うこともできます:

数値のみの場合は、秒単位の時間を表します。
数値の後に ms が続く場合は、ミリ秒単位の時間を表します。

その他の場合は、簡略化されたフォーマットが解析のために java.time.Duration フォーマットに変換されます：

数値の後に h 、 m 、 s が続く場合は、その前に PT が付けられます。
数値の後に d が続く場合は、その前に P が付けられます。

MemorySizeフォーマットについて

A size configuration option recognizes strings in this format (shown as a regular expression): [0-9]+[KkMmGgTtPpEeZzYy]?.

If no suffix is given, assume bytes.

11. トラフィックシェーピングの設定

トラフィックシェーピングを使用すると、開いているチャネルの数に関係なく、すべてのチャネル（つまり接続）の帯域幅を制限することができます。これは、ネットワーク全体のトラフィックを制御して輻輳を防止したり、特定の種類のトラフィックを優先したりする場合に便利です。

トラフィック・シェーピングを有効にするには、アプリケーション・コンフィグレーションに以下のプロパティを追加する：

quarkus.http.traffic-shaping.enabled=true # Required to enable traffic shaping

トラフィックシェーピングでは、書き込みと読み取りの制限（1秒あたりのバイト数）、チェック間隔（帯域幅の2回の計算間の遅延）、最大待機時間など、さまざまなパラメータを設定できます：

quarkus.http.traffic-shaping.enabled=true # Required to enable traffic shaping
quarkus.http.traffic-shaping.check-interval=30s
quarkus.http.traffic-shaping.outbound-global-bandwidth=1M
quarkus.http.traffic-shaping.inbound-global-bandwidth=1M
quarkus.http.traffic-shaping.max-delay=10s

チェック間隔は、トラフィックが計算される期間を表し、間隔が大きいほど、トラフィックシェーピングの精度が低くなる可能性があります。 0が受け入れられるにもかかわらず（アカウンティングなし）、トラフィックシェーピングの精度はトラフィックが計算される期間に依存するため、チェック間隔には高くても正の値を設定することを推奨します。この場合、5分または10分に近い値が推奨されます。

outbound-global-bandwidth 、 inbound-global-bandwidth パラメータは、それぞれ書き込みと読み出し操作の1秒あたりの最大バイト数を表します。また、読み取りまたは書き込み操作のオブジェクト・サイズを、必要な帯域幅に比較的適合させることも考慮する必要があります。例えば、10KB/秒に対して10MBのオブジェクトがあるとバースト効果が生じますが、1MB/秒に対して100KBのオブジェクトがあれば、トラフィックシェーピングによってスムーズに処理できるはずです。

さらに、最大待機時間 ( max-delay ) を設定できます。これは、タイムシェーピングの上限を指定するものです。デフォルトでは 15 秒に設定されています。これは HTTP タイムアウトより小さくなければなりません。しきい値のいずれかに達すると、その期間書き込みは行われません。

12. HTTP アクセスログの設定

application.properties で設定することで、HTTP リクエストのロギングを追加することができます。ロギングには、標準の JBoss ロギング出力にロギングするか、専用ファイルにロギングするかの 2 つのオプションがあります。

ビルド時に固定される設定プロパティ - それ以外の設定プロパティは実行時に上書き可能

Configuration property	タイプ	デフォルト
`quarkus.http.access-log.enabled` If access logging is enabled. By default this will log via the standard logging facility Environment variable: `QUARKUS_HTTP_ACCESS_LOG_ENABLED` Show more	boolean	`false`
`quarkus.http.access-log.exclude-pattern` A regular expression that can be used to exclude some paths from logging. Environment variable: `QUARKUS_HTTP_ACCESS_LOG_EXCLUDE_PATTERN` Show more	string
`quarkus.http.access-log.pattern` The access log pattern. If this is the string `common`, `combined` or `long` then this will use one of the specified named formats: common: `%h %l %u %t "%r" %s %b` - combined: `%h %l %u %t "%r" %s %b "%{i,Referer}" "%{i,User-Agent}"` - long: `%r\n%{ALL_REQUEST_HEADERS}` Otherwise, consult the Quarkus documentation for the full list of variables that can be used. Note that enabling the `%{ALL_REQUEST_HEADERS}` attribute directly or with a `long` named format introduces a risk of sensitive header values being logged. HTTP `Authorization` header value is always masked. Use the `masked-headers()` property to mask other sensitive headers. Environment variable: `QUARKUS_HTTP_ACCESS_LOG_PATTERN` Show more	string	`common`
`quarkus.http.access-log.masked-headers` Set of HTTP headers whose values must be masked when the `%{ALL_REQUEST_HEADERS}` attribute is enabled with the `pattern()` property. Environment variable: `QUARKUS_HTTP_ACCESS_LOG_MASKED_HEADERS` Show more	文字列のリスト
`quarkus.http.access-log.masked-cookies` Set of HTTP Cookie headers whose values must be masked when the `%{ALL_REQUEST_HEADERS}` attribute is enabled with the `pattern()` property. Environment variable: `QUARKUS_HTTP_ACCESS_LOG_MASKED_COOKIES` Show more	文字列のリスト
`quarkus.http.access-log.log-to-file` If logging should be done to a separate file. Environment variable: `QUARKUS_HTTP_ACCESS_LOG_LOG_TO_FILE` Show more	boolean	`false`
`quarkus.http.access-log.base-file-name` The access log file base name, defaults to 'quarkus' which will give a log file name of 'quarkus.log'. Environment variable: `QUARKUS_HTTP_ACCESS_LOG_BASE_FILE_NAME` Show more	string	`quarkus`
`quarkus.http.access-log.log-directory` The log directory to use when logging access to a file If this is not set then the current working directory is used. Environment variable: `QUARKUS_HTTP_ACCESS_LOG_LOG_DIRECTORY` Show more	string
`quarkus.http.access-log.log-suffix` The log file suffix Environment variable: `QUARKUS_HTTP_ACCESS_LOG_LOG_SUFFIX` Show more	string	`.log`
`quarkus.http.access-log.category` The log category to use if logging is being done via the standard log mechanism (i.e. if base-file-name is empty). Environment variable: `QUARKUS_HTTP_ACCESS_LOG_CATEGORY` Show more	string	`io.quarkus.http.access-log`
`quarkus.http.access-log.rotate` If the log should be rotated daily Environment variable: `QUARKUS_HTTP_ACCESS_LOG_ROTATE` Show more	boolean	`true`
`quarkus.http.access-log.consolidate-rerouted-requests` If rerouted requests should be consolidated into one log entry Environment variable: `QUARKUS_HTTP_ACCESS_LOG_CONSOLIDATE_REROUTED_REQUESTS` Show more	boolean	`false`

Configuration property

タイプ

デフォルト

quarkus.http.access-log.enabled

If access logging is enabled. By default this will log via the standard logging facility

Environment variable: QUARKUS_HTTP_ACCESS_LOG_ENABLED

boolean

false

quarkus.http.access-log.exclude-pattern

A regular expression that can be used to exclude some paths from logging.

Environment variable: QUARKUS_HTTP_ACCESS_LOG_EXCLUDE_PATTERN

string

quarkus.http.access-log.pattern

The access log pattern.

If this is the string common, combined or long then this will use one of the specified named formats:

common: %h %l %u %t "%r" %s %b - combined: %h %l %u %t "%r" %s %b "%{i,Referer}" "%{i,User-Agent}" - long: %r\n%{ALL_REQUEST_HEADERS}

Otherwise, consult the Quarkus documentation for the full list of variables that can be used. Note that enabling the %{ALL_REQUEST_HEADERS} attribute directly or with a long named format introduces a risk of sensitive header values being logged.

HTTP Authorization header value is always masked. Use the masked-headers() property to mask other sensitive headers.

Environment variable: QUARKUS_HTTP_ACCESS_LOG_PATTERN

string

common

quarkus.http.access-log.masked-headers

Set of HTTP headers whose values must be masked when the %{ALL_REQUEST_HEADERS} attribute is enabled with the pattern() property.

Environment variable: QUARKUS_HTTP_ACCESS_LOG_MASKED_HEADERS

文字列のリスト

quarkus.http.access-log.masked-cookies

Set of HTTP Cookie headers whose values must be masked when the %{ALL_REQUEST_HEADERS} attribute is enabled with the pattern() property.

Environment variable: QUARKUS_HTTP_ACCESS_LOG_MASKED_COOKIES

文字列のリスト

quarkus.http.access-log.log-to-file

If logging should be done to a separate file.

Environment variable: QUARKUS_HTTP_ACCESS_LOG_LOG_TO_FILE

boolean

false

quarkus.http.access-log.base-file-name

The access log file base name, defaults to 'quarkus' which will give a log file name of 'quarkus.log'.

Environment variable: QUARKUS_HTTP_ACCESS_LOG_BASE_FILE_NAME

string

quarkus

quarkus.http.access-log.log-directory

The log directory to use when logging access to a file

If this is not set then the current working directory is used.

Environment variable: QUARKUS_HTTP_ACCESS_LOG_LOG_DIRECTORY

string

quarkus.http.access-log.log-suffix

The log file suffix

Environment variable: QUARKUS_HTTP_ACCESS_LOG_LOG_SUFFIX

string

.log

quarkus.http.access-log.category

The log category to use if logging is being done via the standard log mechanism (i.e. if base-file-name is empty).

Environment variable: QUARKUS_HTTP_ACCESS_LOG_CATEGORY

string

io.quarkus.http.access-log

quarkus.http.access-log.rotate

If the log should be rotated daily

Environment variable: QUARKUS_HTTP_ACCESS_LOG_ROTATE

boolean

true

quarkus.http.access-log.consolidate-rerouted-requests

If rerouted requests should be consolidated into one log entry

Environment variable: QUARKUS_HTTP_ACCESS_LOG_CONSOLIDATE_REROUTED_REQUESTS

boolean

false

属性ショートフォーム長い形式

属性	ショートフォーム	長い形式
リモート IP アドレス	`%a`	`%{REMOTE_IP}`
ローカル IP アドレス	`%A`	`%{LOCAL_IP}`
HTTP ヘッダーを除く送信済みバイト数。送信されなかった場合は '-' 。	`%b`
HTTP ヘッダーを除く送信済みバイト数	`%B`	`%{BYTES_SENT}`
リモートホスト名	`%h`	`%{REMOTE_HOST}`
Remote logical username from identd (always returns '-')	`%l`
リクエストプロトコル	`%H`	`%{PROTOCOL}`
リクエストメソッド	`%m`	`%{METHOD}`
ローカルポート	`%p`	`%{LOCAL_PORT}`
クエリー文字列 ( 存在する場合は '?' が前に付き、そうでない場合は空文字列 )	`%q`	`%{QUERY_STRING}`
リクエストの最初の行	`%r`	`%{REQUEST_LINE}`
レスポンスの HTTP ステータスコード	`%s`	`%{RESPONSE_CODE}`
Common Log Format 形式の日時	`%t`	`%{DATE_TIME}`
DateTimeFormatter 準拠の文字列で定義された日付と時刻		`%{time,date_fime_formatter_string}`
認証されたリモートユーザー	`%u`	`%{REMOTE_USER}`
リクエストされた URL パス	`%U`	`%{REQUEST_URL}`
リクエストされた相対パス	`%R`	`%{REQUEST_PATH}`
ローカルサーバー名	`%v`	`%{LOCAL_SERVER_NAME}`
リクエストの処理にかかった時間 (ミリ秒 )	`%D`	`%{RESPONSE_TIME}`
リクエストの処理にかかった時間 ( 秒単位 )	`%T`
リクエストの処理にかかった時間 ( マイクロ秒 )		`%{RESPONSE_TIME_MICROS}`
リクエストの処理にかかった時間 ( ナノ秒 )		`%{RESPONSE_TIME_NANOS}`
現在のリクエストスレッド名	`%I`	`%{THREAD_NAME}`
SSL 暗号		`%{SSL_CIPHER}`
SSL クライアント証明書		`%{SSL_CLIENT_CERT}`
SSL セッション ID		`%{SSL_SESSION_ID}`
すべてのリクエストヘッダー		`%{ALL_REQUEST_HEADERS}`
クッキーの値		`%{c,cookie_name}`
クエリーパラメーター		`%{q,query_param_name}`
リクエストヘッダー		`%{i,request_header_name}`
レスポンスヘッダー		`%{o,response_header_name}`
Vert.x Routing Context の内部データ		`%{d,map_key}`
Vert.x Mapped Diagnostic Context ( MDC ) データ ( OpenTelemetry の 'traceId' など)		`%{X,mdc-key}`

リモート IP アドレス

%a

%{REMOTE_IP}

ローカル IP アドレス

%A

%{LOCAL_IP}

HTTP ヘッダーを除く送信済みバイト数。送信されなかった場合は '-' 。

%b

HTTP ヘッダーを除く送信済みバイト数

%B

%{BYTES_SENT}

リモートホスト名

%h

%{REMOTE_HOST}

Remote logical username from identd (always returns '-')

%l

リクエストプロトコル

%H

%{PROTOCOL}

リクエストメソッド

%m

%{METHOD}

ローカルポート

%p

%{LOCAL_PORT}

クエリー文字列 ( 存在する場合は '?' が前に付き、そうでない場合は空文字列 )

%q

%{QUERY_STRING}

リクエストの最初の行

%r

%{REQUEST_LINE}

レスポンスの HTTP ステータスコード

%s

%{RESPONSE_CODE}

Common Log Format 形式の日時

%t

%{DATE_TIME}

DateTimeFormatter 準拠の文字列で定義された日付と時刻

%{time,date_fime_formatter_string}

認証されたリモートユーザー

%u

%{REMOTE_USER}

リクエストされた URL パス

%U

%{REQUEST_URL}

リクエストされた相対パス

%R

%{REQUEST_PATH}

ローカルサーバー名

%v

%{LOCAL_SERVER_NAME}

リクエストの処理にかかった時間 (ミリ秒 )

%D

%{RESPONSE_TIME}

リクエストの処理にかかった時間 ( 秒単位 )

%T

リクエストの処理にかかった時間 ( マイクロ秒 )

%{RESPONSE_TIME_MICROS}

リクエストの処理にかかった時間 ( ナノ秒 )

%{RESPONSE_TIME_NANOS}

現在のリクエストスレッド名

%I

%{THREAD_NAME}

SSL 暗号

%{SSL_CIPHER}

SSL クライアント証明書

%{SSL_CLIENT_CERT}

SSL セッション ID

%{SSL_SESSION_ID}

すべてのリクエストヘッダー

%{ALL_REQUEST_HEADERS}

クッキーの値

%{c,cookie_name}

クエリーパラメーター

%{q,query_param_name}

リクエストヘッダー

%{i,request_header_name}

レスポンスヘッダー

%{o,response_header_name}

Vert.x Routing Context の内部データ

%{d,map_key}

Vert.x Mapped Diagnostic Context ( MDC ) データ ( OpenTelemetry の 'traceId' など)

%{X,mdc-key}

修飾子 < のサポートを有効にするには quarkus.http.access-log.consolidate-rerouted-requests=true を設定します。この修飾子は、元のリクエストを参照するために内部的にリダイレクトされたリクエストに使用できます。以下の属性がこの修飾子をサポートしています：

属性ショートフォーム長い形式

属性	ショートフォーム	長い形式
リクエストの最初の行	`%<r`	`%{<REQUEST_LINE}`
リクエストメソッド	`%<m`	`%{<METHOD}`
リクエストされた相対パス	`%<R`	`%{<REQUEST_PATH}`
リクエストされた URL パス	`%<U`	`%{<REQUEST_URL}`
クエリー文字列 ( 存在する場合は '?' が前に付き、そうでない場合は空文字列 )	`%<q`	`%{<QUERY_STRING}`
クエリーパラメーター		`%{<q,query_param_name}`

リクエストの最初の行

%<r

%{<REQUEST_LINE}

リクエストメソッド

%<m

%{<METHOD}

リクエストされた相対パス

%<R

%{<REQUEST_PATH}

リクエストされた URL パス

%<U

%{<REQUEST_URL}

クエリー文字列 ( 存在する場合は '?' が前に付き、そうでない場合は空文字列 )

%<q

%{<QUERY_STRING}

クエリーパラメーター

%{<q,query_param_name}

リクエストの処理にかかった時間のロギングに関連する属性のいずれかを使用する場合は、 quarkus.http.record-request-start-time=true を設定し、リクエスト開始時間の記録を有効にして下さい。

アプリケーションのセキュリティが設定されていると仮定すると（詳細はガイドを参照）、ロギング属性 Remote user that was authenticated には io.quarkus.security.identity.SecurityIdentity プリンシパルの値が設定されます。アプリケーションがカスタム Jakarta REST SecurityContext を使用する場合、代わりにコンテキストプリンシパルが使用されます。コンテキストログ情報を自分で追加する方法については、ロギングガイドを参照してください。

quarkus.http.access-log.exclude-pattern=/some/path/.* を使用すると、パス /some/path/… （ それ以降のパスも含む ）に関するすべてのエントリーをログから除外します。

13. 任意のカスタマイズ

Quarkusでは、 io.quarkus.vertx.http.HttpServerOptionsCustomizer を使用して、Quarkusが起動するHTTPサーバーのオプションを任意にカスタマイズできます。例えば、HTTPポートをプログラムで設定する必要がある場合、次のコードを使用できます:

import jakarta.inject.Singleton;
import io.quarkus.vertx.http.HttpServerOptionsCustomizer;

@Singleton (1)
public class MyCustomizer implements HttpServerOptionsCustomizer {

    @Override
    public void customizeHttpServer(HttpServerOptions options) { (2)
        options.setPort(9998);
    }
}

1	クラスをマネージドBeanにすることで、QuarkusはVert.xサーバーの起動時にカスタマイザーを考慮します。
2	この場合、HTTPサーバーのカスタマイズにしか関心がないので、 `customizeHttpServer` メソッドをオーバーライドするだけですが、 `HttpServerOptionsCustomizer` ではHTTPSサーバーとドメイン・ソケット・サーバーも設定できることに注意して下さい。

14. HTTP サーバーの起動時にロジックを実行する方法

HTTP サーバーの起動時にカスタムアクションを実行するには、非同期 の CDI オブザーバーメソッドを宣言する必要があります。 Quarkus は、対応する HTTP サーバーが設定されたホストとポートでリッスンを開始すると、io.quarkus.vertx.http.HttpServerStart、io.quarkus.vertx.http.HttpsServerStart、および io.quarkus.vertx.http.DomainSocketServerStart タイプの CDI イベントを 非同期的 に起動します。

HttpServerStart example

@ApplicationScoped
public class MyListener {

   void httpStarted(@ObservesAsync HttpServerStart start) { (1)
      // ...notified when the HTTP server starts listening
   }
}

1	非同期の `HttpServerStart` オブザーバーメソッドは、`HttpServerStart` パラメーターに `@jakarta.enterprise.event.ObservesAsync` をアノテーションすることで宣言できます。

It’s not possible to use the StartupEvent for this particular use case because this CDI event is fired before the HTTP server is started.

15. リバースプロキシーの背後での実行

Quarkus は、プロキシーサーバーが関与すると変更されたり失われたりするクライアント側の情報を保持するために、追加でヘッダー ( 例： X-Forwarded-Host ) を生成するプロキシーを介してアクセスされる可能性があります。このようなシナリオでは、 Quarkus は、これらのヘッダーの値を反映して、プロトコル、ホスト、ポート、 URI などの情報を自動的に更新するように設定することができます。

Activating this feature leaves the server exposed to several security issues (i.e. information spoofing). Consider activate it only when running behind a reverse proxy.

この機能を設定するには、 src/main/resources/application.properties に以下の行を記述してください。

quarkus.http.proxy.proxy-address-forwarding=true

デファクトスタンダードのヘッダー ( Forwarded header ) だけを考慮するためには、 src/main/resources/application.properties に以下の行を記述してください。

quarkus.http.proxy.allow-forwarded=true

非標準のヘッダーのみを考慮するには、代わりに以下の行を src/main/resources/application.properties に記述してください。

quarkus.http.proxy.proxy-address-forwarding=true
quarkus.http.proxy.allow-x-forwarded=true
quarkus.http.proxy.enable-forwarded-host=true
quarkus.http.proxy.enable-forwarded-prefix=true
quarkus.http.proxy.trusted-proxies=127.0.0.1 (1)

1	信頼できるプロキシをIPアドレス `127.0.0.1` で設定します。それ以外のアドレスからのリクエストヘッダーは無視されます。

Alternatively, in mTLS environments where proxy IP addresses are not stable (e.g., Kubernetes), you can trust a proxy by its TLS client certificate Subject DN. The proxy is trusted when its certificate’s Subject DN contains all components specified in any configured value. For example, CN=my-proxy,O=MyOrg matches a certificate with Subject DN CN=my-proxy,O=MyOrg,C=US. When no configured DN matches, forwarded headers are ignored and the original connection values are used:

quarkus.http.proxy.trusted-proxy[0].subject-dn=CN=my-proxy (1) (2) (3)
quarkus.http.proxy.trusted-proxy[1].subject-dn=CN=envoy-client,O=MyOrg

1	DNs must be in RFC 2253 format.
2	This option cannot be combined with `quarkus.http.proxy.trusted-proxies`.
3	TLS client authentication must be enabled via `quarkus.http.ssl.client-auth` set to `request` or `required`.

Configure enough DN components to uniquely identify your proxy. Using only CN=my-proxy will match any certificate with that CN, regardless of issuing organization.

When multiple CAs are trusted, different CAs could issue certificates with the same Subject DN. To also verify the trust anchor, reference a certificate alias in the HTTP server’s truststore. Both conditions must match — the Subject DN and the trust anchor. The following example uses the TLS centralized configuration to set up mTLS and proxy trust:

quarkus.tls.key-store.p12.path=server-keystore.p12
quarkus.tls.key-store.p12.password=secret
quarkus.tls.trust-store.p12.path=server-truststore.p12 (1)
quarkus.tls.trust-store.p12.password=secret
quarkus.http.ssl.client-auth=request

# Proxy trust
quarkus.http.proxy.proxy-address-forwarding=true
quarkus.http.proxy.allow-forwarded=true
quarkus.http.proxy.trusted-proxy[0].subject-dn=CN=my-proxy,O=MyOrg
quarkus.http.proxy.trusted-proxy[0].truststore-alias=my-proxy-ca (2)

1	The truststore must be configured via the TLS registry and must contain a certificate entry with alias `my-proxy-ca`.
2	The alias is resolved from `server-truststore.p12`.

When the truststore is configured with PEM certificates, aliases are assigned automatically as cert-0, cert-1, and so on, based on the order in the configuration:

quarkus.tls.trust-store.pem.certs=proxy-ca.crt,other-ca.crt (1)
quarkus.http.proxy.trusted-proxy[0].truststore-alias=cert-0 (2)

1	`proxy-ca.crt` becomes `cert-0`, `other-ca.crt` becomes `cert-1`.
2	References `proxy-ca.crt`.

Since PEM aliases depend on ordering, we recommend using a PKCS12 truststore to avoid certificate list ordering issues.

The configured Subject DN is trusted to be unique only among clients signed by the CA referenced by the truststore alias. Only reference a CA that you control or trust not to issue another certificate with the same Subject DN.

標準ヘッダーと非標準ヘッダーに関連する両方の設定を組み合わせることができますが、標準ヘッダーの設定が優先されます。ただし、これらを組み合わせると、プロキシーによって上書きされない forwarded ヘッダーを使用してクライアントがリクエストを偽造できるため、セキュリティーに影響があります。したがって、プロキシーはクライアントから予期しない Forwarded または X-Forwarded-* ヘッダーを削除する必要があります。

By default, the proto values from Forwarded and X-Forwarded-Proto headers are validated against the URI scheme syntax. Requests with an invalid proto value receive a 400 Bad Request response. To disable this validation, set the quarkus.http.proxy.forwarded-proto-validation configuration property to none.

サポートされている転送アドレスヘッダーは以下の通りです。

Forwarded
X-Forwarded-Proto
X-Forwarded-Host
X-Forwarded-Port
X-Forwarded-Ssl
X-Forwarded-Prefix

例えば、クッキー名と SameSite 属性を記載することで、 Quarkus のエンドポイントによって設定された任意のクッキーに SameSite クッキープロパティを簡単に追加することができます。

quarkus.http.same-site-cookie.jwt.value=Lax
quarkus.http.same-site-cookie.session.value=Strict

この設定では、 jwt クッキーは SameSite=Lax 属性を持ち、 session クッキーは SameSite=Strict 属性を持つことになります。

17. サーブレットの設定

サーブレットを使用するには、明示的に quarkus-undertow を含める必要があります。

pom.xml

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-undertow</artifactId>
</dependency>

build.gradle

implementation("io.quarkus:quarkus-undertow")

17.1. undertow-handlers.conf

undertow-handlers.conf ファイルを使用することで、 Undertow 述語言語を利用することができます。このファイルは、アプリケーション jar の META-INF ディレクトリーに配置する必要があります。このファイルには、Undertow 述語言語を使用して定義されたハンドラーが含まれています。

17.2. web.xml

設定ファイルとして web.xml を使用している場合は、src/main/resources/META-INF ディレクトリーに配置します。

17.3. 組み込みのルート・オーダー値

ルートオーダーの値は、Vert.x のルート io.vertx.ext.web.Route.order(int) 関数で指定される値です。

Quarkusは、特定のオーダー値を持ついくつかのルートを登録します。定数は io.quarkus.vertx.http.runtime.RouteConstants クラスで定義され、以下の表に記載されています。カスタムルートは、Quarkusやエクステンションが提供する機能を妨げないように、値20000以上のオーダーを定義する必要があります。

io.quarkus.vertx.http.runtime.RouteConstants で定義されているルート順定数および既知の拡張：

ルートオーダー値

定数名

起源

Integer.MIN_VALUE

ROUTE_ORDER_ACCESS_LOG_HANDLER

コンフィギュレーションで有効になっていれば、アクセスログハンドラ。

Integer.MIN_VALUE

ROUTE_ORDER_RECORD_START_TIME

コンフィギュレーションで有効になっていれば、開始時間を追加するハンドラ。

Integer.MIN_VALUE

ROUTE_ORDER_HOT_REPLACEMENT

-代替ボディ・ハンドラー。

Integer.MIN_VALUE

ROUTE_ORDER_HEADERS

コンフィギュレーションで指定されたヘッダーを追加するハンドラ。

Integer.MIN_VALUE + 1

ROUTE_ORDER_HOST_VALIDATION_MANAGEMENT

Host validation handler of the management router.

Integer.MIN_VALUE + 2

ROUTE_ORDER_CORS_MANAGEMENT

管理ルーターのCORS-Originハンドラ。

Integer.MIN_VALUE + 3

ROUTE_ORDER_BODY_HANDLER_MANAGEMENT

管理ルーターのボディハンドラ。

Integer.MIN_VALUE + 1

ROUTE_ORDER_BODY_HANDLER

ボディハンドラー

-2

ROUTE_ORDER_UPLOAD_LIMIT

アップロードボディのサイズ制限を実施するルート。

0

ROUTE_ORDER_COMPRESSION

圧縮ハンドラ。

1000

ROUTE_ORDER_BEFORE_DEFAULT

デフォルトルートよりも優先されるルート（この値からオフセットを追加する）。

10000

ROUTE_ORDER_DEFAULT

デフォルトのルート順序（すなわち、静的リソース、サーブレット）。

20000

ROUTE_ORDER_AFTER_DEFAULT

デフォルトルートより優先されないルート（この値からオフセットを追加）

17.4. Undertow の設定

Undertow Servlet エクステンションを使用する場合、以下の設定プロパティーを使用できます。

設定プロパティタイプデフォルト説明

設定プロパティ	タイプ	デフォルト	説明
`quarkus.undertow.disallowed-methods`	文字列のリスト	`<空>`	`405 Method Not Allowed` で拒否すべき HTTP メソッドのリスト。 `TRACE` や `TRACK` などの安全でないメソッドを無効にするのに便利です。例: ---- quarkus.undertow.disallowed-methods=TRACE,TRACK ----
`quarkus.undertow.record-request-start-time`	boolean	false	有効にすると、 Undertow はリクエスト開始のタイムスタンプを記録します。タイミング計測、ロギング、およびリクエストトレースに役立ちます。
`quarkus.undertow.max-parameters`	int	1000	許可される HTTP パラメーターの最大数。パラメーターベースの DoS 攻撃に対する保護を提供します。

quarkus.undertow.disallowed-methods

文字列のリスト

<空>

405 Method Not Allowed で拒否すべき HTTP メソッドのリスト。 TRACE や TRACK などの安全でないメソッドを無効にするのに便利です。

例: ---- quarkus.undertow.disallowed-methods=TRACE,TRACK ----

quarkus.undertow.record-request-start-time

boolean

false

有効にすると、 Undertow はリクエスト開始のタイムスタンプを記録します。タイミング計測、ロギング、およびリクエストトレースに役立ちます。

quarkus.undertow.max-parameters

int

1000

許可される HTTP パラメーターの最大数。パラメーターベースの DoS 攻撃に対する保護を提供します。

HTTP Reference

1. 静的リソースの提供

1.1. アプリケーションjarから

1.2. webjars や mvnpm などの Web 依存関係から

1.3. ローカルディレクトリから

1.4. ローカルファイルシステムの静的リソース

1.5. HTTP圧縮

1.6. その他の設定

2. コンテキストパスの設定

3. TLS/SSLによる安全な接続のサポート

3.1. TLS 集中設定の使用

3.2. HTTP サーバーの直接設定

3.3. HTTP ポートの設定

3.4. HTTP ポートの無効化

3.5. 証明書の再読込

3.6. クライアントの再ネゴシエーションの防止

4. 追加の HTTP ヘッダー

4.1. パスごとの追加の HTTP ヘッダー

5. Vert.xにおける 100-continue のサポート

6. HTTP/2 サポート

7. ランダムポートでの待ち受け

8. CORS フィルター

9. HTTP Host header validation

9.1. Configuring allowed hosts

9.2. Requiring localhost only

9.3. Reverse proxy considerations

10. HTTP 制限の設定

11. トラフィックシェーピングの設定

12. HTTP アクセスログの設定

13. 任意のカスタマイズ

14. HTTP サーバーの起動時にロジックを実行する方法

15. リバースプロキシーの背後での実行

17. サーブレットの設定

17.1. undertow-handlers.conf

17.2. web.xml

17.3. 組み込みのルート・オーダー値

17.4. Undertow の設定

関連コンテンツ

同じエクステンションについて

同じトピックについて

HTTP Reference

1. 静的リソースの提供

1.1. アプリケーションjarから

1.2. webjars や mvnpm などの Web 依存関係から

1.3. ローカルディレクトリから

1.4. ローカルファイルシステムの静的リソース

1.5. HTTP圧縮

1.6. その他の設定

2. コンテキストパスの設定

3. TLS/SSLによる安全な接続のサポート

3.1. TLS 集中設定の使用

3.2. HTTP サーバーの直接設定

3.3. HTTP ポートの設定

3.4. HTTP ポートの無効化

3.5. 証明書の再読込

3.6. クライアントの再ネゴシエーションの防止

4. 追加の HTTP ヘッダー

4.1. パスごとの追加の HTTP ヘッダー

5. Vert.xにおける 100-continue のサポート

6. HTTP/2 サポート

7. ランダムポートでの待ち受け

8. CORS フィルター

9. HTTP Host header validation

9.1. Configuring allowed hosts

9.2. Requiring localhost only

9.3. Reverse proxy considerations

10. HTTP 制限の設定

11. トラフィックシェーピングの設定

12. HTTP アクセスログの設定

13. 任意のカスタマイズ

14. HTTP サーバーの起動時にロジックを実行する方法

15. リバースプロキシーの背後での実行

16. SameSite クッキー

17. サーブレットの設定

17.1. undertow-handlers.conf

17.2. web.xml

17.3. 組み込みのルート・オーダー値

17.4. Undertow の設定

関連コンテンツ

同じエクステンションについて

同じトピックについて