Spring WebFlux
Mapping a Flow of Datastar events onto a reactive response.
On the reactive side there is no servlet stream to write into. There is a Flow of events, and
Spring knows how to turn ServerSentEvent into a response. The adapter’s whole job is the step
between: turning Streamlord’s DatastarEvent into Spring’s ServerSentEvent.
@GetMapping("/counter")
fun counter(): ResponseEntity<Flow<ServerSentEvent<String>>> =
ticks
.map { n -> PatchElements("""<span id="counter">$n</span>""") }
.asDatastarResponse()
asDatastarResponse() is the flow of server-sent events in a ResponseEntity that carries the
content type and the two headers a stream needs on its way through a proxy,
Cache-Control: no-cache and X-Accel-Buffering: no. They are on Operations.
Two smaller pieces sit under it: asServerSentEvents() on a Flow<DatastarEvent> gives you the
bare flow, for when you build the response yourself, and toServerSentEvent() converts a single
event. Return the bare flow from a controller and Spring sets the content type and no other
header, so prefer the response. Everything before these is your flow, and everything after is
Spring’s.
Markup that holds a value from outside is built with interpolate,
and PatchElements takes the Html it returns as it is:
@GetMapping("/feed")
fun feed(): ResponseEntity<Flow<ServerSentEvent<String>>> =
flowOf(repository.search("gate"))
.map { hits ->
val rows = hits.map { interpolate { "<li>${+it.title}</li>" } }.joinToHtml()
PatchElements(interpolate { """<ul id="feed">${+rows}</ul>""" })
}.asDatastarResponse()
The frames are written by Spring’s own encoder, so they are spelled Spring’s way: no space after
any colon, event:datastar-patch-signals, and id: ahead of event:. The fields and the data
are the ones Ktor and WebMVC send, and the Datastar client reads both spellings alike.
The guard
asDatastarResponse() uses Streamlord., which has the elements guard switched off. To
run your HTML through the guard, pass the bean you declared. It arrives through the
controller’s constructor:
@RestController
class CounterController(private val streamlord: Streamlord) {
@GetMapping("/counter")
fun guarded(): ResponseEntity<Flow<ServerSentEvent<String>>> =
ticks
.map { n -> PatchElements("""<span id="counter">$n</span>""") }
.asDatastarResponse(streamlord)
}
Not as a parameter of the handler method. Spring tries to build a new Streamlord for a
parameter of that type instead of injecting your bean, fails on the constructor, and answers
every request to that handler with 500 and a BeanInstantiationException, as
on WebMVC.
Reading signals
The exchange reads them as the servlet request does on WebMVC, by the same rule for where they
live, with the same limit of size and of 64 levels of nesting, and the same check of the body’s
Content-Type. On WebFlux each read is a suspend function, so the handler is one too:
@PostMapping("/search")
suspend fun search(exchange: ServerWebExchange): ResponseEntity<Flow<ServerSentEvent<String>>> {
val query = exchange.readSignals().string("query") ?: ""
val hits = repository.search(query)
return flowOf(PatchElements(renderResults(hits), selector = "#results", mode = ElementPatchMode.INNER))
.asDatastarResponse()
}
exchange. and exchange.
decode them into your class through the bean’s codec, and exchange. gives the
text. A body that is not declared application/ throws SignalsMediaTypeException, one
over the limit SignalsTooLargeException, and one the codec cannot read SignalsDecodeException;
@Import( answers them with 415, 413 and 400, as on WebMVC.
A form sent with contentType: 'form' holds fields rather than signals: Signals
shows how to read one.
Redirects, the address bar and removing signals
What a stream does with redirect, replaceUrl, pushUrl and removeSignals, a flow does with
the events they send, built by ExecuteScript and PatchSignals:
@PostMapping("/quests")
fun save(): ResponseEntity<Flow<ServerSentEvent<String>>> =
flowOf(
PatchSignals.remove("draft"),
ExecuteScript.replaceUrl("/quests/7"),
ExecuteScript.redirect("/quests"),
).asDatastarResponse()
ExecuteScript. adds a history entry where replaceUrl replaces one, and
PatchElements. removes elements, as removeElements does on a stream. Each refuses what
the stream refuses: redirect a javascript: URL, remove a name the client cannot hold.
Heartbeats
A flow on WebFlux has no heartbeat. The bean’s heartbeat and compress belong to a Streamlord
stream, and a flow is mapped onto Spring’s server-sent events without one, so while the flow is
quiet nothing is written, whatever the bean says. Behind a proxy that closes a connection silent
for longer than your quietest stretch, merge a ticker of comments into the flow:
@GetMapping("/feed")
fun feed(): ResponseEntity<Flow<ServerSentEvent<String>>> {
val keepAlive =
flow {
while (true) {
delay(15.seconds)
emit(ServerSentEvent.builder<String>().comment("keep-alive").build())
}
}
val response = ticks.map { n -> PatchElements("""<span id="counter">$n</span>""") }.asDatastarResponse()
return ResponseEntity.ok().headers(response.headers).body(merge(response.body!!, keepAlive))
}
The response keeps the headers asDatastarResponse() gave it. The merged flow ends when the
client goes away, not when ticks does, which is what a live feed wants. Why fifteen seconds is
on Operations.
Cancellation
When the client goes away, WebFlux cancels the subscription, which cancels the coroutine behind
the flow. A flow { } with a finally releases what it held, and nothing in Streamlord holds
anything past the frame it is writing.
What this page does not cover
Content Security Policy is on Security, including the three lines that put a nonce
on an exchange from a WebFilter of your own.
Backpressure strategy, schedulers and the rest of the reactive toolbox are Spring’s, and the
adapter deliberately does not reach into them. If your flow is hot and fast, the usual
buffer, conflate and sample operators apply before asDatastarResponse(), unchanged.