Concept: 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.