WebSockets

class WebSockets : CoroutineScope

WebSockets support feature. It is required to be installed first before binding any websocket endpoints

install(WebSockets)

install(Routing) {
    webSocket("/ws") {
         incoming.consumeForEach { ... }
    }
}

Parameters

pingIntervalMillis - duration between pings or null to disable pings.

timeoutMillis - write/ping timeout after that a connection will be closed.

maxFrameSize - maximum frame that could be received or sent.

masking - whether masking need to be enabled (useful for security).

extensionsConfig - is configuration for WebSocket extensions.

Types

Feature	`companion object Feature : ApplicationFeature<Application, WebSocketOptions, WebSockets>` Feature installation object.
WebSocketOptions	`class WebSocketOptions` Websockets configuration options

Constructors

<init>

WebSockets(
    pingIntervalMillis: Long, 
    timeoutMillis: Long, 
    maxFrameSize: Long, 
    masking: Boolean)

WebSockets(
    pingIntervalMillis: Long, 
    timeoutMillis: Long, 
    maxFrameSize: Long, 
    masking: Boolean, 
    extensionsConfig: WebSocketExtensionsConfig)

WebSockets support feature. It is required to be installed first before binding any websocket endpoints

Properties

coroutineContext	`val coroutineContext: <ERROR CLASS>`
extensionsConfig	`val extensionsConfig: WebSocketExtensionsConfig` is configuration for WebSocket extensions.
masking	`val masking: Boolean` whether masking need to be enabled (useful for security).
maxFrameSize	`val maxFrameSize: Long` maximum frame that could be received or sent.
pingIntervalMillis	`val pingIntervalMillis: Long` duration between pings or `null` to disable pings.
timeoutMillis	`val timeoutMillis: Long` write/ping timeout after that a connection will be closed.

Companion Object Properties

EXTENSIONS_KEY	`val EXTENSIONS_KEY: AttributeKey<List<WebSocketExtension<*>>>` Key for saving configured WebSocket extensions for the specific call.
key	`val key: AttributeKey<WebSockets>` Unique key that identifies a feature

Companion Object Functions

install

fun install(
    pipeline: Application, 
    configure: WebSocketOptions.() -> Unit
): WebSockets

Feature installation script

Extension Properties

pingInterval	`val WebSockets.pingInterval: Duration?`
timeout	`val WebSockets.timeout: Duration`

Extension Functions

