rspec-agents 0.1.0

data/lib/async_workers/managed_process.rb

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+
+require "async"
+require_relative "errors"
+require_relative "channel_config"
+require_relative "output_stream"
+require_relative "rpc_channel"
+require_relative "transport/stdio_transport"
+require_relative "transport/unix_socket_transport"
+
+module AsyncWorkers
+  # Wraps a single child process with lifecycle management and communication.
+  # Provides process spawning, RPC communication, output streaming, and health monitoring.
+  #
+  # @example Basic usage with RPC
+  #   Async do |task|
+  #     process = ManagedProcess.new(
+  #       command: ['ruby', 'worker.rb'],
+  #       rpc: ChannelConfig.stdio_rpc
+  #     )
+  #
+  #     process.stderr.on_data { |line| puts "[worker] #{line}" }
+  #     process.start(task: task)
+  #
+  #     result = process.rpc.request({ action: 'compute', x: 42 })
+  #     process.stop
+  #   end
+  #
+  class ManagedProcess
+    # @return [Integer, nil] Process ID
+    attr_reader :pid
+
+    # @return [Symbol] :pending, :running, :stopping, :exited
+    attr_reader :status
+
+    # @return [Process::Status, nil] Exit status (nil until exited)
+    attr_reader :exit_status
+
+    # @return [RpcChannel, nil] RPC channel (nil if no_rpc)
+    attr_reader :rpc
+
+    # @return [OutputStream] stderr line stream
+    attr_reader :stderr
+
+    # @return [OutputStream] stdout line stream (empty if stdio_rpc mode)
+    attr_reader :stdout
+
+    # @param command [Array<String>] Command to execute
+    # @param env [Hash] Environment variables
+    # @param chdir [String, nil] Working directory for the process
+    # @param rpc [ChannelConfig] RPC configuration
+    # @param health_check_interval [Numeric] Health polling interval in seconds
+    def initialize(command:, env: {}, chdir: nil, rpc: ChannelConfig.no_rpc, health_check_interval: 0.5)
+      @command    = command
+      @env        = env
+      @chdir      = chdir
+      @rpc_config = rpc
+      @health_check_interval = health_check_interval
+
+      @status         = :pending
+      @pid            = nil
+      @exit_status    = nil
+      @transport      = nil
+      @rpc            = nil
+      @stderr         = OutputStream.new
+      @stdout         = OutputStream.new
+      @exit_callbacks = []
+      @exit_condition = nil
+      @exited_mutex   = Mutex.new
+    end
+
+    # Spawn process and begin monitoring.
+    # @param task [Async::Task] Parent async task
+    def start(task:)
+      raise "Process already started" unless @status == :pending
+
+      @exit_condition = Async::Condition.new
+
+      # Create appropriate transport
+      @transport = create_transport
+      @pid       = @transport.spawn
+      @status    = :running
+
+      # Set up RPC if enabled
+      if @rpc_config.rpc_enabled?
+        @rpc = RpcChannel.new(@transport)
+        @rpc.start(task: task)
+      end
+
+      # Start output readers
+      start_output_readers(task)
+
+      # Start health monitor
+      start_health_monitor(task)
+    end
+
+    # Graceful shutdown: RPC shutdown -> SIGTERM -> SIGKILL.
+    # @param timeout [Numeric] Total timeout for shutdown
+    def stop(timeout: 5)
+      return if @status == :exited
+
+      @status      = :stopping
+      half_timeout = timeout / 2.0
+
+      # Step 1: RPC shutdown request
+      if @rpc && !@rpc.closed?
+        @rpc.shutdown(timeout: half_timeout)
+      end
+
+      # Step 2: Wait for process to exit after RPC shutdown, or send SIGTERM
+      if alive?
+        begin
+          wait(timeout: half_timeout)
+        rescue Async::TimeoutError
+          # Process didn't exit after RPC shutdown, send SIGTERM
+          send_signal(:TERM)
+          begin
+            wait(timeout: half_timeout)
+          rescue Async::TimeoutError
+            # Continue to SIGKILL
+          end
+        end
+      end
+
+      # Step 3: SIGKILL if still alive
+      if alive?
+        send_signal(:KILL)
+        wait
+      end
+
+      # Ensure we have exit status if process exited but health monitor hasn't run
+      collect_exit_status_if_needed
+
+      cleanup
+    end
+
+    # Immediate SIGKILL.
+    def kill
+      return unless alive?
+      send_signal(:KILL)
+      wait
+      cleanup
+    end
+
+    # Send arbitrary signal to the process.
+    # @param signal [Symbol, Integer] Signal to send (e.g., :TERM, :KILL, 9)
+    def send_signal(signal)
+      return unless @pid && alive?
+      Process.kill(signal, @pid)
+    rescue Errno::ESRCH
+      # Process already gone
+    end
+
+    # Check if process is running.
+    # @return [Boolean]
+    def alive?
+      return false unless @pid
+      Process.kill(0, @pid)
+      true
+    rescue Errno::ESRCH, Errno::EPERM
+      false
+    end
+
+    # Block (yield fiber) until process exits.
+    # @param timeout [Numeric, nil] Optional timeout in seconds
+    # @return [Process::Status] Exit status
+    # @raise [Async::TimeoutError] If timeout exceeded
+    def wait(timeout: nil)
+      return @exit_status if @status == :exited
+
+      if timeout
+        Async::Task.current.with_timeout(timeout) { @exit_condition.wait }
+      else
+        @exit_condition.wait
+      end
+
+      @exit_status
+    end
+
+    # Register exit callback.
+    # @yield [Process::Status] Called when process exits
+    def on_exit(&block)
+      @exit_callbacks << block
+    end
+
+    private
+
+    def create_transport
+      case @rpc_config.mode
+      when :stdio_rpc
+        Transport::StdioTransport.new(command: @command, env: @env, chdir: @chdir)
+      when :unix_socket_rpc
+        Transport::UnixSocketTransport.new(command: @command, env: @env, chdir: @chdir)
+      when :no_rpc
+        Transport::StdioTransport.new(command: @command, env: @env, chdir: @chdir)
+      end
+    end
+
+    def start_output_readers(task)
+      # Always read stderr
+      task.async do
+        while (line = @transport.stderr_reader.gets)
+          @stderr.emit(line.chomp)
+        end
+      rescue IOError
+        # Stream closed
+      ensure
+        @stderr.close
+      end
+
+      # Read stdout if not used for RPC (unix_socket or no_rpc mode)
+      unless @rpc_config.stdio?
+        stdout_reader = @transport.respond_to?(:stdout_reader) ? @transport.stdout_reader : nil
+        if stdout_reader
+          task.async do
+            while (line = stdout_reader.gets)
+              @stdout.emit(line.chomp)
+            end
+          rescue IOError
+            # Stream closed
+          ensure
+            @stdout.close
+          end
+        end
+      end
+    end
+
+    def start_health_monitor(task)
+      task.async do
+        loop do
+          sleep(@health_check_interval)
+
+          # Check if process is still alive
+          unless alive?
+            # Process has exited, collect status via transport
+            @exit_status = @transport&.wait_for_exit
+            handle_exit
+            break
+          end
+        end
+      end
+    end
+
+    def handle_exit
+      # Use mutex to ensure we only handle exit once
+      already_exited = @exited_mutex.synchronize do
+        was_exited = @status == :exited
+        @status = :exited unless was_exited
+        was_exited
+      end
+      return if already_exited
+
+      @rpc&.close
+      @transport&.close
+
+      @exit_condition.signal(@exit_status)
+
+      @exit_callbacks.each do |cb|
+        cb.call(@exit_status)
+      rescue => e
+        warn "[AsyncWorkers::ManagedProcess] Exit callback error: #{e.class}: #{e.message}"
+      end
+    end
+
+    def cleanup
+      @rpc&.close
+      @transport&.close
+      @stderr.close
+      @stdout.close
+      @exited_mutex.synchronize { @status = :exited }
+    end
+
+    def collect_exit_status_if_needed
+      return if @exit_status
+
+      # Use transport's wait_for_exit which handles process reaping properly
+      status = @transport&.wait_for_exit
+      if status
+        @exit_status = status
+        handle_exit
+      end
+    end
+  end
+end

