SOLR-16458: Migrate NodeHealthAPI from homegrown @EndPoint to JAX-RS by epugh · Pull Request #4171 · apache/solr

epugh · 2026-02-28T13:08:36Z

Migrates NodeHealthAPI — the last node-level V2 API still using Solr's homegrown @EndPoint annotation — to standard JAX-RS, following the same pattern as NodeLogging, GetPublicKey, etc.

Design

The logic stays in HealthCheckHandler (minimising diff surface). NodeHealthAPI is a thin JAX-RS wrapper (~60 lines) that delegates entirely to it.

Key changes

solr/api — New NodeHealthApi interface (@Path, @GET, @Operation) and NodeHealthResponse model (status, message, num_cores_unhealthy)
NodeHealthAPI — Replaces @EndPoint with JAX-RS; injects CoreContainer, delegates to HealthCheckHandler
HealthCheckHandler — Logic unchanged; adds public NodeHealthResponse checkNodeHealth(Boolean, Integer) as the shared entry point for both v1 (handleRequestBody) and v2 (NodeHealthAPI); switches to getJerseyResources() / empty getApis()
V2NodeAPIMappingTest — Removes the now-obsolete @EndPoint/ApiBag routing test for health
NodeHealthAPITest — New Mockito unit tests for the API class
NodeHealthAPITest2 — New mock-free integration tests: cloud-mode via real MiniSolrCloudCluster, legacy mode via embedded CoreContainer built from NodeConfig
implicit-requesthandlers.adoc — Health section now links to both HealthCheckHandler (v1) and NodeHealthAPI (v2) javadocs

Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

…ef guide Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

epugh · 2026-02-28T13:21:36Z

Some outstanding questions: 1) there is a more mock and less mock versions of the same test. Which do we prefer? 2) Does this seem like a reasonable pattern for the conversion?

epugh · 2026-02-28T13:27:50Z

I wish I didnt' have TWO ways of writing tests, one for cloud and one for standalone... sigh.

solr/api/src/java/org/apache/solr/client/api/model/NodeHealthResponse.java

solr/core/src/java/org/apache/solr/handler/admin/HealthCheckHandler.java

epugh · 2026-03-01T20:53:59Z

tests all pass!

gerlowskija · 2026-03-03T13:34:39Z

@epugh - this should probably be attached to one of the v2 JIRA tickets or another. Maybe https://issues.apache.org/jira/browse/SOLR-16458?

epugh · 2026-03-03T13:37:44Z

@epugh - this should probably be attached to one of the v2 JIRA tickets or another. Maybe https://issues.apache.org/jira/browse/SOLR-16458?

Sure... I suppose I could be crosslinking all of these to various JIRAs?

changelog/unreleased/SOLR-16458-migrate-node-health-api.yml

changelog/unreleased/migrate-node-health-api.yml

solr/api/src/java/org/apache/solr/client/api/endpoint/NodeHealthApi.java

solr/api/src/java/org/apache/solr/client/api/model/NodeHealthResponse.java

gerlowskija · 2026-03-03T14:37:47Z

solr/core/src/test/org/apache/solr/handler/admin/api/NodeHealthAPITest.java

+ * mocks.
+ *
+ * <p>Cloud-mode tests use a real {@link org.apache.solr.cloud.MiniSolrCloudCluster} and get a
+ * {@link CoreContainer} directly from a {@link JettySolrRunner}. Legacy (standalone) mode tests


[Q] Do we have other tests that do standalone testing within a SolrCloudTestCase?

It feels weird conceptually. And in practical terms SolrCloudTestCase does some work that makes it much slower on a per-test basis than our other base classes. Doing standalone testing in a SolrCloudTestCase is going to end up paying that runtime cost for no reason.

Dunno... Do you think we should ahve TWO tests? The setup is only done one in beforeClass.. not per test.

gerlowskija · 2026-03-03T14:42:18Z

solr/core/src/test/org/apache/solr/handler/admin/api/NodeHealthAPITest.java

