bsdkrun 0.1.0 → 0.2.0

data/lib/bsdkrun/shell_session.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module Bsdkrun
+  # A live interactive session opened by {Bsdkrun::Client#shell}.
+  #
+  # Output arrives on the {Bsdkrun::WsClient}'s background reader thread, so
+  # {#on_output} / {#on_exit} callbacks run on that thread, not the caller's —
+  # the same tradeoff +web/src/lib/graphql.ts+ makes with its +onNext+
+  # handlers, just single-threaded there because JS has no threads to worry
+  # about.
+  class ShellSession
+    # @return [String] the session id (+openShell+'s return value).
+    attr_reader :id
+
+    # @!visibility private
+    #
+    # Constructed by {Bsdkrun::Client#shell} — not meant to be built directly.
+    # +unsubscribe+ is assigned right after construction, before the
+    # +shellOutput+ subscription can possibly deliver anything, so callbacks
+    # closing over +self+ never observe it unset.
+    def initialize(client:, id:)
+      @client = client
+      @id = id
+      @unsubscribe = nil
+      @callback_mutex = Mutex.new
+      @on_output = nil
+      @on_exit = nil
+      # The shellOutput subscription starts synchronously inside
+      # Client#shell, on the WsClient's background reader thread — a real,
+      # genuinely concurrent thread here (unlike JS's single-threaded event
+      # loop), so output/exit can arrive before the caller gets around to
+      # calling #on_output/#on_exit. The daemon buffers from the moment the
+      # session opens specifically so nothing is lost in that window (see
+      # daemon/README.md); buffer here too so a late registration still sees
+      # everything, exactly like write-side of this same race in the other
+      # SDKs' shell()/ShellSession.
+      @buffered_output = []
+      @exit_delivered = false
+      @buffered_exit = nil
+    end
+
+    # @!visibility private
+    def unsubscribe=(proc)
+      @unsubscribe = proc
+    end
+
+    # Register a callback for output chunks (already base64-decoded). Any
+    # output that arrived before this was called is replayed immediately.
+    # @yieldparam bytes [String] binary-safe.
+    # @return [void]
+    def on_output(&block)
+      buffered = @callback_mutex.synchronize do
+        @on_output = block
+        buf = @buffered_output
+        @buffered_output = []
+        buf
+      end
+      buffered.each { |bytes| block.call(bytes) }
+    end
+
+    # Register a callback for the session's exit code. Fires once — right
+    # away if the session had already exited before this was called.
+    # @yieldparam exit_code [Integer, nil] nil if the session ended without
+    #   ever reporting one (e.g. the connection dropped).
+    # @return [void]
+    def on_exit(&block)
+      already_exited, code = @callback_mutex.synchronize do
+        @on_exit = block
+        [@exit_delivered, @buffered_exit]
+      end
+      block.call(code) if already_exited
+    end
+
+    # Send keystrokes / input bytes.
+    # @param data [String]
+    # @return [void]
+    def write(data)
+      @client.request(
+        "mutation($s:String!,$d:String!){ sendShellInput(sessionId:$s, dataBase64:$d) }",
+        { s: @id, d: Base64.strict_encode64(data.to_s.b) }
+      )
+      nil
+    end
+
+    # Resize the pseudo-terminal.
+    # @param rows [Integer]
+    # @param cols [Integer]
+    # @return [void]
+    def resize(rows, cols)
+      @client.request(
+        "mutation($s:String!,$r:Int!,$c:Int!){ resizeShell(sessionId:$s, rows:$r, cols:$c) }",
+        { s: @id, r: rows, c: cols }
+      )
+      nil
+    end
+
+    # Unsubscribe and close the session. Idempotent on the wire (+closeShell+
+    # is safe to call on an already-closed session) — a request failure here
+    # (already gone, machine removed, etc.) is swallowed rather than raised,
+    # matching the other SDKs' `close`/`closeShell` handling.
+    # @return [void]
+    def close
+      @unsubscribe&.call
+      begin
+        @client.request("mutation($s:String!){ closeShell(sessionId:$s) }", { s: @id })
+      rescue GraphQLError
+        nil
+      end
+      nil
+    end
+
+    # @!visibility private — invoked from the {WsClient} reader thread.
+    def deliver_output(bytes)
+      cb = @callback_mutex.synchronize do
+        cb = @on_output
+        @buffered_output << bytes if cb.nil?
+        cb
+      end
+      cb&.call(bytes)
+    end
+
+    # @!visibility private — invoked from the {WsClient} reader thread. Only
+    # the first call has any effect, whether that arrives as a real exit code
+    # or (from {Bsdkrun::Client#shell}'s `on_error`) as +nil+ for a dropped
+    # connection.
+    def deliver_exit(exit_code)
+      cb = @callback_mutex.synchronize do
+        next nil if @exit_delivered
+
+        @exit_delivered = true
+        @buffered_exit = exit_code
+        @on_exit
+      end
+      cb&.call(exit_code)
+    end
+  end
+end

