The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.

HTTPリファレンス

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

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

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

1. Serving static resources

If you are looking to use Quarkus for a web application, look at the Quarkus for the Web guide.

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

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

1.2. From mvnpm

If you are using mvnpm, as for the following JQuery dependency:

pom.xml
<dependency>
    <groupId>org.mvnpm</groupId>
    <artifactId>bootstrap</artifactId>
    <version>5.3.3</version>
    <scope>runtime</scope>
</dependency>
build.gradle
runtimeOnly("org.mvnpm:bootstrap:5.3.3")

You can import it in your HTML like this:

<script src="_static/bootstrap/5.3.3/dist/css/bootstrap.min.css"></script>

1.3. WebJarsから

以下の JQuery のように webjar を使用している場合を考えます。

pom.xml
<dependency>
    <groupId>org.webjars</groupId>
    <artifactId>jquery</artifactId>
    <version>3.1.1</version>
</dependency>
build.gradle
implementation("org.webjars:jquery:3.1.1")

HTMLファイルに /webjars/jquery/3.1.1/jquery.min.js の代わりに /webjars/jquery/jquery.min.js と書き、プロジェクトに quarkus-webjars-locator という拡張を追加することができます。これを使用するには、プロジェクトの依存関係に以下を追加します。

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-webjars-locator</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-webjars-locator")

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

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.5. HTTP圧縮

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

デフォルトでは、 text/html , text/plain , text/xml , text/css , text/javascript , application/javascript のメディアタイプが圧縮されます。
クライアントが HTTP 圧縮をサポートしていない場合、レスポンスボディは圧縮されません。

1.6. その他の設定

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

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

Configuration property

デフォルト

Set the index page when serving static resources.

Environment variable: QUARKUS_HTTP_STATIC_RESOURCES_INDEX_PAGE

Show more

string

index.html

Set whether hidden files should be served.

Environment variable: QUARKUS_HTTP_STATIC_RESOURCES_INCLUDE_HIDDEN

Show more

boolean

true

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

Environment variable: QUARKUS_HTTP_STATIC_RESOURCES_ENABLE_RANGE_SUPPORT

Show more

boolean

true

Set whether cache handling is enabled.

Environment variable: QUARKUS_HTTP_STATIC_RESOURCES_CACHING_ENABLED

Show more

boolean

true

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

Environment variable: QUARKUS_HTTP_STATIC_RESOURCES_CACHE_ENTRY_TIMEOUT

Show more

Duration

30S

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

Set the max cache size.

Environment variable: QUARKUS_HTTP_STATIC_RESOURCES_MAX_CACHE_SIZE

Show more

int

10000

Content encoding for text related files

Environment variable: QUARKUS_HTTP_STATIC_RESOURCES_CONTENT_ENCODING

Show more

Charset

UTF-8

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

To write duration values, use the standard java.time.Duration format. See the Duration#parse() Java API documentation for more information.

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

  • 数値のみの場合は、秒単位の時間を表します。

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

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

  • 数値の後に hms が続く場合は、その前に 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. 証明書とキーファイルの提供

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

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

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

3.2. キーストアの提供

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

証明書とキーファイルの組み合わせと同様に、 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]

3.3. パスワードの設定

前述のいずれのシナリオでも、キーストアを作成/ロードするためにパスワードを指定する必要があります。パスワードは、以下のプロパティーを使用して 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.4. HTTP ポートの設定

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

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

3.5. HTTP ポートの無効化

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

enabled

デフォルトでは、 HTTP は通常通りに動作します。

redirect

HTTP リクエストは HTTPS ポートにリダイレクトされます。

disabled

HTTP ポートは開放されません。

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

3.6. 証明書の再読込

きーストア、トラスト・ストア、および証明書ファイルは、定期的にリロードできます。 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

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

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

デフォルト

The path this header should be applied

Environment variable: QUARKUS_HTTP_HEADER__HEADER__PATH

Show more

string