+  public void testCloudMode_RequireHealthyCoresReturnOkWhenAllCoresHealthy() {
+    CoreContainer coreContainer = cluster.getJettySolrRunner(0).getCoreContainer();
+
+    // requireHealthyCores=true should succeed on a node with no unhealthy cores


[-1] You haven't actually created any cores!!

Can you create a collection or something that'll cause this test to actually exercise the per-core logic currently in HealthcheckHandler?

I added something, and one thing is we may want to collapse our tests from HealthCheckHandlerTest at some point into this test case.

solr/core/src/test/org/apache/solr/handler/admin/api/NodeHealthAPITest.java

gerlowskija · 2026-03-03T14:53:15Z

solr/solr-ref-guide/modules/configuration-guide/pages/implicit-requesthandlers.adoc

-v2: `api/node/health` |{solr-javadocs}/core/org/apache/solr/handler/admin/HealthCheckHandler.html[HealthCheckHandler] |
+v2: `api/node/health` |v1: {solr-javadocs}/core/org/apache/solr/handler/admin/HealthCheckHandler.html[HealthCheckHandler]
+
+v2: {solr-javadocs}/core/org/apache/solr/handler/admin/api/NodeHealthAPI.html[NodeHealthAPI] |


[Q] Is it the implementation Javadocs we want to point people to here, or would the solr/api interface docs be more helpful?

Or more broadly - is there much value even in pointing to either Javadoc on the v2 side? HealthcheckHandler has a nice good blurb, but neither NodeHealthAPI nor NodeHealthApi have much of anything that's worth pointing a user at IMO...

Good question.... I think we need to decide what the pattern should be for these new apis... Where DO we want these apis to link to and be documented? I don't have a strong opinion, and honestlhy, if we punted this to a future JIRA I could live with that too.

dsmiley · 2026-03-03T15:14:55Z

Just want to give kudos to Jason's thoroughly amazing code review. Really shows how important it is that we have the right reviewers on the right issues. Hopefully after this issue is done, similar issues can follow the same lessons/advise. Assuming LLM is doing the bulk of the work, it can be pointed specifically at this PR to learn the key aspects to successfully do similar transitions.

epugh · 2026-03-07T17:05:25Z

@gerlowskija all really good comments and also highlights how little I know about the capabilities available in Jax rs and our implementation!!! Will update on Monday.

…e-health-api

epugh · 2026-03-09T16:54:44Z

Okay, at this point down to a decision on Enum impact, migrating all the business logic out of HealthCheckHandler, and Javadocs and then this may be good to go!

epugh · 2026-03-09T18:41:07Z

Okay, at this point down to a decision on Enum impact, migrating all the business logic out of HealthCheckHandler, and Javadocs and then this may be good to go!

Chatted with @gerlowskija on phone, and we're going to take a stab at migrating business logic. Javadocs we won't do anything more creative than what we have for now. Forgot to ask about Enum.

@deprecated

…kHandler delegates to V2 - NodeHealthAPI now owns all business logic (cloud mode, legacy mode, isWithinGenerationLag, findUnhealthyCores) using strongly-typed NodeHealthResponse / NodeStatus throughout. - HealthCheckHandler becomes a thin V1 bridge: handleRequestBody() creates NodeHealthAPI(coreContainer).checkNodeHealth(...) and squashes the typed response into SolrQueryResponse. - findUnhealthyCores() moved to NodeHealthAPI as a public static util; HealthCheckHandler keeps a @deprecated delegation shim so existing callers continue to compile. - HealthCheckHandlerTest updated to call NodeHealthAPI.findUnhealthyCores() directly. - Utils.getReflectWriter() now serialises Enum values as their .name() string so that NodeStatus.OK round-trips as "OK" through NamedList/javabin, keeping HealthCheckHandlerTest assertions passing. - Fixed pre-existing bug in isWithinGenerationLag: condition was `generationDiff < maxGenerationLag` (wrong); corrected to `generationDiff > maxGenerationLag` with the return values adjusted so the method returns true=healthy / false=lagging-too-far. - Fixed missing slf4j log arguments in the negative-diff warning. Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

epugh · 2026-03-10T00:28:11Z

Okay, at this point down to a decision on Enum impact, migrating all the business logic out of HealthCheckHandler, and Javadocs and then this may be good to go!

Chatted with @gerlowskija on phone, and we're going to take a stab at migrating business logic. Javadocs we won't do anything more creative than what we have for now. Forgot to ask about Enum.

Got a fix for handling the Enum comparisoin. I migrated the business logic, and removed a duplicate test in the process...

@gerlowskija I think this is ready for final review!

epugh · 2026-03-10T09:26:53Z

Oh, and the reason, based on spelunking, why we don't support maxGenerationLag in v2 is that it's a feature of the old leader/follower capability only. See TestHealthCheckHandlerLegacyMode.

I used claude for this regressoin test and I don't love how verbose they are. I tried a mock approach first and it was worse.

Copilot AI and others added 4 commits February 22, 2026 12:52

Initial plan

0585c2a

Migrate NodeHealthAPI from @endpoint to JAX-RS annotations

4aa9e8b

Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

Add NodeHealthAPITest2: integration tests without Mockito mocks

8e2ccd5

Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

Restore logic to HealthCheckHandler, simplify NodeHealthAPI, update r…

a50f682

…ef guide Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

epugh mentioned this pull request Feb 28, 2026

Migrate NodeHealthAPI: flip delegation so V2 owns logic, V1 bridges to it epugh/solr#22

Draft

github-actions bot added documentation Improvements or additions to documentation tests cat:api labels Feb 28, 2026

epugh mentioned this pull request Feb 28, 2026

SOLR-16458: Convert /api/node/system to JAX-RS #4078

Open

8 tasks

epugh marked this pull request as ready for review February 28, 2026 13:20

epugh requested review from gerlowskija and janhoy February 28, 2026 13:20

restore docs

b8159ab

epugh added the no-changelog label Feb 28, 2026

Copilot AI mentioned this pull request Feb 28, 2026

Migrate RenameCoreAPI from homegrown @EndPoint/@Command to JAX-RS; use SolrJettyTestRule in tests epugh/solr#24

Closed

lint

01696e3

dsmiley reviewed Feb 28, 2026

View reviewed changes

solr/api/src/java/org/apache/solr/client/api/model/NodeHealthResponse.java Outdated Show resolved Hide resolved

solr/core/src/java/org/apache/solr/handler/admin/HealthCheckHandler.java Show resolved Hide resolved

epugh added 2 commits March 1, 2026 12:58

Keep the non mock version

dac4e14

Responding to feedback

ec8252a

lint

b592322

epugh changed the title ~~Migrate NodeHealthAPI from homegrown @EndPoint to JAX-RS; add ref guide link~~ Migrate NodeHealthAPI from homegrown @EndPoint to JAX-RS Mar 2, 2026

epugh removed the no-changelog label Mar 3, 2026

add changelog

ca88d6e

epugh changed the title ~~Migrate NodeHealthAPI from homegrown @EndPoint to JAX-RS~~ SOLR-16458: Migrate NodeHealthAPI from homegrown @EndPoint to JAX-RS Mar 3, 2026

gerlowskija requested changes Mar 3, 2026

View reviewed changes

epugh added 7 commits March 9, 2026 11:00

Improve changelog

0809a34

Use the name healthcheck

55bf2ce

Use enum for status and proper HTTP SolrJ classes in testing.

abea29c

WIP of hacking this guy up to work with enum :-(

9c52897

Merge remote-tracking branch 'upstream/main' into copilot/migrate-nod…

b47383b

…e-health-api

Restore the exception raised on error behavior that v1 apis had

ff53a9d

better title

2d0c50b

Copilot AI and others added 2 commits March 9, 2026 19:24

Migrate business logic into NodeHealthAPI, and fix enum issue

71feb02

github-actions bot added the client:solrj label Mar 10, 2026

epugh added 2 commits March 11, 2026 07:07

Follow the existing naming pattern.

2a81e9e

Add test for failure cases.

fc6ee9e

I used claude for this regressoin test and I don't love how verbose they are. I tried a mock approach first and it was worse.

Conversation

epugh commented Feb 28, 2026

Design

Key changes

Uh oh!

epugh commented Feb 28, 2026

Uh oh!

epugh commented Feb 28, 2026

Uh oh!

Uh oh!

Uh oh!

epugh commented Mar 1, 2026

Uh oh!

gerlowskija commented Mar 3, 2026

Uh oh!

epugh commented Mar 3, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gerlowskija Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

epugh Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

gerlowskija Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

epugh Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

gerlowskija Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

epugh Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

dsmiley commented Mar 3, 2026

Uh oh!

epugh commented Mar 7, 2026

Uh oh!

epugh commented Mar 9, 2026

Uh oh!

epugh commented Mar 9, 2026

Uh oh!

epugh commented Mar 10, 2026

Uh oh!

epugh commented Mar 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants