Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 38 ยท WebSockets and SSE

Broadcasting to Many Clients - Rooms, SharedFlow, Backpressure

Fan out messages to many WebSocket or SSE clients in Ktor. Build chat rooms with a connection registry and SharedFlow, handle slow consumers with buffers, and keep shared state thread-safe.

One socket talking to one handler is easy. The interesting problem starts when a message from one user must reach everyone in a room, or when a background job must update every dashboard that is open. That is fan-out, or broadcasting, and it forces you to answer three questions: where do you keep the list of connections, how do you deliver a message to all of them, and what do you do about a client that cannot keep up?

This lesson gives two answers, a registry of connections and a SharedFlow, builds both in runnable Kotlin, and then shows the Ktor code that uses them with WebSockets and SSE. You will want to be comfortable with StateFlow and SharedFlow from the Kotlin course.

Approach 1: a registry of connections

The straightforward design keeps a collection of live sessions. When a message arrives, loop over the members and send.

Kotlin
class Room {
    private val members = ConcurrentHashMap<String, DefaultWebSocketServerSession>()

    fun join(name: String, session: DefaultWebSocketServerSession) { members[name] = session }
    fun leave(name: String) { members.remove(name) }

    suspend fun broadcast(from: String, text: String) {
        members.values.forEach { it.send("$from: $text") }
    }
}

val rooms = ConcurrentHashMap<String, Room>()

webSocket("/chat/{room}") {
    val name = call.request.queryParameters["user"] ?: return@webSocket close()
    val room = rooms.computeIfAbsent(call.parameters["room"]!!) { Room() }
    room.join(name, this)
    try {
        for (frame in incoming) {
            if (frame is Frame.Text) room.broadcast(name, frame.readText())
        }
    } finally {
        room.leave(name)
    }
}

Two details matter. Many coroutines run on many threads, so the registry must be thread-safe: ConcurrentHashMap, or a plain map guarded by a Mutex. And leave belongs in finally, otherwise a crashed client stays in the list and every broadcast tries to send to a dead socket.

The weakness is in broadcast: it sends to members one after another. One slow client blocks the loop and delays everybody behind it.

Kotlin Stand-in: a room registry and a slow member

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

In the sequential version Cy waits behind slow Bo. In the parallel version everyone gets the message at their own speed. But parallel sending only moves the problem: if Bo falls further and further behind, you queue messages for him without limit.

Approach 2: SharedFlow as a broadcast bus

A MutableSharedFlow is a hot stream with many collectors. Emitting once delivers to every active collector, and each session simply collects it and forwards what it sees. There is no registry to maintain: a client that disconnects cancels its collector, and it is gone.

Kotlin
class ChatHub {
    private val _messages = MutableSharedFlow<ChatMessage>(
        replay = 0,
        extraBufferCapacity = 64,
        onBufferOverflow = BufferOverflow.DROP_OLDEST,
    )
    val messages: SharedFlow<ChatMessage> = _messages.asSharedFlow()

    suspend fun publish(message: ChatMessage) = _messages.emit(message)
}

webSocket("/chat") {
    val me = call.request.queryParameters["user"] ?: return@webSocket close()

    val sender = launch {
        hub.messages.collect { m -> sendSerialized(m) }
    }
    try {
        for (frame in incoming) {
            if (frame is Frame.Text) hub.publish(ChatMessage(me, frame.readText()))
        }
    } finally {
        sender.cancel()
    }
}

The same hub.messages flow feeds an sse("/stream") route by collecting and calling send(...). One producer, any mix of transports.

Kotlin Stand-in: SharedFlow hub with several listeners

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

After Bo cancels, he no longer receives anything and nothing needs cleaning up. A SharedFlow with replay = 0 also means a newcomer sees only new messages; set replay = 20 to give late joiners the recent history.

Slow consumers and backpressure

What if one collector takes a second per message and messages arrive every millisecond? The SharedFlow suspends the emitter until the slowest collector has room, so one slow client slows the whole room. You choose a policy with onBufferOverflow:

Policy Effect Use when
SUSPEND (default) Emitter waits for the slowest collector Every message must arrive and clients are trusted
DROP_OLDEST Old unread messages are discarded Live data where the latest value matters (prices, positions)
DROP_LATEST New messages are discarded while the buffer is full Rarely; protects the oldest data

For chat, a common design is a per-connection bounded outgoing queue: if it fills up, disconnect that client rather than letting it drag the room down.

Kotlin Stand-in: a bounded outbox disconnects a slow client

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

The fast client kept up with every message. The slow client filled its two-slot outbox, was disconnected, and the rest of the room never noticed. The disconnected browser can reconnect and use Last-Event-ID or a "messages since" request to catch up.

Scaling past one server

A SharedFlow lives inside one JVM. With two server instances behind a load balancer, a message published on server A will not reach clients connected to server B. The usual fix is a message broker (Redis pub/sub, Kafka, NATS or a database LISTEN/NOTIFY): every instance publishes to the broker and also subscribes to it, forwarding broker messages into its local SharedFlow. Your socket code does not change, only what feeds the hub.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why must the connection registry be thread-safe?

    Sessions run concurrently, so use ConcurrentHashMap or a Mutex.
  2. 2. What happens to a SharedFlow collector when the client disconnects?

    Collectors are coroutines; cancelling them removes the subscription.
  3. 3. Which overflow policy suits a live price feed where only the latest value matters?

    DROP_OLDEST keeps the newest values and never stalls the emitter.
  4. 4. Why does a SharedFlow alone not scale across two server instances?

    You need a shared broker (Redis, Kafka and so on) to connect instances.

Summary

  • Fan-out needs a registry of connections or a SharedFlow bus; remove sessions in finally.
  • Sequential sends let one slow client delay everyone; send concurrently and bound each client's queue.
  • SharedFlow collectors clean up automatically on cancellation; pick onBufferOverflow deliberately.
  • Disconnect clients that cannot keep up, and let them catch up after reconnecting.
  • Multiple servers need a broker to share messages.

Next: Testing Ktor Applications