HTTP Reference

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

デフォルトでは、 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 ( デフォルトでは / ) からの相対パスとして解釈されます。

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

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

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

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

すべてのレスポンスに HTTP ヘッダーを送信するようにするには、以下のプロパティーを追加します。

これにより、アプリケーション内の任意のリソースに対して実行されるリクエストのレスポンスに、 X-Content-Type-Options: nosniff HTTP ヘッダーが含まれます。

また、ヘッダーを適用する必要がある path パターンと HTTP methods を指定することもできます。

これにより、 /headers/pragma リソースが GET または HEAD メソッドで呼び出された場合にのみ、 Pragma ヘッダーが適用されます。

100-continue をサポートするためには、 quarkus.http.handle-100-continue-automatically オプションを明示的に有効にする必要があります。追加情報は、 100-continue および関連の Vert.x ドキュメントをご覧ください。

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

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

ポートを指定したくない場合は、 quarkus.http.port=0 または quarkus.http.test-port=0 を指定することができます。ランダムに開いているポートが OS によって選ばれ、コンソールにログメッセージが表示されます。ポートがバインドされると、 quarkus.http.port システムプロパティーには選択された実際のポートが設定されます。そのため、これを利用して、アプリケーション内から実際のポート番号を取得できます。テスト中の場合は普通に URL を注入することができ、これは実際のポートで設定され、REST Assured も適切に設定されます。

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

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

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

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

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

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

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

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

デファクトスタンダードのヘッダー ( Forwarded header ) だけを考慮するためには、 src/main/resources/application.properties に以下の行を記述してください。

非標準のヘッダーのみを考慮するには、代わりに以下の行を src/main/resources/application.properties に記述してください。

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

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

例えば、クッキー名と SameSite 属性を記載することで、 Quarkus のエンドポイントによって設定された任意のクッキーに SameSite クッキープロパティを簡単に追加することができます。

この設定では、 jwt クッキーは SameSite=Lax 属性を持ち、 session クッキーは SameSite=Strict 属性を持つことになります。

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