Skip to content
Streamlordv0.23.0

Strings

A function that returns HTML is a first-class way to write markup here.

Every place Streamlord takes HTML takes a String, and the Html that interpolate returns as well. A function returning a triple-quoted literal is not a fallback for people who have not learned the DSL. It is one of the three supported ways, and the editor tooling treats it as such.

@org.intellij.lang.annotations.Language("HTML")
fun counter(count: Int): String =
    $$"""
    <div id="counter" data-signals="{count: $$count}">
        <button data-on:click="$count++">Raise</button>
        <span data-text="$count"></span>
    </div>
    """.trimIndent()
get("/counter") {
    call.respondDatastar { patchElements(counter(3)) }
}

Two things make this comfortable.

$$"""..."""

Kotlin 2.2 and newer. In a multi-dollar string a single $ is just a dollar, so $count reaches the browser as the signal it is, and $$count is the Kotlin template.

Without it you are back in the $ trap: $count either fails to compile or, when a count happens to be in scope, silently ships its value, data-text="3", or data-text="" when it was empty. On older Kotlin, write ${'$'}count.

@Language("HTML")

From org.intellij.lang.annotations, which your build already has through the Kotlin standard library. Streamlord declares it compileOnly, so nothing new reaches you.

IntelliJ then treats the string as HTML: highlighting, tag completion, and, with the official Datastar plugin, completion of every data-* attribute. Streamlord’s own parameters already carry the annotation (patchElements, PatchElements, respondElements, datastarElements, ElementsResponse; JSON for signals, JavaScript for scripts), so a literal passed straight in is injected without you writing anything. On your own functions, add it yourself.

The VS Code extension does not need the annotation: it treats a string as HTML when it opens with a tag, carries the annotation, by its short name or its qualified one, or has a // language=HTML comment, and gives it the same diagnostics, completions, hover and highlighting as a template file. A string handed straight to a parameter of a function of the same file that carries the annotation gets all of it but the highlighting. Both editors judge the values written into such a string.

The guard

The DSL guards its own expressions because it builds them. A string arrives finished, so the guard has to walk it, and that is opt-in:

install(StreamlordPlugin) { guardElements = true }

With it on, every element patch and elements response leaving that instance is walked by ElementsGuard. It finds each data-* attribute whose value is an expression and runs it through ExpressionGuard, so a data-text="" left behind by a template that ate an empty value throws InterpolatedExpressionException naming the attribute instead of reaching the browser.

The same walk catches a mistyped attribute. data-onn:click is one letter from data-on:click and throws MistypedAttributeException saying so. A name that carries a key or a modifier is judged on any one-letter slip, because data-signal:name is nobody’s own attribute. A bare data-* name is judged far more narrowly: only a changed letter in a long name, so data-indicater and data-computer are caught while data-test, data-kind, data-size and data-theme are yours and pass untouched. A bare name that merely adds a letter passes too: data-signal is left alone, because data-animated and data-effects are honest words in the same shape.

The guard takes two letters swapped for one slip as well, where a key or a modifier follows: data-no:click. The editors warn about the names the guard throws for, and go one step further with a hint, where a bare name one edit away shows that Datastar was meant: its value reads a signal or calls an action where an expression could start, data-shwo="$open", or it stands without a value as the attribute it is near is written, data-persits. data-test="login" says nothing there, and neither does data-test="costs $5" or a value with a template of its own.

With the guard on, a patch without a selector, which the client matches to the page by id, needs an id on each of its top-level elements: patchElements("<p>Saved</p>") throws DatastarEventValidationException saying <p> has no id, since the client would skip it with only a console warning. Without the guard such a patch is sent as written, because the SDK specification’s own tests send <div>Merge</div> that way.

It is a small scan that builds no tree and copies no markup, and it skips <script> and <style> bodies. ElementsGuard.check(html) is also there to call directly, which is worth doing in the tests of your markup functions.

In IntelliJ, where nothing flags an unknown data-* name on its own, this guard is the check.

Values from outside

