[nick-boss-tech]

🤖 AI text below 🤖 (reviewed by Nick Shanin)

Draft status is due to Nick Shanin's open-PR cap; the change is complete and ready for review, and it will be marked Open upon request.

This is the next sibling PR under SOLR-16398, following the split-shard migration in PR #5265, which Eric Pugh asked for as the representative command before the approach scaled up to the remaining commands.

What happens today

Rebalance leaders and migrate docs are still served by annotated v1-style API classes while the shard APIs around them are JAX-RS resources.

RebalanceLeadersAPI and MigrateDocsAPI carry their v2 routes as annotations on v1-shaped classes registered through CollectionsHandler.getApis(). The neighboring collection commands (create shard, delete shard, split shard) are Jersey resources with endpoint interfaces in solr/api, typed request bodies, and generated SolrJ clients. The v2 tracking spreadsheet lists both commands as not yet migrated to JAX-RS.

What this change does

Both commands become JAX-RS resources in the same shape as split shard, and the annotated classes are removed.

New endpoint interfaces RebalanceLeadersApi and MigrateDocsApi, with typed request bodies; the migrate-docs body carries the async field, and the resource passes it to the same submission the v1 route uses. The resources RebalanceLeaders and MigrateDocs are registered in CollectionsHandler alongside SplitShard, and RebalanceLeadersAPI and MigrateDocsAPI are deleted. The v1 routes do not change behavior: MIGRATE still returns its overseer message from the handler, and REBALANCELEADERS still executes the admin operation directly.

A choice to check

The two commands share one PR, and both endpoints carry the request-body fix from PR #5265.

The family plan on the ticket, set by Jason Gerlowski, is one to two APIs per PR; these two share their handler registration and test scaffolding, so they travel together. Shout if you would rather see them split. Separately, PR #5265 recorded that the sibling endpoints carried the same bare @RequestBody defect fixed there; both endpoint interfaces here declare @RequestBody(description = "Contains user provided parameters"), so the generated client and OpenAPI spec include the request body.

Proof

The focused tests pass at the PR head; on the base code the v2 resources and the integration test do not exist.

Verified 2026-11-03 at head 793e1ffa0f1d67271fbf090773651cd8a26171e4, on a branch rebased onto main after PR #5265 merged: tidy clean for the api and core modules; :solr:core:compileJava passes with Error Prone enabled (-Pvalidation.errorprone=true); CollectionCommandsV2IntegrationTest (2 tests), V2CollectionAPIMappingTest (2 tests), TestCollectionAPIs (2 tests), and TestApiFramework (3 tests) all pass with no failures, errors, or skips; :solr:core:check -x test passes.

Limits

Only rebalance leaders and migrate docs are in this PR.

Move replica follows on its own branch, and the core commands and the reindex migration are likewise ready on branches for later PRs, per the plan on the ticket. Replication is not covered here: Jalaz Kumar is carrying those APIs forward, per the ticket discussion. Neither command needed the v1-to-v2 async adapter that split shard needed, because neither v1 operation delegates to a resource: MIGRATE returns its message to the handler, which submits it, and REBALANCELEADERS executes in place.

Changelog: changelog/unreleased/SOLR-16398-rebalance-migrate.yml

Nick Shanin directed the work and takes responsibility for this contribution.

[nick-boss-tech]

I am thinking of splitting this PR in two, one per command: rebalance leaders on its own, migrate docs on its own. That makes two PRs of about 11 files each instead of one at 18, and each can be reviewed and merged independently.

Separately, this PR is still blocked by #5285: the V2ApiIntegrationTest failure there (a malformed request body answered 500 instead of 400) comes from the Jersey body reader, and the fix lives in #5285. Once that lands I will rebase this work over it, in whichever shape you prefer.

🤖 AI-generated text above 🤖