decodeChunked	`fun CoroutineScope.decodeChunked( input: ByteReadChannel ): DecoderJob` `fun CoroutineScope.decodeChunked( input: ByteReadChannel, contentLength: Long ): DecoderJob` Start a chunked stream decoder coroutine
embeddedServer	`fun <TEngine : ApplicationEngine, TConfiguration : Configuration> CoroutineScope.embeddedServer( factory: ApplicationEngineFactory<TEngine, TConfiguration>, port: Int = 80, host: String = "0.0.0.0", watchPaths: List<String> = listOf(WORKING_DIRECTORY_PATH), parentCoroutineContext: <ERROR CLASS> = EmptyCoroutineContext, configure: TConfiguration.() -> Unit = {}, module: Application.() -> Unit ): TEngine` Creates an embedded server with the given factory, listening on host:port
httpServer	`fun CoroutineScope.httpServer( settings: HttpServerSettings, handler: HttpRequestHandler ): HttpServer` Start an http server with settings invoking handler for every request
httpServer	`fun CoroutineScope.httpServer( settings: HttpServerSettings, handler: suspend CoroutineScope.(request: Request, input: ByteReadChannel, output: ByteWriteChannel, upgraded: CompletableDeferred<Boolean>?) -> Unit ): HttpServer` Start an http server with settings invoking handler for every request
mapEngineExceptions	`fun CoroutineScope.mapEngineExceptions( input: ByteReadChannel, request: HttpRequestData ): ByteReadChannel` Returns ByteReadChannel with ByteChannel.close handler that returns SocketTimeoutException instead of SocketTimeoutException. `fun CoroutineScope.mapEngineExceptions( output: ByteWriteChannel, request: HttpRequestData ): ByteWriteChannel` Returns ByteWriteChannel with ByteChannel.close handler that returns SocketTimeoutException instead of SocketTimeoutException.
parseMultipart	`fun CoroutineScope.parseMultipart( input: ByteReadChannel, headers: HttpHeadersMap ): ReceiveChannel<MultipartEvent>` `fun CoroutineScope.parseMultipart( input: ByteReadChannel, contentType: CharSequence, contentLength: Long? ): ReceiveChannel<MultipartEvent>` `fun CoroutineScope.parseMultipart( boundaryPrefixed: ByteBuffer, input: ByteReadChannel, totalLength: Long? ): ReceiveChannel<MultipartEvent>` Starts a multipart parser coroutine producing multipart events
pinger	`fun CoroutineScope.pinger( outgoing: SendChannel<Frame>, period: Duration, timeout: Duration, pool: ObjectPool<ByteBuffer> = KtorDefaultPool ): SendChannel<Pong>` Launch pinger coroutine on CoroutineScope that is sending ping every specified period to outgoing channel, waiting for and verifying client’s pong frames. It is also handling timeout and sending timeout close frame `fun CoroutineScope.pinger( outgoing: SendChannel<Frame>, periodMillis: Long, timeoutMillis: Long, pool: ObjectPool<ByteBuffer> = KtorDefaultPool ): SendChannel<Pong>` Launch pinger coroutine on CoroutineScope that is sending ping every specified periodMillis to outgoing channel, waiting for and verifying client’s pong frames. It is also handling timeoutMillis and sending timeout close frame
pinger	`fun CoroutineScope.pinger( outgoing: SendChannel<Frame>, period: <ERROR CLASS>, timeout: <ERROR CLASS>, pool: ObjectPool<ByteBuffer> = KtorDefaultPool ): SendChannel<Pong>` Launch pinger coroutine on CoroutineScope that is sending ping every specified period to outgoing channel, waiting for and verifying client’s pong frames. It is also handling timeout and sending timeout close frame
ponger	`fun CoroutineScope.ponger( outgoing: SendChannel<Pong>, pool: ObjectPool<ByteBuffer> = KtorDefaultPool ): SendChannel<Ping>` Launch a ponger actor job on the CoroutineScope sending pongs to outgoing channel. It is acting for every client’s ping frame and replying with corresponding pong
reader	`fun CoroutineScope.reader( coroutineContext: <ERROR CLASS> = EmptyCoroutineContext, channel: ByteChannel, block: suspend ReaderScope.() -> Unit ): ReaderJob` `fun CoroutineScope.reader( coroutineContext: <ERROR CLASS> = EmptyCoroutineContext, autoFlush: Boolean = false, block: suspend ReaderScope.() -> Unit ): ReaderJob`
startConnectionPipeline	`fun CoroutineScope.startConnectionPipeline( input: ByteReadChannel, output: ByteWriteChannel, timeout: WeakTimeoutQueue, handler: suspend CoroutineScope.(request: Request, input: ByteReadChannel, output: ByteWriteChannel, upgraded: CompletableDeferred<Boolean>?) -> Unit ): Job` Start connection HTTP pipeline invoking handler for every request. Note that handler could be invoked multiple times concurrently due to HTTP pipeline nature
startServerConnectionPipeline	`fun CoroutineScope.startServerConnectionPipeline( connection: ServerIncomingConnection, timeout: WeakTimeoutQueue, handler: HttpRequestHandler ): Job` Start connection HTTP pipeline invoking handler for every request. Note that handler could be invoked multiple times concurrently due to HTTP pipeline nature
writeMultipleRanges	`fun CoroutineScope.writeMultipleRanges( channelProducer: (LongRange) -> ByteReadChannel, ranges: List<LongRange>, fullLength: Long?, boundary: String, contentType: String ): ByteReadChannel` Start multirange response writer coroutine
writer	`fun CoroutineScope.writer( coroutineContext: <ERROR CLASS> = EmptyCoroutineContext, channel: ByteChannel, block: suspend WriterScope.() -> Unit ): WriterJob` `fun CoroutineScope.writer( coroutineContext: <ERROR CLASS> = EmptyCoroutineContext, autoFlush: Boolean = false, block: suspend WriterScope.() -> Unit ): WriterJob`