Add Enhanced Routing support for Hyperscale reader endpoints (TDS FEATUREEXT 0x0F / ENVCHANGE type 21)

[Ananya Garg (Ananya2)]

Overview

Hyperscale is introducing reader endpoints that load balance connections across named replicas. Unlike standard gateway routing (ENVCHANGE type 20 0x14) which only carries server and port, reader endpoints need to route connections to both a target network location and a specific database — since the client doesn't know the database ahead of time.

This PR implements the full TDS protocol changes required for the JDBC driver to support this scenario.

Changes

Feature negotiation:
The driver now always sends FEATUREEXT 0x0F (EnhancedRouting) in the Login7 feature extension block, regardless of the target server. When the server acknowledges with a 1-byte payload (data[0]=1), the driver enables enhanced routing support for the session. This ensures backward compatibility — older servers that don't recognize the token simply ignore it.

ENVCHANGE 0x21 parsing:
A new ENVCHANGE type 21 (EnhancedRouting) is now parsed alongside the existing type 20 (Routing). The enhanced payload includes all standard routing fields plus a required AlternateDatabase field (≤128 characters). The driver validates port number and database name, and updates hostNameInCertificate for the routed server domain.

Routing guard in login():
When the server sends ENVCHANGE type 21 0X15 with a database name but did not acknowledge the enhanced routing feature, the driver discards the routing info and stays on the original server. This is the critical safety mechanism that prevents an unverified server from redirecting the client to an arbitrary database.

Login7 database name override:
On the reconnection to the routed target, the driver uses the database name from the routing info (not the connection string) in the Login7 packet. This ensures the routed replica receives the correct database context.

ServerPortPlaceHolder extension:
The routing placeholder now carries a databaseName field, enabling the routing info to flow through the existing connection lifecycle without structural changes.

Test coverage

13 tests organized into 3 groups, using crafted TDS packets injected via mocked TDSReader/TDSPacket:

Routing behavior:

• Enhanced routing enabled — server acks feature + sends ENVCHANGE 21 → routing info carries routed server, port, and database
• No feature ack — login() guard discards routing, original database preserved
• Feature ack disabled — login() guard discards routing, original database preserved
• Legacy ENVCHANGE 20 — backward-compatible routing with server/port only

Feature negotiation:

• Enabled — ack [1] sets flag true
• Disabled — ack [0] leaves flag false
• DoNotAcknowledge — no ack, flag stays false
• Invalid ack data — empty/extra bytes throw with exact error message
• Feature ack filter — non-DNS/non-ER acks silently skipped during routing

ENVCHANGE 21 validation:

• Port 0 → throws
• Empty database name → throws
• hostNameInCertificate updated for routed server domain

Manual testing

Validated end-to-end against an Azure Hyperscale database on a OneBox server with 3 named replicas behind a reader endpoint:

• 15 consecutive connections successfully load balanced across all 3 replica servers
• Verified FEATUREEXT 0x0F negotiation and ENVCHANGE type 21 0x15 parsing in TDS traffic
• Confirmed routed database name matches DB_NAME() on each target replica

[codecov]

Codecov Report

❌ Patch coverage is 83.33333% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 60.85%. Comparing base (4a19931) to head (a15f434).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
.../microsoft/sqlserver/jdbc/SQLServerConnection.java	81.48%	3 Missing and 7 partials ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #2935      +/-   ##
============================================
+ Coverage     60.79%   60.85%   +0.05%     
- Complexity     4958     4988      +30     
============================================
  Files           151      151              
  Lines         35175    35221      +46     
  Branches       5882     5900      +18     
============================================
+ Hits          21385    21433      +48     
- Misses        10931    10933       +2     
+ Partials       2859     2855       -4     

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

[Copilot]

Pull request overview

This PR adds JDBC driver support for Hyperscale “Enhanced Routing” by negotiating FEATUREEXT 0x0F, parsing ENVCHANGE 0x21 (server/port + alternate database), and ensuring routed reconnections use the routed database name in Login7.

Changes:

• Always request Enhanced Routing via Login7 feature extensions and handle FEATUREEXTACK for 0x0F.
• Parse ENVCHANGE 21 to capture routed server/port/database and propagate it through ServerPortPlaceHolder.
• Add targeted tests and a new test tag for enhanced routing scenarios.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/main/java/com/microsoft/sqlserver/jdbc/SQLServerConnection.java	Negotiates Enhanced Routing, parses ENVCHANGE 21, adds login routing guard, and overrides Login7 DB name during routed reconnects.
src/main/java/com/microsoft/sqlserver/jdbc/ServerPortPlaceHolder.java	Extends routing placeholder to carry a database name for enhanced routing.
src/main/java/com/microsoft/sqlserver/jdbc/IOBuffer.java	Adds TDS feature constant 0x0F and token name mapping.
src/main/java/com/microsoft/sqlserver/jdbc/SQLServerResource.java	Adds localized strings for enhanced routing ack/validation errors.
src/test/java/com/microsoft/sqlserver/jdbc/EnhancedRoutingIntegrationTest.java	Adds mocked-protocol tests for feature ack parsing, ENVCHANGE 21 validation, and routing guard behavior.
src/test/java/com/microsoft/sqlserver/testframework/Constants.java	Adds enhancedRouting test tag constant.

[Divang Sharma (divang)]

minor comment