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

pingInterval - duration between pings or null to disable pings

timeout - 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)

Types

Feature

companion object Feature : 
    ApplicationFeature<Application, WebSocketOptions, WebSockets>

Feature installation object

WebSocketOptions

class WebSocketOptions

Websockets configuration options

Constructors

<init>

WebSockets(
    pingInterval: Duration?,
    timeout: Duration,
    maxFrameSize: Long,
    masking: Boolean)

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

Properties

coroutineContext

val coroutineContext: <ERROR CLASS>

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

pingInterval

val pingInterval: Duration?

duration between pings or null to disable pings

timeout

val timeout: Duration

write/ping timeout after that a connection will be closed

Companion Object Properties

key

Unique key that identifies a feature

Companion Object Functions

install

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

Feature installation script

Extension Functions

decodeChunked

fun CoroutineScope.decodeChunked(
    input: ByteReadChannel
): 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> = emptyList(),
    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

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

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

startConnectionPipeline

fun CoroutineScope.startConnectionPipeline(
    input: ByteReadChannel,
    output: ByteWriteChannel,
    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