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 &mdash; 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&lt;T&gt;} (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}) &mdash; 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}) &mdash; 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) &mdash; 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 &mdash; 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}