react_on_rails 16.6.0 → 16.7.0.rc.0

data/lib/react_on_rails/dev/file_manager.rb

@@ -1,8 +1,27 @@
 # frozen_string_literal: true
 
+require "open3"
+require "socket"
+
 module ReactOnRails
   module Dev
     class FileManager
+      # Bounded probe so a stuck server with a full accept queue (rare for a
+      # local overmind socket but theoretically possible) cannot stall
+      # bin/dev startup indefinitely.
+      #
+      # Two paths consume this budget differently:
+      #   - synchronous failure (typical): UNIX socket connect() to a dead
+      #     listener fails in microseconds, so 150 ms is far more than needed.
+      #   - async wait_writable: if connect() returns IO::WaitWritable, the
+      #     full 150 ms can be consumed waiting for the kernel to mark the
+      #     socket writable. This is the actual budget for slow-loopback or
+      #     paused-PID cases — not "microseconds".
+      # Result: 150 ms is conservative for the common path and the cap for
+      # the worst case.
+      SOCKET_PROBE_TIMEOUT_SECS = 0.15
+      private_constant :SOCKET_PROBE_TIMEOUT_SECS
+
       class << self
         def cleanup_stale_files
           socket_cleanup = cleanup_overmind_sockets
@@ -13,13 +32,18 @@ module ReactOnRails
 
         private
 
+        # Targets overmind-named sockets only (`.overmind.sock` at the project root and
+        # `tmp/sockets/overmind*.sock` for copied/renamed variants). Inactive matches are
+        # removed on startup. Other apps' Unix sockets in `tmp/sockets/` (Puma, Action
+        # Cable, custom services) are left untouched even when stale, so a tight
+        # startup race window cannot delete a socket bin/dev does not own.
         def cleanup_overmind_sockets
-          return false if overmind_running?
-
-          socket_files = [".overmind.sock", "tmp/sockets/overmind.sock"]
+          socket_files = [".overmind.sock", *Dir.glob("tmp/sockets/overmind*.sock")].uniq
           cleaned_any = false
 
           socket_files.each do |socket_file|
+            next if socket_active?(socket_file)
+
             cleaned_any = true if remove_file_if_exists(socket_file, "stale socket")
           end
 
@@ -43,13 +67,15 @@ module ReactOnRails
             return true
           end
 
-          return false if process_running?(pid)
+          unless process_running?(pid)
+            remove_file_if_exists(server_pid_file, "stale Rails pid file")
+            return true
+          end
 
-          remove_file_if_exists(server_pid_file, "stale Rails pid file")
-        end
+          pid_working_directory = working_directory_for_pid(pid)
+          return false if pid_working_directory.nil? || same_working_directory?(pid_working_directory, Dir.pwd)
 
-        def overmind_running?
-          !`pgrep -f "overmind" 2>/dev/null`.split("\n").empty?
+          remove_file_if_exists(server_pid_file, "stale Rails pid file from another app directory")
         end
 
         def process_running?(pid)
@@ -63,6 +89,107 @@ module ReactOnRails
           true
         end
 
