DefaultWebSocketSession

A default WebSocket session with ping-pong and timeout processing and built-in closeReason population.

Functions

Link copied to clipboard
abstract suspend fun flush()

Flushes all outstanding messages and suspends 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 a session failure. Note that flush doesn't guarantee that frames were actually delivered.

Link copied to clipboard
open suspend fun send(frame: Frame)

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

Link copied to clipboard
abstract fun start(negotiatedExtensions: List<WebSocketExtension<*>> = emptyList())

Starts a WebSocket conversation.

Link copied to clipboard
abstract fun terminate()

Initiates a connection termination immediately. Termination may complete asynchronously.

Properties

Link copied to clipboard
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).

Link copied to clipboard
Link copied to clipboard

Negotiated WebSocket extensions.

Link copied to clipboard
abstract val incoming: ReceiveChannel<Frame>

An incoming frames channel. Note that if you use webSocket to handle a WebSockets session, the incoming channel doesn't contain control frames such as the ping/pong or close frames. If you need control over control frames, use the webSocketRaw function.

Link copied to clipboard
abstract var masking: Boolean

Enables or disables masking output messages by a random XOR mask. Note that changing this flag on the fly could be applied to the messages already sent (enqueued earlier) as the sending pipeline works asynchronously.

Link copied to clipboard
abstract var maxFrameSize: Long

Specifies the frame size limit. A connection will be closed if violated.

Link copied to clipboard
abstract val outgoing: SendChannel<Frame>

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

Link copied to clipboard
abstract var pingIntervalMillis: Long

Specifies the ping interval or -1L to disable pinger. Note that pongs will be handled despite this setting.

Link copied to clipboard
abstract var timeoutMillis: Long

Specifies 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).

Extensions

Link copied to clipboard
suspend fun WebSocketSession.close(reason: CloseReason = CloseReason(CloseReason.Codes.NORMAL, ""))

Sends a close frame with the specified reason. May suspend if the outgoing channel is full. The specified reason could be ignored if there was already close frame sent (for example in reply to a peer close frame). It also may do nothing when a session or an outgoing channel is already closed due to any reason.

suspend fun WebSocketSession.close(cause: Throwable?)

Closes with the reason depending on cause or normally if the cause is null.

Link copied to clipboard

Closes a session with normal or error close reason, depending on whether cause is cancellation or not.

Link copied to clipboard
Link copied to clipboard
Link copied to clipboard
suspend fun WebSocketSession.send(content: String)

Enqueues a text frame for sending with the specified content.

suspend fun WebSocketSession.send(content: ByteArray)

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