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.