+        def socket_active?(socket_path)
+          return false unless File.exist?(socket_path)
+
+          # Pre-pack the sockaddr in a narrow rescue so the only ArgumentError
+          # we swallow is the one Ruby raises for "too long unix socket path"
+          # (sun_path is capped at ~104/108 bytes). The wider connect block
+          # below intentionally does NOT catch ArgumentError, so a programming
+          # mistake in Socket.new or connect_nonblock surfaces instead of
+          # silently returning false.
+          begin
+            sockaddr = Socket.sockaddr_un(socket_path)
+          rescue ArgumentError
+            return false
+          end
+
+          socket = nil
+          begin
+            socket = Socket.new(Socket::AF_UNIX, Socket::SOCK_STREAM, 0)
+            socket.connect_nonblock(sockaddr)
+            true
+          rescue IO::WaitWritable
+            # connect is in progress — wait up to SOCKET_PROBE_TIMEOUT_SECS for
+            # writability, then check SO_ERROR to distinguish accepted vs.
+            # refused/timed-out connections. Uses socket.wait_writable rather
+            # than IO.select so a Fiber scheduler can interleave properly.
+            ready = socket.wait_writable(SOCKET_PROBE_TIMEOUT_SECS)
+            return false unless ready
+
+            socket.getsockopt(Socket::SOL_SOCKET, Socket::SO_ERROR).int.zero?
+          rescue Errno::EISCONN
+            true
+          rescue SystemCallError, IOError
+            false
+          ensure
+            socket&.close
+          end
+        end
+
+        # Two-stage lookup: try the zero-dependency `/proc/PID/cwd` readlink first
+        # (Linux), then fall back to `lsof` (macOS, BSD, Linux without /proc visibility).
+        # The /proc path matters for minimal Alpine/CI containers where `lsof`
+        # is not installed by default — without it, this method would silently
+        # return nil on every container and leave stale PID files behind.
+        #
+        # The lsof call uses Open3.capture2 with a word-list argv (matching
+        # ServerManager#find_port_pids) so the no-shell-injection invariant is
+        # structural rather than caller-enforced.
+        #
+        # Returns nil when both probes fail:
+        #   - /proc not present (macOS, BSD) and `lsof` absent (Errno::ENOENT) — minimal containers,
+        #   - the kernel withholds info (permission denied, process exited mid-probe),
+        #   - any other unexpected error.
+        # The nil return causes `cleanup_rails_pid_file` to keep the PID file as a safe
+        # fallback. Set DEBUG=1 to surface the failure on stderr.
+        def working_directory_for_pid(pid)
+          proc_cwd = working_directory_via_proc(pid)
+          return proc_cwd if proc_cwd
+
+          working_directory_via_lsof(pid)
+        end
+
+        def working_directory_via_proc(pid)
+          # File.readlink either returns a non-empty String or raises.
+          File.readlink("/proc/#{pid}/cwd")
+        rescue Errno::ENOENT, Errno::EACCES, Errno::EPERM, NotImplementedError
+          # /proc not present (macOS, BSD), no permission to read this PID's cwd,
+          # or readlink unsupported on this platform. Fall through to lsof.
+          nil
+        end
+
+        def working_directory_via_lsof(pid)
+          stdout, = Open3.capture2("lsof", "-a", "-p", pid.to_s, "-d", "cwd", "-Fn", err: File::NULL)
+          path_line = stdout.lines.find { |line| line.start_with?("n") }
+          path = path_line&.delete_prefix("n")&.strip
+          return nil if path.nil? || path.empty?
+
+          path
+        rescue Errno::ENOENT => e
+          # `lsof` binary missing — expected on minimal images. DEBUG-gated so
+          # users on Linux/macOS without the package don't see noise.
+          log_lsof_missing(e) if ENV["DEBUG"]
+          nil
+        rescue StandardError => e
+          # Genuinely unexpected: resource limits (Errno::EMFILE), interrupted
+          # syscall (Errno::EINTR), permission errors, etc. Always-warn so the
+          # cross-directory PID check can't silently misfire under load.
+          warn "bin/dev: could not determine working directory for PID #{pid} " \
+               "(#{e.class}: #{e.message})."
+          nil
+        end
+
+        def log_lsof_missing(error)
+          warn "bin/dev: `lsof` not found; cross-directory PID check skipped (#{error.message})."
+        end
+
+        def same_working_directory?(left, right)
+          File.realpath(left) == File.realpath(right)
+        rescue SystemCallError
+          File.expand_path(left) == File.expand_path(right)
+        end
+
         def remove_file_if_exists(file_path, description)
           return false unless File.exist?(file_path)
 

data/lib/react_on_rails/dev/port_selector.rb

@@ -9,13 +9,66 @@ module ReactOnRails
       DEFAULT_WEBPACK_PORT = 3035
       MAX_ATTEMPTS         = 100
 
