Skip to content
Streamlordv0.23.0

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.set(false) 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.set(false) 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.ktor.utils.io.jvm.javaio.ReadingKt, because Ktor 3.6.1 reads Dispatchers.IO as that class is initialized: with io.ktor initialized at build time, the build then fails on some twenty kotlinx.coroutines 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.coroutines classes initialized at build time, ask native-image why rather than guessing. Add --trace-class-initialization=kotlinx.coroutines.Dispatchers, as the error message suggests: the trace ends in the io.ktor 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.qos.logback back with the logging backend if you use one. And where the sample names kotlinx.io.bytestring.ByteString and kotlinx.io.SegmentPool, this names the kotlinx.io 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.serializer() 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(codec.toJsonValue(SearchSignals())) (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/main/resources/META-INF/native-image/resource-config.json 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.io/distroless/base-debian12 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.so.1: cannot open shared object file.

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.

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.