data/lib/bsdkrun/types.rb

@@ -1,6 +1,26 @@
 # frozen_string_literal: true
 
 module Bsdkrun
+  # A host->guest TCP port forward, as reported by +bsdkrun ps --json+.
+  #
+  # @!attribute [r] bind
+  #   @return [String] host interface, e.g. "127.0.0.1" or "0.0.0.0".
+  # @!attribute [r] host
+  #   @return [Integer] host port.
+  # @!attribute [r] guest
+  #   @return [Integer] guest port.
+  PortForward = Data.define(:bind, :host, :guest) do
+    # @param row [Hash]
+    # @return [PortForward]
+    def self.from_row(row)
+      new(
+        bind: row["bind"].to_s,
+        host: row["host"].to_i,
+        guest: row["guest"].to_i
+      )
+    end
+  end
+
   # A machine as reported by +bsdkrun ps --json+.
   #
   # @!attribute [r] id
@@ -9,10 +29,12 @@ module Bsdkrun
   #   @return [String, nil] DNS name on a network, or nil if unnamed.
   # @!attribute [r] status
   #   @return [String] "running" or "exited" (derived from +running+).
+  # @!attribute [r] ports
+  #   @return [Array<PortForward>] host<->guest TCP port forwards.
   SandboxInfo = Data.define(
     :id, :name, :image, :kind, :command, :status, :running, :exit_code,
     :pid, :detached, :cpus, :mem, :volume, :state_dir, :network, :net_ip,
-    :created_at, :finished_at
+    :created_at, :finished_at, :ports
   ) do
     # Map a +ps --json+ row (String keys) to a typed instance.
     # @param row [Hash]
@@ -37,13 +59,46 @@ module Bsdkrun
         network: row["network"],
         net_ip: row["net_ip"],
         created_at: row["created_at"].to_i,
-        finished_at: to_i_or_nil(row["finished_at"])
+        finished_at: to_i_or_nil(row["finished_at"]),
+        ports: (row["ports"] || []).map { |p| PortForward.from_row(p) }
       )
     end
 
     def self.to_i_or_nil(value)
       value.nil? ? nil : value.to_i
     end
+
+    # Map a GraphQL +Machine+ object (String keys, camelCase — it comes from
+    # +JSON.parse+ on the daemon's response, not the CLI) to a typed instance.
+    # Sibling to {from_row}; same fields, different source and casing.
+    #
+    # @param m [Hash] a +MACHINE_FIELDS+-shaped hash, e.g. from
+    #   {Bsdkrun::Client#list} / {Bsdkrun::Client#get}.
+    # @return [SandboxInfo]
+    def self.from_graphql(m)
+      running = !!m["running"]
+      new(
+        id: m["id"].to_s,
+        name: m["name"],
+        image: m["image"].to_s,
+        kind: m["kind"].to_s,
+        command: (m["command"] || "").to_s,
+        status: m["status"].to_s,
+        running: running,
+        exit_code: to_i_or_nil(m["exitCode"]),
+        pid: to_i_or_nil(m["pid"]),
+        detached: !!m["detached"],
+        cpus: m["cpus"].to_i,
+        mem: m["mem"].to_i,
+        volume: m["volume"],
+        state_dir: m["stateDir"].to_s,
+        network: m["network"],
+        net_ip: m["netIp"],
+        created_at: m["createdAt"].to_i,
+        finished_at: to_i_or_nil(m["finishedAt"]),
+        ports: (m["ports"] || []).map { |p| PortForward.from_row(p) }
+      )
+    end
   end
 
   # An image as reported by +bsdkrun images --json+.