+      # Offsets from the base port when REACT_ON_RAILS_BASE_PORT (or a recognized
+      # tool-specific equivalent like CONDUCTOR_PORT) is set. The base port block
+      # is typically 10 consecutive ports allocated per workspace.
+      BASE_PORT_RAILS_OFFSET    = 0
+      BASE_PORT_WEBPACK_OFFSET  = 1
+      BASE_PORT_RENDERER_OFFSET = 2
+      TCP_PORT_MAX  = 65_535
+      MAX_BASE_PORT = TCP_PORT_MAX - BASE_PORT_RENDERER_OFFSET
+
+      # Ports 1..1023 are privileged on Linux/macOS and require root to bind.
+      PRIVILEGED_PORT_MAX = 1023
+
+      # Env vars checked (in order) for a base port value.
+      #
+      # CONDUCTOR_PORT is an empirical interpretation based on Conductor.build
+      # (https://conductor.build) allocating a block of consecutive ports per
+      # workspace and exposing the block base via this env var. This contract
+      # is not in a public Conductor API, so treat CONDUCTOR_PORT support as
+      # best-effort until Conductor documents it. If a future release changes
+      # the meaning (e.g. CONDUCTOR_PORT becomes the Rails port itself rather
+      # than a block base), the derived offsets below will land on the wrong
+      # ports — users would see port-conflict failures at runtime rather than
+      # a clear misconfiguration error. A future "validate derived ports are
+      # reachable on startup" path could surface this earlier.
+      #
+      # Escape hatch: REACT_ON_RAILS_BASE_PORT takes precedence, so users can
+      # override the CONDUCTOR_PORT interpretation without code changes.
+      BASE_PORT_ENV_VARS = %w[REACT_ON_RAILS_BASE_PORT CONDUCTOR_PORT].freeze
+
       class NoPortAvailable < StandardError; end
 
       class << self
-        # Returns { rails: Integer, webpack: Integer }.
-        # Respects existing ENV['PORT'] / ENV['SHAKAPACKER_DEV_SERVER_PORT'].
-        # Probes for free ports when either or both env vars are unset.
-        def select_ports
+        # Returns { rails: Integer, webpack: Integer, renderer: Integer|nil,
+        #           base_port_mode: Boolean }.
+        #
+        # Priority:
+        #   1. Base port (REACT_ON_RAILS_BASE_PORT or CONDUCTOR_PORT) — all ports
+        #      derived deterministically from the base; no probing.
+        #   2. Explicit per-service env vars (PORT, SHAKAPACKER_DEV_SERVER_PORT).
+        #   3. Auto-detect free ports starting from defaults.
+        #
+        # The :renderer key is populated only when a base port is set (it is a
+        # Pro-only service and does not participate in auto-detection).
+        # :base_port_mode is true only in case 1.
+        #
+        # NOTE: This method mutates ENV.
+        # @side_effect Deletes invalid PORT / SHAKAPACKER_DEV_SERVER_PORT
+        #   values via `read_and_sanitize_port_env!` so ServerManager's
+        #   apply_explicit_port_env path doesn't re-warn on the same bad
+        #   value. Intended for `bin/dev` startup; do not call from
+        #   read-only contexts that expect ENV to survive the call. See
+        #   `read_and_sanitize_port_env!` (which uses the `!` suffix to make
+        #   the mutation explicit at the inner call site).
+        # @param pro_renderer [Boolean] when false, suppresses the renderer
+        #   port-in-use warning so OSS apps without a node renderer don't
+        #   see "port X (renderer)" noise on a coincidentally-bound base+2.
+        def select_ports!(pro_renderer: true)
+          base = base_port_ports(pro_renderer: pro_renderer)
+          return base if base
+
           rails_port   = explicit_rails_port
           webpack_port = explicit_webpack_port
 
@@ -30,7 +83,16 @@ module ReactOnRails
             puts "Default ports in use. Using Rails :#{rails_port}, webpack :#{webpack_port}"
           end
 
-          { rails: rails_port, webpack: webpack_port }
+          { rails: rails_port, webpack: webpack_port, renderer: nil, base_port_mode: false }
+        end
+
+        # Deprecated alias for the pre-bang name. Kept as a safety net for any
+        # external caller (generator extension, host-app rake task) that wired
+        # to `select_ports` before the rename. The bang form is preferred — it
+        # surfaces the ENV-mutation side effect at the call site, which was
+        # the whole point of the rename. Remove in a future major release.
+        def select_ports(**kwargs)
+          select_ports!(**kwargs)
         end
 
         # Public so it can be stubbed in tests.
