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.



4919
4920
4921
4922
4923
4924
4925
 
# File 'lib/clacky/server/http_server.rb', line 4919

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.



4908
4909
4910
 
# File 'lib/clacky/server/http_server.rb', line 4908

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.



5039
5040
5041
5042
5043
5044
5045
5046
5047
5048
5049
5050
5051
5052
5053
5054
5055
5056
5057
5058
5059
5060
5061
5062
5063
5064
5065
 
# File 'lib/clacky/server/http_server.rb', line 5039

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) 


4928
4929
4930
 
# File 'lib/clacky/server/http_server.rb', line 4928

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).



4934
4935
4936
4937
4938
4939
 
# File 'lib/clacky/server/http_server.rb', line 4934

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.



4943
4944
4945
4946
4947
4948
 
# File 'lib/clacky/server/http_server.rb', line 4943

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.



4956
4957
4958
4959
4960
4961
4962
4963
4964
4965
4966
4967
4968
4969
4970
4971
4972
4973
4974
4975
4976
4977
4978
4979
4980
4981
4982
4983
4984
4985
4986
4987
4988
4989
4990
4991
4992
4993
4994
4995
4996
4997
4998
4999
5000
5001
 
# File 'lib/clacky/server/http_server.rb', line 4956

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