Native image
Streamlord in a GraalVM native image: the build file, the serializers, the resources and the container, in the order you need them.
I carry what I need and leave the rest at the gate.
Streamlord’s core has no reflection in it, so most of the SDK goes into a native image untouched. Three things need your attention: the serializers your codec would otherwise look up, the resources you read by name, and the flags your server framework wants. This documentation’s own search service is built exactly this way, with no hand-written reflection metadata at all.
One part of the SDK uses reflection, on purpose: on Ktor’s Tomcat and Jetty engines, Streamlord cuts the connection under a stream whose block threw, by reaching into the engine, since Ktor has no API for it (Ktor). In a native image without metadata for those engines’ fields it does nothing, and the stream ends as the engine ends it. CIO and Netty, which a native image usually runs on, cut the connection themselves and need none of it.
1. The build file
// build.gradle.kts
plugins {
id("org.graalvm.buildtools.native") version "0.11.5"
application
}
graalvmNative {
binaries {
named("main") {
imageName.set("my-service")
mainClass.set("com.example.MainKt")
fallback.set(false)
sharedLibrary.set(false)
buildArgs.addAll(
"--initialize-at-build-time=io.ktor,kotlin",
"--initialize-at-build-time=org.slf4j.LoggerFactory",
"--initialize-at-build-time=org.slf4j.helpers.Reporter",
"--initialize-at-build-time=kotlinx.io",
"--initialize-at-build-time=kotlinx.serialization.json.Json",
"--initialize-at-build-time=kotlinx.serialization.json.JsonImpl",
"--initialize-at-build-time=kotlinx.serialization.json.ClassDiscriminatorMode",
"--initialize-at-build-time=kotlinx.serialization.modules.SerializersModuleKt",
"-H:+UnlockExperimentalVMOptions",
"-H:+InstallExitHandlers",
"-H:+ReportUnsupportedElementsAtRuntime",
"-H:+ReportExceptionStackTraces",
"--initialize-at-run-time=io.ktor.utils.io.jvm.javaio.ReadingKt",
)
}
}
}
fallback. so a build that cannot be native fails instead of quietly producing a JVM
image with none of the startup you are doing this for. sharedLibrary. is the default
with the two plugins above and is written out because it stops being the default the day the
build also applies java-library: the plugin then passes --shared and hands you a .so with a
C header beside it.
The list of build arguments is Ktor’s, from
ktor-samples/graalvm, and this is it
whole, with two lines of our own. The first is -H:+UnlockExperimentalVMOptions, because the
three -H:+ options after it are experimental and GraalVM is about to refuse them without it.
The second is --initialize-at-run-time=io., because Ktor
3.6.1 reads Dispatchers. as that class is initialized: with io. initialized at build
time, the build then fails on some twenty kotlinx. classes “unintentionally
initialized at build time”. Ktor’s default response transform refers to that class, so a Ktor
3.6.1 server needs the line whatever it serves; the sample, on Ktor 3.6.1 as well, has no such
line yet. The list is also, in this order, every build argument the service behind this site
uses, bar the container flag that step 4 adds on Linux. Take it whole rather than adding entries
one at a time against a theory of what an error means: three attempts here were spent doing that,
and each theory was wrong.
If the build still fails on kotlinx. classes initialized at build time, ask
native-image why rather than guessing. Add
--trace-class-initialization=kotlinx., as the error message suggests: the
trace ends in the io. class whose static initializer reached Dispatchers, and that class
goes in an --initialize-at-run-time line of its own. respondOutputStream and
respondTextWriter, which this service does not call, lead to one such class in Ktor’s
BlockingBridgeKt.
Two deliberate differences from the sample. Add ch. back with the logging backend if
you use one. And where the sample names kotlinx. and
kotlinx., this names the kotlinx. package, which covers those two and the
further classes Ktor reaches through the filesystem.
2. Name your serializers
install(StreamlordPlugin) {
codec = KotlinxSignalsCodec(
serializers = mapOf(typeOf<SearchSignals>() to SearchSignals.serializer()),
)
}
One entry per class you read signals into. SearchSignals. is generated by the
kotlinx.serialization compiler plugin and resolved where you write it, so the image can see it in
the bytecode.
The same table serves the other direction. A page that declares its signals from the class,
dataSignals( (see Signals), encodes through the
serializer named here, so it needs no entry of its own. The service behind this site renders its
CSP page that way, and the image is called for that page before it ships.
Add requireNamedSerializers = true beside them, and a type you forgot fails on the JVM (in a test, with the name
of the class) instead of in the image on the first request that carries it:
KotlinxSignalsCodec(
serializers = mapOf(typeOf<SearchSignals>() to SearchSignals.serializer()),
requireNamedSerializers = true,
)
It asks only for what an image cannot resolve by itself: your own classes, and containers holding
them. A container is named whole, because kotlinx.serialization looks up List<SearchSignals> by
reading the class of what it holds, which is the reflection an image cannot do; naming
SearchSignals alone does not cover it:
typeOf<List<SearchSignals>>() to ListSerializer(SearchSignals.serializer())
String, Int, List<String> and the rest are answered from a table inside
kotlinx.serialization that ships in the bytecode like any other code, so requireNamedSerializers
lets them through.
It is worth turning on the day you add the second signals class, because the failure it prevents is a silent one. Leave it out and the codec falls back to asking kotlinx.serialization to find the serializer by reading the class, which native-image cannot see. The build is green, the service starts, the health check answers, and the first read fails:
Unresolved class: class SearchSignals (kind = CLASS)
With Jackson the same applies and there is no equivalent shortcut: register your signals classes for reflection, or let Spring’s AOT processing do it. See Spring WebMVC.
3. Resources you read by name
Anything loaded through getResourceAsStream is invisible to the image, because the file name is
a string and nothing in the bytecode mentions it. Name it:
{
"resources": {
"includes": [
{ "pattern": "\\Qindex.json\\E" }
]
}
}
Put that in src/ and the plugin picks it
up. Skip it and the image ships without the file, starts cleanly, and finds nothing.
The service behind this site reads one such file, its search index, and names it as above.
streamlord-analysis, which it runs in its /judge route, needs no entry: its catalog is
compiled into it as a string, not read from the jar by name.
4. The container
A native image links glibc and zlib dynamically by default. A distroless base image promises
glibc and no more: gcr. has no zlib, and base-debian13 has it
today. Link zlib in, so the binary needs nothing the base may drop:
// GraalVM for JDK 21
buildArgs.add("-H:+StaticExecutableWithDynamicLibC")
// GraalVM for JDK 23 and newer, where the same option was renamed
buildArgs.add("--static-nolibc")
Everything the image needs is then linked in except glibc, which the base image provides.
FROM gcr.io/distroless/base-debian13:nonroot
WORKDIR /app
COPY build/native/nativeCompile/my-service /app/my-service
USER nonroot
ENTRYPOINT ["/app/my-service"]
Check the flag name against the documentation for the GraalVM in your toolchain, not the version at
/latest. Pass the wrong one and the compiler tells you plainly; pass none and nothing tells you
until the container exits with libz..
5. Check it before you ship it
Every failure above happens after the build succeeds. A native image that is wrong builds, pushes and deploys green, and then fails at startup or on the first request. So start it and call it:
docker build -t my-service .
docker run -d --name check -p 8080:8080 my-service
curl -fsS localhost:8080/health
curl -fsS -H 'Accept: text/event-stream' \
'localhost:8080/search?datastar=%7B%22query%22%3A%22x%22%7D'
docker rm -f check
Those five lines belong in your pipeline, before the push. A health check alone is not enough: it answers before a single signal has been read, which is precisely the part that breaks.