@@ -52,6 +114,48 @@ module ReactOnRails
           end
         end
 
+        # Returns the base-port-derived port hash when a base port env var is
+        # set (with the same shape as #select_ports!), otherwise nil. Does not
+        # fall back to per-service env vars or auto-detect, so callers can
+        # branch on "is base-port mode active?" without triggering probing.
+        # Used by ServerManager so all bin/dev modes (development, static,
+        # production-like) honor the base-port contract consistently.
+        #
+        # Logs the detected base port and warns on derived-port collisions.
+        # Callers that need the derived ports without user-facing output
+        # (e.g. ServerManager#kill_processes, which shouldn't print a banner
+        # while killing) should use #base_port_hash instead.
+        def base_port_ports(pro_renderer: true)
+          bp, source = base_port_with_source
+          return nil unless bp
+
+          ports = derive_ports_from_base(bp)
+          source_note = if source == "CONDUCTOR_PORT"
+                          " (unofficial contract; set REACT_ON_RAILS_BASE_PORT to override)"
+                        else
+                          ""
+                        end
+          renderer_segment = pro_renderer ? ", renderer :#{ports[:renderer]}" : ""
+          puts "Base port #{bp} detected via #{source}#{source_note}. Using Rails :#{ports[:rails]}, " \
+               "webpack :#{ports[:webpack]}#{renderer_segment}"
+          warn_if_derived_ports_in_use(bp, ports, source: source, pro_renderer: pro_renderer)
+          ports
+        end
+
+        # Pure derivation: returns the same port hash as #base_port_ports but
+        # without the "Base port X detected" log line or the derived-port
+        # collision warnings. Safe to call from any context where logging is
+        # undesirable (e.g. kill flows). Still delegates to
+        # #base_port_with_source, which surfaces invalid-value warnings — those
+        # describe the env input, not the port output, and are desirable even
+        # in silent callers.
+        def base_port_hash
+          bp, _source = base_port_with_source
+          return nil unless bp
+
+          derive_ports_from_base(bp)
+        end
+
         def find_available_port(start_port, exclude: nil)
           MAX_ATTEMPTS.times do |i|
             port = start_port + i
@@ -63,14 +167,162 @@ module ReactOnRails
           raise NoPortAvailable, "No available port found starting at #{start_port}."
         end
 
+        # Strict port-string predicate shared with ServerManager so the two
+        # layers can't silently diverge. `String#to_i` would otherwise truncate
+        # `"3000abc"` to 3000 and slip it through here while ServerManager's
+        # overwrite path rejected it.
+        def valid_port_string?(value)
+          return false if value.nil?
+
+          stripped = value.to_s.strip
+          return false if stripped.empty?
+          return false unless stripped.match?(/\A\d+\z/)
+
+          stripped.to_i.between?(1, TCP_PORT_MAX)
+        end
+
         private
 
