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

HTTP Reference

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

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

1. 静的リソースの提供

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

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

If you are using webjars, like the following JQuery one:

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 Compression

The response body of a static resource is not compressed by default. You can enable the HTTP compression support by means of quarkus.http.enable-compression=true. If compression support is enabled then the response body is compressed if the Content-Type header derived from the file name of a resource is a compressed media type as configured via quarkus.http.compress-media-types.

By default, the following list of media types is compressed: text/html, text/plain, text/xml, text/css, text/javascript and application/javascript.
If the client does not support HTTP compression then the response body is not compressed.

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

By default, Quarkus will serve content from under the root context. If you want to change this you can use the quarkus.http.root-path config key to set the context 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 はルートパスには含めないでください。

In general, path configurations for web content are interpreted relative to quarkus.http.root-path (which is / by default).

  • To specify paths within this context root, use a relative path that does not begin with a forward slash.

  • If you want to specify the URI explicitly, so it is always the same regardless of the value of quarkus.http.root-path, use an absolute path that begins with a forward slash.

As an example, if an extension configures a service path, that endpoint will be served from ${quarkus.http.root-path}/service. If you change the configuration of that path to /service, that endpoint will be served from /service.

The Path Resolution in Quarkus blog post further explains how path resolution works for both user and extension defined paths.

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

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

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

To enable SSL support with native executables, please refer to our Using SSL With Native Executables guide.

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 ポートは開けません。

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

4. Additional HTTP Headers

To enable HTTP headers to be sent on every response, add the following properties:

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

This will include the X-Content-Type-Options: nosniff HTTP Header on responses for requests performed on any resource in the application.

You can also specify a path pattern and the HTTP methods the header needs to be applied:

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

This will apply the Pragma header only when the /headers/pragma resource is called with a GET or a HEAD method

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

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. Additional HTTP Headers per path

If you need different header values depending on the path, you can use the following configuration:

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

This will set the Cache-Control header to none when /index.html is called.

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

You can use a regular expression in the path and also specify the HTTP methods where the HTTP header will be set:

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

In case of overlapping paths in the configuration, you can specify an order (higher values take precedence). For example, having the following configuration:

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

Will include the Cache-Control: max-age=1 header when /paths/order is requested.

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

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. Support 100-Continue in vert.x

In order to support 100-continue, the quarkus.http.handle-100-continue-automatically option needs to be enabled explicitly For additional information check https://datatracker.ietf.org/doc/html/rfc7231#section-5.1.1.

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 形式が得られます。

Here’s what a full CORS filter configuration could look like, including a regular expression defining an allowed origin:

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

ローカルサーバー名

%v

%{LOCAL_SERVER_NAME}

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

%D

%{RESPONSE_TIME}

要求の処理にかかった時間 (秒単位)

%T

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

%{RESPONSE_TIME_MICROS}

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

%{RESPONSE_TIME_NANOS}

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

%I

%{THREAD_NAME}

SSL 暗号

%{SSL_CIPHER}

SSL クライアント証明書

%{SSL_CLIENT_CERT}

SSL セッション id

%{SSL_SESSION_ID}

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

%{ALL_REQUEST_HEADERS}

クッキーの値

%{c,cookie_name}

クエリーパラメーター

%{q,query_param_name}

リクエストヘッダー

%{i,request_header_name}

レスポンスヘッダー

%{o,response_header_name}

Vert.x Routing Context Internal Data

%{d,map_key}

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

Quarkus could be accessed through proxies that additionally generate headers (e.g. X-Forwarded-Host) to keep information from the client-facing side of the proxy servers that is altered or lost when they are involved. In those scenarios, Quarkus can be configured to automatically update information like protocol, host, port and URI reflecting the values in these headers.

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

To set up this feature, please include the following lines in src/main/resources/application.properties:

quarkus.http.proxy-address-forwarding=true

To consider only de-facto standard header (Forwarded header), please include the following lines in src/main/resources/application.properties:

quarkus.http.proxy.allow-forwarded=true

To consider only non-standard headers, please include the following lines instead in 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

Both configurations related to standard and non-standard headers can be combined, although the standard headers configuration will have precedence. However, combining them has security implications as clients can forge requests with a forwarded header that is not overwritten by the proxy. Therefore, proxies should strip unexpected X-Forwarded or X-Forwarded-* headers from the client.

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

  • Forwarded

  • X-Forwarded-Proto

  • X-Forwarded-Host

  • X-Forwarded-Port

  • X-Forwarded-Ssl

  • X-Forwarded-Prefix

One can easily add a SameSite cookie property to any of the cookies set by a Quarkus endpoint by listing a cookie name and a SameSite attribute, for example:

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

Given this configuration, the jwt cookie will have a SameSite=Lax attribute and the session cookie will have a SameSite=Strict attribute.

13. サーブレット設定

Servlet を使用するには、明示的に 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

You can make use of the Undertow predicate language using an undertow-handlers.conf file. This file should be placed in the META-INF directory of your application jar. This file contains handlers defined using the Undertow predicate language.

13.2. web.xml

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