Implement xDS virtual host routing by jrhee17 · Pull Request #6322 · line/armeria

jrhee17 · 2025-07-23T09:41:16Z

Motivation:

This changeset attempts to implement routing based on virtual hosts.

The relevant documentation regarding matching can be found in the following locations:

The rules for domain matching can be found in detail at the VirtualHost#domains section.

The relevant upstream implementation can be found in the router configuration:

https://github.com/envoyproxy/envoy/blob/0d341b982a24f3ddb9f4fd3a9bdd8880561103be/source/common/router/config_impl.cc#L1930-L1976

Note that there is a slight difference in behavior compared to upstream - given that armeria's integration acts more as a client rather than a proxy, the default virtual host will be used when the authority is null.

Modifications:

Introduced VirtualHostMatcher which pre-computes a map for quicker virtual host matching.
RouteEntry#index, VirtualHost#index are exposed publicly. This allows for easier referencing to the selected route.

Result:

xDS clients route requests based on the authority

github-actions · 2025-07-23T09:59:11Z

🔍 Build Scan® (commit: `e1eefe9`)

Job name	Status	Build Scan®
build-ubicloud-standard-16-jdk-8	✅	https://ge.armeria.dev/s/7jta3hj5hzvhw
build-ubicloud-standard-16-jdk-21-snapshot-blockhound	❌ (failure)	https://ge.armeria.dev/s/msfnuq6qemxty
build-ubicloud-standard-16-jdk-17-min-java-17-coverage	✅	https://ge.armeria.dev/s/f4h55s6hcxmzq
build-ubicloud-standard-16-jdk-17-min-java-11	✅	https://ge.armeria.dev/s/vsokeqb2765fi
build-ubicloud-standard-16-jdk-17-leak	✅	https://ge.armeria.dev/s/u3jwjvddi27ts
build-ubicloud-standard-16-jdk-11	✅	https://ge.armeria.dev/s/yscs2iuk2rmfq
build-macos-latest-jdk-21	✅	https://ge.armeria.dev/s/bz5gbrzwg4pl2

codecov · 2025-07-23T10:14:19Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 0.00%. Comparing base (8150425) to head (e1eefe9).
⚠️ Report is 131 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff              @@
##               main   #6322       +/-   ##
============================================
- Coverage     74.46%       0   -74.47%     
============================================
  Files          1963       0     -1963     
  Lines         82437       0    -82437     
  Branches      10764       0    -10764     
============================================
- Hits          61385       0    -61385     
+ Misses        15918       0    -15918     
+ Partials       5134       0     -5134

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

minwoox

Left some questions. Looks good to me. 👍

minwoox · 2025-07-24T05:42:26Z

+        if (routeEntries.isEmpty()) {
+            return null;
        }
+        final RouteEntry routeEntry = routeEntries.get(0);


Question: The first route is only used for now, and it's going to be changed in the future. Is that correct?

Right, do you prefer route matching is done in the same PR?

No, I just wanted to make sure. 😉

minwoox · 2025-07-24T05:47:31Z

