ruby-utcp 1.1.0

data/lib/utcp/protocols/tcp.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module UTCP
+  class TCPProtocol < CommunicationProtocol
+    include SocketSupport
+
+    def initialize(socket_factory: nil)
+      @socket_factory = socket_factory || lambda do |host, port, timeout|
+        Socket.tcp(host, port, connect_timeout: timeout)
+      end
+    end
+
+    def register_manual(client, template)
+      assert_template!(template)
+      response = exchange(template, JSON.generate("type" => "utcp"))
+      success(template, manual_from_payload(template, response, source: "TCP discovery response"))
+    rescue StandardError => error
+      client.logger.warn("Unable to register TCP manual #{template.name.inspect}: #{error.message}")
+      failure(template, error)
+    end
+
+    def call_tool(_client, tool_name, tool_args, template)
+      assert_template!(template)
+      exchange(template, format_socket_message(template, tool_args))
+    rescue Error
+      raise
+    rescue StandardError => error
+      raise ToolCallError.new("TCP tool #{tool_name.inspect} failed: #{error.message}", tool_name: tool_name)
+    end
+
+    private
+
+    def assert_template!(template)
+      return if template.is_a?(TcpCallTemplate)
+
+      raise ValidationError, "TCP protocol requires a TcpCallTemplate"
+    end
+
+    def exchange(template, message)
+      timeout = socket_timeout_seconds(template)
+      socket = @socket_factory.call(template.host, template.port, timeout)
+      socket.write(frame_message(message.to_s.b, template))
+      payload = read_framed(socket, template, timeout)
+      decode_socket_payload(payload, template.response_byte_format)
+    rescue Timeout::Error, Errno::ETIMEDOUT => error
+      raise TimeoutError, "TCP request timed out: #{error.message}"
+    rescue Error
+      raise
+    rescue SocketError, IOError, SystemCallError => error
+      raise ToolCallError, "TCP request failed: #{error.message}"
+    ensure
+      socket.close if socket && !socket.closed?
+    end
+
+    def frame_message(message, template)
+      case template.framing_strategy
+      when "length_prefix"
+        pack = {
+          [1, "big"] => "C", [1, "little"] => "C",
+          [2, "big"] => "n", [2, "little"] => "v",
+          [4, "big"] => "N", [4, "little"] => "V",
+          [8, "big"] => "Q>", [8, "little"] => "Q<"
+        }.fetch([template.length_prefix_bytes, template.length_prefix_endian])
+        [message.bytesize].pack(pack) + message
+      when "delimiter"
+        message + escaped_delimiter(template.message_delimiter, template.interpret_escape_sequences)
+      else
+        message
+      end
+    end
+
+    def read_framed(socket, template, timeout)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      case template.framing_strategy
+      when "length_prefix"
+        prefix = read_exact(socket, template.length_prefix_bytes, deadline)
+        unpack = {
+          [1, "big"] => "C", [1, "little"] => "C",
+          [2, "big"] => "n", [2, "little"] => "v",
+          [4, "big"] => "N", [4, "little"] => "V",
+          [8, "big"] => "Q>", [8, "little"] => "Q<"
+        }.fetch([template.length_prefix_bytes, template.length_prefix_endian])
+        length = prefix.unpack1(unpack)
+        raise ToolCallError, "TCP response exceeds max_response_size" if length > template.max_response_size
+
+        read_exact(socket, length, deadline)
+      when "delimiter"
+        read_until(socket, escaped_delimiter(template.message_delimiter, template.interpret_escape_sequences),
+                   template.max_response_size, deadline)
+      when "fixed_length"
+        read_exact(socket, template.fixed_message_length, deadline)
+      when "stream"
+        read_stream(socket, template.max_response_size, deadline)
+      end
+    end
+
+    def read_exact(socket, length, deadline)
+      result = +"".b
+      while result.bytesize < length
+        wait_readable!(socket, deadline, "TCP read")
+        chunk = socket.readpartial(length - result.bytesize)
+        raise ToolCallError, "TCP connection closed before the complete response" if chunk.nil? || chunk.empty?
+
+        result << chunk
+      end
+      result
+    rescue EOFError
+      raise ToolCallError, "TCP connection closed before the complete response"
+    end
+
+    def read_until(socket, delimiter, maximum, deadline)
+      raise ValidationError, "message_delimiter cannot be empty" if delimiter.empty?
+
+      result = +"".b
+      until result.end_with?(delimiter)
+        raise ToolCallError, "TCP response exceeds max_response_size" if result.bytesize >= maximum
+
+        wait_readable!(socket, deadline, "TCP read")
+        result << socket.readpartial([4096, maximum - result.bytesize].min)
+      end
+      result.byteslice(0, result.bytesize - delimiter.bytesize)
+    rescue EOFError
+      raise ToolCallError, "TCP connection closed before the message delimiter"
+    end
+
+    def read_stream(socket, maximum, deadline)
+      result = +"".b
+      while result.bytesize < maximum
+        remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        break unless remaining.positive? && IO.select([socket], nil, nil, remaining)
+
+        begin
+          result << socket.readpartial([4096, maximum - result.bytesize].min)
+        rescue EOFError
+          break
+        end
+      end
+      result
+    end
+  end
+  TcpCommunicationProtocol = TCPProtocol
+  TCPCommunicationProtocol = TCPProtocol
+end

