バージョン:

HTTPリファレンス

1. 静的リソースの提供
2. コンテキストパスの設定
3. SSL によるセキュアな接続のサポート
4. 追加の HTTP ヘッダー
- 4.1. パスごとの追加の HTTP ヘッダー
5. Vert.xにおける 100-continue のサポート
6. HTTP/2 サポート
7. ランダムポートでの待ち受け
8. CORS フィルター
- 8.1. devmodeですべてのオリジンをサポート
9. HTTP 制限の設定
10. HTTP アクセスログの設定
11. リバースプロキシーの背後での実行
12. SameSite クッキー
13. サーブレットの設定
- 13.1. undertow-handlers.conf
- 13.2. web.xml

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

HTTPは、ベースとなるHTTPレイヤーとしてEclipse Vert.xを使用して提供されます。サーブレットは、Vert.x上で動作するUndertowの修正バージョンを使用してサポートされ、RESTEasyは、Jakarta RESTサポートを提供するために使用されます。Undertowが存在する場合、RESTEasyはServletフィルターとして実行され、そうでない場合は、Servletの関与なしにVert.xの上で直接実行されます。

1. 静的リソースの提供

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

1.1. WebJar ロケーターのサポート

以下の 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.2. 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.3. その他の設定

さらに、静的リソースのインデックスページをデフォルトの 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`	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`

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

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

期間のフォーマットは標準の java.time.Duration フォーマットを使用します。詳細は Duration#parse() javadoc を参照してください。

数値で始まる期間の値を指定することもできます。この場合、値が数値のみで構成されている場合、コンバーターは値を秒として扱います。そうでない場合は、 PT が暗黙的に値の前に付加され、標準の java.time.Duration 形式が得られます。

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

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

サーブレットを使用している場合は、quarkus.servlet.context-path を通して Servlet のコンテキストパスを制御することができます。この項目は、上記の HTTP ルートからの相対パスであり、サーブレットと、サーブレットの上で実行されるものにのみ影響します。多くのアプリケーションでは、 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. SSL によるセキュアな接続のサポート

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

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

ネイティブ実行可能ファイルで 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 はファイル拡張子からキーストアのタイプの推測を試行し、デフォルトでは JKS タイプになります。

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-port と quarkus.http.test-ssl-port で設定することができます。