+        for (VirtualHostSnapshot virtualHostSnapshot: routeSnapshot.virtualHostSnapshots()) {
+            for (String domain: virtualHostSnapshot.xdsResource().resource().getDomainsList()) {
+                domain = Ascii.toLowerCase(domain);
+                if ("*".equals(domain)) {


Can't we use the DomainMappingBuilder?

I've pushed 2ad3b39 so you can check failing tests.
https://github.com/line/armeria/actions/runs/16557827889

Most notably:

The behavior regarding asterisks is different. Single asterisks aren't allowed, and asterisks not separated by a dot aren't allowed.

Support for longest match for multiple matching entries isn't supported.

Even if DomainMappingBuilder is used, my feeling is that there is no benefit as most of the logic will have to be rewritten anyways.

I see. I didn't know that xDS has its own rule for the domain matching:
https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto.html#config-route-v3-virtualhost

This reverts commit 2ad3b39.

ikhoon

Looks good! 👍 👍

minwoox

👍 👍 👍

Motivation: Following #6322, this changeset attempts to implement route matching (`Route#match`). ref: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#envoy-v3-api-msg-config-route-v3-route Implementation is focused on following upstream behavior as closely as possible. The corresponding implementation can be found here: https://github.com/envoyproxy/envoy/blob/4bb05db55ecd583b6f451d81445d94210445176f/source/common/router/config_impl.cc#L831-L881 Matching rules that aren't implemented are: - tls_context: Since the client doesn't act as a proxy yet, there are no downstream tls contexts. - dynamic_metadata: While this may be useful, users don't have a way to supply a metadata directly for a request yet. - runtime_fraction: This will be implemented when rtds is implemented. - filter_state: may consider this when the set_filter_state filter is introduced. Overall, the above rules have been verified to not being used in basic istio cases. Modifications: - Implemented `RouteEntryMatcher` which matches a route based on the path, headers and query parameters. - Added a dependency to `re2j`, which provides linear time regex matching. - ref: https://www.envoyproxy.io/docs/envoy/latest/api-v3/type/matcher/v3/regex.proto#envoy-v3-api-msg-type-matcher-v3-regexmatcher - Note that the default regex engine is `re2j` in `bootstrap#default_regex_engine` - https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/bootstrap/v3/bootstrap.proto - Misc) Added CLAUDE.md to `.gitignore` since it seems like other major repositories aren't checking in this file either. Result: - The xDS integration can now route requests based on the path, headers, and query parameters.

minimal impl

559c706

jrhee17 added this to the 1.33.0 milestone Jul 23, 2025

jrhee17 added the new feature label Jul 23, 2025

minor lint

3809909

jrhee17 marked this pull request as ready for review July 24, 2025 00:53

jrhee17 requested review from ikhoon, minwoox and trustin as code owners July 24, 2025 00:53

minwoox reviewed Jul 24, 2025

View reviewed changes

ikhoon reviewed Jul 24, 2025

View reviewed changes

Comment thread it/xds-client/src/test/java/com/linecorp/armeria/xds/it/VirtualHostRoutingTest.java

Comment thread xds/src/main/java/com/linecorp/armeria/xds/client/endpoint/VirtualHostMatcher.java

jrhee17 added 3 commits July 28, 2025 10:24

address comment by @minwoox

2ad3b39

Revert "address comment by @minwoox"

ba584af

This reverts commit 2ad3b39.

address comment by @ikhoon

e1eefe9

ikhoon approved these changes Jul 29, 2025

View reviewed changes

minwoox approved these changes Jul 30, 2025

View reviewed changes

jrhee17 merged commit 2441b44 into line:main Jul 30, 2025
13 of 14 checks passed

jrhee17 mentioned this pull request Jul 31, 2025

Implement basic route matching for xDS clients #6333

Merged

Navigation Menu

Uh oh!

Implement xDS virtual host routing - #6322

Implement xDS virtual host routing#6322
jrhee17 merged 5 commits into
line:mainfrom
jrhee17:feat/xds-vhost-routing

jrhee17 commented Jul 23, 2025 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 23, 2025 •

edited

Loading

Uh oh!

codecov Bot commented Jul 23, 2025 •

edited

Loading

Uh oh!

minwoox left a comment

Uh oh!

minwoox Jul 24, 2025

Uh oh!

jrhee17 Jul 28, 2025

Uh oh!

minwoox Jul 30, 2025

Uh oh!

minwoox Jul 24, 2025

Uh oh!

jrhee17 Jul 28, 2025 •

edited

Loading

Uh oh!

minwoox Jul 30, 2025

Uh oh!

Uh oh!

Uh oh!

ikhoon left a comment

Uh oh!

minwoox left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

jrhee17 commented Jul 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jul 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Build Scan® (commit: e1eefe9)

Uh oh!

codecov Bot commented Jul 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

minwoox left a comment

Choose a reason for hiding this comment

Uh oh!

minwoox Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

jrhee17 Jul 28, 2025

Choose a reason for hiding this comment

Uh oh!

minwoox Jul 30, 2025

Choose a reason for hiding this comment

Uh oh!

minwoox Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

jrhee17 Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

minwoox Jul 30, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ikhoon left a comment

Choose a reason for hiding this comment

Uh oh!

minwoox left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jrhee17 commented Jul 23, 2025 •

edited

Loading

github-actions Bot commented Jul 23, 2025 •

edited

Loading

🔍 Build Scan® (commit: `e1eefe9`)

codecov Bot commented Jul 23, 2025 •

edited

Loading

jrhee17 Jul 28, 2025 •

edited

Loading