ktor-http-cio / io.ktor.http.cio.websocket / DefaultWebSocketSession

DefaultWebSocketSession

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

dispatcher	`open val dispatcher: <ERROR CLASS>` Dispatcher to handle io operations
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	`open 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
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>, 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

Inheritors

DefaultWebSocketSessionImpl

class DefaultWebSocketSessionImpl : DefaultWebSocketSession, WebSocketSession

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