superkick 0.1.0

data/lib/superkick/hosted/attach/relay.rb

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Hosted
+    module Attach
+      # Server-side relay/mux for remote attach sessions over raw WebSocket.
+      #
+      # Manages one agent WebSocket and multiple user WebSockets, routing
+      # Attach::Protocol binary frames between them. The relay enforces RW
+      # exclusivity, buffers output for replay on new connections, and handles
+      # idle timeout auto-demotion.
+      #
+      # WebSocket objects must respond to #send_binary(data) and #close.
+      # The relay is transport-agnostic — the hosted server wraps its WebSocket
+      # library to provide this interface.
+      class Relay
+        DEFAULT_REPLAY_BUFFER_SIZE = 65_536 # 64 KB
+        DEFAULT_MAX_CONNECTIONS = 10
+        DEFAULT_RW_IDLE_TIMEOUT = 300 # 5 minutes
+
+        def initialize(agent_id:, config: {})
+          @agent_id = agent_id
+          @replay_buffer_size = config.fetch(:replay_buffer_size, DEFAULT_REPLAY_BUFFER_SIZE).to_i
+          @max_connections = config.fetch(:max_connections, DEFAULT_MAX_CONNECTIONS).to_i
+          @rw_idle_timeout = config.fetch(:rw_idle_timeout, DEFAULT_RW_IDLE_TIMEOUT)
+
+          @agent_ws = nil
+          @users = []          # Array of { websocket:, mode: }
+          @rw_user = nil       # The current RW user websocket (or nil)
+          @rw_last_input_at = nil
+
+          @mutex = Mutex.new
+          @history = HistoryBuffer.new(capacity: @replay_buffer_size)
+          @idle_check_thread = nil
+
+          start_idle_check if @rw_idle_timeout && @rw_idle_timeout > 0
+        end
+
+        # --- Agent connection ---
+
+        # Called when the agent connects via WebSocket.
+        def attach_agent(websocket)
+          @mutex.synchronize do
+            @agent_ws = websocket
+          end
+          Superkick.logger.info("attach:relay") { "Agent #{@agent_id} attached" }
+        end
+
+        # Called when the agent WebSocket closes.
+        def detach_agent
+          @mutex.synchronize do
+            @agent_ws = nil
+
+            # Notify all users that the agent disconnected
+            error_frame = Superkick::Attach::Protocol.build_frame(
+              Superkick::Attach::Protocol::ERROR,
+              JSON.generate({message: "Agent disconnected"})
+            )
+            @users.each do |user|
+              user[:websocket].send_binary(error_frame)
+            rescue IOError, Errno::EPIPE, Errno::ECONNRESET
+              nil
+            end
+          end
+          Superkick.logger.info("attach:relay") { "Agent #{@agent_id} detached" }
+        end
+
+        def agent_connected?
+          @mutex.synchronize { !@agent_ws.nil? }
+        end
+
+        # --- User connections ---
+
+        # Add a user connection. Enforces RW exclusivity and max connections.
+        # Sends META frame and replays history.
+        def add_user(websocket, mode:, force: false)
+          @mutex.synchronize do
+            # Enforce max connections
+            if @users.size >= @max_connections
+              error_frame = Superkick::Attach::Protocol.build_frame(
+                Superkick::Attach::Protocol::ERROR,
+                JSON.generate({message: "Maximum connections reached"})
+              )
+              websocket.send_binary(error_frame)
+              websocket.close
+              return
+            end
+
+            # Enforce RW exclusivity
+            if mode == :rw
+              if @rw_user
+                if force
+                  demote_rw_user_locked("Read-write taken over by another client")
+                else
+                  error_frame = Superkick::Attach::Protocol.build_frame(
+                    Superkick::Attach::Protocol::ERROR,
+                    JSON.generate({message: "Another read-write client is already connected"})
+                  )
+                  websocket.send_binary(error_frame)
+                  websocket.close
+                  return
+                end
+              end
+              @rw_user = websocket
+              @rw_last_input_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            end
+
+            @users << {websocket:, mode:}
+
+            # Send META
+            meta_frame = Superkick::Attach::Protocol.build_frame(
+              Superkick::Attach::Protocol::META,
+              JSON.generate({agent_id: @agent_id, history_bytes: @history.size})
+            )
+            websocket.send_binary(meta_frame)
+
+            # Replay history
+            history_data = @history.snapshot
+            unless history_data.empty?
+              history_frame = Superkick::Attach::Protocol.build_frame(Superkick::Attach::Protocol::HISTORY, history_data)
+              websocket.send_binary(history_frame)
+            end
+          end
+          Superkick.logger.info("attach:relay") { "User added to #{@agent_id} (#{mode})" }
+        end
+
+        # Remove a user connection.
+        def remove_user(websocket)
+          @mutex.synchronize do
+            @users.reject! { it[:websocket] == websocket }
+            if @rw_user == websocket
+              @rw_user = nil
+              @rw_last_input_at = nil
+            end
+          end
+          Superkick.logger.debug("attach:relay") { "User removed from #{@agent_id}" }
+        end
+
+        # --- Frame routing ---
+
+        # Handle a binary frame from the agent. Parses the frame type,
+        # updates history for OUTPUT, and broadcasts to all users.
+        def handle_agent_frame(data)
+          data = data.b if data.is_a?(String) && data.encoding != Encoding::BINARY
+          return if data.bytesize < 5
+
+          type = data.getbyte(0)
+
+          # Buffer OUTPUT frames in history for replay
+          if type == Superkick::Attach::Protocol::OUTPUT
+            payload_len = data[1, 4].unpack1("N")
+            payload = data[5, payload_len]
+            @history.write(payload) if payload
+          end
+
+          # Broadcast to all users
+          @mutex.synchronize do
+            @users.reject! do |user|
+              user[:websocket].send_binary(data)
+              false
+            rescue IOError, Errno::EPIPE, Errno::ECONNRESET
+              @rw_user = nil if @rw_user == user[:websocket]
+              true # remove disconnected user
+            end
+          end
+        end
+
+        # Handle a binary frame from a user. Parses the frame type and routes:
+        # - INPUT/RESIZE: forward to agent (RW user only)
+        # - COMMAND: handle mode switching locally
+        def handle_user_frame(websocket, data)
+          data = data.b if data.is_a?(String) && data.encoding != Encoding::BINARY
+          return if data.bytesize < 5
+
+          type = data.getbyte(0)
+
+          case type
+          when Superkick::Attach::Protocol::INPUT
+            @mutex.synchronize do
+              if @rw_user == websocket
+                @rw_last_input_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+                @agent_ws&.send_binary(data)
+              end
+              # Silently drop INPUT from non-RW users
+            end
+          when Superkick::Attach::Protocol::RESIZE
+            @mutex.synchronize do
+              @agent_ws&.send_binary(data) if @rw_user == websocket
+            end
+          when Superkick::Attach::Protocol::COMMAND
+            payload_len = data[1, 4].unpack1("N")
+            payload = data[5, payload_len]
+            cmd = Superkick::Attach::Protocol.decode_json(payload) if payload
+            handle_command(websocket, cmd) if cmd
+          end
+        end
+
+        # --- Lifecycle ---
+
+        def stop
+          @idle_check_thread&.kill
+        rescue ThreadError
+          nil
+        end
+
+        def user_count
+          @mutex.synchronize { @users.size }
+        end
+
+        def rw_user
+          @mutex.synchronize { @rw_user }
+        end
+
+        private
+
+        def handle_command(websocket, cmd)
+          case cmd[:action]
+          when "promote_rw"
+            @mutex.synchronize do
+              if @rw_user == websocket
+                notify_user(websocket, "Already in read-write mode")
+              elsif @rw_user
+                notify_user(websocket, "Read-write slot is occupied — use forced promotion to take over")
+              else
+                promote_user_locked(websocket)
+              end
+            end
+          when "force_promote_rw"
+            @mutex.synchronize do
+              if @rw_user == websocket
+                notify_user(websocket, "Already in read-write mode")
+              else
+                demote_rw_user_locked("Read-write taken over by another client") if @rw_user
+                promote_user_locked(websocket)
+              end
+            end
+          when "demote_ro"
+            @mutex.synchronize do
+              if @rw_user == websocket
+                @rw_user = nil
+                @rw_last_input_at = nil
+                entry = @users.find { it[:websocket] == websocket }
+                entry[:mode] = :ro if entry
+                notify_user(websocket, "Switched to read-only mode")
+              else
+                notify_user(websocket, "Already in read-only mode")
+              end
+            end
+          when "claim", "unclaim"
+            # Forward claim/unclaim to agent — these are control plane commands
+            @mutex.synchronize do
+              @agent_ws&.send_binary(Superkick::Attach::Protocol.build_frame(
+                Superkick::Attach::Protocol::COMMAND, JSON.generate(cmd)
+              ))
+            end
+          end
+        end
+
+        # Promote a user to RW. MUST be called while holding @mutex.
+        def promote_user_locked(websocket)
+          @rw_user = websocket
+          @rw_last_input_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          entry = @users.find { it[:websocket] == websocket }
+          entry[:mode] = :rw if entry
+          notify_user(websocket, "Promoted to read-write mode")
+        end
+
+        # Demote the current RW user. MUST be called while holding @mutex.
+        def demote_rw_user_locked(reason)
+          old = @rw_user
+          return unless old
+
+          @rw_user = nil
+          @rw_last_input_at = nil
+          entry = @users.find { it[:websocket] == old }
+          entry[:mode] = :ro if entry
+          notify_user(old, reason)
+        end
+
+        def notify_user(websocket, message)
+          frame = Superkick::Attach::Protocol.build_frame(
+            Superkick::Attach::Protocol::NOTIFY,
+            JSON.generate({message:})
+          )
+          websocket.send_binary(frame)
+        rescue IOError, Errno::EPIPE, Errno::ECONNRESET
+          nil
+        end
+
+        def start_idle_check
+          @idle_check_thread = Thread.new do
+            check_interval = [@rw_idle_timeout / 2.0, 30].min
+            loop do
+              sleep check_interval
+              @mutex.synchronize do
+                next unless @rw_user && @rw_last_input_at
+
+                elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @rw_last_input_at
+                if elapsed >= @rw_idle_timeout
+                  demote_rw_user_locked(
+                    "Demoted to read-only after #{@rw_idle_timeout.to_i}s of inactivity"
+                  )
+                end
+              end
+            rescue => e
+              Superkick.logger.error("attach:relay") { "Idle check error: #{e.message}" }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/superkick/hosted/attach/relay_store.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Hosted
+    module Attach
+      # Thread-safe registry of Attach::Relay instances, one per agent.
+      # Created at server startup in hosted mode. The hosted server wires
+      # WebSocket connections to relays via get_or_create on agent connect
+      # and remove on permanent disconnect.
+      class RelayStore
+        def initialize(config: {})
+          @config = config
+          @relays = {}
+          @mutex = Mutex.new
+        end
+
+        # Get or create a relay for the given agent.
+        def get_or_create(agent_id)
+          @mutex.synchronize do
+            @relays[agent_id] ||= Relay.new(agent_id:, config: @config)
+          end
+        end
+
+        # Get an existing relay (nil if none).
+        def get(agent_id)
+          @mutex.synchronize { @relays[agent_id] }
+        end
+
+        # Remove a relay when the agent disconnects permanently.
+        # Calls stop on the relay to clean up the idle timeout thread.
+        def remove(agent_id)
+          relay = @mutex.synchronize { @relays.delete(agent_id) }
+          relay&.stop
+          relay
+        end
+
+        # Iterate over all relays.
+        def each(&block)
+          @mutex.synchronize { @relays.each_value(&block) }
+        end
+
+        def size
+          @mutex.synchronize { @relays.size }
+        end
+      end
+    end
+  end
+end