3.5. HTTP ポートの無効化

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

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

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

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`	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 Environment variable: `QUARKUS_HTTP_HEADER__HEADER__METHODS`	list of string
`quarkus.management.header."header".path` The path this header should be applied Environment variable: `QUARKUS_MANAGEMENT_HEADER__HEADER__PATH`	string	`/*`
`quarkus.management.header."header".value` The value for this header configuration Environment variable: `QUARKUS_MANAGEMENT_HEADER__HEADER__VALUE`	string	required
`quarkus.management.header."header".methods` The HTTP methods for this header configuration Environment variable: `QUARKUS_MANAGEMENT_HEADER__HEADER__METHODS`	list of string

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

Environment variable: QUARKUS_HTTP_HEADER__HEADER__METHODS

list of string

quarkus.management.header."header".path

The path this header should be applied

Environment variable: QUARKUS_MANAGEMENT_HEADER__HEADER__PATH

string

/*

quarkus.management.header."header".value

The value for this header configuration

Environment variable: QUARKUS_MANAGEMENT_HEADER__HEADER__VALUE

string

required

quarkus.management.header."header".methods

The HTTP methods for this header configuration

Environment variable: QUARKUS_MANAGEMENT_HEADER__HEADER__METHODS

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	型	デフォルト
`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` Additional HTTP Headers always sent in the response Environment variable: `QUARKUS_HTTP_FILTER__FILTER__HEADER`	`Map<String,String>`
`quarkus.http.filter."filter".methods` The HTTP methods for this path configuration Environment variable: `QUARKUS_HTTP_FILTER__FILTER__METHODS`	list of string
`quarkus.http.filter."filter".order` Environment variable: `QUARKUS_HTTP_FILTER__FILTER__ORDER`	int
`quarkus.management.filter."filter".matches` A regular expression for the paths matching this configuration Environment variable: `QUARKUS_MANAGEMENT_FILTER__FILTER__MATCHES`	string	required
`quarkus.management.filter."filter".header` Additional HTTP Headers always sent in the response Environment variable: `QUARKUS_MANAGEMENT_FILTER__FILTER__HEADER`	`Map<String,String>`
`quarkus.management.filter."filter".methods` The HTTP methods for this path configuration Environment variable: `QUARKUS_MANAGEMENT_FILTER__FILTER__METHODS`	list of string
`quarkus.management.filter."filter".order` Environment variable: `QUARKUS_MANAGEMENT_FILTER__FILTER__ORDER`	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

Additional HTTP Headers always sent in the response

Environment variable: QUARKUS_HTTP_FILTER__FILTER__HEADER

Map<String,String>

quarkus.http.filter."filter".methods

The HTTP methods for this path configuration

Environment variable: QUARKUS_HTTP_FILTER__FILTER__METHODS

list of string

quarkus.http.filter."filter".order

Environment variable: QUARKUS_HTTP_FILTER__FILTER__ORDER

int

quarkus.management.filter."filter".matches

A regular expression for the paths matching this configuration

Environment variable: QUARKUS_MANAGEMENT_FILTER__FILTER__MATCHES

string

required

quarkus.management.filter."filter".header

Additional HTTP Headers always sent in the response

Environment variable: QUARKUS_MANAGEMENT_FILTER__FILTER__HEADER

Map<String,String>

quarkus.management.filter."filter".methods

The HTTP methods for this path configuration

Environment variable: QUARKUS_MANAGEMENT_FILTER__FILTER__METHODS

list of string

quarkus.management.filter."filter".order

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 はデフォルトで有効になっており、 JDK11 以降で SSL が使用されている場合はブラウザーで使用されます。 JDK8 は ALPN をサポートしていないため、SSL 上で HTTP/2 を実行するために使用することはできません。 SSL が使用されていない場合でも、平分のアップグレードによる HTTP/2 はサポートされており、ブラウザー以外のクライアントでも使用することができます。

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

quarkus.http.http2=false

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 フィルター

オリジン間リソース共有 ( CORS ) は、ウェブページ上の制限されたリソースを、最初のリソースが提供されたドメイン以外の別のドメインから要求できるようにするメカニズムです。

Quarkusには、 jakarta.servlet.Filter インターフェイスを実装し、すべての着信HTTPリクエストをインターセプトするCORSフィルターが付属しています。このフィルタは、Quarkusの設定ファイル（ src/main/resources/application.properties ）で有効にすることができます:

quarkus.http.cors=true

フィルターが有効で、HTTPリクエストがクロスオリジンとして識別された場合、リクエストを実際のターゲット（サーブレット、Jakarta RESTリソースなど）に渡す前に、以下のプロパティで定義されたCORSポリシーとヘッダーが適用されます:

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

Configuration property	型	デフォルト
`quarkus.http.cors.origins` Origins allowed for CORS Comma separated list of valid URLs, e.g.: http://www.quarkus.io,http://localhost:3000 In case an entry of the list is surrounded by forward slashes, it is interpreted as a regular expression. Environment variable: `QUARKUS_HTTP_CORS_ORIGINS`	list of string
`quarkus.http.cors.methods` HTTP methods allowed for CORS Comma separated list of valid methods. ex: GET,PUT,POST The filter allows any method if this is not set. default: returns any requested method as valid Environment variable: `QUARKUS_HTTP_CORS_METHODS`	list of string
`quarkus.http.cors.headers` HTTP headers allowed for CORS Comma separated list of valid headers. ex: X-Custom,Content-Disposition The filter allows any header if this is not set. default: returns any requested header as valid Environment variable: `QUARKUS_HTTP_CORS_HEADERS`	list of string
`quarkus.http.cors.exposed-headers` HTTP headers exposed in CORS Comma separated list of valid headers. ex: X-Custom,Content-Disposition default: empty Environment variable: `QUARKUS_HTTP_CORS_EXPOSED_HEADERS`	list of string
`quarkus.http.cors.access-control-max-age` The `Access-Control-Max-Age` response header value indicating how long the results of a pre-flight request can be cached. Environment variable: `QUARKUS_HTTP_CORS_ACCESS_CONTROL_MAX_AGE`	Duration
`quarkus.http.cors.access-control-allow-credentials` The `Access-Control-Allow-Credentials` header is used to tell the browsers to expose the response to front-end JavaScript code when the request’s credentials mode Request.credentials is “include”. The value of this header will default to `true` if `quarkus.http.cors.origins` property is set and there is a match with the precise `Origin` header. Environment variable: `QUARKUS_HTTP_CORS_ACCESS_CONTROL_ALLOW_CREDENTIALS`	boolean

Configuration property

型

デフォルト

quarkus.http.cors.origins

Origins allowed for CORS Comma separated list of valid URLs, e.g.: http://www.quarkus.io,http://localhost:3000 In case an entry of the list is surrounded by forward slashes, it is interpreted as a regular expression.

Environment variable: QUARKUS_HTTP_CORS_ORIGINS

list of string

quarkus.http.cors.methods

HTTP methods allowed for CORS Comma separated list of valid methods. ex: GET,PUT,POST The filter allows any method if this is not set. default: returns any requested method as valid

Environment variable: QUARKUS_HTTP_CORS_METHODS

list of string

quarkus.http.cors.headers

HTTP headers allowed for CORS Comma separated list of valid headers. ex: X-Custom,Content-Disposition The filter allows any header if this is not set. default: returns any requested header as valid

Environment variable: QUARKUS_HTTP_CORS_HEADERS

list of string

quarkus.http.cors.exposed-headers

HTTP headers exposed in CORS Comma separated list of valid headers. ex: X-Custom,Content-Disposition default: empty

Environment variable: QUARKUS_HTTP_CORS_EXPOSED_HEADERS

list of string

quarkus.http.cors.access-control-max-age

The Access-Control-Max-Age response header value indicating how long the results of a pre-flight request can be cached.

Environment variable: QUARKUS_HTTP_CORS_ACCESS_CONTROL_MAX_AGE

Duration

quarkus.http.cors.access-control-allow-credentials

The Access-Control-Allow-Credentials header is used to tell the browsers to expose the response to front-end JavaScript code when the request’s credentials mode Request.credentials is “include”. The value of this header will default to true if quarkus.http.cors.origins property is set and there is a match with the precise Origin header.

Environment variable: QUARKUS_HTTP_CORS_ACCESS_CONTROL_ALLOW_CREDENTIALS

boolean

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

期間のフォーマットは標準の java.time.Duration フォーマットを使用します。詳細は Duration#parse() javadoc を参照してください。

以下は、許可されるオリジンを定義する正規表現を含む、完全な CORS フィルタ設定の例です。

quarkus.http.cors=true
quarkus.http.cors.origins=http://foo.com,http://www.bar.io,/https://([a-z0-9\\-_]+)\\.app\\.mydomain\\.com/
quarkus.http.cors.methods=GET,PUT,POST
quarkus.http.cors.headers=X-Custom
quarkus.http.cors.exposed-headers=Content-Disposition
quarkus.http.cors.access-control-max-age=24H
quarkus.http.cors.access-control-allow-credentials=true

/https://([a-z0-9\\-_]+)\\.app\\.mydomain\\.com/ は、フォワードスラッシュ文字で囲まれているため、正規表現として扱われます。

8.1. devmodeですべてのオリジンをサポート

CORSサポートが必要なQuarkusアプリケーションの開発を開始する際に、必要なオリジンを設定するのは困難です。このような場合、まず実際の開発に集中するために、すべてのオリジンを開発モードでのみ許可したいでしょう。

quarkus.http.cors=true
%dev.quarkus.http.cors.origins=/.*/

