WebSockets

http4k provides WebSocket support using a simple, consistent, typesafe, and testable API on supported server backends.

WebSocket communication consists of a few main concepts:

WsMessage

As per the http4k ethos, an immutable message object providing duplex communication between the server to the connected client. Lenses can be used to provide typesafe object marshalling with WsMessages.

WebSocket

interface Websocket {
    val upgradeRequest: Request
    fun send(message: WsMessage)
    fun close(status: WsStatus = NORMAL)
    fun onError(fn: (Throwable) -> Unit)
    fun onClose(fn: (WsStatus) -> Unit)
    fun onMessage(fn: (WsMessage) -> Unit)
}

An interface representing the available server callback API to the WebSocket channel. WebSocket objects can send() WsMessages to the client, or react to incoming events by binding behaviour with onMessage(), onError() or onClose(). The WebSocket has a reference to the incoming HTTP Request which was used during connection.

WsConsumer

typealias WsConsumer = (WebSocket) -> Unit

The primary callback received when an WebSocket server is connected to a client. API user behaviour is configured here.

WsHandler

typealias WsHandler = (Request) -> WsConsumer

Provides the route mapping of an HTTP Request to a particular WsConsumer.

WsFilter

fun interface WsFilter : (WsConsumer) -> WsConsumer

Applies decoration to a matched WsConsumer before it is invoked. WsFilters can be used to apply tangental effects to the matched WsConsumer such as logging/security, or to modify the incoming HTTP Request.

WsRouter

interface WsRouter {
    fun match(request: Request): WsRouterMatch
    fun withBasePath(new: String): WsRouter
    fun withFilter(new: WsFilter): WsRouter
}

Applies the route matching functionality when requests for WebSocket connections are received by the server.