Class: Clacky::Server::HttpServer::WebSocketConnection

Inherits:
Object
  • Object
show all
Defined in:
lib/clacky/server/http_server.rb

Overview

Wraps a raw TCP socket, providing thread-safe WebSocket frame sending.

IMPORTANT: send_raw is called from the Agent thread via broadcast() → send_json(). A blocking socket write with no deadline can pin the Agent thread indefinitely when the client's receive buffer fills up (silent disconnects such as Wi-Fi handoff or NAT timeout, where TCP keepalive defaults are measured in hours). Thread#raise on blocking native socket writes is best-effort and unreliable, so instead we bound every write with an explicit deadline using IO.select + write_nonblock and declare the connection dead on timeout.

Constant Summary collapse

SEND_DEADLINE =

Maximum time a single send_raw call is allowed to spend writing. 5 seconds is generous for healthy LAN/Internet clients and short enough that a stuck Agent becomes responsive again quickly.

5.0
SEND_SLOW_WARN =

Warn threshold — any individual send_raw that exceeds this is logged so we can spot sluggish clients before they fully hang.

1.0

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(socket, version) ⇒ WebSocketConnection

Returns a new instance of WebSocketConnection.



6675
6676
6677
6678
6679
6680
6681
 
# File 'lib/clacky/server/http_server.rb', line 6675

def initialize(socket, version)
  @socket     = socket
  @version    = version
  @send_mutex = Mutex.new
  @closed     = false
  WebSocketConnection.apply_keepalive(socket)
end

Instance Attribute Details

#session_id ⇒ Object

Returns the value of attribute session_id.



6664
6665
6666
 
# File 'lib/clacky/server/http_server.rb', line 6664

def session_id
  @session_id
end

Class Method Details

.apply_keepalive(socket) ⇒ Object

Enable TCP keepalive on the underlying socket so silently dead peers are detected in minutes instead of the OS default of hours. Best-effort: any failure is logged at debug level and ignored.



6795
6796
6797
6798
6799
6800
6801
6802
6803
6804
6805
6806
6807
6808
6809
6810
6811
6812
6813
6814
6815
6816
6817
6818
6819
6820
6821
 
# File 'lib/clacky/server/http_server.rb', line 6795

def self.apply_keepalive(socket)
  return unless socket.respond_to?(:setsockopt)

  socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_KEEPALIVE, true)

  # TCP-level keepalive tuning — constants vary by platform and are
  # only set when available. Values chosen to detect dead peers in
  # roughly 60-90 seconds total.
  if defined?(Socket::IPPROTO_TCP)
    # Idle time before first probe (Linux: TCP_KEEPIDLE, macOS: TCP_KEEPALIVE)
    idle_const = if Socket.const_defined?(:TCP_KEEPIDLE)
                   Socket::TCP_KEEPIDLE
                 elsif Socket.const_defined?(:TCP_KEEPALIVE)
                   Socket::TCP_KEEPALIVE
                 end
    socket.setsockopt(Socket::IPPROTO_TCP, idle_const, 60) if idle_const

    if Socket.const_defined?(:TCP_KEEPINTVL)
      socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_KEEPINTVL, 10)
    end
    if Socket.const_defined?(:TCP_KEEPCNT)
      socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_KEEPCNT, 3)
    end
  end
rescue StandardError => e
  Clacky::Logger.debug("[WS] failed to set keepalive: #{e.class}: #{e.message}")
end

Instance Method Details

#closed? ⇒ Boolean

Returns true if the underlying socket has been detected as dead.

Returns:

  • (Boolean) 


6684
6685
6686
 
# File 'lib/clacky/server/http_server.rb', line 6684

def closed?
  @closed
end

#force_close! ⇒ Object

Force-close the connection (used by the interrupt watchdog when an Agent thread is stuck on an unresponsive socket write).



6690
6691
6692
6693
6694
6695
 
# File 'lib/clacky/server/http_server.rb', line 6690

def force_close!
  @closed = true
  @socket.close
rescue StandardError
  # best effort
end

#send_json(data) ⇒ Object

Send a JSON-serializable object over the WebSocket. Returns true on success, false if the connection is dead.



6699
6700
6701
6702
6703
6704
 
# File 'lib/clacky/server/http_server.rb', line 6699

def send_json(data)
  send_raw(:text, JSON.generate(data))
rescue => e
  Clacky::Logger.debug("WS send error (connection dead): #{e.message}")
  false
end

#send_raw(type, data) ⇒ Object

Send a raw WebSocket frame. Returns true on success, false on broken/closed/sluggish socket.

Uses write_nonblock with an overall deadline so the caller (typically the Agent thread) never blocks longer than SEND_DEADLINE, even if the client silently stopped reading.



6712
6713
6714
6715
6716
6717
6718
6719
6720
6721
6722
6723
6724
6725
6726
6727
6728
6729
6730
6731
6732
6733
6734
6735
6736
6737
6738
6739
6740
6741
6742
6743
6744
6745
6746
6747
6748
6749
6750
6751
6752
6753
6754
6755
6756
6757
 
# File 'lib/clacky/server/http_server.rb', line 6712

def send_raw(type, data)
  started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)

  @send_mutex.synchronize do
    return false if @closed

    outgoing = WebSocket::Frame::Outgoing::Server.new(
      version: @version,
      data: data,
      type: type
    )
    bytes = outgoing.to_s

    unless write_with_deadline(bytes, SEND_DEADLINE)
      # Deadline exceeded — treat as a dead connection so broadcast
      # purges it and the Agent thread is freed immediately.
      @closed = true
      begin
        @socket.close
      rescue StandardError
        # ignore
      end
      Clacky::Logger.warn(
        "[WS] send_raw deadline exceeded — closing sluggish connection " \
        "(bytes=#{bytes.bytesize}, deadline=#{SEND_DEADLINE}s)"
      )
      return false
    end
  end

  elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
  if elapsed > SEND_SLOW_WARN
    Clacky::Logger.warn(
      "[WS] send_raw slow: #{elapsed.round(2)}s (type=#{type})"
    )
  end
  true
rescue Errno::EPIPE, Errno::ECONNRESET, IOError, Errno::EBADF => e
  @closed = true
  Clacky::Logger.debug("WS send_raw error (client disconnected): #{e.message}")
  false
rescue => e
  @closed = true
  Clacky::Logger.debug("WS send_raw unexpected error: #{e.message}")
  false
end