ws-server/server
ws-upgrade
(ws-upgrade [conn : Conn req : Request ^fat handler : (fn [WsConn])
upgrade an httpd connection to a WebSocket session.
| conn | httpd Conn handle (from the two-arg handler signature). | |
| req | httpd Request (read for the Upgrade / Sec-WebSocket-Key / | |
| Sec-WebSocket-Version headers). | ||
| handler | (fn [WsConn] void), called after the upgrade succeeds. (The | |
| plan sketches a `^linear WsConn` handler that owns the close; | ||
| WsConn is shared with ws-client as a non-linear ws-core type, | ||
| so ws-upgrade keeps ownership and frees after the handler | ||
| returns | a safe default. See UPG-V0 notes in the README.) |
(Result bool UpgradeError) -- ok(true) once the upgrade succeeded and the handler ran (the Response the handler returns is then ignored, the connection having been hijacked); err(UpgradeError) when the request was not a valid WebSocket Upgrade, in which case the caller should return a normal HTTP error Response. For the old 1/0 shape see ws-upgrade-or-zero.
(defn ws-echo [conn : Conn req : Request] : Response
(if (ok? (ws-upgrade conn req
(fn [ws : WsConn] : void
(let [f (ws-server-recv ws)]
(ws-server-send ws (ws-frame-text f))
(ws-server-close ws)))))
(resp-ok "text/plain" "") ;; placeholder; worker skips it
(bad-request "not a websocket request")))
Since: WS1 (result-shaped since UPG-V0)
ws-upgrade-or-zero
(ws-upgrade-or-zero [conn : Conn req : Request ^fat handler : (fn [WsConn])
backward-compatible :int shape of ws-upgrade.
Since: UPG-V0
ws-upgrade-with-subprotocols
(ws-upgrade-with-subprotocols)
upgrade with application subprotocol
| conn | httpd Conn handle. | |
| req | httpd Request. | |
| accepted | comma-separated list of supported subprotocols. | |
| handler | (fn [WsConn] void), invoked after a successful upgrade. |
(Result bool UpgradeError) -- ok(true) on a successful upgrade and handler run; err(UpgradeError) otherwise.
Since: SUB-V0
ws-server-subprotocol
(ws-server-subprotocol [ws : WsConn] :)
the application subprotocol selected during the
Since: SUB-V0
ws-server-send
(ws-server-send [ws : WsConn msg : cstr] :)
send a UTF-8 text frame to the client (unmasked).
| ws | server WsConn handle. | |
| msg | null-terminated UTF-8 string. |
Bytes written, or negative on error.
Since: WS1
ws-server-send-bytes
(ws-server-send-bytes [ws : WsConn ptr ptr<void> len : int] :)
send a binary frame to the client (unmasked).
| ws | server WsConn handle. | |
| ptr | payload buffer. | |
| len | byte length. |
Bytes written, or negative on error.
Since: WS1
ws-server-send-fragmented
(ws-server-send-fragmented [ws : WsConn ptr ptr<void> len : int frame-size : int] :)
send a binary message split across multiple
| ws | server WsConn handle. | |
| ptr | payload buffer. | |
| len | byte length of the payload. | |
| frame-size | max bytes per outbound frame (a value <= 0 sends one frame). |
Total bytes handed to the transport, or negative on error.
Since: FRAG-V0
ws-server-recv
(ws-server-recv [ws : WsConn] :)
receive the next message from the client.
| ws | server WsConn handle. |
A WsFrame handle (a view valid until the next ws-server-recv). Its kind is :text / :binary / :ping / :pong / :close / :timeout / :error.
Since: WS1
ws-server-close
(ws-server-close [ws : WsConn] :)
initiate the WebSocket closing handshake.
| ws | server WsConn handle. |
Since: WS1
ws-set-server-timeout
(ws-set-server-timeout [ws : WsConn ms : int] :)
set the receive timeout in milliseconds.
| ws | server WsConn handle. | |
| ms | timeout in milliseconds. |
Since: WS1
Internal definitions
wss-header-websocket?wss-wrapwss-write-handshake-protowss-write-handshakewss-negotiate-subprotowss-read-subprotowss-free-wrapperwss-freewss-atoiwss-req-versionwss-cstr-empty?