Transport and compression
JSON, XML and other formats, and compressed API responses. ktor-svelte can set up Ktor's ContentNegotiation and Compression for you, and compresses API responses by default.
Quick start
Choose how your API talks inside install(Svelte). Without a transport block, nothing is installed and you stay in control.
install(Svelte) {
transport {
json { prettyPrint = true }
xml()
compression()
}
}Formats
| Function | Effect |
|---|---|
json() | Adds JSON to Ktor's ContentNegotiation. Takes a kotlinx.serialization Json builder |
xml() | Adds XML. Needs implementation("io.ktor:ktor-serialization-kotlinx-xml") in your build |
negotiation { } | Registers any other format, such as CBOR, on ContentNegotiation directly |
compression { } | Installs Ktor's Compression. Takes its normal configuration, and defaults to gzip and deflate |
- The client picks a format with its
Acceptheader, and the first format you list is the default. - The generated TypeScript client always speaks JSON.
install(Svelte) {
transport {
json { ignoreUnknownKeys = true }
}
}Already installing these plugins yourself?
You will get a clear error at startup, so remove one of the two.
API compression
API responses are compressed by default, without any transport block. Responses of 1 KiB or more on your API paths with a JSON, XML, CBOR or text content type are sent with gzip or deflate, whichever the client prefers.
- Browsers decompress them natively, so the generated client and DevTools see plain JSON.
- Clients that send no
Accept-Encoding, such as curl, get plain JSON too. - Server-sent events, small responses, other content types and frontend files are left alone.
- Request bodies are never decompressed.
- Files precompressed by your adapter are left alone.
Setting in install(Svelte) | Default | What it does |
|---|---|---|
apiCompression | true | Compresses API responses as described above |
zstd
Add Ktor's zstd module, and current browsers get zstd instead, which compresses about as well as gzip at a fraction of the CPU time:
implementation("io.ktor:ktor-server-compression-zstd:<ktor version>")It adds a native library of about 7 MB to your JAR, which is why it is not included by default.
Your own configuration
If you install Compression yourself, before or after install(Svelte), or use transport { compression() }, your configuration is used instead. To send API responses uncompressed:
install(Svelte) {
apiCompression = false
}Compression and secrets
BREACH
A response that contains a secret, such as an API key, next to text an attacker can choose can leak that secret byte by byte through its compressed size (the BREACH attack). ktor-svelte's own CSRF protection uses no tokens, so it is not affected. If one of your endpoints returns such a mix, turn apiCompression off or install Compression yourself with a condition that skips that route.
Why compression and not a binary format
For 5000 notes, measured from server to parsed data:
| 50 Mbit connection | 4G | |
|---|---|---|
| Plain JSON | 318 ms | 1537 ms |
| gzip | 152 ms | 381 ms |
| zstd | 84 ms | 345 ms |
CBOR was 7 percent smaller than JSON before compression and larger after it, and decoding it in JavaScript took about seven times as long as JSON.parse, so it never came out ahead.
Full example
An API that serves JSON to the generated client, XML and CBOR to other callers that ask for them, and compresses with your own settings.
dependencies {
implementation("io.ktor:ktor-serialization-kotlinx-xml")
implementation("io.ktor:ktor-serialization-kotlinx-cbor")
}@OptIn(ExperimentalSerializationApi::class)
fun Application.module() {
install(Svelte) {
generateTs = true
transport {
json { ignoreUnknownKeys = true }
xml()
negotiation { cbor() }
compression {
gzip { priority = 1.0 }
deflate { priority = 0.5 }
}
}
}
routing {
get("/api/notes") { call.respond(store.all()) }
}
}curl http://localhost:8080/api/notes
curl -H "Accept: application/xml" http://localhost:8080/api/notes
curl -H "Accept-Encoding: gzip" --compressed http://localhost:8080/api/notesJSON stays the default, because it is listed first. A caller that sends Accept: application/xml gets XML, and one that asks for application/cbor gets CBOR.
Use cases
- Most apps: nothing to do. JSON through your own
ContentNegotiation, and API compression on by default. - One place for the setup:
transport { json() }instead of installingContentNegotiationyourself. - Partners that need XML or CBOR:
xml()ornegotiation { }. - Large lists on slow connections: keep
apiCompressionon, and add zstd. - Responses that mix secrets with user input: turn
apiCompressionoff for them, see Compression and secrets.
Good to know
- The generated TypeScript client always speaks JSON, whatever else you add.
- Installing
ContentNegotiationorCompressionyourself and throughtransportfails at startup with a clear error. - See Calling the API for the client, and the Ktor reference for every setting.