001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.juneau.rest.server.reactive; 018 019import static jakarta.servlet.http.HttpServletResponse.*; 020import static org.apache.juneau.commons.utils.Shorts.*; 021 022import java.io.*; 023import java.util.*; 024import java.util.concurrent.*; 025import java.util.concurrent.atomic.*; 026import java.util.function.*; 027import java.util.logging.*; 028 029import org.apache.juneau.commons.http.MediaRanges; 030import org.apache.juneau.commons.inject.*; 031import org.apache.juneau.http.response.*; 032import org.apache.juneau.marshall.marshaller.*; 033import org.apache.juneau.marshall.serializer.*; 034import org.apache.juneau.marshall.sse.*; 035import org.apache.juneau.rest.server.*; 036import org.apache.juneau.rest.server.logging.*; 037import org.apache.juneau.rest.server.processor.*; 038import org.apache.juneau.rest.server.util.*; 039 040import jakarta.servlet.*; 041import jakarta.servlet.http.*; 042 043/** 044 * Response processor that bridges <a class="doclink" href="https://www.reactive-streams.org/">Reactive Streams</a> 045 * return values from {@code @RestOp} handlers to Juneau's response pipeline. 046 * 047 * <h2 class='topic'>Activation (opt-in)</h2> 048 * <p> 049 * This processor ships in the opt-in {@code juneau-rest-server-reactive} module and is <b>not</b> wired 050 * into {@code DefaultConfig}. A bare {@code juneau-rest-server} has zero reactive behavior. When the 051 * {@code juneau-rest-server-reactive} jar is on the classpath, its 052 * {@code META-INF/services/ResponseProcessor} provider file is discovered 053 * by {@code RestContext} via {@link ServiceLoader} and this processor is front-loaded ahead of 054 * {@code AsyncResponseProcessor} in the chain — no {@code @Rest(responseProcessors=...)} entry required. 055 * 056 * <h2 class='topic'>What it handles</h2> 057 * <p> 058 * This is the single, shared spine for all reactive return-type support. It natively understands the 059 * JDK type {@link java.util.concurrent.Flow.Publisher Flow.Publisher<T>} (no external dependency 060 * required) and, through registered {@link ReactiveStreamsAdapter} providers, any third-party reactive 061 * type the opt-in {@code juneau-rest-server-reactive-reactor} module adapts to it (Project Reactor 062 * {@code Mono} / {@code Flux}, RxJava 3 {@code Single} / {@code Maybe} / {@code Flowable} / 063 * {@code Observable}, and the Reactive-Streams {@code org.reactivestreams.Publisher}). 064 * 065 * <p> 066 * Single-value reactive types (e.g. {@code Mono}, {@code Single}) are adapted to a {@link CompletionStage} 067 * and collapse onto the existing {@link AsyncResponseProcessor} async path, inheriting its timeout, 068 * completion-executor ({@code @Rest(asyncCompletionExecutor)}), and MDC bridging behavior for free. 069 * 070 * <h2 class='topic'>Response shapes for multi-value streams</h2> 071 * <p> 072 * A streaming publisher is rendered as one of three shapes, selected by the negotiated response media 073 * type (the handler's {@link RestResponse#setContentType(String) Content-Type}, then the request 074 * {@code Accept} header): 075 * <ul> 076 * <li><b>SSE</b> ({@code text/event-stream}) — each element is emitted as a Server-Sent-Events 077 * frame. {@link SseEvent} elements are written verbatim; any other element type is JSON-encoded 078 * into the {@code data:} field. 079 * <li><b>NDJSON</b> ({@code application/x-ndjson}, {@code application/jsonl}, {@code application/jsonlines}, 080 * {@code application/json5l}, {@code application/json5lines}, {@code application/json-seq}) — each 081 * element is JSON-encoded on its own line. Unless the handler set a Content-Type, the response echoes the 082 * highest-ranked NDJSON-family {@code Accept} range in canonical form ({@code jsonlines} becomes 083 * {@code jsonl}, {@code json5lines} becomes {@code json5l}, {@code json-seq} becomes {@code x-ndjson}); 084 * otherwise it is {@code application/x-ndjson}. See {@link #NDJSON_ALIASES}. 085 * <li><b>Buffer</b> (default, any other media type) — all elements are collected into a 086 * {@link List List} and serialized through the normal serializer chain (e.g. a JSON 087 * array). The collection is wrapped in a {@link CompletableFuture} and handed to the async path, 088 * so a slow producer never blocks the request thread. The collection is bounded by 089 * {@link ReactiveResponseProperties#getMaxBufferedElements() ReactiveResponse.maxBufferedElements} 090 * (default 10,000 elements). 091 * </ul> 092 * 093 * <h2 class='topic'>Backpressure</h2> 094 * <p> 095 * Streaming subscribers request one element at a time ({@code request(1)} on subscribe and again after 096 * each frame is written and flushed). Because writing to the servlet output stream blocks until the 097 * socket accepts the bytes, this gives natural backpressure — the producer is paced by the 098 * client's drain rate and the server-side buffer does not grow without bound. Buffer-shape subscribers 099 * request at most one element more than the configured limit 100 * ({@link ReactiveResponseProperties#getMaxBufferedElements() ReactiveResponse.maxBufferedElements}, default 101 * 10,000). If the publisher emits more elements than the limit, the subscription is cancelled and the request 102 * fails with a {@code 500} response whose message names the limit; the response is never silently truncated. 103 * The subscription is likewise cancelled when the buffered response times out or is otherwise abandoned. 104 * 105 * <h2 class='topic'>Threading, executors, and MDC</h2> 106 * <p> 107 * Buffer-shape responses route through {@link AsyncResponseProcessor} and therefore honor 108 * {@code @Rest(asyncCompletionExecutor)} and the SLF4J MDC bridge. Streaming-shape 109 * frame writes happen on whichever thread the publisher emits on (the Reactor / RxJava scheduler); this 110 * processor does not impose a {@code subscribeOn(...)} so it never fights the library's scheduler model. 111 * When MDC propagation is enabled, the request-thread MDC snapshot is reinstalled around each 112 * {@code onNext} / terminal callback via {@link MdcAsyncListener} so log statements emitted while writing 113 * a frame see the request's diagnostic context. 114 * 115 * <h2 class='topic'>Synchronous fallback</h2> 116 * <p> 117 * In environments where {@link HttpServletRequest#startAsync()} is unsupported (notably Juneau's 118 * {@code MockServletRequest}), streaming subscribes synchronously and blocks the request thread until 119 * the publisher terminates (bounded by the configured async timeout), writing frames as they arrive. 120 * This keeps the unit-test surface working without a real servlet container. 121 * 122 * @see ReactiveStreamsAdapter 123 * @see AsyncResponseProcessor 124 * @since 10.0.0 125 */ 126@SuppressWarnings({ 127 "java:S1192", // Media-type literals are protocol tokens; the alias table reads best with them inline 128 "java:S2095", // Writer is response-owned; we never close it. 129 "resource" // Closeables here are framework-managed and not owned/closed by this class; not a real leak. 130}) 131public class ReactiveResponseProcessor implements ResponseProcessor { 132 133 private static final Logger LOG = Logger.getLogger(ReactiveResponseProcessor.class.getName()); 134 135 private static final AtomicReference<List<ReactiveStreamsAdapter>> ADAPTERS = new AtomicReference<>(); 136 137 private enum Shape { BUFFER, SSE, NDJSON } 138 139 /** 140 * NDJSON-family media types accepted from {@code Accept}, mapped to the Content-Type echoed on an NDJSON-shape 141 * response. {@code application/json-seq} maps to {@code application/x-ndjson} because this writer does not emit 142 * RFC 7464 record separators. 143 */ 144 static final Map<String,String> NDJSON_ALIASES = Map.of( 145 "application/jsonl", "application/jsonl", 146 "application/jsonlines", "application/jsonl", 147 "application/json5l", "application/json5l", 148 "application/json5lines", "application/json5l", 149 "application/x-ndjson", "application/x-ndjson", 150 "application/json-seq", "application/x-ndjson" 151 ); 152 153 /** 154 * Returns the canonical NDJSON-family type of the highest-ranked {@code Accept} range in that family. 155 * 156 * <p> 157 * Ranges are walked in {@link MediaRanges} order (q descending, then its own tie-break). Ranges with 158 * {@code q=0} are skipped; parameters other than {@code q} are ignored; matching is case-insensitive. 159 * 160 * @param accept The raw {@code Accept} header, possibly <jk>null</jk>. 161 * @return The canonical type, or <jk>null</jk> when no NDJSON-family range is acceptable. 162 */ 163 static String negotiatedNdjsonType(String accept) { 164 for (var r : MediaRanges.of(accept).toList()) { 165 if (r.getQValue() <= 0f) 166 continue; 167 var echoed = NDJSON_ALIASES.get((r.getType() + "/" + r.getSubType()).toLowerCase(Locale.ROOT)); 168 if (echoed != null) 169 return echoed; 170 } 171 return null; 172 } 173 174 @FunctionalInterface 175 private interface FrameEncoder { 176 void write(FinishablePrintWriter w, Object element) throws IOException, SerializeException; 177 } 178 179 @Override /* Overridden from ResponseProcessor */ 180 public int process(RestOpSession opSession) throws IOException, BasicHttpException { 181 var res = opSession.getResponse(); 182 var content = res.getContent().orElse(null); 183 184 if (content == null) 185 return NEXT; 186 187 if (content instanceof Flow.Publisher<?> content2) 188 return dispatch(opSession, content2); 189 190 var a = adapters(); 191 for (var adapter : a) { 192 if (adapter.canAdapt(content)) { 193 var adaptation = adapter.adapt(content); 194 if (adaptation.isStream()) 195 return dispatch(opSession, adaptation.stream()); 196 res.setContent(adaptation.single()); 197 return RESTART; 198 } 199 } 200 201 return NEXT; 202 } 203 204 private int dispatch(RestOpSession opSession, Flow.Publisher<?> pub) throws IOException { 205 var shape = resolveShape(opSession); 206 if (shape == Shape.BUFFER) 207 return handleBuffer(opSession, pub); 208 return handleStream(opSession, pub, shape); 209 } 210 211 // ----------------------------------------------------------------------------------------------------------------- 212 // Buffer shape — collect into a List, hand to the async path. 213 // ----------------------------------------------------------------------------------------------------------------- 214 215 private int handleBuffer(RestOpSession opSession, Flow.Publisher<?> pub) { 216 var cf = new CompletableFuture<List<Object>>(); 217 var subscriber = new CollectingSubscriber(cf, maxBufferedElements(opSession)); 218 // Release the subscription whenever the future ends without the subscriber's own terminal signal 219 // (async timeout, client abort, or an overflow failure). 220 cf.whenComplete((v, t) -> { 221 if (t != null) 222 subscriber.cancel(); 223 }); 224 pub.subscribe(subscriber); 225 opSession.getResponse().setContent(cf); 226 return RESTART; 227 } 228 229 // ----------------------------------------------------------------------------------------------------------------- 230 // Streaming shapes — SSE / NDJSON. 231 // ----------------------------------------------------------------------------------------------------------------- 232 233 @SuppressWarnings({ 234 "java:S1141", // Nested try/catch cleanly separates startAsync recovery from the sync fallback. 235 "java:S3776" // Streaming setup is branchy by nature (content-type prep + async-vs-sync fallback). 236 }) 237 private int handleStream(RestOpSession opSession, Flow.Publisher<?> pub, Shape shape) throws IOException { 238 var res = opSession.getResponse(); 239 prepareStreamingHeaders(res, shape, opSession.getRequest().getHttpServletRequest().getHeader("Accept")); 240 241 var writer = res.getNegotiatedWriter(); 242 FrameEncoder encoder = shape == Shape.SSE 243 ? ReactiveResponseProcessor::writeSseFrame 244 : ReactiveResponseProcessor::writeNdjsonFrame; 245 246 var req = opSession.getRequest().getHttpServletRequest(); 247 var mdc = opSession.getRestContext().isMdcAsyncPropagation() 248 ? MdcAsyncListener.snapshot() 249 : null; 250 251 AsyncContext asyncCtx = null; 252 if (req.isAsyncSupported()) { 253 try { 254 asyncCtx = req.startAsync(); 255 } catch (IllegalStateException e) { 256 asyncCtx = null; // Already committed, or async not actually supported. 257 } 258 } 259 260 if (asyncCtx != null) { 261 // Publish async ownership + the resolved debug snapshot on the request thread BEFORE subscribing, so an 262 // inline-terminating publisher never observes a null snapshot and finish() reliably skips synchronous emit. 263 AsyncResponseProcessor.markAsyncOwnedAndSnapshot(opSession); 264 var ac = asyncCtx; 265 ac.setTimeout(0); // No artificial timeout — streams are paced by the producer / client disconnect. 266 267 // Single exactly-once completion gate shared by the subscriber terminal, the container AsyncListener 268 // fallback (error/timeout/complete), and a subscribe() that throws after handoff — so a client abort or 269 // container error can never silently skip the completion-path emit, and it can never fire twice. 270 var completed = new AtomicBoolean(false); 271 Consumer<Throwable> completion = t -> { 272 if (completed.compareAndSet(false, true)) 273 completeAsync(ac, opSession, t); 274 }; 275 ac.addListener(new ReactiveCompletionListener(completion)); 276 try { 277 pub.subscribe(new StreamingSubscriber(res, writer, encoder, mdc, completion)); 278 } catch (RuntimeException e) { 279 // subscribe() threw after the async handoff — route it through the same completion hook rather than 280 // leaking async ownership with no emit and no AsyncContext.complete(). 281 completion.accept(e); 282 } 283 return FINISHED; 284 } 285 286 // Synchronous fallback (MockServletRequest et al.): block until the publisher terminates. 287 var done = new CompletableFuture<Void>(); 288 var subscriber = new StreamingSubscriber(res, writer, encoder, mdc, 289 t -> { if (t == null) done.complete(null); else done.completeExceptionally(t); }); 290 pub.subscribe(subscriber); 291 if (! awaitSync(done, syncTimeoutMillis(opSession))) 292 // Timed out or interrupted before the publisher terminated — cancel the still-live subscription so it 293 // cannot emit late writes against a response we are about to finish. 294 subscriber.cancel(); 295 try { 296 writer.flush(); 297 res.flushBuffer(); 298 } catch (IOException e) { 299 LOG.log(Level.FINEST, e, () -> "Final flush of synchronous reactive stream failed: " + e.getMessage()); 300 } 301 return FINISHED; 302 } 303 304 private static void prepareStreamingHeaders(RestResponse res, Shape shape, String accept) { 305 var ct = res.getContentType(); 306 if (shape == Shape.SSE) { 307 if (ct == null || ! ct.contains("event-stream")) 308 res.setContentType(SseSerializer.MEDIA_TYPE); 309 res.setHeader("X-Content-Type-Options", "nosniff"); 310 } else if (ct == null) { 311 var echoed = negotiatedNdjsonType(accept); 312 res.setContentType(echoed == null ? "application/x-ndjson" : echoed); 313 } 314 res.setHeader("Cache-Control", "no-cache"); 315 res.setHeader("Content-Encoding", "identity"); 316 } 317 318 /** 319 * Blocks until the synchronous stream completes, times out, or is interrupted. 320 * 321 * @return <jk>true</jk> if the publisher terminated (normally or with an error) before the timeout; <jk>false</jk> 322 * if the wait timed out or was interrupted (in which case the caller must cancel the still-live subscription). 323 */ 324 @SuppressWarnings({ 325 "java:S2142" // Interrupt flag restored before returning. 326 }) 327 private static boolean awaitSync(CompletableFuture<Void> done, long timeoutMs) { 328 try { 329 done.get(timeoutMs, TimeUnit.MILLISECONDS); 330 } catch (InterruptedException e) { 331 Thread.currentThread().interrupt(); 332 return false; 333 } catch (TimeoutException e) { 334 LOG.log(Level.FINE, e, () -> "Synchronous reactive stream timed out: " + e.getMessage()); 335 return false; 336 } catch (ExecutionException e) { 337 // Publisher terminated with an error — the subscription is already finished, no orphan to cancel. 338 LOG.log(Level.FINE, e, () -> "Synchronous reactive stream did not complete cleanly: " + e.getMessage()); 339 } 340 return true; 341 } 342 343 private static void completeAsync(AsyncContext asyncCtx, RestOpSession opSession, Throwable error) { 344 var res = opSession.getResponse(); 345 var session = opSession.getRestSession(); 346 try { 347 if (error != null) { 348 LOG.log(Level.FINE, error, () -> "Reactive stream terminated with error: " + error.getMessage()); 349 session.exception(error); 350 } 351 if (! res.getHttpServletResponse().isCommitted()) 352 res.flushBuffer(); 353 } catch (IOException e) { 354 LOG.log(Level.FINEST, e, () -> "Flush during async stream completion failed: " + e.getMessage()); 355 } finally { 356 // Same completion-path ordering as ordinary async: render from the final stream state, then release the 357 // request, then complete the async context. Nested try/finally isolates each step so a debug-emit failure 358 // cannot suppress request close, and a request-close failure cannot suppress async-context completion. 359 try { 360 RestDebugPipeline.emitOnCompletion(session); 361 } finally { 362 try { 363 opSession.closeRequest(); 364 } catch (RuntimeException e) { // HTT: defensive; the guarded call does not throw today 365 LOG.log(Level.FINEST, e, () -> "Async request close failed: " + e.getMessage()); 366 } finally { 367 completeQuietly(asyncCtx); 368 } 369 } 370 } 371 } 372 373 private static void completeQuietly(AsyncContext asyncCtx) { 374 try { 375 asyncCtx.complete(); 376 } catch (IllegalStateException e) { 377 LOG.log(Level.FINEST, e, () -> "AsyncContext.complete() raced with the container: " + e.getMessage()); 378 } 379 } 380 381 /** 382 * Container-side fallback that routes servlet async terminal events (error, timeout, complete) through the shared 383 * completion hook. 384 * 385 * <p> 386 * The subscriber's own terminal callback is the normal completion trigger; this listener guarantees that a container 387 * error or timeout that bypasses the subscriber still reaches the exactly-once completion gate, so completion-path 388 * emission and request close are never silently skipped. All events funnel through the same gated {@link Consumer}; 389 * {@code onComplete} (fired by our own {@code AsyncContext.complete()}) is therefore a gated no-op. 390 */ 391 private static final class ReactiveCompletionListener implements AsyncListener { 392 private final Consumer<Throwable> completion; 393 394 ReactiveCompletionListener(Consumer<Throwable> completion) { 395 this.completion = completion; 396 } 397 398 @Override public void onComplete(AsyncEvent event) { completion.accept(null); } 399 @Override public void onError(AsyncEvent event) { completion.accept(event.getThrowable()); } 400 @Override public void onTimeout(AsyncEvent event) { completion.accept(new TimeoutException("Reactive stream timed out.")); } 401 @Override public void onStartAsync(AsyncEvent event) { /* no-op */ } 402 } 403 404 // ----------------------------------------------------------------------------------------------------------------- 405 // Frame encoders. 406 // ----------------------------------------------------------------------------------------------------------------- 407 408 private static void writeSseFrame(FinishablePrintWriter w, Object element) throws IOException, SerializeException { 409 if (element == null) 410 return; 411 if (element instanceof SseEvent element2) { 412 Sse.DEFAULT.write(element2, w); 413 return; 414 } 415 var data = element instanceof CharSequence element2 ? element2.toString() : Json.of(element); 416 Sse.DEFAULT.write(new SseEvent(null, data), w); 417 } 418 419 private static void writeNdjsonFrame(FinishablePrintWriter w, Object element) throws SerializeException { 420 if (element == null) 421 return; 422 var json = element instanceof CharSequence element2 ? element2.toString() : Json.of(element); 423 w.write(json); 424 w.write("\n"); 425 w.flush(); 426 } 427 428 // ----------------------------------------------------------------------------------------------------------------- 429 // Shape / timeout resolution. 430 // ----------------------------------------------------------------------------------------------------------------- 431 432 private static Shape resolveShape(RestOpSession opSession) { 433 var res = opSession.getResponse(); 434 var ct = res.getContentType(); 435 var accept = opSession.getRequest().getHttpServletRequest().getHeader("Accept"); 436 var probe = ((ct == null ? "" : ct) + "," + (accept == null ? "" : accept)).toLowerCase(Locale.ROOT); 437 if (probe.contains("event-stream")) 438 return Shape.SSE; 439 if (probe.contains("ndjson") || probe.contains("jsonl") || probe.contains("json5l") || probe.contains("json-seq")) 440 return Shape.NDJSON; 441 return Shape.BUFFER; 442 } 443 444 private static int maxBufferedElements(RestOpSession opSession) { 445 var bs = opSession.getRestContext().getBeanStore(); 446 var props = bs.getBean(ReactiveResponseProperties.class).orElse(null); 447 if (props == null) 448 props = BeanInstantiator.of(ReactiveResponseProperties.class, bs).run(); 449 return props.getMaxBufferedElements(); 450 } 451 452 private static long syncTimeoutMillis(RestOpSession opSession) { 453 var t = opSession.getContext().getAsyncTimeoutMillis(); 454 if (t <= 0) 455 t = opSession.getRestContext().getAsyncTimeoutMillis(); 456 return t > 0 ? t : AsyncResponseProcessor.DEFAULT_ASYNC_TIMEOUT_MILLIS; 457 } 458 459 // ----------------------------------------------------------------------------------------------------------------- 460 // Adapter discovery (ServiceLoader, cached, defensive against absent backing libraries). 461 // ----------------------------------------------------------------------------------------------------------------- 462 463 private static List<ReactiveStreamsAdapter> adapters() { 464 var a = ADAPTERS.get(); 465 if (a == null) { 466 synchronized (ReactiveResponseProcessor.class) { 467 a = ADAPTERS.get(); 468 if (a == null) { // HTT: inner DCL null-check missed branch requires concurrent first-load race 469 a = loadAdapters(); 470 ADAPTERS.set(a); 471 } 472 } 473 } 474 return a; 475 } 476 477 private static List<ReactiveStreamsAdapter> loadAdapters() { 478 var out = new ArrayList<ReactiveStreamsAdapter>(); 479 try { 480 var it = ServiceLoader.load(ReactiveStreamsAdapter.class).iterator(); 481 while (it.hasNext()) 482 addNextAdapter(it, out); 483 } catch (ServiceConfigurationError | RuntimeException e) { // HTT: defensive; a malformed registration file fails inside it.next(), which addNextAdapter handles, so this only triggers if hasNext() itself fails (not reproducible without breaking ServiceLoader for the other tests) 484 LOG.log(Level.FINE, e, () -> "ServiceLoader for ReactiveStreamsAdapter failed: " + e.getMessage()); 485 } 486 return List.copyOf(out); 487 } 488 489 private static void addNextAdapter(Iterator<ReactiveStreamsAdapter> it, List<ReactiveStreamsAdapter> out) { 490 try { 491 out.add(it.next()); 492 } catch (ServiceConfigurationError | RuntimeException e) { 493 LOG.log(Level.FINE, e, () -> "Skipping reactive adapter (backing library likely absent): " + e.getMessage()); // HTT: adapters are loaded once per JVM, before any test can attach a log handler, so this message supplier only runs when FINE logging is on at first use; a seam (resettable adapter cache) would make this testable 494 } 495 } 496 497 // ----------------------------------------------------------------------------------------------------------------- 498 // Subscribers. 499 // ----------------------------------------------------------------------------------------------------------------- 500 501 /** 502 * Collects emitted elements into a list and completes the supplied future (buffer shape). 503 * 504 * <p> 505 * Demand is bounded at one element more than the limit, so a compliant publisher can never deliver more than 506 * that; receiving the extra element means the stream exceeds the limit. 507 */ 508 private static final class CollectingSubscriber implements Flow.Subscriber<Object> { 509 private final CompletableFuture<List<Object>> cf; 510 private final int max; 511 private final List<Object> items = l(); 512 private final AtomicReference<Flow.Subscription> subscription = new AtomicReference<>(); 513 private volatile boolean done; 514 515 CollectingSubscriber(CompletableFuture<List<Object>> cf, int max) { 516 this.cf = cf; 517 this.max = max; 518 } 519 520 @Override public void onSubscribe(Flow.Subscription s) { 521 subscription.set(s); 522 if (done) 523 s.cancel(); 524 else 525 s.request((long)max + 1); 526 } 527 528 @Override public void onNext(Object item) { 529 if (done) 530 return; 531 if (items.size() >= max) { 532 done = true; 533 cancel(); 534 cf.completeExceptionally(new InternalServerError("Reactive response exceeded the limit of %s buffered elements.", max)); 535 return; 536 } 537 items.add(item); 538 } 539 540 @Override public void onError(Throwable t) { 541 done = true; 542 cf.completeExceptionally(t); 543 } 544 545 @Override public void onComplete() { 546 done = true; 547 cf.complete(items); 548 } 549 550 /** Cancels the upstream subscription (if any) and ignores any further signals. */ 551 void cancel() { 552 done = true; 553 var s = subscription.get(); 554 if (s != null) 555 s.cancel(); 556 } 557 } 558 559 /** Writes each emitted element as a wire frame (SSE / NDJSON), one element at a time (bounded backpressure). */ 560 private static final class StreamingSubscriber implements Flow.Subscriber<Object> { 561 private final RestResponse res; 562 private final FinishablePrintWriter writer; 563 private final FrameEncoder encoder; 564 private final Map<String,String> mdc; 565 private final Consumer<Throwable> onTerminate; 566 private final AtomicBoolean terminated = new AtomicBoolean(); 567 private volatile boolean wrote; 568 569 /** Published once by {@code onSubscribe} (Reactive Streams: at most one call); read by {@code onNext}/{@code cancel}. */ 570 private final AtomicReference<Flow.Subscription> subscription = new AtomicReference<>(); 571 572 StreamingSubscriber(RestResponse res, FinishablePrintWriter writer, FrameEncoder encoder, 573 Map<String,String> mdc, Consumer<Throwable> onTerminate) { 574 this.res = res; 575 this.writer = writer; 576 this.encoder = encoder; 577 this.mdc = mdc; 578 this.onTerminate = onTerminate; 579 } 580 581 @Override public void onSubscribe(Flow.Subscription s) { 582 subscription.set(s); 583 s.request(1); 584 } 585 586 @Override public void onNext(Object item) { 587 try { 588 withMdc(() -> writeFrame(item)); 589 subscription.get().request(1); 590 } catch (RuntimeException e) { 591 subscription.get().cancel(); 592 terminate(unwrap(e)); 593 } 594 } 595 596 @Override public void onError(Throwable t) { terminate(t); } 597 @Override public void onComplete() { terminate(null); } 598 599 /** 600 * Cancels the underlying subscription and marks this subscriber terminated so no late frames are written. 601 * 602 * <p> 603 * Invoked by the synchronous fallback path when the wait times out or is interrupted before the publisher 604 * terminates, preventing an orphaned subscription from emitting writes against a finished response. 605 */ 606 void cancel() { 607 if (! terminated.compareAndSet(false, true)) // HTT: true branch needs the publisher to terminate between the wait timing out and cancel(), a cross-thread race; a seam would make this testable 608 return; 609 var s = subscription.get(); 610 if (s != null) 611 s.cancel(); 612 } 613 614 private void writeFrame(Object item) { 615 try { 616 encoder.write(writer, item); 617 writer.flush(); 618 // PrintWriter (which writer extends) never lets an IOException from the underlying stream escape — 619 // it swallows it and only records it via checkError(). Without this check, a broken/closed client 620 // connection is silently absorbed here and the pump keeps "succeeding" forever instead of detecting 621 // the write failure and cleaning up (the dead-client cleanup path, see SEP-2243). 622 if (writer.checkError()) 623 throw new IOException("Write failed: the client connection is no longer writable."); 624 res.flushBuffer(); 625 wrote = true; 626 } catch (IOException | SerializeException e) { 627 throw isex(e); 628 } 629 } 630 631 private void withMdc(Runnable r) { 632 MdcAsyncListener.wrap((BiConsumer<Object,Throwable>) (v, e) -> r.run(), mdc).accept(null, null); 633 } 634 635 private void terminate(Throwable t) { 636 if (! terminated.compareAndSet(false, true)) 637 return; 638 withMdc(() -> { 639 if (t != null && ! wrote) { 640 try { 641 if (! res.getHttpServletResponse().isCommitted()) 642 res.getHttpServletResponse().sendError(SC_INTERNAL_SERVER_ERROR); 643 } catch (IOException e) { 644 LOG.log(Level.FINEST, e, () -> "sendError on pre-write stream failure failed: " + e.getMessage()); 645 } 646 } 647 }); 648 onTerminate.accept(t); 649 } 650 651 private static Throwable unwrap(Throwable t) { 652 if ((t instanceof IllegalStateException || t instanceof CompletionException) && t.getCause() != null) 653 return t.getCause(); 654 return t; 655 } 656 } 657}