class HTTP::WebSocket

Defined in:

http/web_socket.cr

Constructors

.new(host : String, path : String, port = nil, tls : HTTP::Client::TLSContext = nil, headers = HTTP::Headers.new)
Opens a new websocket to the target host.
.new(uri : URI | String, headers = HTTP::Headers.new)
Opens a new websocket using the information provided by the URI.

Instance Method Summary

#close(code : CloseCode | Int? = nil, message = nil) : Nil
Sends a close frame to the client, and closes the connection.
#closed? : Bool
#on_binary(&on_binary : Bytes -> )
Called when the server receives a binary message from a client.
#on_close(&on_close : CloseCode, String -> )
Called when the server closes a client's connection.
#on_message(&on_message : String -> )
Called when the server receives a text message from a client.
#on_ping(&on_ping : String -> )
Called when the server sends a ping to a client.
#on_pong(&on_pong : String -> )
Called when the server receives a pong from a client.
#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.
#pong(message = nil) : Nil
Server can send an unsolicited PONG frame which the client should not respond to.
#run : Nil
Continuously receives messages and calls previously set callbacks until the websocket is closed.
#send(message) : Nil
Sends a message payload (message) to the client.
#stream(binary = true, frame_size = 1024, &)

Instance methods inherited from class `Reference`

, , , , , , ,

Constructor methods inherited from class `Reference`

Instance methods inherited from class `Object`

, , , , , , , , , , , , , , , , , , , , , , , , , ,

Class methods inherited from class `Object`

Constructor Detail

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

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`

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

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"})
HTTP::WebSocket.new(
  URI.parse("ws://user:[email protected]/chat")) # Creates a new WebSocket to `websocket.example.com` with an HTTP basic auth Authorization header

Instance Method Detail

def close(code : CloseCode | Int? = nil, message = nil) : Nil Source

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.

def closed? : Bool Source

def on_binary(&on_binary : Bytes -> )Source

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

def on_close(&on_close : CloseCode, String -> )Source

Called when the server closes a client's connection.

def on_message(&on_message : String -> )Source

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

def on_ping(&on_ping : String -> )Source

Called when the server sends a ping to a client.

def on_pong(&on_pong : String -> )Source

Called when the server receives a pong from a client.

def ping(message = nil)Source

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.

def pong(message = nil) : Nil Source

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

See #ping.

def run : Nil Source

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

def send(message) : Nil Source

Sends a message payload (message) to the client.

def stream(binary = true, frame_size = 1024, &)Source

© 2012–2021 Manas Technology Solutions.
Licensed under the Apache License, Version 2.0.
https://crystal-lang.org/api/1.2.1/HTTP/WebSocket.html