dev プロファイルに対してのみすべてのオリジンを有効にすることが重要です。本番環境ですべてのオリジンを許可することは推奨されていません。アプリケーションが重大なセキュリティ問題にさらされる可能性があります。

9. HTTP 制限の設定

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

Configuration property	型	デフォルト
`quarkus.http.limits.max-header-size` The maximum length of all headers. Environment variable: `QUARKUS_HTTP_LIMITS_MAX_HEADER_SIZE`	MemorySize	`20K`
`quarkus.http.limits.max-body-size` The maximum size of a request body. Environment variable: `QUARKUS_HTTP_LIMITS_MAX_BODY_SIZE`	MemorySize	`10240K`
`quarkus.http.limits.max-chunk-size` The max HTTP chunk size 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. Environment variable: `QUARKUS_HTTP_LIMITS_MAX_FORM_ATTRIBUTE_SIZE`	MemorySize	`2048`
`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.management.limits.max-header-size` The maximum length of all headers. Environment variable: `QUARKUS_MANAGEMENT_LIMITS_MAX_HEADER_SIZE`	MemorySize	`20K`
`quarkus.management.limits.max-body-size` The maximum size of a request body. Environment variable: `QUARKUS_MANAGEMENT_LIMITS_MAX_BODY_SIZE`	MemorySize	`10240K`
`quarkus.management.limits.max-chunk-size` The max HTTP chunk size Environment variable: `QUARKUS_MANAGEMENT_LIMITS_MAX_CHUNK_SIZE`	MemorySize	`8192`
`quarkus.management.limits.max-initial-line-length` The maximum length of the initial line (e.g. `"GET / HTTP/1.0"`). Environment variable: `QUARKUS_MANAGEMENT_LIMITS_MAX_INITIAL_LINE_LENGTH`	int	`4096`
`quarkus.management.limits.max-form-attribute-size` The maximum length of a form attribute. Environment variable: `QUARKUS_MANAGEMENT_LIMITS_MAX_FORM_ATTRIBUTE_SIZE`	MemorySize	`2048`
`quarkus.management.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_MANAGEMENT_LIMITS_MAX_CONNECTIONS`	int