data/lib/superkick/hosted/bridge.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Superkick
+  module Hosted
+    # Abstract base class for agent-side WebSocket bridges that connect local
+    # agent components to the hosted server over a persistent WebSocket.
+    #
+    # Provides the shared WebSocket lifecycle: TCP/TLS connect, auth handshake,
+    # read loop, and reconnection with exponential backoff. Subclasses override
+    # hook methods to handle channel-specific messages.
+    #
+    # Uses a simple raw WebSocket protocol (NOT ActionCable):
+    #   1. Client connects to a WebSocket endpoint
+    #   2. Client sends auth JSON text frame: {"type":"auth","agent_id":"...","api_key":"..."}
+    #   3. Server responds: {"type":"welcome"} or {"type":"error","message":"..."}
+    #   4. After auth, data frames flow (text or binary depending on channel)
+    #
+    # Subclasses implement:
+    #   - websocket_path  → URL path (e.g. "/api/v1/agents/#{@agent_id}/buffer/ws")
+    #   - channel_name    → log tag (e.g. "buffer:ws")
+    #   - handle_server_message(message) → process parsed JSON text messages
+    #   - handle_binary_message(data)    → process binary messages (optional)
+    #   - on_authenticated               → called after welcome (optional)
+    class Bridge
+      RECONNECT_DELAYS = [1, 2, 4, 8, 16, 30].freeze
+      PING_INTERVAL = 30 # seconds
+
+      def initialize(agent_id:, server_url:, api_key:)
+        @agent_id = agent_id
+        @server_url = server_url.chomp("/")
+        @api_key = api_key
+        @thread = nil
+        @stop = false
+        @reconnect_attempt = 0
+      end
+
+      def start
+        @stop = false
+        @thread = Thread.new { run_loop }
+        self
+      end
+
+      def stop
+        @stop = true
+        @driver&.close
+        @socket&.close
+        @thread&.join(5)
+      rescue IOError, Errno::EBADF
+        nil
+      end
+
+      private
+
+      # Subclass hooks — override as needed.
+
+      def websocket_path
+        raise NotImplementedError, "#{self.class} must implement #websocket_path"
+      end
+
+      def channel_name
+        raise NotImplementedError, "#{self.class} must implement #channel_name"
+      end
+
+      # Called for each parsed JSON text message after auth is complete.
+      def handle_server_message(message)
+      end
+
+      # Called for each binary WebSocket message. Override for binary channels.
+      def handle_binary_message(data)
+      end
+
+      # Called once after the server sends a welcome response.
+      def on_authenticated
+      end
+
+      # Sending helpers for subclasses.
+
+      def send_text(data)
+        return unless @driver
+
+        @driver.text(data)
+        flush_write_buffer
+      end
+
+      def send_binary(data)
+        return unless @driver
+
+        @driver.binary(data)
+        flush_write_buffer
+      end
+
+      # Internal lifecycle.
+
+      def run_loop
+        until @stop
+          connect_and_serve
+          break if @stop
+
+          delay = RECONNECT_DELAYS.fetch(@reconnect_attempt) { RECONNECT_DELAYS.last }
+          Superkick.logger.info(channel_name) { "Reconnecting in #{delay}s (attempt #{@reconnect_attempt + 1})..." }
+          sleep(delay)
+          @reconnect_attempt += 1
+        end
+      rescue => e
+        Superkick.logger.error(channel_name) { "WebSocket loop error: #{e.message}" }
+      end
+
+      def connect_and_serve
+        uri = URI.parse("#{@server_url}#{websocket_path}")
+        @socket = open_socket(uri)
+        @driver = create_driver(uri)
+
+        setup_driver_handlers
+        start_driver
+
+        # Send auth frame
+        authenticate
+
+        # Read loop — blocks until connection closes
+        read_loop
+
+        @reconnect_attempt = 0 # successful connection resets backoff
+      rescue Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::ETIMEDOUT,
+        Errno::EHOSTUNREACH, Errno::ENETUNREACH, IOError, OpenSSL::SSL::SSLError => e
+        Superkick.logger.warn(channel_name) { "Connection failed: #{e.message}" }
+      ensure
+        begin
+          @socket&.close
+        rescue IOError, Errno::EBADF
+          nil
+        end
+        @driver = nil
+        @socket = nil
+        @authenticated = false
+      end
+
+      def open_socket(uri)
+        default_port = (uri.scheme == "wss") ? 443 : 80
+        port = uri.port || default_port
+        tcp = TCPSocket.new(uri.host, port)
+
+        if uri.scheme == "wss"
+          require "openssl"
+          ctx = OpenSSL::SSL::SSLContext.new
+          ctx.set_params(verify_mode: OpenSSL::SSL::VERIFY_PEER)
+          ssl = OpenSSL::SSL::SSLSocket.new(tcp, ctx)
+          ssl.hostname = uri.host
+          ssl.connect
+          ssl
+        else
+          tcp
+        end
+      end
+
+      def create_driver(uri)
+        require "websocket/driver"
+
+        socket_wrapper = SocketWrapper.new(@socket, uri.to_s)
+        driver = WebSocket::Driver.client(socket_wrapper)
+        driver.set_header("Authorization", "Bearer #{@api_key}")
+        driver
+      end
+
+      def setup_driver_handlers
+        @authenticated = false
+
+        @driver.on :open do
+          Superkick.logger.info(channel_name) { "WebSocket connected for #{@agent_id}" }
+        end
+
+        @driver.on :message do |event|
+          dispatch_text_message(event.data)
+        end
+
+        @driver.on :binary do |event|
+          handle_binary_message(event.data)
+        end
+
+        @driver.on :close do
+          Superkick.logger.info(channel_name) { "WebSocket closed for #{@agent_id}" }
+        end
+
+        @driver.on :error do |event|
+          Superkick.logger.error(channel_name) { "WebSocket error: #{event.message}" }
+        end
+      end
+
+      def start_driver
+        @driver.start
+        flush_write_buffer
+      end
+
+      def authenticate
+        auth = {type: "auth", agent_id: @agent_id, api_key: @api_key}
+        send_text(JSON.generate(auth))
+      end
+
+      def read_loop
+        until @stop
+          data = begin
+            @socket.read_nonblock(4096)
+          rescue IO::WaitReadable
+            IO.select([@socket], nil, nil, PING_INTERVAL)
+            retry unless @stop
+            break
+          rescue IOError, Errno::ECONNRESET, Errno::EBADF
+            break
+          end
+
+          break unless data && !data.empty?
+
+          @driver.parse(data)
+          flush_write_buffer
+        end
+      end
+
+      def dispatch_text_message(data)
+        message = JSON.parse(data, symbolize_names: true)
+
+        case message[:type]
+        when "welcome"
+          @authenticated = true
+          Superkick.logger.info(channel_name) { "Authenticated for #{@agent_id}" }
+          on_authenticated
+        when "error"
+          Superkick.logger.error(channel_name) { "Server error: #{message[:message]}" }
+        when "ping"
+          send_text(JSON.generate({type: "pong"}))
+        when "disconnect"
+          Superkick.logger.info(channel_name) { "Server requested disconnect: #{message[:reason]}" }
+        else
+          handle_server_message(message) if @authenticated
+        end
+      rescue JSON::ParserError => e
+        Superkick.logger.warn(channel_name) { "Invalid JSON from server: #{e.message}" }
+      end
+
+      def flush_write_buffer
+        # websocket-driver writes to the SocketWrapper, which writes directly
+      end
+
+      # Minimal wrapper that websocket-driver requires.
+      # Must respond to #url and #write.
+      class SocketWrapper
+        attr_reader :url
+
+        def initialize(socket, url)
+          @socket = socket
+          @url = url
+        end
+
+        def write(data)
+          @socket.write(data)
+          @socket.flush
+        rescue IOError, Errno::EPIPE, Errno::ECONNRESET
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/superkick/hosted/buffer/bridge.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Hosted
+    module Buffer
+      # Agent-side bridge that connects the local Buffer::Server to the hosted
+      # server over a persistent WebSocket. Commands from the server
+      # (enqueue_injection, idle_state, etc.) arrive as JSON text frames and are
+      # dispatched to the local Buffer::Server command handlers. Responses flow
+      # back the same way.
+      #
+      # Subclass of Superkick::Hosted::Bridge — inherits the WebSocket lifecycle,
+      # auth handshake, read loop, and reconnection with exponential backoff.
+      class Bridge < Superkick::Hosted::Bridge
+        def initialize(agent_id:, server_url:, api_key:, command_handler:)
+          super(agent_id:, server_url:, api_key:)
+          @command_handler = command_handler
+        end
+
+        private
+
+        def websocket_path
+          "/api/v1/agents/#{@agent_id}/buffer/ws"
+        end
+
+        def channel_name
+          "buffer:ws"
+        end
+
+        def handle_server_message(message)
+          response = @command_handler.call(message)
+
+          # If the command had a request_id, send the response back
+          if message[:request_id] && response
+            response[:request_id] = message[:request_id]
+            send_text(JSON.generate(response))
+          end
+        end
+      end
+    end
+  end
+end