HTTP::WebSocket - Crystal 1.4.1

# class HTTP::WebSocket

- HTTP::WebSocket
- Reference
- Object

##
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`

==(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

### 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! 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

##
Constructor Detail

def self.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`

def self.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"})
    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

def close(code : CloseCode | Int? = nil, message = nil) : 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.

def closed? : Bool #
def on_binary(&on_binary : Bytes -> ) #

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

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

Called when the server closes a client's connection.

def on_message(&on_message : String -> ) #

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

def on_ping(&on_ping : String -> ) #

Called when the server sends a ping to a client.

def on_pong(&on_pong : String -> ) #

Called when the server receives a pong from a client.

def 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`.

def pong(message = nil) : Nil #

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

See `#ping`.

def run : Nil #

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 #

Sends a message payload (message) to the client.

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