data/lib/async_workers/output_stream.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module AsyncWorkers
+  # Unified callback and iterator interface for streaming data.
+  # Thread-safe, supports multiple callbacks and blocking iteration.
+  #
+  # @example Callback style
+  #   stream.on_data { |item| puts item }
+  #
+  # @example Iterator style (blocking, use in dedicated task)
+  #   stream.each { |item| puts item }
+  #
+  # @example Enumerable
+  #   stream.each.take(10)
+  #
+  class OutputStream
+    include Enumerable
+
+    def initialize
+      @callbacks = []
+      @mutex     = Mutex.new
+      @queue     = Thread::Queue.new
+      @closed    = false
+    end
+
+    # Register callback for incoming data.
+    # Multiple callbacks can be registered and will all be called.
+    #
+    # @yield [item] Block called for each item
+    # @return [self]
+    def on_data(&block)
+      @mutex.synchronize { @callbacks << block }
+      self
+    end
+
+    # Blocking iterator - yields until stream closes.
+    # Use in a dedicated async task to avoid blocking other operations.
+    #
+    # @yield [item] Block called for each item
+    # @return [Enumerator] if no block given
+    def each
+      return enum_for(:each) unless block_given?
+
+      loop do
+        item = @queue.pop
+        break if item.equal?(CLOSED_SENTINEL)
+        yield item
+      end
+    end
+
+    # Check if stream is closed
+    # @return [Boolean]
+    def closed?
+      @closed
+    end
+
+    # @api private
+    # Emit item to all callbacks and the iterator queue
+    def emit(item)
+      return if @closed
+
+      callbacks = @mutex.synchronize { @callbacks.dup }
+      callbacks.each do |cb|
+        cb.call(item)
+      rescue => e
+        warn "[AsyncWorkers::OutputStream] Callback error: #{e.class}: #{e.message}"
+      end
+
+      @queue.push(item)
+    end
+
+    # @api private
+    # Close the stream, signaling iterators to stop
+    def close
+      return if @closed
+      @closed = true
+      @queue.push(CLOSED_SENTINEL)
+    end
+
+    private
+
+    # Sentinel object to signal stream closure
+    CLOSED_SENTINEL = Object.new.freeze
+    private_constant :CLOSED_SENTINEL
+  end
+end

