docscribe 1.6.0 → 1.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1016144165d119ade7719092f38974b29082a1bd86824864dd3a9b3412268771
-  data.tar.gz: ed2f6bbaf4e6f5892e0977a34c9aecb4924badc7e21ef25892d88bb4b0f8611a
+  metadata.gz: 24df08456004986c5cae869a2e7dc9ba4a1176cbf5dbaaca679cb4661836a3dc
+  data.tar.gz: 746d064972fe321f6b0d7459d87f1fc4cec8c414b4b4b73b9cce916f72b4139d
 SHA512:
-  metadata.gz: 7d1a11cef005ba87ef7fdf97d594ea699d638bc2a75dd62838ccec6f9260fca9b090e44a3176957584a30506f1159545354566a372c54e16382a2d384ae8248d
-  data.tar.gz: fd23695cdba7b7726e306ac2300665cb1f5eaf2764d2e19946df99fec6f7fee112408459fc774710305358a55d394413c4c8b3c663bd432514ffaf8f939d6dcf
+  metadata.gz: 4cf1ba70c9a43ec923abda6c16bbd599b287803fd9c6968b0e4c0ea87079fd8d1dd95317f7a20715f6664a7a1876da46cf008b3f6c21fc115237592b041f29b2
+  data.tar.gz: 0e7e994de57e167edf3a47b3d92ad1c123cb2decf973d137fcc7ac0bcd33f869fc380abd2d2705a2820d09837bce012b12f2f7efc2bbf0fe679da226040e43fb

