Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 38 ยท HTTP Server and Clients

Streaming, Server-Sent Events and Async

Handle slow work and live data in Micronaut: reactive return types, server-sent events, streaming responses and @ExecuteOn. With runnable Java stand-ins.

A simple controller returns a value and finishes. Real services also wait: on a database, on another service, on a file, or for the next piece of data to push to a browser. Micronaut's server is built on a small set of event-loop threads, so how you wait matters. If you block an event-loop thread, every connection that thread serves is delayed.

This lesson explains the three tools for non-trivial responses: returning asynchronous types, moving blocking work to another thread pool with @ExecuteOn, and streaming data to the client with server-sent events (SSE). The framework code is read-only because Micronaut is not installed on this site. The runnable programs are Java stand-ins for the underlying ideas: futures that compose, and the exact text format of an SSE stream.

Event loop and blocking executor

The server accepts requests on a few event-loop threads (roughly one per CPU core). They are very efficient as long as they never wait. A method that calls a blocking JDBC query or reads a big file should run somewhere else:

Java
import io.micronaut.scheduling.TaskExecutors;
import io.micronaut.scheduling.annotation.ExecuteOn;

@Controller("/reports")
public class ReportController {

    @Get("/{id}")
    @ExecuteOn(TaskExecutors.BLOCKING)
    public Report find(long id) {
        return repository.loadSlowly(id);   // safe to block here
    }
}

TaskExecutors.BLOCKING is a larger thread pool meant for blocking I/O. TaskExecutors.VIRTUAL uses virtual threads on a modern JDK, where blocking is cheap. Put @ExecuteOn on the controller class to cover all its methods. As a rule: if a method may block, give it an executor; if it only returns reactive types and never blocks, leave it on the event loop.

Asynchronous return types

A controller method can return a promise of a result instead of the result itself. The thread is freed immediately and the response is written when the value arrives.

Java
@Get("/{id}/summary")
CompletableFuture<Summary> summary(long id) {
    return service.loadAsync(id).thenApply(Summary::of);
}

@Get("/{id}/name")
Mono<String> name(long id) {            // Reactor; Micronaut also supports RxJava
    return service.findName(id);
}

Mono<T> is zero or one value, Flux<T> is a sequence, and Publisher<T> is the common interface under both. Reactive types are lazy: nothing happens until something subscribes, and Micronaut subscribes for you. They also support back-pressure, which means a slow consumer can tell a fast producer to wait.

When two independent lookups are needed, start both and combine them instead of waiting for one after the other:

Java
Mono<User> user = users.find(id);
Mono<List<Order>> orders = orderService.forUser(id);
return Mono.zip(user, orders).map(t -> new Profile(t.getT1(), t.getT2()));

Streaming JSON and files

Returning a Flux<Book> with the type application/x-json-stream sends one JSON document per line as results become available, so the client can start processing the first item while the server is still producing the rest:

Java
@Get(value = "/stream", produces = MediaType.APPLICATION_JSON_STREAM)
Flux<Book> stream() {
    return repository.streamAll();
}

To send a file, return a StreamedFile or a SystemFile; Micronaut sets headers such as Content-Type and Content-Disposition and supports range requests for large files. For uploads, StreamingFileUpload mirrors this on the way in (see request binding and responses).

Server-sent events

SSE is a simple way to push updates from the server to a browser over one long-lived HTTP response. The browser's built-in EventSource API reconnects by itself. You return a Publisher<Event<T>>:

Java
import io.micronaut.http.sse.Event;

@Get(value = "/ticker", produces = MediaType.TEXT_EVENT_STREAM)
Flux<Event<Price>> ticker() {
    return Flux.interval(Duration.ofSeconds(1))
               .map(n -> Event.of(new Price("ACME", 100 + n)).id(String.valueOf(n)).name("price"));
}

Each item is written to the connection as soon as it exists. On the browser side:

JavaScript
const source = new EventSource("/ticker");
source.addEventListener("price", (e) => console.log(JSON.parse(e.data)));

SSE is one-way (server to client) and runs over plain HTTP, which makes it easier to deploy than WebSockets. Use WebSockets (@ServerWebSocket) when the browser also needs to send frequent messages.

Three ways to wait well

@ExecuteOn Move blocking work off the event loop.
Async types Return a Mono, Flux or future.
Streaming Send data as it appears.

Never block an event-loop thread.

1 / 2

Stand-in 1: composing futures

The next program uses CompletableFuture, the standard Java promise type, to show why combining independent calls is faster than chaining them. Each "service" pretends to take a fixed time using a simulated clock, so the printed numbers never vary. The sequential version adds the durations; the parallel version takes the longest one.

Java Sequential versus parallel calls

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

In Micronaut the same code would use Mono.zip(...) and onErrorReturn(...). The idea carries across every async library: start independent work together, combine the results, and decide what happens on failure.

Stand-in 2: the SSE wire format

An SSE response is plain text. Each event is a few field: value lines followed by a blank line. This program builds the exact bytes the ticker() method above would send, and parses them back the way a browser does, so you can see how little magic there is.

Java Writing and parsing an event stream

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The id field matters for reconnection: when a browser reconnects it sends the last id it saw in a Last-Event-ID header, so the server can resume where it left off.

Practical advice

  • Know which thread you are on. Database drivers using JDBC block. Use @ExecuteOn(TaskExecutors.BLOCKING) or a reactive driver.
  • Do not call block() or get() in reactive code. It defeats the purpose and can deadlock the event loop.
  • Bound your streams. Stop infinite streams when the client disconnects; Micronaut cancels the subscription for you.
  • Mind proxies. Reverse proxies sometimes buffer responses. For SSE, disable buffering for that path (for example X-Accel-Buffering: no with nginx).
  • Set timeouts. Both for server read idle time and for client calls, so a stuck dependency cannot hold resources forever.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why should a controller method that runs a blocking JDBC query use @ExecuteOn(TaskExecutors.BLOCKING)?

    The annotation moves the call to a pool meant for blocking work, so event-loop threads never wait.
  2. 2. What does a Flux<T> return type promise you?

    Flux is a reactive sequence. Nothing runs until it is subscribed to, and consumers can slow the producer.
  3. 3. Which media type marks a server-sent events response?

    Browsers recognize text/event-stream and feed the data to EventSource.
  4. 4. What ends one event in the SSE text format?

    Fields are written as lines, and a blank line completes the event.

Summary

  • Event-loop threads must not block; give blocking methods @ExecuteOn(TaskExecutors.BLOCKING) or use virtual threads.
  • Return CompletableFuture, Mono, Flux or Publisher for asynchronous results.
  • Combine independent calls with zip or thenCombine, and plan recovery with fallbacks.
  • JSON streams send one document per line; SSE (text/event-stream) pushes events to browsers over plain HTTP.
  • SSE is one-way; use WebSockets for two-way messaging.
  • Watch for proxy buffering and always set timeouts.

Next: Data Sources and Connection Pools