guardElements walks a finished string, so it can tell you an expression was eaten. What it cannot tell you is where a value came from, because by then Kotlin has concatenated everything. interpolate turns that around: mark each value where it stands, and Streamlord keeps it out of the string until the markup is whole, which means it knows exactly where each value landed.

fun hit(title: String, url: String): Html =
    interpolate { """<li><a class="lt-link" href="${+url}">${+title}</a></li>""" }

The + marks a value. It may stand in a loop, rows.joinToString("") { "<li>${+it}</li>" }, and a trim call on the string runs before the values go in. A value written without the mark is filled in by Kotlin as in any string, neither escaped nor refused: that is right for a constant and for markup you built, and the editors warn of anything else and offer to mark it. A number is never marked, since + on a number is Kotlin’s own, and is written as the number it is. A mark belongs to the block it is written in, and written anywhere else it is no mark and no value stands there: do nothing to the string but trim it. Inside the block this is the block. So is the receiver of a call written without one, toString() or an extension of your own on Any, and a unaryPlus of your own on String is not reached there, since the block’s + comes first. The editors know the block by the name interpolate, and not by another name you import it under.

A mark you forget is caught by the editors alone: the code compiles, and the value is written as it is. Where nobody has an editor open, the analysis holds the project to it in one test:

@Test
fun `no value reaches a page without its mark`() {
    val failures = Analyzer().analyzeProject(java.io.File("src/main/kotlin")).failures(strict = true)

    assertTrue(failures.isEmpty(), failures.joinToString("\n") { it.format() })
}

The same rule with the values as arguments, which is the form Java has:

fun hitByPlace(title: String, url: String): Html =
    interpolate("""<li><a class="lt-link" href="%s">%s</a></li>""", url, title)

%s is a placeholder and %% writes one %. Every other % is literal, so width: 50% and /a%20b need no ceremony. A miscounted placeholder throws rather than shipping a half-filled page. In a block a % is always literal.

What happens to a value is decided by where it landed, not by where it came from, and it is the same for a value marked with + and for the value of a %s:

Where the value landsWhat happens to it
Element textEscaped
A quoted attribute that is not Datastar’sEscaped
A URL attribute: href, src, action, formaction, xlink:href, poster, cite, background, ping, manifest, and values, to or from on an SVG animationEscaped, and refused unless the whole URL, every value in it written, is relative, http, https, mailto or tel
A URL the browser loads code from: src of <script>, <iframe> or <embed>, href of <base> or <link>, data of <object>, href of an SVG <script>Escaped, and refused unless the markup before the value already fixes the host: /x, #, ?, or a whole origin such as https://cdn.example/
The content of a <meta> that starts with a time, as http-equiv="refresh" reads itEscaped, and the URL after url= refused unless it is relative, http, https, mailto or tel
A style attributeRefused, unless it is a number
A data-* attribute Datastar evaluates, an expression or a signal filter, or follows as a signal path: data-bind, data-ref, data-indicator; and Pro’s data-match-media, whose query the reference writes as a string literalRefused, unless it is a number or a boolean
A data-* attribute Datastar reads as it stands: data-nonce, data-preserve-attr, data-ignore, data-ignore-morphEscaped
An event handler such as onclick, or srcdocRefused
A tag name, an attribute name, an unquoted valueRefused
Inside <script> or <style>Refused

So the url in the example above may be /heads/1 or https://thurn.example/, and a javascript: URL throws instead of becoming a link that runs. The value is judged whole, as the browser reads it: a value that ends a path the markup begins takes anything, because the markup already chose where it points, and href="${+a}${+b}" cannot be made into javascript: across its two values. Character references are decoded once the attribute is whole, as the browser does, so href="&${+a}" cannot be finished into &#106;avascript: by its value. A Trusted value counts toward the URL as the markup does: it is written as it stands, and the URL is still judged whole, so href="${+a}${+b}" given Trusted("") and javascript:alert(1) throws. Only a URL with no other value in it goes unjudged.

