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

HTTPリファレンス

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

HTTP はベースとなる HTTP レイヤーとして Eclipse Vert.x を使用して提供されます。サーブレットは Vert.x の上で動作する Undertow の修正版を使用してサポートされています。また、JAX-RS のサポートには RESTEasy が使用されています。Undertow が存在する場合、RESTEasy はサーブレットフィルターとして動作します。そうでない場合は、サーブレットの関与なしに 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 圧縮をサポートしていない場合、レスポンスボディは圧縮されません。

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

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

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

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

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

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

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

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

quarkus.http.ssl.certificate.file=/path/to/certificate
quarkus.http.ssl.certificate.key-file=/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 ポートの無効化

HTTP ポートを無効化して、セキュアなリクエストのみをサポートすることも可能です。これは application.propertiesquarkus.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

タイプ

デフォルト

The path this header should be applied

Environment variable: QUARKUS_HTTP_HEADER__HEADER__PATH

string

/*

The value for this header configuration

Environment variable: QUARKUS_HTTP_HEADER__HEADER__VALUE

string

required

The HTTP methods for this header configuration

Environment variable: QUARKUS_HTTP_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

タイプ

デフォルト

A regular expression for the paths matching this configuration

Environment variable: QUARKUS_HTTP_FILTER__FILTER__MATCHES

string

required

Additional HTTP Headers always sent in the response

Environment variable: QUARKUS_HTTP_FILTER__FILTER__HEADER

Map<String,String>

The HTTP methods for this path configuration

Environment variable: QUARKUS_HTTP_FILTER__FILTER__METHODS

list of string

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 はデフォルトで有効になっており、 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 には、javax.servlet.Filter インターフェースを実装し、すべての受信 HTTP リクエストを遮断する CORS フィルターが付属しています。これは、Quarkus の設定ファイル (src/main/resources/application.properties) で有効にすることができます。

quarkus.http.cors=true

フィルターが有効になっていて、HTTP リクエストがクロスオリジンであると識別された場合は、要求を実際のターゲット ( サーブレット、 JAX-RS リソースなど ) に渡す前に、以下のプロパティーを使用して定義された CORS ポリシーとヘッダーが適用されます。

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

Configuration property

タイプ

デフォルト

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. The filter allows any origin if this is not set. default: returns any requested origin as valid

Environment variable: QUARKUS_HTTP_CORS_ORIGINS

list of string

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

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

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

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

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 and that header is not '*'.

Environment variable: QUARKUS_HTTP_CORS_ACCESS_CONTROL_ALLOW_CREDENTIALS

boolean

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

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

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

以下は、許可されるオリジンを定義する正規表現を含む、完全な 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

9. HTTP 制限の設定

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

Configuration property

タイプ

デフォルト

The maximum length of all headers.

Environment variable: QUARKUS_HTTP_LIMITS_MAX_HEADER_SIZE

MemorySize

20K

The maximum size of a request body.

Environment variable: QUARKUS_HTTP_LIMITS_MAX_BODY_SIZE

MemorySize

10240K

The max HTTP chunk size

Environment variable: QUARKUS_HTTP_LIMITS_MAX_CHUNK_SIZE

MemorySize

8192

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

Environment variable: QUARKUS_HTTP_LIMITS_MAX_INITIAL_LINE_LENGTH

int

4096

The maximum length of a form attribute.

Environment variable: QUARKUS_HTTP_LIMITS_MAX_FORM_ATTRIBUTE_SIZE

MemorySize

2048

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

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

タイプ

デフォルト

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

Environment variable: QUARKUS_HTTP_ACCESS_LOG_ENABLED

boolean

false

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

Environment variable: QUARKUS_HTTP_ACCESS_LOG_EXCLUDE_PATTERN

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

string

common

If logging should be done to a separate file.

Environment variable: QUARKUS_HTTP_ACCESS_LOG_LOG_TO_FILE

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

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

string

The log file suffix

Environment variable: QUARKUS_HTTP_ACCESS_LOG_LOG_SUFFIX

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

string

io.quarkus.http.access-log

If the log should be rotated daily

Environment variable: QUARKUS_HTTP_ACCESS_LOG_ROTATE

boolean

true

属性 短い形式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}

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

標準ヘッダーと非標準ヘッダーに関連する設定はどちらも組み合わせることが できるますが、標準ヘッダーの設定が優先されます。しかしながら、これらを組み合わせることは、クライアントがプロキシにーよって上書きされない転送 ( 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 ディレクトリーに配置します。