@@ -141,4 +196,41 @@ module Bsdkrun
       self
     end
   end
+
+  # The outcome of a {Bsdkrun::Client} lifecycle mutation (+stopMachine+,
+  # +startMachine+, +removeMachines+, +updateMachine+, +commitMachine+, ...).
+  # A non-zero +exit_code+ is a value to inspect, not necessarily a failure —
+  # mirrors +daemon/src/graphql.rs+'s +CommandResult+.
+  #
+  # @!attribute [r] exit_code
+  #   @return [Integer]
+  # @!attribute [r] stdout
+  #   @return [String]
+  # @!attribute [r] stderr
+  #   @return [String]
+  CommandResult = Data.define(:exit_code, :stdout, :stderr)
+
+  # A {Bsdkrun::Client#exec} result: the guest command's exit status and its
+  # combined (stdout+stderr, in arrival order) output, decoded from the
+  # +shellOutput+ subscription's base64 frames.
+  #
+  # @!attribute [r] exit_code
+  #   @return [Integer]
+  # @!attribute [r] output
+  #   @return [String] binary-safe combined output.
+  ExecResult = Data.define(:exit_code, :output)
+
+  # An open interactive shell session, as reported by +openShell+ / the
+  # +shellSessions+ query. Mirrors +daemon/src/graphql.rs+'s +ShellSessionInfo+.
+  #
+  # @!attribute [r] id
+  #   @return [String]
+  # @!attribute [r] machine_id
+  #   @return [String]
+  # @!attribute [r] finished
+  #   @return [Boolean]
+  # @!attribute [r] truncated
+  #   @return [Boolean] whether buffered output was dropped to stay under the
+  #     session buffer cap.
+  ShellSessionInfo = Data.define(:id, :machine_id, :finished, :truncated)
 end

data/lib/bsdkrun/version.rb

@@ -2,5 +2,5 @@
 
 module Bsdkrun
   # The bsdkrun Ruby SDK version.
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/bsdkrun/websocket_frame.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Bsdkrun
+  # RFC 6455 §5.2 frame encode/decode, hand-rolled because the Ruby standard
+  # library has no WebSocket client.
+  #
+  # Deliberately narrow: only what {WsClient} needs to speak
+  # +graphql-transport-ws+, which exchanges small JSON text frames. Fragmented
+  # messages (a logical message split across CONTINUATION frames) are
+  # unsupported — {read} returns whatever single frame arrives, and a caller
+  # that gets a non-FIN frame is expected to treat it as an error. In
+  # practice every graphql-ws message this SDK deals with is small enough
+  # that no server has ever been observed to fragment one.
+  module WebSocketFrame
+    OPCODES = {
+      continuation: 0x0,
+      text: 0x1,
+      binary: 0x2,
+      close: 0x8,
+      ping: 0x9,
+      pong: 0xA
+    }.freeze
+
+    module_function
+
+    # Build a complete frame.
+    #
+    # @param opcode [Symbol] a key of {OPCODES}.
+    # @param payload [String] the frame body (binary-safe).
+    # @param mask [Boolean] +true+ for client->server frames (RFC 6455
+    #   requires it — the mask key is randomly generated per frame); +false+
+    #   for server->client frames, which MUST NOT be masked.
+    # @return [String] the raw bytes to write to the socket.
+    def build(opcode:, payload: "".b, mask: true)
+      payload = payload.to_s.dup.force_encoding(Encoding::BINARY)
+      code = OPCODES.fetch(opcode) { raise ArgumentError, "unknown opcode #{opcode.inspect}" }
+
+      frame = +"".b
+      frame << [0x80 | code].pack("C") # FIN=1, RSV1-3=0
+      frame << length_bytes(payload.bytesize, mask)
+
+      if mask
+        key = Random.bytes(4)
+        frame << key
+        frame << apply_mask(payload, key)
+      else
+        frame << payload
+      end
+      frame
+    end
+
+    # Read exactly one frame from +io+ (anything responding to +#read(n)+ —
+    # a +TCPSocket+, an +OpenSSL::SSL::SSLSocket+, or a +StringIO+ in tests).
+    #
+    # @param io [#read]
+    # @return [Array(Boolean, Integer, String)] +[fin, opcode, payload]+ —
+    #   +payload+ is already unmasked.
+    # @raise [EOFError] if the socket closes mid-frame.
+    def read(io)
+      b0, b1 = read_exact(io, 2).unpack("C2")
+      fin = (b0 & 0x80) != 0
+      opcode = b0 & 0x0F
+      masked = (b1 & 0x80) != 0
+      len = b1 & 0x7F
+
+      len = read_exact(io, 2).unpack1("n") if len == 126
+      len = read_exact(io, 8).unpack1("Q>") if len == 127
+
+      mask_key = masked ? read_exact(io, 4) : nil
+      payload = len.positive? ? read_exact(io, len) : "".b
+      payload = apply_mask(payload, mask_key) if masked
+
+      [fin, opcode, payload]
+    end
+
+    # XOR-mask (or, symmetrically, unmask) +payload+ against a 4-byte +key+.
+    # @param payload [String]
+    # @param key [String] exactly 4 bytes.
+    # @return [String]
+    def apply_mask(payload, key)
+      out = payload.b
+      key_bytes = key.bytes
+      bytes = out.bytes
+      bytes.each_index { |i| bytes[i] ^= key_bytes[i % 4] }
+      bytes.pack("C*")
+    end
+
+    # @!visibility private
+    def length_bytes(len, mask)
+      mask_bit = mask ? 0x80 : 0x00
+      if len < 126
+        [mask_bit | len].pack("C")
+      elsif len < 65_536
+        [mask_bit | 126].pack("C") + [len].pack("n")
+      else
+        [mask_bit | 127].pack("C") + [len].pack("Q>")
+      end
+    end
+
+    # @!visibility private
+    #
+    # +io.read(n)+ already blocks until +n+ bytes are available or EOF, but a
+    # partial read (fewer than +n+ bytes, non-nil) is technically possible
+    # per the IO contract, so this loops to be sure.
+    def read_exact(io, n)
+      buf = "".b
+      while buf.bytesize < n
+        chunk = io.read(n - buf.bytesize)
+        raise EOFError, "socket closed mid-frame" if chunk.nil?
+
+        buf << chunk
+      end
+      buf
+    end
+  end
+end