A URL that loads code asks more of the markup. https:// settles the scheme of a <script src> but not whose script it is, so a value there is refused until the markup has written the host too: <script src="https://cdn.example/${+file}"> takes a file name, <script src="${+file}"> takes nothing. A single / is not enough on its own either, since the value could add a second and name another host; /js/${+file} is. The same goes for <link href>, whatever its rel, since a stylesheet or a module loads from there too. The exception says so, and its loadsCode tells such a refusal apart. Wrap a URL you chose yourself in Trusted.

The markup is read the way the browser’s tokenizer reads it, comments, end tags and all, and in more than one way: as HTML, as the inside of an <svg> or <math>, where a title or a textarea holds elements rather than text, and following the browser’s own stack of open elements, which switches between HTML and svg or math, and the rules for CDATA sections, as the markup opens and closes them. A value has to be safe every way, since a patch with an SVG namespace carries no <svg> of its own. A <noscript> holds elements, as the client parses a patch with scripting off; markup that mentions one is also read with scripting on, as a page loads it, where a noscript holds text, and the stricter reading wins. So a title or a textarea that shows markup as a code sample cannot take a value inside a data-* attribute of that sample; make the whole sample one value instead, where it is text either way.

One thing the reading does not follow yet is the browser building the page: inside a <select> the browser drops start tags such as <title> or <style> that the reading still takes as the start of text, so markup that writes one there can put a later value somewhere it is not judged. Only markup you write yourself can do this, never a value; leave such tags out of a <select>.

The refusals are the point. Escaping cannot save these: a value in a data-* attribute Datastar evaluates becomes part of a Datastar expression, and your own server signed the page it arrived on; a value in data-bind, data-ref or data-indicator is a signal path the client follows without a guard, so __proto__.x there writes into every object of the page; a value in an attribute name or an unquoted value can add attributes beside itself, because escaping does not escape a space; HTML escaping inside a <script> is meaningless; and an escaped value in onclick or at the head of an href is still something the browser runs. UnsafeInterpolationException says which value, where it landed, and what to do instead.

val name = "Gorvek"
val heads = 3

interpolate { """<li data-text="${+name}"></li>""" }    // throws

// Passes: a number carries no expression, and needs no mark.
interpolate { """<li data-signals="{n: $heads}"></li>""" }

A number or a boolean is let into a Datastar attribute because its text is digits, a dot, a sign or true/false. A number here is a kotlin.Number: a UInt or a ULong is not one, so it is refused there; write n.toLong(). No string renders that way and also closes a quote, so the common honest case of a server-rendered initial signal needs no waiver.

Markup built from markup

What interpolate returns is Html: markup whose values have been through it. Hand it to patchElements, respondElements or datastarElements as it is; inside respondDatastar { } patchElements(html) needs no import of its own. Hand it to another interpolate, and it is written as it stands in element text, as long as its own markup closes everything it opens and ends nothing it did not open. An Html that ends inside a tag, a quoted value, a comment or a <script>, leaves an element open, interpolate("<svg>") or an <li> without its </li>, or ends one it did not open, x</div>, would change how the browser reads the values after it, so it is escaped like a string instead. Anywhere else, inside an attribute, it is characters like any value, and escaped or refused as one.

val heading = interpolate { """<h2 class="lt-heading">${+"Gorvek"}</h2>""" }

interpolate { """<section id="hero">${+heading}<p>${+"<the oath>"}</p></section>""" }

A list of rows is a list of Html, and joinToHtml() makes them one, to be marked as a single value. Each row already closes what it opens, so nothing is read again or escaped:

val hits = repository.search("gate")
val rows = hits.map { interpolate { """<li><a href="${+it.url}">${+it.title}</a></li>""" } }

interpolate { """<ul class="lt-list">${+rows.joinToHtml()}</ul>""" }

joinToString would give a String, which interpolate escapes, so the rows would show as their tags. Where you build the events yourself, as a Flow does on Spring WebFlux, PatchElements(html) and ElementsResponse(html) take the Html too.

Only interpolate makes an Html, and joinToHtml() from the ones it made, so holding one says where it came from. A Kotlin template writes its markup, so "<main>$page</main>" works too, but the editors cannot see that page is markup unless its type says so. An Html is never equal to a String: JUnit’s assertEquals("<p>x</p>", interpolate(...)), or AssertJ’s isEqualTo, compiles and fails though both print the same, so compare .text.

