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 57.10%. Comparing base (2892236) to head (14a496c).

❗ There is a different number of reports uploaded between BASE (2892236) and HEAD (14a496c). Click for more details.

HEAD has 8 uploads less than BASE

Flag	BASE (2892236)	HEAD (14a496c)
unittests	2	1
java-25	5	3
temurin	5	3
integration	3	2
custom-integration1	1	0
unittests2	1	0

Additional details and impacted files

@@             Coverage Diff              @@
##             master   #18709      +/-   ##
============================================
- Coverage     65.39%   57.10%   -8.29%     
+ Complexity     1405        7    -1398     
============================================
  Files          3423     2629     -794     
  Lines        215968   156316   -59652     
  Branches      34186    25533    -8653     
============================================
- Hits         141228    89269   -51959     
+ Misses        63380    59423    -3957     
+ Partials      11360     7624    -3736     

Flag	Coverage Δ
custom-integration1	?
integration	100.00% <ø> (ø)
integration1	100.00% <ø> (ø)
integration2	0.00% <ø> (ø)
java-25	57.10% <100.00%> (-8.29%)	⬇️
temurin	57.10% <100.00%> (-8.29%)	⬇️
unittests	57.10% <100.00%> (-8.29%)	⬇️
unittests1	57.10% <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.