class HTTP::WebSocket
Overview
NOTE To use WebSocket
, you must explicitly import it with require "http/web_socket"
Defined in:
http/web_socket.crConstructors
-
.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 = nil, message = nil) : Nil
Sends a close frame, and closes the connection.
- #closed? : Bool
-
#on_binary(&on_binary : Bytes -> )
Called when a binary message is received.
-
#on_close(&on_close : CloseCode, String -> )
Called when the connection is closed by the other party.
-
#on_message(&on_message : String -> )
Called when a text message is received.
-
#on_ping(&on_ping : String -> )
Called when a PING frame is received.
-
#on_pong(&on_pong : String -> )
Called when a PONG frame is received.
-
#ping(message = nil)
Sends a PING frame.
-
#pong(message = nil) : Nil
Sends a PONG frame, which must be in response to a previously received PING frame from
#on_ping
. -
#run : Nil
Continuously receives messages and calls previously set callbacks until the websocket is closed.
-
#send(message) : Nil
Sends a message payload (message).
-
#stream(binary = true, frame_size = 1024, &)
Streams data into io until the io is flushed and sent as a message.
Instance methods inherited from class Reference
==(other : self)==(other : JSON::Any)
==(other : YAML::Any)
==(other) ==, dup dup, hash(hasher) hash, initialize initialize, inspect(io : IO) : Nil inspect, object_id : UInt64 object_id, pretty_print(pp) : Nil pretty_print, same?(other : Reference) : Bool
same?(other : Nil) same?, to_s(io : IO) : Nil to_s
Constructor methods inherited from class Reference
new
new,
unsafe_construct(address : Pointer, *args, **opts) : self
unsafe_construct
Class methods inherited from class Reference
pre_initialize(address : Pointer)
pre_initialize
Instance methods inherited from class Object
! : Bool
!,
!=(other)
!=,
!~(other)
!~,
==(other)
==,
===(other : JSON::Any)===(other : YAML::Any)
===(other) ===, =~(other) =~, as(type : Class) as, as?(type : Class) as?, class class, dup dup, hash(hasher)
hash hash, in?(collection : Object) : Bool
in?(*values : Object) : Bool in?, inspect(io : IO) : Nil
inspect : String inspect, is_a?(type : Class) : Bool is_a?, itself itself, nil? : Bool nil?, not_nil!(message)
not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, responds_to?(name : Symbol) : Bool responds_to?, tap(&) tap, to_json(io : IO) : Nil
to_json : String to_json, to_pretty_json(indent : String = " ") : String
to_pretty_json(io : IO, indent : String = " ") : Nil to_pretty_json, to_s(io : IO) : Nil
to_s : String to_s, to_yaml(io : IO) : Nil
to_yaml : String to_yaml, try(&) try, unsafe_as(type : T.class) forall T unsafe_as
Class methods inherited from class Object
from_json(string_or_io, root : String)from_json(string_or_io) from_json, from_yaml(string_or_io : String | IO) from_yaml
Macros inherited from class Object
class_getter(*names, &block)
class_getter,
class_getter!(*names)
class_getter!,
class_getter?(*names, &block)
class_getter?,
class_property(*names, &block)
class_property,
class_property!(*names)
class_property!,
class_property?(*names, &block)
class_property?,
class_setter(*names)
class_setter,
def_clone
def_clone,
def_equals(*fields)
def_equals,
def_equals_and_hash(*fields)
def_equals_and_hash,
def_hash(*fields)
def_hash,
delegate(*methods, to object)
delegate,
forward_missing_to(delegate)
forward_missing_to,
getter(*names, &block)
getter,
getter!(*names)
getter!,
getter?(*names, &block)
getter?,
property(*names, &block)
property,
property!(*names)
property!,
property?(*names, &block)
property?,
setter(*names)
setter
Constructor Detail
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`
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:password@websocket.example.com/chat")) # Creates a new WebSocket to `websocket.example.com` with an HTTP basic auth Authorization header
Instance Method Detail
Sends a close frame, and closes the connection. The close frame may contain a body (message) that indicates the reason for closing.
Called when the connection is closed by the other party.
Called when a PONG frame is received.
An unsolicited PONG frame should not be responded to.
Sends a PING frame. Received pings will call #on_ping
.
The receiving party must respond with a PONG.
Sends a PONG frame, which must be in response to a previously received PING frame from #on_ping
.
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
Streams data into io until the io is flushed and sent as a message.
The method accepts a block with an io
argument.
The io object can call on IO#write
and IO#flush
method.
The write
method accepts Bytes
(Slice(UInt8)
) and sends the data in chunks of frame_size bytes. The flush
method sends all the data in io and resets it.
The remaining data in it is sent as a message when the block is finished executing.
For further information, see the HTTP::WebSocket::Protocol::StreamIO
class.
# Open websocket connection
ws = HTTP::WebSocket.new("websocket.example.com", "/chat")
# Open stream
ws.stream(false) do |io|
io.write "Hello, ".encode("UTF-8") # Sends "Hello, " to io
io.flush # Sends "Hello, " to the socket
io.write "world!".encode("UTF-8") # Sends "world!" to io
end
# Sends "world!" to the socket