/*

The value for this header configuration

Environment variable: QUARKUS_HTTP_HEADER__HEADER__VALUE

Show more

string

required

The HTTP methods for this header configuration

Environment variable: QUARKUS_HTTP_HEADER__HEADER__METHODS

Show more

list of string

The path this header should be applied

Environment variable: QUARKUS_MANAGEMENT_HEADER__HEADER__PATH

Show more

string

/*

The value for this header configuration

Environment variable: QUARKUS_MANAGEMENT_HEADER__HEADER__VALUE

Show more

string

required

The HTTP methods for this header configuration

Environment variable: QUARKUS_MANAGEMENT_HEADER__HEADER__METHODS

Show more

list of string

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/.*

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

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

デフォルト

A regular expression for the paths matching this configuration

Environment variable: QUARKUS_HTTP_FILTER__FILTER__MATCHES

Show more

string

required

Additional HTTP Headers always sent in the response

Environment variable: QUARKUS_HTTP_FILTER__FILTER__HEADER

Show more

Map<String,String>

The HTTP methods for this path configuration

Environment variable: QUARKUS_HTTP_FILTER__FILTER__METHODS

Show more

list of string

Environment variable: QUARKUS_HTTP_FILTER__FILTER__ORDER

int

A regular expression for the paths matching this configuration

Environment variable: QUARKUS_MANAGEMENT_FILTER__FILTER__MATCHES

Show more

string

required

Additional HTTP Headers always sent in the response

Environment variable: QUARKUS_MANAGEMENT_FILTER__FILTER__HEADER

Show more

Map<String,String>

The HTTP methods for this path configuration

Environment variable: QUARKUS_MANAGEMENT_FILTER__FILTER__METHODS

Show more

list of string

Environment variable: QUARKUS_MANAGEMENT_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 によって選ばれ、コンソールにログメッセージが表示されます。ポートがバインドされると、quarkus.http.port システムプロパティーには選択された実際のポートが設定されます。そのため、これを利用して、アプリケーション内から実際のポート番号を取得できます。テスト中の場合は普通に URL を注入することができ、これは実際のポートで設定され、REST Assured も適切に設定されます。

これはシステムプロパティを設定するものなので、MicroProfile Config から quarkus.http.port にアクセスできます。ただし、インジェクションを使用した場合は、注入された値が常に正しいとは限りません。このポート割り当ては、Quarkus の起動時に最後に起こることの 1 つなので、インジェクションされるオブジェクトがポートが開く前にしきりに作成された場合、インジェクションされた値は正しくなりません。

8. CORS フィルター

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

9. HTTP 制限の設定

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

Configuration property

デフォルト

The maximum length of all headers.

Environment variable: QUARKUS_HTTP_LIMITS_MAX_HEADER_SIZE

Show more

MemorySize

20K

The maximum size of a request body.

Environment variable: QUARKUS_HTTP_LIMITS_MAX_BODY_SIZE

Show more

MemorySize

10240K

The max HTTP chunk size

Environment variable: QUARKUS_HTTP_LIMITS_MAX_CHUNK_SIZE

Show more

MemorySize

8192

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

The maximum length of a form attribute.

Environment variable: QUARKUS_HTTP_LIMITS_MAX_FORM_ATTRIBUTE_SIZE

Show more

MemorySize

2048

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

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

Environment variable: QUARKUS_HTTP_LIMITS_MAX_FORM_BUFFERED_BYTES

Show more

MemorySize

1K

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

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

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

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

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

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

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

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

The maximum length of all headers.

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_HEADER_SIZE

Show more

MemorySize

20K

The maximum size of a request body.

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_BODY_SIZE

Show more

MemorySize

10240K

The max HTTP chunk size

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_CHUNK_SIZE

Show more

MemorySize

8192

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

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_INITIAL_LINE_LENGTH

Show more

int

4096

The maximum length of a form attribute.

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_FORM_ATTRIBUTE_SIZE

Show more

MemorySize

2048

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

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_FORM_FIELDS

Show more

int

256

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

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_FORM_BUFFERED_BYTES

Show more

MemorySize

1K

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_MANAGEMENT_LIMITS_MAX_PARAMETERS

Show more

int

1000

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_MANAGEMENT_LIMITS_MAX_CONNECTIONS

Show more

int

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_MANAGEMENT_LIMITS_HEADER_TABLE_SIZE

Show more

long

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_MANAGEMENT_LIMITS_MAX_CONCURRENT_STREAMS

Show more

long

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_MANAGEMENT_LIMITS_MAX_FRAME_SIZE

Show more

int

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_MANAGEMENT_LIMITS_MAX_HEADER_LIST_SIZE

Show more

long

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_MANAGEMENT_LIMITS_RST_FLOOD_MAX_RST_FRAME_PER_WINDOW

Show more

int

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_MANAGEMENT_LIMITS_RST_FLOOD_WINDOW_DURATION

Show more

Duration

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

To write duration values, use the standard java.time.Duration format. See the Duration#parse() Java API documentation for more information.

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

  • 数値のみの場合は、秒単位の時間を表します。

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

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

  • 数値の後に hms が続く場合は、その前に PT が付けられます。

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

About the MemorySize format

A size configuration option recognises string 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

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

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

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

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

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

Configuration property

デフォルト

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

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

Environment variable: QUARKUS_HTTP_ACCESS_LOG_EXCLUDE_PATTERN

Show more

string

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.

Environment variable: QUARKUS_HTTP_ACCESS_LOG_PATTERN

Show more

string

common

If logging should be done to a separate file.

Environment variable: QUARKUS_HTTP_ACCESS_LOG_LOG_TO_FILE

Show more

boolean

false

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

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

The log file suffix

Environment variable: QUARKUS_HTTP_ACCESS_LOG_LOG_SUFFIX

Show more

string

.log

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

If the log should be rotated daily

Environment variable: QUARKUS_HTTP_ACCESS_LOG_ROTATE

Show more

boolean

true

If rerouted requests should be consolidated into one log entry

Environment variable: QUARKUS_HTTP_ACCESS_LOG_CONSOLIDATE_REROUTED_REQUESTS

Show more

boolean

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}

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

%u

%{REMOTE_USER}

リクエストされた URL パス

%U

%{REQUEST_URL}

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

%R

%{REQUEST_URL}

ローカルサーバー名

%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}

リクエストの処理にかかった時間のロギングに関連する属性のいずれかを使用する場合は、 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/…​それ以降のパスも含む )に関するすべてのエントリーをログから除外します。

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. リバースプロキシーの背後での実行

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

この機能を有効にすると、サーバーはいくつかのセキュリティ上の問題(情報の偽装など)にさらされます。リバースプロキシーを利用している場合のみ、この機能を有効にすることを検討してください。

この機能を設定するには、 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 で設定します。それ以外のアドレスからのリクエストヘッダーは無視されます。

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

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

  • 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 属性を持つことになります。

15. サーブレットの設定

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

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-undertow</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-undertow")

15.1. undertow-handlers.conf

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

15.2. web.xml

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

15.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

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

20000

ROUTE_ORDER_AFTER_DEFAULT

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

関連コンテンツ