Class: Telnyx::Lib::WebSocket::Base

Inherits:
Object
  • Object
show all
Defined in:
lib/telnyx/lib/websocket/base.rb

Overview

Base class for WebSocket connections.

This class provides the foundation for STT and TTS WebSocket clients, including event handling, connection state management, and error handling.

The class uses a simple event emitter pattern with block callbacks for handling WebSocket events.

Example usage:

class MyWS < Base
  def initialize(client)
    super()
    @client = client
  end
end

ws = MyWS.new(client)
ws.on(:message) { |data| puts data }
ws.on(:error) { |error| puts error.message }

Direct Known Subclasses

SpeechToTextWS, TextToSpeechWS

Constant Summary collapse

CONNECTING =

WebSocket ready states (matching WebSocket spec)

0
OPEN = 
1
CLOSING = 
2
CLOSED = 
3

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Base

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Base.



45
46
47
48
49
50
51
 
# File 'lib/telnyx/lib/websocket/base.rb', line 45

def initialize
  @listeners = Hash.new { |h, k| h[k] = [] }
  @ready_state = CONNECTING
  @socket = nil
  @mutex = Mutex.new
  @open_queue = ::Queue.new
end

Instance Attribute Details

#ready_state ⇒ Integer (readonly)

Returns Current connection state.

Returns:

  • (Integer) —

    Current connection state



39
40
41
 
# File 'lib/telnyx/lib/websocket/base.rb', line 39

def ready_state
  @ready_state
end

#url ⇒ URI (readonly)

Returns The WebSocket URL.

Returns:

  • (URI) —

    The WebSocket URL



42
43
44
 
# File 'lib/telnyx/lib/websocket/base.rb', line 42

def url
  @url
end

Instance Method Details

#close(code: 1000, reason: "OK") ⇒ void

This method returns an undefined value.

Close the WebSocket connection.

rubocop:disable Lint/UnusedMethodArgument

Parameters:

  • code (Integer) (defaults to: 1000) —

    Close status code (default: 1000 normal closure)

  • reason (String) (defaults to: "OK") —

    Close reason



135
136
137
138
139
140
141
142
143
144
145
 
# File 'lib/telnyx/lib/websocket/base.rb', line 135

def close(code: 1000, reason: "OK")
  return if closed?

  @ready_state = CLOSING
  begin
    @socket&.close
  rescue StandardError => e
    emit_error(nil, "could not close the connection", e)
  end
  @ready_state = CLOSED
end

#closed? ⇒ Boolean

Check if the connection is closed.

Returns:

  • (Boolean) 


102
103
104
 
# File 'lib/telnyx/lib/websocket/base.rb', line 102

def closed?
  @ready_state == CLOSED || @ready_state == CLOSING
end

#connecting? ⇒ Boolean

Check if the connection is connecting.

Returns:

  • (Boolean) 


95
96
97
 
# File 'lib/telnyx/lib/websocket/base.rb', line 95

def connecting?
  @ready_state == CONNECTING
end

#off(event, block = nil) ⇒ self

Remove an event listener.

Parameters:

  • event (Symbol, String) —

    The event name

  • block (Proc, nil) (defaults to: nil) —

    The specific block to remove, or nil to remove all

Returns:

  • (self) 


76
77
78
79
80
81
82
83
 
# File 'lib/telnyx/lib/websocket/base.rb', line 76

def off(event, block = nil)
  if block
    @listeners[event.to_sym].delete(block)
  else
    @listeners.delete(event.to_sym)
  end
  self
end

#on(event) {|Object| ... } ⇒ self

Register an event listener.

Available events:

  • :open - Connection established

  • :message - Raw message received

  • :event - Parsed event received

  • :error - Error occurred

  • :close - Connection closed

  • Event-specific types (e.g., :transcript, :audio_chunk)

Parameters:

  • event (Symbol, String) —

    The event name to listen for

Yields:

  • (Object) —

    Block to call when event is emitted

Returns:

  • (self) 


66
67
68
69
 
# File 'lib/telnyx/lib/websocket/base.rb', line 66

def on(event, &block)
  @listeners[event.to_sym] << block
  self
end

#open? ⇒ Boolean

Check if the connection is open.

Returns:

  • (Boolean) 


88
89
90
 
# File 'lib/telnyx/lib/websocket/base.rb', line 88

def open?
  @ready_state == OPEN
end

#wait_for_open(timeout: nil) ⇒ self

Wait for the connection to be established.

Parameters:

  • timeout (Numeric, nil) (defaults to: nil) —

    Maximum time to wait in seconds

Returns:

  • (self)

Raises:



111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
 
# File 'lib/telnyx/lib/websocket/base.rb', line 111

def wait_for_open(timeout: nil)
  return self if open?

  result = if timeout
    @open_queue.pop(timeout: timeout)
  else
    @open_queue.pop
  end

  if result.is_a?(Exception)
    raise result
  end

  self
rescue ThreadError
  raise WebSocketError.new("Connection timed out")
end