data/lib/async_workers/rpc_channel.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "async"
+require_relative "errors"
+require_relative "output_stream"
+
+module AsyncWorkers
+  # JSON-RPC message framing and request/response correlation.
+  # Handles bidirectional communication with newline-delimited JSON.
+  class RpcChannel
+    SHUTDOWN_ACTION = "__shutdown__"
+
+    # @return [OutputStream] Incoming notifications (messages without reply_to)
+    attr_reader :notifications
+
+    # @param transport [Transport::Base] Underlying transport
+    def initialize(transport)
+      @transport        = transport
+      @pending_requests = {}
+      @mutex            = Mutex.new
+      @closed           = false
+      @notifications    = OutputStream.new
+      @reader_task      = nil
+    end
+
+    # Start the reader task to process incoming messages.
+    # Must be called after the process is started.
+    # @param task [Async::Task] Parent task
+    def start(task:)
+      @reader_task = task.async { reader_loop }
+    end
+
+    # Send request and wait for response.
+    # @param payload [Hash] Request payload
+    # @param timeout [Numeric, nil] Optional timeout in seconds
+    # @return [Hash] Response payload
+    # @raise [ChannelClosedError] If channel is closed
+    # @raise [Async::TimeoutError] If timeout exceeded
+    def request(payload, timeout: nil)
+      raise ChannelClosedError, "Channel closed" if @closed
+
+      id = SecureRandom.uuid
+      condition = Async::Condition.new
+
+      @mutex.synchronize do
+        @pending_requests[id] = { condition: condition, response: nil }
+      end
+
+      send_message(payload.merge(id: id))
+
+      begin
+        if timeout
+          Async::Task.current.with_timeout(timeout) { condition.wait }
+        else
+          condition.wait
+        end
+      rescue Async::TimeoutError
+        @mutex.synchronize { @pending_requests.delete(id) }
+        raise
+      end
+
+      entry = @mutex.synchronize { @pending_requests.delete(id) }
+      response = entry&.fetch(:response, nil)
+      raise ChannelClosedError, "Channel closed while waiting" if response.nil? && @closed
+
+      response
+    end
+
+    # Send fire-and-forget notification.
+    # @param payload [Hash] Notification payload (should not have id field)
+    def notify(payload)
+      raise ChannelClosedError, "Channel closed" if @closed
+      send_message(payload.reject { |k, _| k == :id || k == "id" })
+    end
+
+    # Request graceful shutdown via protocol.
+    # Sends __shutdown__ action and waits for acknowledgment.
+    # @param timeout [Numeric] Timeout for shutdown acknowledgment
+    # @return [Hash, nil] Shutdown response or nil on timeout
+    def shutdown(timeout: 5)
+      return nil if @closed
+
+      begin
+        request({ action: SHUTDOWN_ACTION }, timeout: timeout)
+      rescue Async::TimeoutError
+        nil
+      end
+    end
+
+    # Register callback for notifications (convenience method).
+    # @yield [Hash] Notification payload
+    def on_notification(&block)
+      @notifications.on_data(&block)
+    end
+
+    # Check if channel is closed.
+    # @return [Boolean]
+    def closed?
+      @closed
+    end
+
+    # Close the channel.
+    # Signals all pending requests and stops the reader.
+    def close
+      return if @closed
+      @closed = true
+
+      # Signal all pending requests so they don't hang
+      @mutex.synchronize do
+        @pending_requests.each_value do |pending|
+          pending[:condition].signal
+        end
+        @pending_requests.clear
+      end
+
+      @notifications.close
+      @reader_task&.stop
+    end
+
+    private
+
+    def send_message(payload)
+      @transport.write_line(payload.to_json)
+    end
+
+    def reader_loop
+      while (line = @transport.read_line)
+        begin
+          message = JSON.parse(line, symbolize_names: true)
+          handle_incoming(message)
+        rescue JSON::ParserError => e
+          warn "[AsyncWorkers::RpcChannel] JSON parse error: #{e.message}"
+        end
+      end
+    rescue IOError, Errno::EPIPE, Errno::ECONNRESET
+      # Transport closed
+    ensure
+      close
+    end
+
+    def handle_incoming(message)
+      if message[:reply_to]
+        # Response to a request
+        @mutex.synchronize do
+          pending = @pending_requests[message[:reply_to]]
+          if pending
+            pending[:response] = message
+            pending[:condition].signal
+          end
+        end
+      else
+        # Notification (no reply_to field)
+        @notifications.emit(message)
+      end
+    end
+  end
+end