data/lib/docscribe/server/base.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require 'socket'
+require 'fileutils'
+require 'digest/md5'
+require 'tmpdir'
+
+module Docscribe
+  # Server/daemon mode for persistent multi-request operation.
+  #
+  # Architecture:
+  # - Daemon process loads Ruby runtime once, listens on a Unix socket
+  # - Client sends JSON-line requests, receives JSON-line responses
+  # - Auto-shutdown after idle timeout
+  # - Protocol: JSON-RPC 2.0 over Unix socket
+  module Server
+    # Unix socket path max is 104 bytes on macOS (the more restrictive).
+    # Dir.tmpdir on macOS often returns a long path under /var/folders/.../T
+    # that exceeds this limit, so we fall back to /tmp when needed.
+    SOCKET_DIR = begin
+      tmp = Dir.tmpdir || '/tmp'
+      sock_overhead = "/docscribe-#{'a' * 32}.sock".bytesize # 48
+      tmp.bytesize <= 104 - sock_overhead ? tmp : '/tmp'
+    end
+    IDLE_TIMEOUT = 300
+
+    class << self
+      # Start the server daemon if not running.
+      #
+      # @param [String, nil] config_path optional config file path
+      # @param [Boolean] daemonize redirect stdin/stdout/stderr to /dev/null
+      # @param [Integer] timeout max seconds to wait for readiness
+      # @return [void]
+      def ensure_running!(config_path: nil, daemonize: false, timeout: 5)
+        return if running?(config_path)
+
+        check_platform_support!
+
+        lock_path = "#{socket_path(config_path)}.lock"
+        File.open(lock_path, File::RDWR | File::CREAT, 0o644) do |lock|
+          lock.flock(File::LOCK_EX)
+          next if running?(config_path)
+
+          start_daemon_process(config_path: config_path, daemonize: daemonize)
+        end
+        wait_for_ready(config_path: config_path, timeout: timeout)
+      end
+
+      # Start the server daemon and wait for it to become ready.
+      #
+      # @param [String, nil] config_path optional config path for socket/pid lookup
+      # @param [Integer] timeout max seconds to wait for readiness
+      # @param [Boolean] raise_on_timeout
+      # @raise [StandardError]
+      # @return [Boolean]
+      def wait_for_ready(config_path: nil, timeout: 5, raise_on_timeout: true) # rubocop:disable SortedMethodsByCall/Waterfall
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        loop do
+          return true if running?(config_path)
+
+          if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+            raise('Docscribe: server failed to start') if raise_on_timeout
+
+            warn('Docscribe server failed to start within timeout')
+            return false
+          end
+
+          sleep 0.1
+        end
+      end
+
+      # Whether a server process is listening on the socket.
+      #
+      # On ECONNREFUSED, checks whether the PID process is still alive:
+      # if yes, the daemon is still starting up (don't clean up);
+      # if no, removes stale socket and pid files.
+      #
+      # @param [String, nil] config_path optional config path for socket lookup
+      # @raise [Errno::ECONNREFUSED]
+      # @raise [Errno::ENOENT]
+      # @raise [Errno::ENOTSOCK]
+      # @raise [StandardError]
+      # @return [Boolean]
+      # @return [Boolean] if Errno::ECONNREFUSED
+      # @return [void, Boolean] if Errno::ENOENT, Errno::ENOTSOCK
+      # @return [Boolean] if StandardError
+      def running?(config_path = nil)
+        return false unless defined?(UNIXSocket)
+
+        socket = UNIXSocket.new(socket_path(config_path))
+        socket.close
+        true
+      rescue Errno::ECONNREFUSED
+        handle_stale_socket?(config_path)
+      rescue Errno::ENOENT, Errno::ENOTSOCK
+        clean_socket_files(config_path) && false
+      rescue StandardError
+        false
+      end
+
+      # Handle ECONNREFUSED: check if the pid process is alive.
+      # Cleans up only if the process is dead.
+      #
+      # @param [String, nil] config_path
+      # @return [Boolean] false (not running)
+      def handle_stale_socket?(config_path)
+        pid = read_pid(config_path)
+        return false if pid && process_alive?(pid)
+
+        clean_socket_files(config_path)
+        false
+      end
+
+      # @param [Integer] pid
+      # @raise [Errno::ESRCH]
+      # @return [Boolean]
+      # @return [Boolean] if Errno::ESRCH
+      def process_alive?(pid)
+        Process.kill(0, pid)
+        true
+      rescue Errno::ESRCH
+        false
+      end
+
+      # @param [String, nil] config_path
+      # @raise [StandardError]
+      # @return [Integer, nil]
+      # @return [nil] if StandardError
+      def read_pid(config_path = nil)
+        File.read(pid_path(config_path)).to_i if File.exist?(pid_path(config_path))
+      rescue StandardError
+        nil
+      end
+
+      # Remove stale socket and pid files.
+      #
+      # @param [String, nil] config_path
+      # @return [void]
+      def clean_socket_files(config_path)
+        FileUtils.rm_f(socket_path(config_path))
+        FileUtils.rm_f(pid_path(config_path))
+      end
+
+      # @param [String, nil] config_path
+      # @return [String]
+      def pid_path(config_path = nil)
+        "#{socket_path(config_path)}.pid"
+      end
+
+      ENV_FILES = %w[Gemfile.lock rbs_collection.lock.yaml].freeze
+
+      # @param [String] config_path
+      # @return [String]
+      def config_hash(config_path)
+        resolved = File.expand_path(config_path)
+        mtime = File.exist?(resolved) ? File.mtime(resolved).to_f : 0.0
+        Digest::MD5.hexdigest("#{resolved}:#{mtime}")
+      end
+
+      # Check platform compatibility before starting server.
+      #
+      # @raise [StandardError]
+      # @return [void]
+      def check_platform_support!
+        unless defined?(UNIXSocket)
+          raise 'Server mode requires Unix domain sockets, which are not available on Windows. ' \
+                'Use docscribe directly without --server flag.'
+        end
+        return if Process.respond_to?(:fork)
+
+        raise 'Server mode requires Process.fork, which is not available on JRuby. ' \
+              'Use docscribe directly without --server flag.'
+      end
+
+      # Derive a project-specific socket path from the current working directory.
+      # Uses MD5 (deterministic across processes) instead of String#hash
+      # (which varies per Ruby process due to random seeding).
+      # When a config_path is given, its path + mtime are included in the hash
+      # so different configs get different daemons.
+      # Environment files (Gemfile.lock, rbs_collection.lock.yaml) are also
+      # included so daemon is invalidated when gems or RBS types change.
+      #
+      # @param [String, nil] config_path optional config path to differentiate
+      # @return [String]
+      def socket_path(config_path = nil)
+        seed = +Dir.pwd
+        seed << ":#{env_hash}"
+        if config_path
+          resolved = File.expand_path(config_path)
+          mtime = File.exist?(resolved) ? File.mtime(resolved).to_f : 0.0
+          seed << ":#{resolved}:#{mtime}"
+        end
+        "#{SOCKET_DIR}/docscribe-#{Digest::MD5.hexdigest(seed)}.sock"
+      end
+
+      # Hash of environment files that affect analysis results.
+      # When any of these change, the daemon is invalidated (new socket path).
+      #
+      # @return [String]
+      def env_hash
+        parts = ENV_FILES.map do |file|
+          path = File.join(Dir.pwd, file)
+          File.exist?(path) ? File.mtime(path).to_f.to_s : '0'
+        end
+        Digest::MD5.hexdigest(parts.join(':'))
+      end
+
+      public :read_pid, :pid_path, :socket_path
+
+      # @param [String, nil] config_path
+      # @param [Boolean] daemonize
+      # @return [void]
+      def start_daemon_process(config_path:, daemonize:)
+        warn 'Docscribe: starting server...' if daemonize
+        pid = Process.fork do # steep:ignore NoMethod
+          [$stdin, $stdout].each { _1.reopen(File::NULL) }
+          $stderr.reopen(File::NULL)
+          Daemon.new(config_path: config_path).start
+        end
+        Process.detach(pid)
+      end
+    end
+  end
+end

