バージョン:

HTTP リファレンス

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

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

Undertow が存在する場合、RESTEasy はサーブレットフィルターとして機能します。Undertow が存在しない場合、RESTEasy はサーブレットを介さずに Vert.x 上で直接動作します。

1. 静的リソースの提供

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

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

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

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

WebJars 、 mvnpm 、および importmaps の使用方法の詳細については、 Web dependency locator ガイドを参照してください。

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

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

例えば、現在のパスからの相対パスである static/ ディレクトリーにあるリソースを http://localhost:8080/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. ローカルファイルシステムの静的リソース

quarkus.http.static-dir.path が設定されている場合、ローカルファイルシステムのディレクトリーからの静的リソースの提供が有効になります。 quarkus.http.static-dir.enabled プロパティーを使用して、この機能を明示的に無効にすることもできます。

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 圧縮

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

デフォルトでは、以下のメディアタイプのリストが圧縮されます。 text/html 、 text/plain 、 text/xml 、 text/css 、 text/javascript 、 application/javascript 、 application/json 、 application/graphql+json 、および application/xhtml+xml 。

クライアントがリクエストヘッダー（例: Accept-Encoding: deflate, gzip, br ）で HTTP 圧縮への対応を明示していない場合、レスポンスボディは圧縮されません。

Brotli 圧縮はデフォルトでは利用できません。 quarkus.http.compressors=deflate,gzip,br を設定することで有効にできます。ネイティブイメージをビルドする場合、実行可能ファイルのサイズが約 1MB 増加します。

1.6. その他の設定

さらに、静的リソースのインデックスページをデフォルトの index.html から変更したり、隠しファイル（例: ドットファイル）を提供しないように指定したり、範囲リクエスト（range requests）を無効にしたり、キャッシュサポート（例: キャッシュヘッダーやファイルプロパティーのキャッシュ）を設定したりできます。

ビルド時に固定される設定プロパティ - その他の設定プロパティは実行時にオーバーライド可能です。

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	ブーリアン	`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	ブーリアン	`true`
`quarkus.http.static-resources.caching-enabled` Set whether cache handling is enabled. Environment variable: `QUARKUS_HTTP_STATIC_RESOURCES_CACHING_ENABLED` Show more	ブーリアン	`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

ブーリアン

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

ブーリアン

true

quarkus.http.static-resources.caching-enabled

Set whether cache handling is enabled.

Environment variable: QUARKUS_HTTP_STATIC_RESOURCES_CACHING_ENABLED

ブーリアン

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 ルートを使用することをお勧めします。

両方が指定されている場合、すべての非 Servlet Web エンドポイントは quarkus.http.root-path からの相対パスになり、Servlet のエンドポイントは {quarkus.http.root-path}/{quarkus.servlet.context-path} からの相対パスで提供されます。

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

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

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

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

Path Resolution in Quarkus ブログ記事では、ユーザー定義およびエクステンション定義の両方のパスに対してパス解決がどのように機能するかを詳しく説明しています。

管理インターフェース

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

詳細については、管理インターフェースリファレンスを参照してください。

3. TLS/SSL によるセキュアな接続のサポート

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

どちらの場合も、パスワードを提供する必要があります。提供方法の詳細については、指定されたパラグラフを参照してください。

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

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

オプションのヒントとして、リストされているオプションのいずれかとしてキーストアのタイプを指定できます。タイプが指定されない場合、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 シークレットと組み合わせて動作させることもできます。

注意: 以前のバージョンの Quarkus (0.16 未満) との互換性を維持するため、デフォルトのパスワードは "password" に設定されています。したがって、これは必須のパラメーターではありません。

3.3. HTTPS ポートの設定

デフォルトでは、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 ポートは開かれません。

redirect または disabled を使用し、SSL 証明書またはキーストアを追加していない場合、サーバーは起動しません。

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

これにより、 GET または HEAD メソッドで /headers/pragma リソースが呼び出された場合にのみ 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 に設定されます。

キーの quarkus.http.filter の後にある index はグルーピングに使用され、（例として）好きな名前に設定できます。

パスで正規表現を使用したり、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/.*

設定でパスが重複する場合、順序（order）を指定できます（値が大きいほど優先されます）。例えば、以下のような設定の場合、

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 フィルターの詳細については、「Cross-origin resource sharing」ガイドの Quarkus CORS フィルターセクションを参照してください。

9. 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-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	長
`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	長
`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	長
`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-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

長

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

長

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

長

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.

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

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

トラフィックシェーピングを有効にするには、アプリケーション設定に以下のプロパティーを追加します。

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

トラフィックシェーピングでは、書き込みおよび読み取りの制限（バイト/秒）、チェック間隔（帯域幅の 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 秒あたりの最大バイト数を表します。また、読み取りまたは書き込み操作のオブジェクトサイズを、要求した帯域幅に相対的に適応させることも考慮する必要があります。例えば、10 KB/s に対して 10 MB のオブジェクトがあるとバースト効果が発生しますが、1 MB/s に対して 100 KB のオブジェクトがあれば、トラフィックシェーピングによってスムーズに処理されます。

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

11. 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	ブーリアン	`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	ブーリアン	`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	ブーリアン	`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	ブーリアン	`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

ブーリアン

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

ブーリアン

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

ブーリアン

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

ブーリアン

false

属性短縮形式完全形式

属性	短縮形式	完全形式
リモート IP アドレス	`%a`	`%{REMOTE_IP}`
ローカル IP アドレス	`%A`	`%{LOCAL_IP}`
送信されたバイト数（HTTP ヘッダーを除く）、送信されなかった場合は '-'	`%b`
送信されたバイト数（HTTP ヘッダーを除く）	`%B`	`%{BYTES_SENT}`
リモートホスト名	`%h`	`%{REMOTE_HOST}`
リクエストプロトコル	`%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 暗号（cypher）		`%{SSL_CIPHER}`
SSL クライアント証明書		`%{SSL_CLIENT_CERT}`
SSL セッション ID		`%{SSL_SESSION_ID}`
すべてのリクエストヘッダー		`%{ALL_REQUEST_HEADERS}`
Cookie の値		`%{c,cookie_name}`
クエリパラメーター		`%{q,query_param_name}`
リクエストヘッダー		`%{i,request_header_name}`
レスポンスヘッダー		`%{o,response_header_name}`
Vert.x ルーティングコンテキストの内部データ		`%{d,map_key}`
Vert.x MDC データ（例: OpenTelemetry の 'traceId'）		`%{X,mdc-key}`