data/lib/async_workers/transport/base.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module AsyncWorkers
+  module Transport
+    # Abstract base class for transport implementations.
+    # Transports handle raw I/O for RPC messages.
+    class Base
+      # Spawn the child process
+      # @return [Integer] Process ID
+      def spawn
+        raise NotImplementedError, "#{self.class}#spawn must be implemented"
+      end
+
+      # Send a line to the transport (without newline)
+      # @param line [String] Line to send
+      def write_line(line)
+        raise NotImplementedError, "#{self.class}#write_line must be implemented"
+      end
+
+      # Read a line from the transport
+      # @return [String, nil] Line read (without newline) or nil on EOF
+      def read_line
+        raise NotImplementedError, "#{self.class}#read_line must be implemented"
+      end
+
+      # Get the stderr reader IO for log capture
+      # @return [IO]
+      def stderr_reader
+        raise NotImplementedError, "#{self.class}#stderr_reader must be implemented"
+      end
+
+      # Close the transport
+      def close
+        raise NotImplementedError, "#{self.class}#close must be implemented"
+      end
+
+      # Check if transport is closed
+      # @return [Boolean]
+      def closed?
+        raise NotImplementedError, "#{self.class}#closed? must be implemented"
+      end
+
+      # Get the process ID
+      # @return [Integer, nil]
+      def pid
+        raise NotImplementedError, "#{self.class}#pid must be implemented"
+      end
+
+      # Wait for the process to exit and return exit status.
+      # This is a blocking call.
+      # @return [Process::Status]
+      def wait_for_exit
+        raise NotImplementedError, "#{self.class}#wait_for_exit must be implemented"
+      end
+    end
+  end
+end

data/lib/async_workers/transport/stdio_transport.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "open3"
+require_relative "base"
+require_relative "../errors"
+
+module AsyncWorkers
+  module Transport
+    # Transport over stdin/stdout using Open3.popen3.
+    # RPC messages go over stdin (write) and stdout (read).
+    # Stderr is available separately for log capture.
+    class StdioTransport < Base
+      attr_reader :wait_thread
+
+      # @param command [Array<String>] Command to execute
+      # @param env [Hash] Environment variables
+      # @param chdir [String, nil] Working directory for the process
+      def initialize(command:, env: {}, chdir: nil)
+        @command     = command
+        @env         = env
+        @chdir       = chdir
+        @closed      = false
+        @stdin       = nil
+        @stdout      = nil
+        @stderr      = nil
+        @wait_thread = nil
+      end
+
+      # Spawn the process using Open3.popen3
+      # @return [Integer] PID
+      def spawn
+        spawn_opts = {}
+        spawn_opts[:chdir] = @chdir if @chdir
+
+        @stdin, @stdout, @stderr, @wait_thread = Open3.popen3(@env, *@command, **spawn_opts)
+
+        # Enable sync for proper fiber scheduling
+        @stdin.sync  = true
+        @stdout.sync = true
+        @stderr.sync = true
+
+        @wait_thread.pid
+      end
+
+      def write_line(line)
+        raise ChannelClosedError, "Transport closed" if @closed
+        @stdin.puts(line)
+        @stdin.flush
+      end
+
+      def read_line
+        return nil if @closed
+        line = @stdout.gets
+        return nil if line.nil?
+        line.chomp
+      end
+
+      def stderr_reader
+        @stderr
+      end
+
+      def stdout_reader
+        @stdout
+      end
+
+      def close
+        return if @closed
+        @closed = true
+
+        @stdin&.close rescue nil
+        @stdout&.close rescue nil
+        @stderr&.close rescue nil
+      end
+
+      def closed?
+        @closed
+      end
+
+      def pid
+        @wait_thread&.pid
+      end
+
+      # Wait for the process to exit and return exit status.
+      # Uses Open3's wait_thread which handles process reaping.
+      # @return [Process::Status]
+      def wait_for_exit
+        @wait_thread&.value
+      end
+    end
+  end
+end