data/lib/docscribe/server/client.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'socket'
+
+module Docscribe
+  module Server
+    # Client for communicating with a running Docscribe daemon.
+    class Client
+      # @param [String, nil] socket_path custom socket path (defaults to server default)
+      # @param [String, nil] config_path optional config path for socket lookup
+      # @return [void]
+      def initialize(socket_path = nil, config_path: nil)
+        @socket_path = socket_path || Server.socket_path(config_path)
+      end
+
+      # Send a check request to the server.
+      #
+      # @param [String] file path to file to check
+      # @param [Symbol] strategy rewrite strategy (:safe, :aggressive)
+      # @param [Hash<Symbol, Object>] rest extra JSON-RPC params (e.g. cli_overrides)
+      # @return [Hash<String, Object>, nil] response hash or nil if server unreachable
+      def check(file:, strategy: :safe, **rest)
+        request('check', file: file, strategy: strategy, **rest)
+      end
+
+      # Send a fix request to the server.
+      #
+      # @param [String] file path to file to fix
+      # @param [Symbol] strategy rewrite strategy (:safe, :aggressive)
+      # @param [Hash<Symbol, Object>] rest extra JSON-RPC params (e.g. cli_overrides)
+      # @return [Hash<String, Object>, nil] response hash or nil if server unreachable
+      def fix(file:, strategy: :safe, **rest)
+        request('fix', file: file, strategy: strategy, **rest)
+      end
+
+      # Send a shutdown request to the server.
+      #
+      # @return [Hash<String, Object>, nil] response hash or nil if server unreachable
+      def shutdown
+        request('shutdown')
+      end
+
+      # Ping the server and get version/pid/uptime info.
+      #
+      # @return [Hash<String, Object>, nil] response hash or nil if server unreachable
+      def ping
+        request('ping')
+      end
+
+      private
+
+      # Send a JSON-RPC request and read the response.
+      #
+      # @private
+      # @param [String] method method name
+      # @param [Hash<Symbol, Object>] params request parameters
+      # @return [Hash<String, Object>, nil]
+      def request(method, **params)
+        connect do |socket|
+          req = Protocol.build_request(method, params)
+          socket.write(Protocol.serialize(req))
+          socket.close_write
+          line = socket.gets
+          break unless line
+
+          Protocol.parse_response(line)
+        end
+      end
+
+      # Connect to the Unix socket and yield the connection.
+      #
+      # @private
+      # @raise [Errno::ECONNREFUSED]
+      # @raise [Errno::ENOENT]
+      # @return [T, nil] yield return value or nil on connection error
+      def connect
+        socket = UNIXSocket.new(@socket_path)
+        yield socket
+      rescue Errno::ECONNREFUSED, Errno::ENOENT
+        nil
+      ensure
+        socket&.close
+      end
+    end
+  end
+end