+        def derive_ports_from_base(base)
+          {
+            rails: base + BASE_PORT_RAILS_OFFSET,
+            webpack: base + BASE_PORT_WEBPACK_OFFSET,
+            renderer: base + BASE_PORT_RENDERER_OFFSET,
+            base_port_mode: true
+          }
+        end
+
+        # Advisory: surface early conflicts when a base port's derived ports are
+        # already bound (e.g. two worktrees share a base). Does not fail — the
+        # actual bind at server start gives the definitive error.
+        #
+        # Skips the renderer port when `pro_renderer` is false: OSS apps don't
+        # run a node renderer, so "port base+2 (renderer) is already in use"
+        # would be confusing noise on a coincidental collision with an
+        # unrelated local service.
+        #
+        # When the base came from CONDUCTOR_PORT and the *Rails* port (base+0)
+        # is taken, append a hint that Conductor's contract is unofficial —
+        # this is the most likely failure mode if Conductor ever changes
+        # CONDUCTOR_PORT to mean "the Rails port" rather than "a block base"
+        # (the derived ports would silently land on whatever the user already
+        # has bound).
+        def warn_if_derived_ports_in_use(base, ports, source: nil, pro_renderer: true)
+          roles = pro_renderer ? %i[rails webpack renderer] : %i[rails webpack]
+          roles.each do |role|
+            port_num = ports[role]
+            next if port_available?(port_num)
+
+            hint = if role == :rails && source == "CONDUCTOR_PORT"
+                     " If your Conductor workspace exposes CONDUCTOR_PORT as the Rails port " \
+                       "rather than a block base, set REACT_ON_RAILS_BASE_PORT explicitly to override."
+                   else
+                     ""
+                   end
+            warn "WARNING: port #{port_num} (#{role}, derived from base #{base}) is already in use.#{hint}"
+          end
+        end
+
+        # Returns [val, source_var] when a valid base port env var is set,
+        # otherwise nil. The source var is included so callers can surface it
+        # in user-facing log lines (helpful when CONDUCTOR_PORT vs.
+        # REACT_ON_RAILS_BASE_PORT activated base-port mode).
+        def base_port_with_source
+          # Upper bound accounts for the largest derived offset so base + N stays
+          # within the valid TCP port range (1..65_535).
+          #
+          # Strip before validating so whitespace-padded values (common with
+          # copy-paste or env-file templating) parse the same way PORT and
+          # SHAKAPACKER_DEV_SERVER_PORT do via read_and_sanitize_port_env!.
+          BASE_PORT_ENV_VARS.each_with_index do |var, idx|
+            raw = ENV.fetch(var, nil)
+            next if raw.nil?
+
+            stripped = raw.strip
+            next if stripped.empty?
+
+            unless stripped.match?(/\A\d+\z/)
+              warn invalid_base_port_warning(var, raw, "not a valid integer", idx)
+              next
+            end
+
+            val = stripped.to_i
+            unless val.between?(1, MAX_BASE_PORT)
+              reason = "out of range (1..#{MAX_BASE_PORT}; must leave room for " \
+                       "+#{BASE_PORT_RENDERER_OFFSET} renderer offset)"
+              warn invalid_base_port_warning(var, raw, reason, idx)
+              next
+            end
+
+            if val <= PRIVILEGED_PORT_MAX
+              warn "WARNING: #{var}=#{raw.inspect} is in the privileged range " \
+                   "(1..#{PRIVILEGED_PORT_MAX}); binding will fail without root."
+            end
+
+            return [val, var]
+          end
+          nil
+        end
+
+        # Invalid REACT_ON_RAILS_BASE_PORT silently falls through to CONDUCTOR_PORT
+        # (or any future later entry). Surface the fallthrough in the warning so
+        # users who set a non-integer to "disable" base port mode realize they
+        # also need to unset the next var.
+        #
+        # Filter `remaining` against the same validity rules as `base_port_ports`
+        # (numeric + 1..MAX_BASE_PORT) so we never promise activation from a
+        # var that the validator will also reject — e.g.
+        # `REACT_ON_RAILS_BASE_PORT="disabled"` + `CONDUCTOR_PORT="abc"` must
+        # not say "will still activate from CONDUCTOR_PORT".
+        def invalid_base_port_warning(var, raw, reason, idx)
+          msg = "WARNING: #{var}=#{raw.inspect} is #{reason}; ignoring."
+          remaining = BASE_PORT_ENV_VARS[(idx + 1)..].select do |v|
+            val = ENV.fetch(v, "").strip
+            val.match?(/\A\d+\z/) && val.to_i.between?(1, MAX_BASE_PORT)
+          end
+          return msg if remaining.empty?
+
+          msg + " Base port mode will still activate from #{remaining.join(', ')}; " \
+                "unset to disable entirely."
+        end
+
         def explicit_rails_port
-          ENV["PORT"]&.to_i&.then { |p| p.between?(1, 65_535) ? p : nil }
+          read_and_sanitize_port_env!("PORT")
         end
 
         def explicit_webpack_port
