Add broker drain API

[xiangfu0]

Summary

• Add a broker-local drain manager plus POST /drain and GET /drain/status admin APIs.
• Reject new broker query admissions during drain with BrokerShuttingDown while waiting for already accepted queries to finish.
• Mark the broker shutdownInProgress=true, remove it from brokerResource, fail health checks while draining, and restore stale drain state on startup.

User manual

To gracefully drain the broker and stop it after accepted queries finish:

curl -X POST "http://<broker-host>:<admin-port>/drain?timeoutMs=-1&shutdown=true"

timeoutMs=-1 uses pinot.broker.delayShutdownTimeMs. Use shutdown=false when an external orchestrator should terminate the process after drain completes:

curl -X POST "http://<broker-host>:<admin-port>/drain?timeoutMs=30000&shutdown=false"
curl "http://<broker-host>:<admin-port>/drain/status"

While draining, the broker health check returns 503 and new valid queries sent to this broker fail with BrokerShuttingDown (212), so clients should retry another broker.

Sample query

SELECT COUNT(*) FROM myTable;

If this query is sent to a draining broker, the broker returns BrokerShuttingDown instead of accepting it for execution.

Tests

• ./mvnw -pl pinot-broker -am -Dtest=BrokerDrainManagerTest,BrokerRequestHandlerDelegateTest -Dsurefire.failIfNoSpecifiedTests=false test
• ./mvnw spotless:apply -pl pinot-broker,pinot-spi,pinot-controller
• ./mvnw checkstyle:check -pl pinot-broker,pinot-spi,pinot-controller
• ./mvnw license:format -pl pinot-broker,pinot-spi,pinot-controller
• ./mvnw license:check -pl pinot-broker,pinot-spi,pinot-controller
• git diff --check upstream/master...HEAD

Review notes

• Self-review found and fixed one shutdown lifecycle issue: shutdown=true now delays the asynchronous stop callback briefly so the drain API response is not raced by admin server shutdown.
• No remaining self-review findings.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 56.85%. Comparing base (dded09d) to head (71baf18).

❗ There is a different number of reports uploaded between BASE (dded09d) and HEAD (71baf18). Click for more details.

HEAD has 16 uploads less than BASE

Flag	BASE (dded09d)	HEAD (71baf18)
unittests	2	1
java-25	5	1
temurin	5	1
unittests2	1	0
integration	3	0
integration1	1	0
integration2	1	0
custom-integration1	1	0

Additional details and impacted files

@@             Coverage Diff              @@
##             master   #18709      +/-   ##
============================================
- Coverage     65.45%   56.85%   -8.61%     
+ Complexity     1421        1    -1420     
============================================
  Files          3425     2628     -797     
  Lines        216303   156618   -59685     
  Branches      34266    25606    -8660     
============================================
- Hits         141590    89040   -52550     
+ Misses        63317    59961    -3356     
+ Partials      11396     7617    -3779     

Flag	Coverage Δ
custom-integration1	?
integration	?
integration1	?
integration2	?
java-25	56.85% <100.00%> (-8.61%)	⬇️
temurin	56.85% <100.00%> (-8.61%)	⬇️
unittests	56.85% <100.00%> (-8.61%)	⬇️
unittests1	56.85% <100.00%> (+0.02%)	⬆️
unittests2	?

Flags with carried forward coverage won't be shown. Click here to find out more.

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

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[xiangfu0]

Found one high-signal issue; see inline comment.

[xiangfu0]

startDrain() marks the broker draining before getConnectedHelixManager() and the Helix writes succeed. Because BaseBrokerStarter exposes the admin API before _participantHelixManager.connect(), a startup-window POST /drain (or any Helix write failure here) returns 500 but still leaves _draining set, so later queries are rejected until restart. Please make this transition rollback-safe or only flip the local drain state after the Helix preconditions/writes succeed.