Quarkusでのパス解決

昔々、Quarkusでは、ヘルスチェックやメトリクスなどのエンドポイントを追加で定義していました。これらは、アプリケーションが定義したエンドポイントと一緒に quarkus.http.root-path から提供されていました。デフォルトでは quarkus.http.root-path は / であり、事実上見えないようになっているため、これは必ずしも明らかではありません。

そして、 アプリケーションエンドポイントとの衝突を避け、セキュリティやアクセスポリシーの処理を容易にするために、アプリケーション以外のエンドポイントをどのようにグループ化するかを考え始めました。さらに何人かのユーザからは、これらの非アプリケーションエンドポイントを 完全に別のポートから提供できないかという意見もありました (まだ実現していません)。

最初のステップは、これらのエクステンションで定義されたエンドポイントをすべて一緒にグループ化することでした。これが、 非アプリケーションエンドポイントパスの始まりでした。この新しいパスのデフォルトの場所は /q で、他のエンドポイントと同様に HTTP ルートパスの下に入れ子になっていました。この効果は、例えば /health を /q/health に移動させることでした。

私たちは、メトリクスやヘルスなどのエンドポイントの一部を移動することは、すでに展開されているアプリケーションや人間の記憶にとって問題があることを知っていました。移行を容易にするために、これらのエンドポイントの一部にリダイレクトを追加し、 /metrics にアクセスした場合は /q/metrics にリダイレクトされるようにしました。

アプリケーション以外のエンドポイントのサポートは 1.11.0.Final で出荷されました。

そして、事態は 悪化 し始めました。クラウドホスティングプロバイダの中には、例えば、ヘルスの定義として 200 のみを受け入れるものがあり、リダイレクト ( 301) は意図した効果を発揮しませんでした。また、アプリケーション以外のエンドポイントをオフにして以前の動作に戻す方法についても混乱があり、特定のエンドポイントをこのアプリケーション以外のエンドポイントコレクションから移動させる方法についても疑問が残りました。

余談ですが、どのようにしてこのような状況になったかというと、ライブラリの挙動の違いによるものではありません。Vert.x は、例えばルートを作成する際に、常に先頭のスラッシュで始まるセグメントを求めますが、JAX-RS は @Path のアノテーションでは先頭のスラッシュを事実上無視します。Vert.x に慣れている人は常に先頭のスラッシュを追加し、JAX-RS を使用している人は何をしても魔法のように動作します。

Quarkusでは、実装の詳細が偶然にも露わになりました。エクステンションによって定義されたアプリケーション以外のエンドポイントは、Vert.xのルートをベースにしています。デフォルトのパス設定値はスラッシュで始まり、迅速なルート作成を可能にし、単純な追加動作を可能にします。Quarkusの初期の頃は、これが悪い考えであることを示唆するようなものは何もなく、JAX-RSの経験がある開発者は、JAX-RSが処理するので、どちらにしても警告を受けることはありませんでした。

しかし、人々が期待していた通りにパスが解決されず、その状況を解決するために必要な設定の変更が直感的ではなかったり、別の問題を引き起こしたりする状況に陥りました。そこで私たちは、異なる設定値を組み合わせたときに何が起こるかを並べて見ることができるように、すべての可能な設定の組み合わせをスプレッドシートに入れてみました。結果はそれほど素晴らしいものではありませんでした。しかし、この演習により、アプリケーションと非アプリケーションのエンドポイントが必要な動作をするようにするために何を変更する必要があるかを評価するために、一歩下がって全体像を見ることができました。

Quarkusでパスを設定するために使用される設定属性のセットは変更されませんが、設定された値がどのように解釈されるかは異なります。

1.11.5.Final と 1.12.1.Final でこれらのアップデートが利用可能になり、埃は全て解消するはずです。

アプリケーション以外のエンドポイントのための便利なリダイレクトはまだ存在しますが、 quarkus.http.redirect-to-non-application-root-path を false に設定することで無効にすることができます。これは全く変わっていません。

新しいルールを使用してパスがどのように解決されるか、いくつかの例を見てみましょう。まず、以下の前提条件から始めましょう。

私たちが最も気にしている設定属性は:

また、設定可能なアプリケーション以外のエンドポイントにも注目しています:

レバーを引き始めると何が起こるかを見てみましょう。以下の例では、config の句読点に注意を払ってください。句読点が、そのように動作する鍵となるからです。

ほとんどの部分では、これが透明であることを願っています。途中で非常に一貫性のないパス処理を発見し、これらの値の多く（あるいはほとんど）がカスタマイズされることはないと考えさせられました。

HTTP ルートパスをカスタマイズしている場合は、挙動の変化に気づく可能性が高いでしょう。その場合は、上記の新しいルールと例が、設定を微調整してすべてを思い通りに動作させる方法を理解するのに役立つことを願っています。

エクステンション開発者は最も大きな変更点を目にすることになるでしょう。 エクステンション開発ガイドが更新され、アプリケーション以外のエンドポイントを作成するために使用されるビルド項目の変更が記述されています。しかし、一般的なルールとしては、自分でエンドポイントパスを構築することは避け、 NonApplicationRootPathBuildItem と HttpRootPathBuildItem に頼って構築してもらうようにしましょう。

すべての人を幸せにすることは不可能であることはわかっていますが、少なくとも、より予測可能で一貫性のある結果につながる設定のパターンを達成することができたことを願っています。また、この問題を解決した際に観察された挙動の変化については、（再度）お詫び申し上げます。