リモート IP アドレス

%a

%{REMOTE_IP}

ローカル IP アドレス

%A

%{LOCAL_IP}

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

%b

送信されたバイト数（HTTP ヘッダーを除く）

%B

%{BYTES_SENT}

リモートホスト名

%h

%{REMOTE_HOST}

リクエストプロトコル

%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 暗号（cypher）

%{SSL_CIPHER}

SSL クライアント証明書

%{SSL_CLIENT_CERT}

SSL セッション ID

%{SSL_SESSION_ID}

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

%{ALL_REQUEST_HEADERS}

Cookie の値

%{c,cookie_name}

クエリパラメーター

%{q,query_param_name}

リクエストヘッダー

%{i,request_header_name}

レスポンスヘッダー

%{o,response_header_name}

Vert.x ルーティングコンテキストの内部データ

%{d,map_key}

Vert.x 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 を使用している場合は、代わりにコンテキストプリンシパルが使用されます。独自にコンテキストログ情報を追加するオプションについては、ロギングガイドを参照してください。

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

12. 任意のカスタマイズ

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 およびドメインソケットサーバーも設定可能であることに注意してください。

13. HTTP サーバー起動時のロジック実行方法

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

HttpServerStart の例

@ApplicationScoped
public class MyListener {

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

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

この特定のユースケースに StartupEvent を使用することはできません。なぜなら、この CDI イベントは HTTP サーバーが起動する前に発火されるためです。

14. リバースプロキシ配下での実行

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

この機能を有効にすると、サーバーがいくつかのセキュリティー問題 (情報のなりすましなど) にさらされることになります。リバースプロキシの背後で実行する場合にのみ有効にすることを検討してください。

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

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

デファクトスタンダードのヘッダー (Forwarded ヘッダー) のみを考慮するには、 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` で設定します。他のアドレスからのリクエストヘッダーは無視されます。

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

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

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

Quarkus エンドポイントによって設定される任意のクッキーに、 SameSite クッキープロパティーを簡単に追加できます。これには、以下のようにクッキー名と SameSite 属性をリストします。

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

この設定により、 jwt クッキーには SameSite=Lax 属性が付与され、 session クッキーには SameSite=Strict 属性が付与されます。

16. Servlet 設定

Servlet を使用するには、明示的に quarkus-undertow を含める必要があります。

pom.xml

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

build.gradle

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

16.1. undertow-handlers.conf

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

16.2. web.xml

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

16.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_BODY_HANDLER_MANAGEMENT

マネジメントルーターのボディハンドラー。

Integer.MIN_VALUE

ROUTE_ORDER_HEADERS

設定で指定されたヘッダーを追加するハンドラー。

Integer.MIN_VALUE

ROUTE_ORDER_CORS_MANAGEMENT

マネジメントルーターの CORS-Origin ハンドラー。

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

デフォルトのルート順序 (静的リソース、 Servlet など)。

20000

ROUTE_ORDER_AFTER_DEFAULT

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

16.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 攻撃に対する保護を提供します。

1. 静的リソースの提供
2. コンテキストパスの設定
3. TLS/SSL によるセキュアな接続のサポート
4. 追加の HTTP ヘッダー
- 4.1. パスごとの追加 HTTP ヘッダー
5. Vert.x での 100-Continue のサポート
6. HTTP/2 サポート
7. ランダムなポートでのリスニング
8. CORS フィルター
9. HTTP 制限の設定
10. トラフィックシェーピングの設定
11. HTTP アクセスログの設定
12. 任意のカスタマイズ
13. HTTP サーバー起動時のロジック実行方法
14. リバースプロキシ配下での実行
15. SameSite クッキー
16. Servlet 設定

HTTP リファレンス

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. HTTPS ポートの設定

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 制限の設定

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

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

12. 任意のカスタマイズ

13. HTTP サーバー起動時のロジック実行方法

14. リバースプロキシ配下での実行

16. Servlet 設定

16.1. undertow-handlers.conf

16.2. web.xml

16.3. 組み込みのルート順序値

16.4. Undertow の設定

関連コンテンツ

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

同じトピックについて

HTTP リファレンス

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. HTTPS ポートの設定

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 制限の設定

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

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

12. 任意のカスタマイズ

13. HTTP サーバー起動時のロジック実行方法

14. リバースプロキシ配下での実行

15. SameSite クッキー

16. Servlet 設定

16.1. undertow-handlers.conf

16.2. web.xml

16.3. 組み込みのルート順序値

16.4. Undertow の設定

関連コンテンツ

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

同じトピックについて