Async Controllers with DeferredResult and CompletableFuture

// All three free the Servlet thread so Tomcat can serve more requests while
// your work is in progress. They differ in WHO completes the response and HOW.

@RestController
@RequestMapping("/v1/reports")
class ReportController {

    private final TaskExecutor executor;       // bounded thread pool
    private final ReportPipeline pipeline;     // emits results asynchronously
    private final WebClient upstream;          // reactive HTTP client

    // ---- Callable: Spring submits it to the MVC task executor automatically ----
    // Best when you just need off-servlet-thread work (blocking JDBC, etc.).
    @GetMapping("/simple")
    Callable<ReportDto> simple(@RequestParam long id) {
        return () -> pipeline.buildBlocking(id);   // runs on MVC task executor
    }

    // ---- DeferredResult: YOU decide when to complete it, from any thread. ----
    // Ideal for long-polling, push/event patterns, or completion driven by
    // an external callback (message bus, websocket, scheduled producer).
    @GetMapping("/events/{jobId}")
    DeferredResult<ReportEvent> nextEvent(@PathVariable String jobId) {
        DeferredResult<ReportEvent> dr = new DeferredResult<>(30_000L, () -> {
            // called on timeout — respond with 200 + empty event
            return ReportEvent.empty(jobId);
        });

        pipeline.onNextEvent(jobId, ev -> dr.setResult(ev));   // any thread may call setResult
        dr.onCompletion(() -> pipeline.unsubscribe(jobId));
        dr.onError(ex -> log.error("deferred failed", ex));
        return dr;
    }

    // ---- CompletableFuture: idiomatic for composing async Java -----------------
    // Best when the work is already CompletableFuture-shaped (async HTTP,
    // gRPC clients, async repositories, CompletionStage from JDK).
    @GetMapping("/compose/{id}")
    CompletableFuture<ReportDto> compose(@PathVariable long id) {
        CompletableFuture<User>   user   = userClient.getAsync(id);
        CompletableFuture<Metric> metric = metricsClient.getAsync(id);

        return user.thenCombineAsync(metric,
                (u, m) -> pipeline.assemble(u, m),
                executor)
            .orTimeout(4, TimeUnit.SECONDS);
    }

    // ---- ResponseBodyEmitter / SseEmitter: streaming many chunks ---------------
    // When you want to push multiple responses over a single HTTP connection.
    @GetMapping(path = "/stream/{id}", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    SseEmitter stream(@PathVariable long id) {
        SseEmitter emitter = new SseEmitter(Duration.ofMinutes(5).toMillis());
        executor.execute(() -> {
            try {
                pipeline.eachChunk(id, chunk ->
                    emitter.send(SseEmitter.event().id(chunk.id()).data(chunk)));
                emitter.complete();
            } catch (Exception ex) {
                emitter.completeWithError(ex);
            }
        });
        return emitter;
    }
}

// Configure the async executor — never rely on the SimpleAsyncTaskExecutor default.
@Configuration
class AsyncMvcConfig implements WebMvcConfigurer {
    @Override
    public void configureAsyncSupport(AsyncSupportConfigurer cfg) {
        ThreadPoolTaskExecutor exec = new ThreadPoolTaskExecutor();
        exec.setCorePoolSize(16);
        exec.setMaxPoolSize(64);
        exec.setQueueCapacity(500);
        exec.setThreadNamePrefix("mvc-async-");
        exec.initialize();
        cfg.setTaskExecutor(exec);
        cfg.setDefaultTimeout(Duration.ofSeconds(10).toMillis());
    }
}

// Decision cheatsheet:
//   Off-servlet-thread blocking I/O, no composition      -> Callable
//   Result produced by an external event / callback      -> DeferredResult
//   Already have async clients / need .thenCompose       -> CompletableFuture
//   Many chunks over one response                        -> SseEmitter / ResponseBodyEmitter
//   Fully reactive pipeline                              -> return Mono/Flux (WebFlux)