async-bulkhead-spring-poc

Spring Boot 4 + Virtual Threads proof-of-concept for an async bulkhead (fail-fast admission, no queue) with a tiny UI + API to generate load, observe saturation, and cancel in-flight work.

What this demonstrates

• Fail-fast admission: when the bulkhead is saturated, new requests are rejected immediately.
• “Cold” downstream work: downstream work should only start when admission succeeds.
• Accounting of terminal outcomes: SUCCESS / FAILURE / CANCELLED counters.
• Virtual Threads: runs with spring.threads.virtual.enabled=true.

Prereqs

• Java 21+
• Maven 3.9+

Run locally

mvn spring-boot:run

Then open:

• UI: http://localhost:8080/
• API: see endpoints below

Configuration

Set in src/main/resources/application.properties:

• poc.bulkhead.limit — max in-flight admitted operations
• poc.downstream.failureRate — simulate downstream failure probability
• poc.downstream.minDelayMs / poc.downstream.maxDelayMs — simulate downstream latency range

Endpoints

UI (redirect/HTML)

• GET / — dashboard (bulkhead snapshot + counters + in-flight registry)
• POST /ui/submit?n={N} — submit N operations (redirects back to /)
• POST /ui/cancel/{id} — cancels an in-flight operation (redirects back to /)

API (JSON)

• POST /api/submit?n={N} — submits N operations, returns { "submitted": N }
• POST /api/try-once — submits one; returns 200 if accepted or 429 if rejected
• POST /api/cancel/{id} — cancels by id, returns { "id": "...", "cancelIssued": true|false }

Testing

mvn test

Notes for Spring Boot 4:

• @WebMvcTest import is org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest
• @MockBean was removed; use @MockitoBean from org.springframework.test.context.bean.override.mockito.MockitoBean

If you mock final classes (e.g., BulkheadRejectedException), add:

<dependency>
  <groupId>org.mockito</groupId>
  <artifactId>mockito-inline</artifactId>
  <scope>test</scope>
</dependency>

This POC targets async-bulkhead v0.3.x semantics. Ergonomic and observability improvements introduced in v0.4.0 are intentionally not reflected yet.

License

Licensed under the Apache License, Version 2.0.
See the LICENSE file for details.