data/lib/utcp/protocols/text.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module UTCP
+  class TextProtocol < CommunicationProtocol
+    def register_manual(client, template)
+      assert_template!(template)
+      data = Utils.parse_document(template.content, source: "text manual")
+      manual = if openapi?(data)
+                 OpenAPIConverter.new(
+                   data,
+                   spec_url: "text://content",
+                   call_template_name: template.name,
+                   auth_tools: template.auth_tools,
+                   base_url: template.base_url
+                 ).convert
+               else
+                 Manual.from_h(data)
+               end
+      success(template, manual)
+    rescue StandardError => error
+      client.logger.warn("Unable to register text manual #{template.name.inspect}: #{error.message}")
+      failure(template, error)
+    end
+
+    def call_tool(_client, _tool_name, _tool_args, template)
+      assert_template!(template)
+      template.content
+    end
+
+    private
+
+    def assert_template!(template)
+      return if template.is_a?(TextCallTemplate)
+
+      raise ValidationError, "text protocol requires a TextCallTemplate"
+    end
+
+    def openapi?(data)
+      data.is_a?(Hash) && (data.key?("openapi") || data.key?("swagger") || data.key?("paths"))
+    end
+  end
+  TextCommunicationProtocol = TextProtocol
+end
+

data/lib/utcp/protocols/udp.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module UTCP
+  class UDPProtocol < CommunicationProtocol
+    include SocketSupport
+
+    def initialize(socket_factory: nil)
+      @socket_factory = socket_factory || -> { UDPSocket.new }
+    end
+
+    def register_manual(client, template)
+      assert_template!(template)
+      response = exchange(template, JSON.generate("type" => "utcp"), response_count: 1)
+      success(template, manual_from_payload(template, response, source: "UDP discovery response"))
+    rescue StandardError => error
+      client.logger.warn("Unable to register UDP manual #{template.name.inspect}: #{error.message}")
+      failure(template, error)
+    end
+
+    def call_tool(_client, tool_name, tool_args, template)
+      assert_template!(template)
+      exchange(template, format_socket_message(template, tool_args),
+               response_count: template.number_of_response_datagrams)
+    rescue Error
+      raise
+    rescue StandardError => error
+      raise ToolCallError.new("UDP tool #{tool_name.inspect} failed: #{error.message}", tool_name: tool_name)
+    end
+
+    private
+
+    def assert_template!(template)
+      return if template.is_a?(UdpCallTemplate)
+
+      raise ValidationError, "UDP protocol requires a UdpCallTemplate"
+    end
+
+    def exchange(template, message, response_count:)
+      socket = @socket_factory.call
+      socket.connect(template.host, template.port)
+      socket.write(message.to_s.b)
+      return nil if response_count.zero?
+
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + socket_timeout_seconds(template)
+      values = response_count.times.map do
+        wait_readable!(socket, deadline, "UDP read")
+        payload = socket.recv(65_535)
+        decode_socket_payload(payload, template.response_byte_format)
+      end
+      values.length == 1 ? values.first : values
+    rescue Error
+      raise
+    rescue SocketError, IOError, SystemCallError => error
+      raise ToolCallError, "UDP request failed: #{error.message}"
+    ensure
+      socket.close if socket && !socket.closed?
+    end
+  end
+  UdpCommunicationProtocol = UDPProtocol
+  UDPCommunicationProtocol = UDPProtocol
+end

