feat(health): add runtime‑agnostic Health SPI and Run /health endpoint by Tomnm1 · Pull Request #1582 · operaton/operaton

Tomnm1 · 2025-11-16T18:56:51Z

Introduce a lightweight, runtime-agnostic health surface and integrate it across modules so health checks work consistently in different deployment models.

add HealthService (SPI) and HealthResult (value object)
expose GET /health returning JSON
HealthController delegates to HealthService and is outside REST auth
new OperatonBpmHealthServiceConfiguration registers DefaultHealthService using optional DataSource, JobExecutor, FrontendHealthContributor
implement SpringWebappFrontendHealthContributor to report webapp presence and configured application path
no hard dependency on Actuator in Run; Actuator remains optional

related to #1245, closes #1245

Copilot

Pull Request Overview

This PR introduces a runtime-agnostic health check system for Operaton by adding a new Health SPI and implementing a /health endpoint across deployment models.

Creates core health abstractions (HealthService, HealthResult, FrontendHealthContributor) in the engine module
Implements DefaultHealthService to check database connectivity, job executor status, and frontend availability
Integrates health checks into Spring Boot via OperatonHealthIndicator for Actuator compatibility
Exposes a standalone /health endpoint in Operaton Run via HealthController

Reviewed Changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
`engine/src/main/java/org/operaton/bpm/health/HealthService.java`	New SPI interface for health check operations
`engine/src/main/java/org/operaton/bpm/health/HealthResult.java`	Immutable record holding health check results
`engine/src/main/java/org/operaton/bpm/health/FrontendHealthContributor.java`	SPI interface for frontend health contributions
`engine/src/main/java/org/operaton/bpm/health/DefaultHealthService.java`	Default implementation checking database, job executor, and frontend
`spring-boot-starter/starter/src/main/java/org/operaton/bpm/spring/boot/starter/OperatonBpmHealthServiceConfiguration.java`	Auto-configuration registering `DefaultHealthService` bean
`spring-boot-starter/starter/src/main/java/org/operaton/bpm/spring/boot/starter/actuator/OperatonHealthIndicator.java`	Actuator adapter delegating to `HealthService`
`spring-boot-starter/starter/src/main/java/org/operaton/bpm/spring/boot/starter/OperatonBpmActuatorConfiguration.java`	Registers `OperatonHealthIndicator` bean
`spring-boot-starter/starter/src/main/java/org/operaton/bpm/spring/boot/starter/OperatonBpmAutoConfiguration.java`	Imports health service configuration
`spring-boot-starter/starter-webapp-core/src/main/java/org/operaton/bpm/spring/boot/starter/webapp/SpringWebappFrontendHealthContributor.java`	Implementation checking webapp resource availability
`spring-boot-starter/starter-webapp-core/src/main/java/org/operaton/bpm/spring/boot/starter/webapp/OperatonBpmWebappAutoConfiguration.java`	Registers webapp frontend health contributor
`distro/run/core/src/main/java/org/operaton/bpm/run/health/HealthController.java`	REST controller exposing `/health` endpoint
`distro/run/core/src/test/java/org/operaton/bpm/run/test/health/HealthEndpointTest.java`	Integration test for `/health` endpoint

Copilot · 2025-11-17T04:39:30Z