Configuration property

型

デフォルト

quarkus.http.limits.max-header-size

The maximum length of all headers.

Environment variable: QUARKUS_HTTP_LIMITS_MAX_HEADER_SIZE

MemorySize

20K

quarkus.http.limits.max-body-size

The maximum size of a request body.

Environment variable: QUARKUS_HTTP_LIMITS_MAX_BODY_SIZE

MemorySize

10240K

quarkus.http.limits.max-chunk-size

The max HTTP chunk size

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.

Environment variable: QUARKUS_HTTP_LIMITS_MAX_FORM_ATTRIBUTE_SIZE

MemorySize

2048

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.management.limits.max-header-size

The maximum length of all headers.

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_HEADER_SIZE

MemorySize

20K

quarkus.management.limits.max-body-size

The maximum size of a request body.

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_BODY_SIZE

MemorySize

10240K

quarkus.management.limits.max-chunk-size

The max HTTP chunk size

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_CHUNK_SIZE

MemorySize

8192

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

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

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_INITIAL_LINE_LENGTH

int

4096

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

The maximum length of a form attribute.

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_FORM_ATTRIBUTE_SIZE

MemorySize

2048

quarkus.management.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_MANAGEMENT_LIMITS_MAX_CONNECTIONS

int

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. 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`	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. Environment variable: `QUARKUS_HTTP_ACCESS_LOG_PATTERN`	string	`common`
`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`

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.

Environment variable: QUARKUS_HTTP_ACCESS_LOG_PATTERN

string

common

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

属性短い形式m 長い形式

属性	短い形式m	長い形式
リモート 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}`

リモート 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.exclude-pattern=/some/path/.* を使用すると、パス /some/path/… （ それ以降のパスも含む ）に関するすべてのエントリーをログから除外します。

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

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

13. サーブレットの設定

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

pom.xml

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

build.gradle

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

13.1. undertow-handlers.conf

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

13.2. web.xml

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

HTTPリファレンス

1. 静的リソースの提供

1.1. WebJar ロケーターのサポート

1.2. HTTP圧縮

1.3. その他の設定

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

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

3.1. 証明書とキーファイルの提供

3.2. キーストアの提供

3.3. パスワードの設定

3.4. HTTP ポートの設定

3.5. HTTP ポートの無効化

4. 追加の HTTP ヘッダー

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

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

6. HTTP/2 サポート

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

8. CORS フィルター

8.1. devmodeですべてのオリジンをサポート

9. HTTP 制限の設定

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

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

12. SameSite クッキー

13. サーブレットの設定

13.1. undertow-handlers.conf

13.2. web.xml