When you mean it to be markup

Wrap it in Trusted, which writes the value as it stands wherever it lands:

val hits = repository.search("gate")

interpolate { """<ul class="lt-list">${+Trusted(renderResults(hits))}</ul>""" }

That waives both the escaping and the refusals for that value, which is right for a fragment you rendered yourself and wrong for anything that came out of a request. It is a word in your source that a reviewer can search for, which is the whole reason it is a type and not a flag. It vouches for itself alone: in a URL with other values it is part of the URL, and the URL is judged whole. Its text is markup like the literal around it, so the other values are judged where it puts them:

val name = "Gorvek"

val title = Trusted("title")
val onclick = Trusted("onclick")
val script = Trusted("script")

interpolate { """<button ${+title}="${+name}">""" }    // escaped into the title
interpolate { """<button ${+onclick}="${+name}">""" }  // throws: the browser runs it
interpolate { "<${+script}>${+name}</${+script}>" }    // throws: a script body

This is the editors’ rule, at run time

The editors ask the same question of a Kotlin template in an HTML string as you type, with the same reading of the markup: core’s, which interpolate uses and the VS Code analysis is held to. Every $name, ${...} and value joined with + is judged by where it lands, in a + chain handed straight to a DSL call too:

Where the value landsWhat the editors say
Element text, a quoted attribute, a URL whose literal start settles the scheme (#, /, ?, https://)unescaped-interpolation: a hint, a warning when the value is a String, or markup anywhere but element text, where markup says nothing; with a fix that marks the values with + in interpolate { }, and in element text a second, “Mark … as markup”, that wraps the value in Trusted(...)
The start of a URL, style, a data-* expression, signal path or filter, <script>, <style>, on*, srcdocunsafe-interpolation: a warning, since escaping cannot help there, but none for a number, a boolean or null in code, nor for a boolean in style; at the start of a URL, the URL of a <meta> refresh among them, with the fix that marks the values with + in interpolate { }, which refuses a URL that runs, and none after a scheme the markup writes that does more than navigate, javascript: or data:, since interpolate refuses every value there; in the body of a <style> with the fix that marks the value as Trusted(...)
A URL the browser loads code from (src of a script, an iframe or an embed, href of a base or a link, data of an object) whose literal start does not fix the hostunsafe-interpolation: a warning, and no fix, since interpolate refuses it too; in a call to interpolate, an error where the value is known
An attribute value without quotesunsafe-interpolation: a warning, a hint for a number or a boolean, with a fix that quotes the value, put first only for a number or a boolean, since any other value is still to be escaped once it is quoted
A tag name, an attribute name, a list of attributes, an end tagunsafe-interpolation: a hint, a warning when the value is a String or markup; an end tag takes no attributes, so write it from literals alone
$name where a Datastar signal could standkotlin-interpolation, the dollar trap; a hint when name is declared a number or a boolean, which is safe to write in, so only what you meant is in question

A value the editor can see is yours says nothing anywhere: a const val, also a qualified one such as ${Routes.SAVE}, a literal, ${"$"}, an enum entry such as ${Tab.HOME}, an if or a when whose every branch is one, and a call to one of Streamlord’s expression helpers whose arguments are all yours or a declared number or boolean, ${signal("count")} or ${post("/save")}. A helper is only as safe as what it is given: ${signal(query)} writes the request’s text into a Datastar expression, where it runs, so it is judged as the String it returns. IntelliJ reads the enum itself and takes an entry only when the enum does not override toString. Any other value is judged by what interpolate would let in where it lands. A number or a boolean says nothing in text, an attribute, a URL, a data-* expression or style, nor in a <script>, a <style> or an event handler, which digits, true and false cannot end, though a kotlin.Number, which any class may be, is no digits there; one that may be null, an Int?, only where escaping is enough and in code, which null cannot end either. Where interpolate would refuse such a value, the rewrite leaves it unmarked. An unsigned number, a UInt or a 3u, says nothing where escaping is enough and is a hint in a data-* expression or style: Kotlin writes its digits, but interpolate would refuse it there. A value that is markup you built, as a whole, says nothing in element text and is a warning anywhere else, where its quotes and tags can end what holds it: an HTML literal, an interpolate(...) or Trusted(...) call, a value declared Html or @Language("HTML"), kotlinx.html output, or a joinToString whose every element is markup. Html and Trusted are Streamlord’s own; a com.acme.Html is judged as any type the editor does not know. Markup joined to a value is read as one string: in ${"<b>" + query + "</b>"} the literals are markup and query is the value that is judged. An if, a when or an ?: is judged by its weakest result, so ${if (blank) "nothing" else query} is the String it may be.

VS Code knows what the file it is in declares, each name in the scope it is declared in, and every const val in the workspace that the file does not declare as something else; it reads a comparison as a Boolean, arithmetic of numbers it knows as a number, and the name of an entry of an enum the file shows as yours; IntelliJ also knows the types, and what it knows of a value comes before anything the text suggests. Nothing here is an error, because a value the text cannot see into may well be a number.

For a String in element text the editors cannot tell which you hold, so they offer both the rewrite and “Mark … as markup”, which wraps the value in Trusted(...). The rewrite stands first in the list, and in VS Code neither is the preferred fix, the one Auto Fix applies unasked: text from outside wants the rewrite, a fragment you rendered yourself wants Trusted, or better, to be declared Html.

The rewrite, before and after

“Mark the values with + in interpolate { }” is offered on a value’s warning wherever interpolate accepts every value of the string, and as a context action anywhere else in such a string: among the intentions in IntelliJ, under Refactor in VS Code. This is what it writes.

The string stays as you wrote it, in the block, with each value marked where it stands. A trim call stays on the string, and CSS in the body of a <style> is marked as Trusted(...), your word that it is yours. That fix is on the value in the <style>, and the other values say that the fix marks it so:

class LayoutContext(val pageId: String, val sectionId: String)

fun pageHtmlBefore(k: LayoutContext, pageStyle: String?, mainHtml: String): String =
    """
    <div id="${k.pageId}">
        <style>${pageStyle.orEmpty()}</style>
        <div id="${k.sectionId}">$mainHtml</div>
    </div>
    """.trimIndent()

fun pageHtmlAfter(k: LayoutContext, pageStyle: String?, mainHtml: String): String =
    interpolate { """
    <div id="${+k.pageId}">
        <style>${+Trusted(pageStyle.orEmpty())}</style>
        <div id="${+k.sectionId}">${+mainHtml}</div>
    </div>
    """.trimIndent() }.text

Under .trimIndent() the fix is first in the list but in VS Code never the preferred one, because the trim now runs before the values go in: a value that holds a line break no longer changes how much is trimmed. .trimMargin() has no such catch. Nor is it preferred beside a value that may be null, a String? or an Int?: a template writes null for it, which no page means, and interpolate nothing, as the message says.

A $$"..." literal keeps its prefix, so a single dollar that was text for the browser stays text. Literals joined to values with + become one string, and where they are written differently each keeps its form, with the value marked at the end of the one before it:

fun priceBefore(name: String) = $$"""<p title="$${name}" data-text="$price"></p>"""
fun priceAfter(name: String) = interpolate { $$"""<p title="$${+name}" data-text="$price"></p>""" }.text

fun rowBefore(name: String, note: String) = "<li title=\"" + name + "\">" + note + "</li>"
fun rowAfter(name: String, note: String) = interpolate { "<li title=\"${+name}\">${+note}</li>" }.text

fun mixedBefore(name: String, note: String) = "<li title=\"" + name + """">""" + note + "</li>"
fun mixedAfter(name: String, note: String) = interpolate { "<li title=\"${+name}" + """">${+note}""" + "</li>" }.text

Every value is marked as it is written, a collection too. interpolate writes a List it is given as one value, the way a template does, so the page stays as it was:

class Hero(val tags: List<String>)

fun tagsBefore(hero: Hero) = "<p>${hero.tags}</p>"
fun tagsAfter(hero: Hero) = interpolate { "<p>${+hero.tags}</p>" }.text

A value that is yours, a constant, an enum entry or ${"$"}, stays unmarked where interpolate would refuse it or might escape markup it holds: Kotlin fills it in as before, and interpolate reads it as part of the markup:

const val SAVE_ROUTE = "/save"

fun saveBefore(label: String) = "<button data-on:click=\"@post('$SAVE_ROUTE')\">$label</button>"
fun saveAfter(label: String) = interpolate { "<button data-on:click=\"@post('$SAVE_ROUTE')\">${+label}</button>" }.text

When no rewrite is offered, the warning of each value ends with the reason:

What stands in the wayWhat to do
A value where interpolate refuses a String: a data-* expression, style, a <script>, an event handler, the markup’s structureMove that value out first: into an attribute of its own read with el.dataset, a class, or a literal. A Trusted there is accepted as it is.
A call or an if in element text that may give markup, ${if (open) "<li>$name</li>" else ""}Build that part with interpolate or declare it Html, so that the rewrite does not escape it.
A call or an index after one literal of a + chain, "<p>" + name + "</p>".uppercase()The call is that literal’s alone. Put the chain in brackets, or the call on the result.
A trim call with a margin that is not a literalTrim the string yourself, or use `
A value that says this, or calls toString(), hashCode(), let { } and their like without a receiverIn the block these are the block’s: name the value first, val self = this, or write the receiver, this@Row.toString().

A string in an annotation’s argument or a const val gets no rewrite, since Kotlin takes a constant there, and neither does a string whose values need no escaping: numbers, constants, an Html in element text.

A call to interpolate is judged as it will run. A miscounted %s is an error, interpolate-placeholders, because it always throws. A %s whose value interpolate will refuse, a String in a data-* expression, is an error where the value is known to be one and a warning where it is not; a UInt there is an error, with a toLong() fix. And a Kotlin template written into the format, interpolate("<p>$name</p>"), is interpolate-template: Kotlin fills it in before interpolate sees the markup, so it is neither escaped nor refused, and the fix turns it into a %s placeholder with the value among the arguments, or in a block marks it with + where it stands. In VS Code the fix is not the preferred one under .trimIndent(), where the trim then runs before the value goes in, nor for a value that may be null, which a template writes as null and interpolate as nothing. Markup is no exception, an Html or a Trusted: in interpolate("<div>$inner</div>") Kotlin writes the text of inner into the format, where interpolate reads it again as markup of yours, so a %s in it, which a value may have put there, becomes a placeholder and the call throws, and a %% becomes %. It is interpolate-template too, a warning, with the fix that gives it a placeholder of its own, where interpolate writes it as it is; in a <textarea> or a <title> it escapes an Html, as it does anywhere but element text:

val inner = interpolate { "<b>${+"Gorvek"}</b>" }

interpolate { """<div class="lt-card">${+inner}</div>""" }

A value marked in element text, or passed for a %s there, that is markup held as a String, h.text, elements { }, a joinToString over markup or over a list of Html, or a val set to any of these, is interpolate-template too, a warning: interpolate escapes it, so its tags are printed as text. Pass the Html itself, or wrap markup you built in Trusted(...). A literal is left alone, "<the oath>" among them: text you chose to have escaped.

At run time the source is gone and only the finished string arrives, so each value has to be marked, or left a placeholder, for the same question to be asked. That is the whole of what interpolate wants from you.

On Spring

Spring has no auto-configuration, so the helpers take the bean: datastarElements(html, streamlord = bean), response.toResponseEntity(streamlord = bean), events.asDatastarResponse(bean). With Streamlord.Default the guard is off.

Hand an Html to datastarElements(html), not to ResponseEntity.ok(...). That compiles, but Spring writes a body through its message converters, and StringHttpMessageConverter takes a String only, so no converter writes an Html as markup. Where you need the ResponseEntity yourself, pass html.text.

What went over the wire

The frames your last search produced, encoded by the same SseEncoder the golden-file tests check. Not a description of them. The frames.

Nothing yet. Search from the top of the page, and what the server sends will appear here.