+      frontend = new LinkedHashMap<>(frontendHealthContributor.frontendDetails());
+    } else {
+      frontend = new LinkedHashMap<>();
+      frontend.put("operational", "unknown");


The "operational" field is documented to be a boolean in the FrontendHealthContributor interface (line 31 comment), but here it's set to the string "unknown". This inconsistency can confuse API consumers. Consider using a boolean with a separate field for "status" or consistently using strings.

Suggested change

frontend.put("operational", "unknown");

frontend.put("operational", false);

seems legit. please rethink how this case should be handled. Either do not set the value, set it to a boolean, or introduce a tri-state.

After reconsideration, I’d say keeping it as a boolean is a reasonable choice. Since we first check whether we have a frontendHealthContributor—meaning, colloquially, “do I even have a frontend?”—we can assume that if there is no frontend, then it is not operational. On the other hand, using a tri-state value would provide clearer information about whether the frontend actually exists

kthoms

In general, a very valuable addition. Let's make this now ready. There are some nitpicks from Copilot and a general discussion related the package structure.

In general for such an addition extensive tests are required. There should be at least one integration test in spring-boot-starter/starter/src/test/java. And unit tests for each added component.

Please press "Re-request Review" when you are ready for the next review.

kthoms · 2025-11-17T05:14:08Z

The REST API is usually defined in the engine-rest API. This would make the health endpoint just available for the Operaton distribution.
I think that is fine, as installations on Tomcat or Wildfly would have their own endpoints. Am I correct?

That's correct — only the Operation Run distro keeps the HTTP health. The only thing I'm considering now is whether it should be made ConditionalOnProperty, since that would give users the option to disable it if they want. On the other hand, I think we should assume that the health check should be enabled by default.

Sounds good. Having it ConditionalOnProperty where the property is assumed to be true by default seems good.

kthoms · 2025-11-17T05:20:37Z

IMO this should be merged into ProcessEngineHealthIndicator.
The JobExecutorHealthIndicator could be made obsolete, but its check goes beyond what the HealthService is adding. Maybe the HealthService should be extended?

kthoms · 2025-11-17T05:25:36Z

The package structure should be changed. The current package is too high-level and details are not hidden.

I think the both interfaces and the result record should go to org.operaton.bpm.engine.health and the DefaultHealthService to org.operaton.bpm.engine.impl.health.

Also mark the public interfaces/record with "since 1.1" in Javadoc

javahippie

Hi, thanks for your contribution!

I'm wondering if the way this health check is structured is grouping too many things together. A database health check and the engine health check might be better treated as two different things. The engine can only be healthy if the database is healthy.

As an example: If I were to write my own Spring Boot application using the Operaton Starter, I already have an actuator in place which does readiness and liveness checks on the database. Duplicating this database health check into the DefaultHealthService would then not be necessary, because another subsystem is already taking care of this. I could reuse this in my health check, stating "Operaton can only be healthy if the database is healthy".

For the service checks themselves, I'm worndering how the check for the JobExecutor and the check for the Webapps could ever be negative. Have you checked if it is even possible to start an Operaton based application if the JobExecutor cannot be created? This is a central part of the system and my guess would be that the whole engine initialization failed in this case – including the HealthService.

For the webapps, the test checks if the WebJars are on the classpath. From my understanding this would only be possible if a user failed to include the dependencies during build time, so this would not really be a check for correct configuration and runtime behavior.

javahippie · 2025-11-17T07:38:35Z

The run distribution is based on Spring Boot, I'm wondering what the benefit is of providing a custom health endpoint over the Spring Boot actuator? The OperatonHealthIndicator was added in the code below, this would be a good fit in my opinion

Prefer Spring Boot Actuator for Spring Boot apps. The custom endpoint is only useful as a lightweight /health for Run (e.g., load balancer pings) or in environments where Actuator isn’t enabled and could be a baseline for user-specific implementation of health. The OperatonHealthIndicator integrates Operaton health into Actuator and is the recommended approach in Spring Boot apps.

javahippie · 2025-11-17T07:46:25Z

+    details.put("frontend", frontend);
+
+    boolean dbOk = (dataSource == null) || dbConnected;
+    boolean jobOk = (jobExecutor == null) || jobExecutorActive;


Having an inactive Job Executor might be a valid choice, I would not expect the health check to fail in this case

I was considering the use of Operation in a HA environment and assuming that the JobExecutor would be turned off to avoid split-brain scenarios, but that wouldn’t necessarily mean the application is unhealthy. Under that assumption, it could give a completely incorrect result, so right that shall be removed.

Tomnm1 · 2025-11-26T18:48:48Z

I am still not sure about the details being hidden enough and if it's still not trying to group too many things together, but would like to check out with you and exchange thoughts

kthoms · 2025-11-30T10:33:39Z

The build error will disappear after rebase. There was a problem in restructuring the integration build.

Tomnm1 · 2025-12-05T18:43:26Z

The build error will disappear after rebase. There was a problem in restructuring the integration build.

@kthoms Sorted out

Tomnm1 · 2026-01-06T14:58:49Z

I've fix the mess I've caused with the rebase, PR looks clear, howver there are some issues with tests - also on when building from clear main.

Tomnm1 · 2026-01-08T15:52:38Z

@kthoms if you could please take a look at this one :)

kthoms · 2026-04-22T20:19:40Z

This PR has become obsolete by #2730

kthoms requested review from Copilot and kthoms November 17, 2025 04:29

Copilot started reviewing on behalf of kthoms November 17, 2025 04:29 View session

kthoms added the noteworthy Should be documented in the release notes label Nov 17, 2025

Copilot finished reviewing on behalf of kthoms November 17, 2025 04:31

Copilot AI reviewed Nov 17, 2025

View reviewed changes

kthoms requested changes Nov 17, 2025

View reviewed changes

javahippie reviewed Nov 17, 2025

View reviewed changes

Tomnm1 requested review from javahippie and kthoms November 26, 2025 19:10

Tomnm1 force-pushed the #1245 branch from 1d1f464 to 04cb32d Compare January 4, 2026 16:50

Tomnm1 marked this pull request as draft January 4, 2026 17:01

feat(health): add runtime-agnostic Health SPI

7e486b9

Tomnm1 force-pushed the #1245 branch from 04cb32d to 7e486b9 Compare January 4, 2026 17:06

Tomnm1 marked this pull request as ready for review January 6, 2026 14:58

kthoms assigned Tomnm1 Feb 10, 2026

Fejbien mentioned this pull request Apr 10, 2026

feat(health): add runtime‑agnostic Health SPI and Run /health endpoint #2730

Merged

kthoms closed this Apr 22, 2026

kthoms added wontfix This will not be worked on and removed noteworthy Should be documented in the release notes labels Apr 22, 2026

	frontend.put("operational", "unknown");
	frontend.put("operational", false);

Conversation

Tomnm1 commented Nov 16, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Nov 17, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kthoms left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

javahippie left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Tomnm1 commented Nov 26, 2025

Uh oh!

kthoms commented Nov 30, 2025

Uh oh!

Tomnm1 commented Dec 5, 2025

Uh oh!

Tomnm1 commented Jan 6, 2026

Uh oh!

Tomnm1 commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kthoms commented Apr 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Tomnm1 commented Jan 8, 2026 •

edited

Loading