-          ENV["SHAKAPACKER_DEV_SERVER_PORT"]&.to_i&.then { |p| p.between?(1, 65_535) ? p : nil }
+          read_and_sanitize_port_env!("SHAKAPACKER_DEV_SERVER_PORT")
+        end
+
+        # Reject values that aren't valid port strings and clear the env var
+        # so ServerManager's apply_explicit_port_env path (which also rejects
+        # them) doesn't emit a second warning for the same value.
+        #
+        # The `!` suffix signals the ENV-mutation side effect at the call site
+        # (explicit_rails_port / explicit_webpack_port); the "warn once + fall
+        # back" flow is shared with ServerManager via the cleared env, not via
+        # the return value. Kept in one place so the coupling is obvious.
+        def read_and_sanitize_port_env!(var_name)
+          raw = ENV.fetch(var_name, nil)
+          return nil if raw.nil?
+
+          stripped = raw.strip
+          return nil if stripped.empty?
+
+          unless stripped.match?(/\A\d+\z/)
+            warn "WARNING: #{var_name}=#{raw.inspect} is not a valid integer; ignoring."
+            ENV.delete(var_name)
+            return nil
+          end
+
+          n = stripped.to_i
+          unless n.between?(1, TCP_PORT_MAX)
+            warn "WARNING: #{var_name}=#{raw.inspect} is out of range (1..#{TCP_PORT_MAX}); ignoring."
+            ENV.delete(var_name)
+            return nil
+          end
+
+          n
         end
       end
     end

data/lib/react_on_rails/dev/process_manager.rb

@@ -14,7 +14,29 @@ module ReactOnRails
       # before entering the block and pass them explicitly to system().
       # This follows the same pattern used by Rails' bundle_command (railties),
       # Spring's process spawning, and this codebase's own PackGenerator.
-      ENV_KEYS_TO_PRESERVE = %w[PORT SHAKAPACKER_DEV_SERVER_PORT].freeze
+      #
+      # REACT_ON_RAILS_BASE_PORT and CONDUCTOR_PORT are intentionally excluded:
+      # by the time sub-processes spawn, configure_ports has already derived
+      # concrete values into PORT / SHAKAPACKER_DEV_SERVER_PORT / RENDERER_PORT /
+      # REACT_RENDERER_URL. Sub-processes should use those fixed ports rather
+      # than re-deriving from the base.
+      # SHAKAPACKER_SKIP_PRECOMPILE_HOOK is also runtime-only and must survive
+      # Bundler's env reset so nested shakapacker commands don't rerun the hook.
+      # RENDERER_URL is the legacy name for REACT_RENDERER_URL; preserved for
+      # mid-migration users (see ServerManager#warn_if_legacy_renderer_url_env_used).
+      # Inclusion here also matters when base-port mode scrubs the legacy var:
+      # `preserve_runtime_env_vars` returns `nil` (not the string "nil") for unset
+      # keys, which `Process.spawn`/`system` use to explicitly unset the variable
+      # in the child — preventing `with_unbundled_env` from resurrecting a stale
+      # pre-Bundler value. See the comment on `preserve_runtime_env_vars` below.
+      ENV_KEYS_TO_PRESERVE = %w[
+        PORT
+        SHAKAPACKER_DEV_SERVER_PORT
+        RENDERER_PORT
+        REACT_RENDERER_URL
+        RENDERER_URL
+        SHAKAPACKER_SKIP_PRECOMPILE_HOOK
+      ].freeze
 
       class << self
         # Check if a process is available and usable in the current execution context
@@ -180,9 +202,14 @@ module ReactOnRails
           MSG
         end
 
+        # Always include every key (nil when unset) so Process.spawn/system
+        # explicitly unsets it in the child. A non-nil-only hash would let
+        # `with_unbundled_env` restore a pre-Bundler value the parent had
+        # just deleted — e.g. an invalid `RENDERER_PORT=abc` that
+        # PortSelector scrubbed would resurrect in the renderer child.
         def preserve_runtime_env_vars
           ENV_KEYS_TO_PRESERVE.each_with_object({}) do |key, hash|
-            hash[key] = ENV[key] if ENV[key]
+            hash[key] = ENV.fetch(key, nil)
           end
         end