Skip to content

class HTTP::WebSocket
inherits Reference

Class methods

.new(host : String, path : String, port = nil, tls : HTTP::Client::TLSContext = nil, headers = HTTP::Headers.new)

Opens a new websocket to the target host. This will also handle the handshake and will raise an exception if the handshake did not complete successfully.

require "http/web_socket"

HTTP::WebSocket.new("websocket.example.com", "/chat")            # Creates a new WebSocket to `websocket.example.com`
HTTP::WebSocket.new("websocket.example.com", "/chat", tls: true) # Creates a new WebSocket with TLS to `ẁebsocket.example.com`
View source

.new(uri : URI | String, headers = HTTP::Headers.new)

Opens a new websocket using the information provided by the URI. This will also handle the handshake and will raise an exception if the handshake did not complete successfully. This method will also raise an exception if the URI is missing the host and/or the path.

Please note that the scheme will only be used to identify if TLS should be used or not. Therefore, schemes apart from wss and https will be treated as the default which is ws.

require "http/web_socket"

HTTP::WebSocket.new(URI.parse("ws://websocket.example.com/chat"))        # Creates a new WebSocket to `websocket.example.com`
HTTP::WebSocket.new(URI.parse("wss://websocket.example.com/chat"))       # Creates a new WebSocket with TLS to `websocket.example.com`
HTTP::WebSocket.new(URI.parse("http://websocket.example.com:8080/chat")) # Creates a new WebSocket to `websocket.example.com` on port `8080`
HTTP::WebSocket.new(URI.parse("ws://websocket.example.com/chat"),        # Creates a new WebSocket to `websocket.example.com` with an Authorization header
  HTTP::Headers{"Authorization" => "Bearer authtoken"})
View source

Methods

#close(code : CloseCode | Int? = nil, message = nil)

Sends a close frame to the client, and closes the connection. The close frame may contain a body (message) that indicates the reason for closing.

View source

#closed? : Bool

View source

#on_binary(&on_binary : Bytes -> )

Called when the server receives a binary message from a client.

View source

#on_close(&on_close : CloseCode, String -> )

Called when the server closes a client's connection.

View source

#on_message(&on_message : String -> )

Called when the server receives a text message from a client.

View source

#on_ping(&on_ping : String -> )

Called when the server sends a ping to a client.

View source

#on_pong(&on_pong : String -> )

Called when the server receives a pong from a client.

View source

#ping(message = nil)

It's possible to send a PING frame, which the client must respond to with a PONG, or the server can send an unsolicited PONG frame which the client should not respond to.

See #pong.

View source

#pong(message = nil)

Server can send an unsolicited PONG frame which the client should not respond to.

See #ping.

View source

#run

Continuously receives messages and calls previously set callbacks until the websocket is closed. Ping and pong messages are automatically handled.

# Open websocket connection
ws = HTTP::WebSocket.new("websocket.example.com", "/chat")

# Set callback
ws.on_message do |msg|
  ws.send "response"
end

# Start infinite loop
ws.run
View source

#send(message)

Sends a message payload (message) to the client.

View source

#stream(binary = true, frame_size = 1024

View source