DefaultWebSocketSession

expect interface DefaultWebSocketSession : WebSocketSession

Default websocket session with ping-pong and timeout processing and built-in closeReason population

Properties

closeReason

abstract val closeReason: Deferred<CloseReason?>

A close reason for this session. It could be null if a session is terminated with no close reason (for example due to connection failure).

pingIntervalMillis

abstract var pingIntervalMillis: Long

Ping interval or -1L to disable pinger. Please note that pongs will be handled despite of this setting.

timeoutMillis

abstract var timeoutMillis: Long

A timeout to wait for pong reply to ping otherwise the session will be terminated immediately. It doesn’t have any effect if pingIntervalMillis is -1 (pinger is disabled).

Inherited Properties

incoming

abstract val incoming: ReceiveChannel<Frame>

Incoming frames channel

masking

abstract var masking: Boolean

Enable or disable masking output messages by a random xor mask. Please note that changing this flag on the fly could be applied to the messages already sent (enqueued earlier) as the sending pipeline works asynchronously

maxFrameSize

abstract var maxFrameSize: Long

Specifies frame size limit. Connection will be closed if violated

outgoing

abstract val outgoing: SendChannel<Frame>

Outgoing frames channel. It could have limited capacity so sending too much frames may lead to suspension at corresponding send invocations. It also may suspend if a peer doesn’t read frames for some reason.

Inherited Functions

close

abstract suspend fun close(cause: Throwable? = null): Unit

Close session with the specified cause or with no reason if null

flush

abstract suspend fun flush(): Unit

Flush all outstanding messages and suspend until all earlier sent messages will be written. Could be called at any time even after close. May return immediately if the connection is already terminated. However it may also fail with an exception (or cancellation) at any point due to session failure. Please note that flush doesn’t guarantee that frames were actually delivered.

send

abstract suspend fun send(frame: Frame): Unit

Enqueue frame, may suspend if outgoing queue is full. May throw an exception if outgoing channel is already closed so it is impossible to transfer any message. Frames that were sent after close frame could be silently ignored. Please note that close frame could be sent automatically in reply to a peer close frame unless it is raw websocket session.

terminate

abstract fun terminate(): Unit

Initiate connection termination immediately. Termination may complete asynchronously.

Extension Functions

close

suspend fun WebSocketSession.close(reason: CloseReason): Unit

Send a close frame with the specified reason. May suspend if outgoing channel is full or may throw an exception if it is already closed. The specified reason could be ignored if there was already close frame sent (for example in reply to a peer close frame).

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

run

suspend fun DefaultWebSocketSession.run(
    handler: suspend DefaultWebSocketSession.() -> Unit
): Unit

send

suspend fun WebSocketSession.send(content: String): Unit

Enqueues a text frame for sending with the specified content.

suspend fun WebSocketSession.send(content: ByteArray): Unit

Enqueues a final binary frame for sending with the specified content.

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

Inheritors

DefaultClientWebSocketSession

class DefaultClientWebSocketSession : 
    ClientWebSocketSession,
    DefaultWebSocketSession

ClientSpecific DefaultWebSocketSession.

DefaultWebSocketServerSession

interface DefaultWebSocketServerSession : 
    DefaultWebSocketSession,
    WebSocketServerSession

Represents a server-side web socket session with all default implementations

DefaultWebSocketSessionImpl

class DefaultWebSocketSessionImpl : 
    DefaultWebSocketSession,
    WebSocketSession

Default web socket session implementation that handles ping-pongs, close sequence and frame fragmentation