WebSocket Deflate extension

Ktor implements Deflate WebSocket extensions RFC-7692 for the client and server. The extension can transparently compress frame before sending, and decompress after receiving. It's useful to enable this extension if you're sending large amounts of text data.

The API is production ready, but may be slightly modified in a minor release. This is why it's marked with the @ExperimentalWebSocketExtensionsApi annotation. If you want to use this API, you need to OptIn:

@OptIn(ExperimentalWebSocketExtensionsApi::class)

If you want to leave your feedback or subscribe on updates, check out the KTOR-688 design issue.

Installation

To use the extension it should be installed first. To do that we can use install method in extensions block:

// For client and server
install(WebSockets) {
    extensions {
        install(WebSocketDeflateExtension) {
            /**
             * Compression level to use for [java.util.zip.Deflater].
             */
            compressionLevel = Deflater.DEFAULT_COMPRESSION

            /**
             * Prevent to compress small outgoing frames.
             */
            compressIfBiggerThan(bytes = 4 * 1024)
        }
    }
}

Advanced configuration parameters

Context takeover

Specify if the client (and server) should use compression window. Enabling these parameters reduce the amount of space allocated per single session. Please note that window size cannot be configured due to limitations of java.util.zip.Deflater API. The value is fixed to 15.

clientNoContextTakeOver = false

serverNoContextTakeOver = false

These parameters are described in RFC-7692 Section 7.1.1

Specify compress condition

To specify a compress condition explicitly, you can use the compressIf method. For instance, to compress text-only:

compressIf { frame -> 
    frame is Frame.Text
}

All calls to compressIf will be evaluated before compression takes place.

Fine-tune list of protocols

The list of protocols to send can be edited as needed using the configureProtocols method:

configureProtocols { protocols ->
    protocols.clear()
    protocols.add(...)
}

Last modified: 27 May 2021