data/lib/bsdkrun/ws_client.rb

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+
+require "socket"
+require "openssl"
+require "uri"
+require "json"
+require "digest/sha1"
+require "base64"
+
+require_relative "websocket_frame"
+require_relative "errors"
+
+module Bsdkrun
+  # A hand-rolled +graphql-transport-ws+ client (the graphql-ws project's
+  # protocol; the negotiated subprotocol string is literally
+  # +"graphql-transport-ws"+), because the Ruby standard library has no
+  # WebSocket client.
+  #
+  # One socket per instance, opened lazily on the first {#subscribe} and
+  # closed once the last subscription ends. A background reader +Thread+
+  # pumps frames off the socket and dispatches to each subscription's
+  # callbacks — this SDK is otherwise synchronous (see
+  # {Bsdkrun::Sandbox}, which shells out via +Open3+), so the public surface
+  # here stays callback-based and lets callers like {Bsdkrun::Client#exec}
+  # block on a +Queue+ instead of needing their own event loop.
+  #
+  # Two mutexes, deliberately not one: +@state_mutex+ guards the small bits
+  # of bookkeeping (+@subs+, +@pending+, +@acked+) so the reader thread and
+  # callers never race on them, while +@write_mutex+ only serializes actual
+  # socket writes. Holding one lock across a blocking socket write while the
+  # other is needed just for a hash lookup would let a slow write stall
+  # unrelated bookkeeping.
+  class WsClient
+    GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+    private_constant :GUID
+
+    # @param ws_url [String] e.g. "ws://host:50052/graphql/ws".
+    # @param token [String]
+    def initialize(ws_url:, token:)
+      @ws_url = ws_url
+      @token = token
+
+      @connect_mutex = Mutex.new
+      @write_mutex = Mutex.new
+      @state_mutex = Mutex.new
+
+      @socket = nil
+      @reader_thread = nil
+      @acked = false
+      @subs = {}
+      @pending = []
+      @next_id = 0
+    end
+
+    # Start a subscription.
+    #
+    # Connects (and sends +connection_init+) on the first call. If
+    # +connection_ack+ has not arrived yet, the +subscribe+ message is queued
+    # and flushed once it does — starting a subscription before the ack
+    # would be sent to a daemon not yet ready to accept operations.
+    #
+    # @param query [String]
+    # @param variables [Hash]
+    # @param on_next [#call] invoked with the +data+ hash for each +next+.
+    # @param on_error [#call, nil] invoked with an {Error} exception once.
+    # @param on_complete [#call, nil] invoked with no args once, on a clean end.
+    # @return [Proc] call to unsubscribe (sends +complete+, then closes the
+    #   socket if this was the last subscription).
+    def subscribe(query, variables, on_next:, on_error: nil, on_complete: nil)
+      ensure_connected
+
+      id = (@state_mutex.synchronize { @next_id += 1 }).to_s
+      sub = {
+        on_next: on_next,
+        on_error: on_error || ->(_e) {},
+        on_complete: on_complete || -> {}
+      }
+      start = lambda do
+        send_json({ id: id, type: "subscribe", payload: { query: query, variables: variables } })
+      end
+
+      ready = @state_mutex.synchronize do
+        @subs[id] = sub
+        if @acked
+          true
+        else
+          @pending << start
+          false
+        end
+      end
+      start.call if ready
+
+      unsubscribed = false
+      lambda do
+        next if unsubscribed
+
+        unsubscribed = true
+        existed = @state_mutex.synchronize { !!@subs.delete(id) }
+        next unless existed
+
+        send_json({ id: id, type: "complete" }) if connected?
+        close_if_idle
+      end
+    end
+
+    # @return [Boolean] whether the socket is currently open.
+    def connected?
+      !@socket.nil?
+    end
+
+    # Close the socket immediately, regardless of open subscriptions. Used by
+    # {Bsdkrun::Client} teardown paths; normal use tears itself down when the
+    # last subscription unsubscribes.
+    # @return [void]
+    def close
+      @connect_mutex.synchronize { close_socket }
+    end
+
+    private
+
+    def ensure_connected
+      @connect_mutex.synchronize do
+        return if @socket
+
+        uri = URI.parse(@ws_url)
+        port = uri.port || (uri.scheme == "wss" ? 443 : 80)
+        tcp = TCPSocket.new(uri.host, port)
+        socket = uri.scheme == "wss" ? wrap_tls(tcp, uri.host) : tcp
+
+        path = uri.path.to_s
+        path = "/" if path.empty?
+        path = "#{path}?#{uri.query}" if uri.query
+
+        handshake(socket, uri.host, port, path)
+
+        @socket = socket
+        @state_mutex.synchronize do
+          @acked = false
+          @pending = []
+        end
+        start_reader
+        send_json({ type: "connection_init", payload: { authorization: "Bearer #{@token}" } })
+      end
+    end
+
+    def wrap_tls(tcp, hostname)
+      ctx = OpenSSL::SSL::SSLContext.new
+      ssl = OpenSSL::SSL::SSLSocket.new(tcp, ctx)
+      ssl.hostname = hostname
+      ssl.connect
+      ssl
+    end
+
+    # The RFC 6455 opening handshake: an HTTP/1.1 Upgrade request, and the
+    # server's +Sec-WebSocket-Accept+ verified against the client's key
+    # (SHA-1 of key+GUID, base64-encoded — the one bit of cryptography this
+    # protocol asks of a client).
+    def handshake(socket, host, port, path)
+      key = Base64.strict_encode64(Random.bytes(16))
+      request = +"GET #{path} HTTP/1.1\r\n"
+      request << "Host: #{host}:#{port}\r\n"
+      request << "Upgrade: websocket\r\n"
+      request << "Connection: Upgrade\r\n"
+      request << "Sec-WebSocket-Key: #{key}\r\n"
+      request << "Sec-WebSocket-Version: 13\r\n"
+      request << "Sec-WebSocket-Protocol: graphql-transport-ws\r\n"
+      request << "\r\n"
+      socket.write(request)
+
+      status_line = socket.gets
+      unless status_line
+        raise GraphQLError, "cannot reach the bsdkrun daemon at #{@ws_url} — connection closed during handshake"
+      end
+      unless status_line.include?(" 101 ")
+        raise GraphQLError, "websocket handshake with #{@ws_url} failed: #{status_line.strip}"
+      end
+
+      headers = {}
+      while (line = socket.gets) && line.strip != ""
+        k, v = line.split(":", 2)
+        headers[k.strip.downcase] = v.strip if k && v
+      end
+
+      expected = Base64.strict_encode64(Digest::SHA1.digest(key + GUID))
+      return if headers["sec-websocket-accept"] == expected
+
+      raise GraphQLError, "websocket handshake with #{@ws_url} failed: bad Sec-WebSocket-Accept"
+    end
+
+    def start_reader
+      socket = @socket
+      @reader_thread = Thread.new { read_loop(socket) }
+      @reader_thread.report_on_exception = false
+    end
+
+    def read_loop(socket)
+      loop do
+        _fin, opcode, payload = WebSocketFrame.read(socket)
+        case opcode
+        when WebSocketFrame::OPCODES[:text]
+          dispatch(payload)
+        when WebSocketFrame::OPCODES[:ping]
+          write_frame(opcode: :pong, payload: payload)
+        when WebSocketFrame::OPCODES[:close]
+          break
+        else
+          # binary / pong / continuation: nothing this protocol sends that we
+          # need to act on. Fragmented text messages would arrive as
+          # continuation frames, which is the documented unsupported case.
+        end
+      end
+    rescue EOFError, IOError, Errno::ECONNRESET, OpenSSL::SSL::SSLError
+      # The socket closed — handled uniformly below.
+    ensure
+      handle_disconnect(socket)
+    end
+
+    def dispatch(raw)
+      msg = JSON.parse(raw)
+      case msg["type"]
+      when "connection_ack"
+        flush_pending
+      when "next"
+        sub = @state_mutex.synchronize { @subs[msg["id"]] }
+        sub&.[](:on_next)&.call(msg.dig("payload", "data"))
+      when "error"
+        sub = @state_mutex.synchronize { @subs.delete(msg["id"]) }
+        sub&.[](:on_error)&.call(GraphQLError.new(error_detail(msg["payload"])))
+        close_if_idle
+      when "complete"
+        sub = @state_mutex.synchronize { @subs.delete(msg["id"]) }
+        sub&.[](:on_complete)&.call
+        close_if_idle
+      when "ping"
+        send_json({ type: "pong" })
+      end
+    rescue JSON::ParserError
+      nil
+    end
+
+    def error_detail(payload)
+      if payload.is_a?(Array)
+        payload.map { |e| e["message"] }.compact.join("; ")
+      else
+        payload.to_s
+      end
+    end
+
+    def flush_pending
+      queued = @state_mutex.synchronize do
+        @acked = true
+        q = @pending
+        @pending = []
+        q
+      end
+      queued.each(&:call)
+    end
+
+    # The reader thread's terminal state: fan out a close reason to every
+    # still-open subscription and drop the socket. Whether a +connection_ack+
+    # was ever received decides the reason — an unacked close means the
+    # daemon rejected our token; an acked close is just "the connection
+    # dropped."
+    def handle_disconnect(socket)
+      acked, subs = @state_mutex.synchronize do
+        next [@acked, {}] unless @socket.equal?(socket)
+
+        result = [@acked, @subs.dup]
+        @subs.clear
+        @pending = []
+        @acked = false
+        result
+      end
+
+      @connect_mutex.synchronize { close_socket if @socket.equal?(socket) }
+
+      return if subs.empty?
+
+      err = acked ? GraphQLError.new("the connection to the daemon was closed") : AuthError.new
+      subs.each_value { |sub| sub[:on_error]&.call(err) }
+    end
+
+    def close_if_idle
+      close if @state_mutex.synchronize { @subs.empty? }
+    end
+
+    def close_socket
+      return unless @socket
+
+      socket = @socket
+      @socket = nil
+      begin
+        @write_mutex.synchronize { socket.write(WebSocketFrame.build(opcode: :close, payload: "".b)) }
+      rescue StandardError
+        nil
+      end
+      begin
+        socket.close
+      rescue StandardError
+        nil
+      end
+    end
+
+    def send_json(obj)
+      write_frame(opcode: :text, payload: JSON.generate(obj).b)
+    end
+
+    def write_frame(opcode:, payload:)
+      frame = WebSocketFrame.build(opcode: opcode, payload: payload)
+      @write_mutex.synchronize { @socket&.write(frame) }
+    rescue StandardError
+      nil
+    end
+  end
+end