data/lib/utcp/protocols/webrtc.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+module UTCP
+  class WebRTCPeer
+    def initialize(template)
+      gem "webrtc-ruby", ">= 1.0.0"
+      require "webrtc"
+      WebRTC.init
+      @template = template
+      @mutex = Mutex.new
+      @condition = ConditionVariable.new
+      @responses = {}
+      @candidates = []
+      configuration = template.ice_servers.empty? ? nil : { ice_servers: template.ice_servers }
+      @connection = WebRTC::RTCPeerConnection.new(configuration)
+      install_candidate_handler
+      @channel = @connection.create_data_channel(template.data_channel_name)
+      install_channel_handlers
+    rescue LoadError => error
+      raise MissingDependencyError,
+            "WebRTC requires the optional 'webrtc-ruby' gem and libdatachannel: #{error.message}"
+    end
+
+    def connect
+      offer = @connection.create_offer.await
+      @connection.set_local_description(offer).await
+      wait_for_ice_gathering
+      response = post_json("connect", "peer_id" => @template.peer_id, "sdp" => @connection.local_description.sdp)
+      answer = WebRTC::RTCSessionDescription.new(type: :answer, sdp: response.fetch("sdp"))
+      @connection.set_remote_description(answer).await
+      Array(response["candidates"]).each do |candidate|
+        @connection.add_ice_candidate(WebRTC::RTCIceCandidate.new(Utils.symbolize_keys(candidate))).await
+      rescue StandardError
+        nil
+      end
+      @candidates.each { |candidate| post_candidate(candidate) }
+      wait_for_channel
+      response
+    end
+
+    def request(payload, timeout: @template.timeout)
+      identifier = payload.fetch("id")
+      @channel.send_text(JSON.generate(payload))
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      @mutex.synchronize do
+        until @responses.key?(identifier)
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          raise TimeoutError, "WebRTC response timed out" unless remaining.positive?
+          @condition.wait(@mutex, remaining)
+        end
+        @responses.delete(identifier)
+      end
+    end
+
+    def close
+      @channel.close if @channel
+      @channel.destroy if @channel&.respond_to?(:destroy)
+      @connection.close if @connection
+    rescue StandardError
+      nil
+    end
+
+    private
+
+    def install_candidate_handler
+      @connection.on_ice_candidate do |candidate|
+        @mutex.synchronize { @candidates << candidate } if candidate
+      end
+    end
+
+    def install_channel_handlers
+      @channel_open = false
+      @channel.on_open do
+        @mutex.synchronize do
+          @channel_open = true
+          @condition.broadcast
+        end
+      end
+      @channel.on_message do |message|
+        envelope = JSON.parse(message.data)
+        identifier = envelope["id"]
+        @mutex.synchronize do
+          @responses[identifier] = envelope.key?("result") ? envelope["result"] : envelope
+          @condition.broadcast
+        end
+      rescue JSON::ParserError
+        nil
+      end
+    end
+
+    def wait_for_ice_gathering
+      return unless @connection.respond_to?(:on_ice_gathering_state_change)
+
+      complete = @connection.ice_gathering_state == :complete
+      @connection.on_ice_gathering_state_change do
+        @mutex.synchronize do
+          complete = @connection.ice_gathering_state == :complete
+          @condition.broadcast if complete
+        end
+      end
+      wait_for_flag(@template.timeout) { complete }
+    rescue TimeoutError
+      # Trickle ICE remains valid when a backend does not expose a reliable gathering event.
+      nil
+    end
+
+    def wait_for_channel
+      wait_for_flag(@template.timeout) { @channel_open || @channel.ready_state == :open }
+    end
+
+    def wait_for_flag(timeout)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      @mutex.synchronize do
+        until yield
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          raise TimeoutError, "WebRTC connection timed out" unless remaining.positive?
+          @condition.wait(@mutex, remaining)
+        end
+      end
+    end
+
+    def post_candidate(candidate)
+      value = candidate.respond_to?(:to_h) ? candidate.to_h : candidate
+      post_json("candidate", "peer_id" => @template.peer_id, "candidate" => value)
+    rescue StandardError
+      nil
+    end
+
+    def post_json(path, payload)
+      url = "#{@template.signaling_server.sub(%r{/+\z}, "")}/#{path}"
+      uri = URLSecurity.validate!(url, context: "WebRTC signaling")
+      request = Net::HTTP::Post.new(uri.request_uri)
+      request["Content-Type"] = "application/json"
+      request.body = JSON.generate(payload)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.verify_mode = OpenSSL::SSL::VERIFY_PEER if http.use_ssl?
+      http.open_timeout = [@template.timeout, 10].min
+      http.read_timeout = @template.timeout
+      response = http.start { |connection| connection.request(request) }
+      unless response.code.to_i.between?(200, 299)
+        raise ToolCallError.new("WebRTC signaling failed with status #{response.code}",
+                                status: response.code.to_i, response_body: response.body)
+      end
+      response.body.to_s.empty? ? {} : JSON.parse(response.body)
+    rescue JSON::ParserError => error
+      raise SerializerValidationError, "Invalid WebRTC signaling response: #{error.message}"
+    end
+  end
+
+  class WebRTCProtocol < CommunicationProtocol
+    def initialize(peer_factory: nil)
+      @peer_factory = peer_factory || ->(template) { WebRTCPeer.new(template) }
+      @peers = {}
+      @mutex = Mutex.new
+    end
+
+    def register_manual(client, template)
+      assert_webrtc_template!(template)
+      response = peer_for(template).connect
+      payload = if response.is_a?(Hash) && response.key?("tools") && !response.key?("utcp_version")
+                  {
+                    "utcp_version" => VERSION,
+                    "manual_version" => "1.0.0",
+                    "tools" => response["tools"]
+                  }
+                else
+                  response
+                end
+      success(template, manual_from_payload(template, payload, source: "WebRTC signaling response"))
+    rescue StandardError => error
+      client.logger.warn("Unable to register WebRTC manual #{template.name.inspect}: #{error.message}")
+      failure(template, error)
+    end
+
+    def deregister_manual(_client, template)
+      peer = @mutex.synchronize { @peers.delete(peer_key(template)) }
+      peer&.close
+      nil
+    end
+
+    def call_tool(_client, tool_name, tool_args, template)
+      assert_webrtc_template!(template)
+      identifier = SecureRandom.uuid
+      peer_for(template).request(
+        {
+          "id" => identifier,
+          "tool" => tool_name.to_s.split(".").last,
+          "args" => Utils.stringify_keys(tool_args || {})
+        },
+        timeout: template.timeout
+      )
+    rescue Error
+      raise
+    rescue StandardError => error
+      raise ToolCallError.new("WebRTC tool #{tool_name.inspect} failed: #{error.message}", tool_name: tool_name)
+    end
+
+    private
+
+    def assert_webrtc_template!(template)
+      return if template.is_a?(WebRtcCallTemplate)
+
+      raise ValidationError, "WebRTC protocol requires a WebRtcCallTemplate"
+    end
+
+    def peer_for(template)
+      @mutex.synchronize { @peers[peer_key(template)] ||= @peer_factory.call(template) }
+    end
+
+    def peer_key(template)
+      [template.name, template.signaling_server, template.peer_id, template.data_channel_name].join("\0")
+    end
+  end
+  WebrtcCommunicationProtocol = WebRTCProtocol
+  WebRTCCommunicationProtocol = WebRTCProtocol
+end