woods 2.0.0.beta4 → 2.0.1

data/lib/woods/watch/lifecycle.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'managed_child'
+
+module Woods
+  module Watch
+    # Validates the private attempt protocol independently of application logs.
+    class Lifecycle # rubocop:disable Metrics/ClassLength -- one attempt's ordered protocol state must stay together
+      # @param launcher [String] expected launcher token
+      # @param attempt [String] expected attempt token
+      # @param root [String] selected application root
+      def initialize(launcher:, attempt:, root:)
+        @launcher = launcher
+        @attempt = attempt
+        @root = File.realpath(root)
+      end
+
+      # @return [String, nil] resolved index directory, only after Rails boot
+      attr_reader :index, :child_pid, :terminal, :exit_code, :state, :reason
+
+      # @return [Boolean] Rails has resolved the application/index identity
+      def booted?
+        !@index.nil?
+      end
+
+      # @return [Boolean] guardian explicitly reported the application's exit
+      def finished?
+        @exited == true
+      end
+
+      # @param line [String] bounded JSON event from the private descriptor
+      # @return [Hash] validated event
+      def accept(line)
+        raise ArgumentError, 'oversized Woods lifecycle record' if line.bytesize > ManagedChild::MAX_BYTES
+
+        record = JSON.parse(line)
+        validate_envelope!(record)
+        event = record.fetch('event')
+        raise ArgumentError, 'event after guardian exit' if @exited
+
+        if %w[hello spawned exit spawn_error].include?(event)
+          guardian_event(record)
+        else
+          task_event(record)
+        end
+        record
+      rescue JSON::ParserError, KeyError, TypeError, SystemCallError
+        raise ArgumentError, 'invalid Woods lifecycle protocol'
+      end
+
+      private
+
+      def validate_envelope!(record)
+        return if record.is_a?(Hash) && record['version'] == 1 && record['launcher'] == @launcher &&
+                  record['attempt'] == @attempt && record['pid'].is_a?(Integer) && record['pid'].positive?
+
+        raise ArgumentError, 'invalid Woods lifecycle envelope'
+      end
+
+      def guardian_event(record)
+        case record['event']
+        when 'hello'
+          raise ArgumentError, 'duplicate guardian hello' if @guardian
+
+          @guardian = record['pid']
+        when 'spawned'
+          spawned(record)
+        when 'exit', 'spawn_error'
+          validate_guardian!(record)
+          validate_exit!(record)
+          @exit_code = record['event'] == 'spawn_error' ? 127 : record['code']
+          @exited = true
+        end
+      end
+
+      def spawned(record)
+        validate_guardian!(record)
+        raise ArgumentError, 'duplicate child spawn' if @spawned
+
+        pid = record['child_pid']
+        raise ArgumentError, 'invalid child PID' unless pid.is_a?(Integer) && pid.positive?
+        raise ArgumentError, 'child PID changed' if @child_pid && @child_pid != pid
+
+        @child_pid = pid
+        @spawned = true
+      end
+
+      def validate_exit!(record)
+        return if record['event'] == 'spawn_error' && !@spawned
+        return if record['event'] == 'exit' && @spawned && exit_status_valid?(record)
+
+        raise ArgumentError, 'invalid guardian exit'
+      end
+
+      def exit_status_valid?(record)
+        code, signal = record.values_at('code', 'signal')
+        return code.between?(0, 255) if code.is_a?(Integer)
+
+        code.nil? && signal.is_a?(Integer) && signal.positive?
+      end
+
+      def validate_guardian!(record)
+        raise ArgumentError, 'guardian identity mismatch' unless @guardian == record['pid']
+      end
+
+      def task_event(record)
+        validate_task_identity!(record)
+        event = record['event']
+        case event
+        when 'task_loaded' then load_task(record)
+        when 'identity' then resolve_identity(record)
+        when 'backend_ready' then ready_backend
+        when 'startup' then startup(record)
+        when 'terminal' then finish(record)
+        else raise ArgumentError, 'unknown Woods lifecycle event'
+        end
+      end
+
+      def validate_task_identity!(record)
+        raise ArgumentError, 'missing guardian hello' unless @guardian
+        raise ArgumentError, 'task event after terminal' if @terminal
+        raise ArgumentError, 'task identity mismatch' if @child_pid && @child_pid != record['pid']
+
+        @child_pid = record['pid']
+      end
+
+      def load_task(record)
+        version = record['woods_version']
+        unless !@task && version.is_a?(String) && Gem::Version.correct?(version)
+          raise ArgumentError, 'invalid task handshake'
+        end
+
+        @task = true
+        @state = 'booting'
+      end
+
+      def resolve_identity(record)
+        root, index = record.values_at('root', 'index')
+        unless @task && !@index && root.is_a?(String) && File.realpath(root) == @root &&
+               index.is_a?(String) && File.expand_path(index) == index
+          raise ArgumentError, 'invalid task root/index identity'
+        end
+
+        @index = index
+        @state = 'starting'
+      end
+
+      def ready_backend
+        raise ArgumentError, 'invalid backend ready event' unless booted? && !@backend
+
+        @backend = true
+        @state = 'reconciling'
+      end
+
+      def startup(record)
+        validate_startup!(record)
+        reconciled = record['reason'] == 'reconciled' && record['generation'].positive?
+        raise ArgumentError, 'inconsistent startup completion' unless (record['state'] == 'ready') == reconciled
+
+        @state = record['state']
+        @reason = record['reason']
+      end
+
+      def validate_startup!(record)
+        return if @backend && %w[ready degraded].include?(record['state']) &&
+                  ManagedChild::STARTUP_REASONS.include?(record['reason']) &&
+                  record['generation'].is_a?(Integer) && record['generation'] >= 0
+
+        raise ArgumentError, 'invalid startup completion'
+      end
+
+      def finish(record)
+        unless @task && ManagedChild::TERMINAL_REASONS.include?(record['reason'])
+          raise ArgumentError, 'invalid terminal event'
+        end
+
+        @terminal = record['reason']
+      end
+    end
+  end
+end

data/lib/woods/watch/managed_child.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Woods
+  module Watch
+    # Private, bounded lifecycle reporting for a task owned by woods-watch.
+    # Raw rake tasks do not open descriptors or alter their lifecycle.
+    class ManagedChild
+      ENV_KEYS = %w[WOODS_WATCH_EVENT_FD WOODS_WATCH_LAUNCHER_TOKEN WOODS_WATCH_ATTEMPT_TOKEN].freeze
+      TOKEN = /\A[A-Za-z0-9_-]{1,128}\z/
+      MAX_BYTES = 4096
+      FIELDS = {
+        task_loaded: %i[woods_version], identity: %i[root index], backend_ready: [],
+        startup: %i[state generation reason], terminal: %i[reason]
+      }.freeze
+      STARTUP_REASONS = %w[reconciled startup_failed pending_work restart_required no_index catch_up_disabled].freeze
+      TERMINAL_REASONS = %w[restart_required already_running stopped idle unsupported_environment].freeze
+
+      # @param env [#[]] child process environment
+      # @return [ManagedChild, nil] nil for an ordinary unmanaged task
+      def self.from_env(env: ENV)
+        values = ENV_KEYS.map { |key| env[key] }
+        return if values.all?(&:nil?)
+
+        descriptor, launcher, attempt = values
+        validate_environment!(descriptor, [launcher, attempt])
+
+        unless env['WOODS_WATCH_IDLE_TIMEOUT'].to_s.empty?
+          raise ArgumentError, 'WOODS_WATCH_IDLE_TIMEOUT must be unset for managed watching'
+        end
+
+        new(IO.for_fd(descriptor.to_i, 'w'), launcher: launcher, attempt: attempt)
+      end
+
+      def self.validate_environment!(descriptor, tokens)
+        valid_tokens = tokens.all? { |token| token.is_a?(String) && token.match?(TOKEN) }
+        valid_fd = descriptor.is_a?(String) && descriptor.match?(/\A\d+\z/) && descriptor.to_i >= 3
+        return if valid_tokens && valid_fd
+
+        raise ArgumentError, 'invalid Woods managed-child environment'
+      end
+      private_class_method :validate_environment!
+
+      # @param io [IO] private event descriptor owned by this reporter
+      # @param launcher [String] supervisor identity token
+      # @param attempt [String] current child attempt identity token
+      def initialize(io, launcher:, attempt:)
+        @io = io
+        @io.binmode
+        @io.sync = true
+        @io.close_on_exec = true
+        @launcher = launcher
+        @attempt = attempt
+        @mutex = Mutex.new
+      end
+
+      # @param event [Symbol] an allowlisted lifecycle boundary
+      # @param fields [Hash] bounded protocol data, never application exceptions
+      # @return [void]
+      def call(event, **fields)
+        validate!(event, fields)
+        message = JSON.generate(version: 1, launcher: @launcher, attempt: @attempt,
+                                event: event.to_s, pid: Process.pid, **fields) << "\n"
+        raise ArgumentError, 'Woods lifecycle message exceeds size limit' if message.bytesize > MAX_BYTES
+
+        @mutex.synchronize { @io.write(message) }
+      end
+
+      # @return [void]
+      def close
+        @mutex.synchronize { @io.close unless @io.closed? }
+      end
+
+      private
+
+      def validate!(event, fields)
+        expected = FIELDS[event]
+        raise ArgumentError, 'invalid Woods lifecycle event fields' unless expected && fields.keys.sort == expected.sort
+
+        validate_payload!(event, fields)
+      end
+
+      def validate_payload!(event, fields)
+        case event
+        when :startup then validate_startup!(fields)
+        when :terminal
+          raise ArgumentError, 'invalid Woods terminal reason' unless TERMINAL_REASONS.include?(fields[:reason])
+        when :identity
+          validate_identity!(fields)
+        when :task_loaded
+          raise ArgumentError, 'invalid Woods version' unless fields[:woods_version].is_a?(String)
+        end
+      end
+
+      def validate_identity!(fields)
+        return if %i[root index].all? do |key|
+          fields[key].is_a?(String) && fields[key] == File.expand_path(fields[key])
+        end
+
+        raise ArgumentError, 'Woods lifecycle identity must contain absolute paths'
+      end
+
+      def validate_startup!(fields)
+        return if %w[ready degraded].include?(fields[:state]) &&
+                  fields[:generation].is_a?(Integer) && fields[:generation] >= 0 &&
+                  STARTUP_REASONS.include?(fields[:reason])
+
+        raise ArgumentError, 'invalid Woods startup state or reason'
+      end
+    end
+  end
+end

data/lib/woods/watch/managed_cleanup.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Woods
+  module Watch
+    # Bounded, idempotent cleanup of groups registered by an owned guardian.
+    module ManagedCleanup
+      private
+
+      def stop_owned
+        return if @stopped
+
+        @io_mutex.synchronize { @liveness.close if @liveness && !@liveness.closed? }
+        wait_until_stopped(@config[:shutdown_timeout] + 1)
+        force_stop if alive? || @status&.signaled?
+        @stopped = true
+      ensure
+        close
+      end
+
+      def force_stop
+        child = @stream&.child_pid
+        signal_owned_group('KILL', child) if child
+        signal_owned_group('KILL', @pid) if alive?
+        wait_until_stopped(1)
+      end
+
+      def wait_until_stopped(seconds)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
+        while alive? && Process.clock_gettime(Process::CLOCK_MONOTONIC) < deadline
+          drain_cleanup_events
+          sleep 0.02
+        end
+      end
+
+      def drain_cleanup_events
+        read_events
+      rescue ArgumentError
+        @io_mutex.synchronize { @reader.close unless @reader.closed? }
+      end
+
+      def signal_owned_group(signal, pid)
+        Process.kill(signal, -pid)
+      rescue Errno::ESRCH
+        nil
+      end
+    end
+  end
+end

data/lib/woods/watch/managed_process.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'rbconfig'
+require 'securerandom'
+require_relative 'child_environment'
+require_relative 'event_stream'
+require_relative 'managed_cleanup'
+
+module Woods
+  module Watch
+    # Owns one guardian and its private pipes. File-based PIDs never grant
+    # signal authority. The guardian starts before the application bundle.
+    class ManagedProcess
+      include ManagedCleanup
+
+      MAX_EVENT_BYTES = 4096
+
+      # @param command [Array<String>] explicit application argument vector
+      # @param root [String] application working directory
+      # @param env [Hash] application environment
+      # @param shutdown_timeout [Numeric] graceful shutdown seconds
+      # @param events [Boolean] expose the private task protocol to the child
+      # @param launcher [String] launcher identity
+      # @param attempt [String] fresh attempt identity
+      # rubocop:disable-next Metrics/ParameterLists -- the process and protocol identities are explicit collaborators
+      def initialize(command:, root:, env:, shutdown_timeout: 10, events: false,
+                     launcher: SecureRandom.hex(16), attempt: SecureRandom.hex(16))
+        @config = { command: command, root: root, env: ChildEnvironment.build(ENV.to_h.merge(env), root: root),
+                    shutdown_timeout: shutdown_timeout,
+                    events: events, launcher: launcher, attempt: attempt }
+        @io_mutex = Mutex.new
+        @stop_mutex = Mutex.new
+        @pending_events = []
+      end
+
+      # @return [Integer, nil] owned guardian PID
+      attr_reader :pid
+
+      # @return [ManagedProcess] this started process
+      def start
+        raise ArgumentError, 'process already started' if @pid
+
+        parent, @liveness = IO.pipe
+        @reader, writer = IO.pipe
+        config_reader, config_writer = IO.pipe
+        spawn_guardian(parent, writer, config_reader)
+        @stream = EventStream.new(reader: @reader, guardian: @pid,
+                                  launcher: @config[:launcher], attempt: @config[:attempt])
+        [parent, writer, config_reader].each(&:close)
+        config_writer.write(JSON.generate(child_config))
+        config_writer.close
+        await_registration
+        self
+      rescue StandardError
+        [parent, writer, config_reader, config_writer].compact.each { |io| io.close unless io.closed? }
+        close
+        raise
+      end
+
+      # @return [Boolean] guardian still owns an active attempt
+      def alive?
+        return false unless @pid
+        return false if @status
+
+        @status = Process.waitpid2(@pid, Process::WNOHANG)&.last
+        @status.nil?
+      rescue Errno::ECHILD
+        false
+      end
+
+      # @return [Integer, nil] observed guardian exit code
+      def exit_status
+        alive?
+        @status&.exitstatus
+      end
+
+      # @return [Array<String>] bounded complete private protocol records
+      def read_events
+        @io_mutex.synchronize do
+          pending = @pending_events
+          @pending_events = []
+          pending + (@stream ? @stream.read : [])
+        end
+      end
+
+      # @return [Boolean] private stream ended
+      def eof?
+        @stream&.eof? == true
+      end
+
+      # Stop only this owned group, with cleanup delegated to its guardian.
+      # @return [void]
+      def stop
+        @stop_mutex.synchronize { stop_owned }
+      end
+
+      # Drop ownership; guardian observes EOF even if application boot hangs.
+      # @return [void]
+      def close
+        @io_mutex.synchronize do
+          [@liveness, @reader].compact.each { |io| io.close unless io.closed? }
+        end
+      end
+
+      private
+
+      def await_registration
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 5
+        loop do
+          @pending_events.concat(@stream.read)
+          if @stream.child_pid
+            @liveness.write('S')
+            return
+          end
+          raise ArgumentError, 'guardian could not register its child' unless alive?
+          if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+            raise ArgumentError,
+                  'guardian registration timed out'
+          end
+
+          sleep 0.01
+        end
+      end
+
+      def spawn_guardian(parent, writer, config_reader)
+        guardian = File.expand_path('guardian.rb', __dir__)
+        @pid = Process.spawn({ 'RUBYOPT' => nil, 'RUBYLIB' => nil }, RbConfig.ruby, '--disable-gems', guardian,
+                             3 => writer, 4 => parent, 5 => config_reader, in: File::NULL,
+                             pgroup: true, close_others: true)
+      end
+
+      def child_config
+        config = @config.dup
+        env = config[:env].dup
+        if config[:events]
+          env.merge!('WOODS_WATCH_EVENT_FD' => '3', 'WOODS_WATCH_LAUNCHER_TOKEN' => config[:launcher],
+                     'WOODS_WATCH_ATTEMPT_TOKEN' => config[:attempt])
+        end
+        config.merge(env: env, owner_pid: Process.pid)
+      end
+    end
+  end
+end

data/lib/woods/watch/puma_adapter.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative 'puma_child'
+
+module Woods
+  module Watch
+    # Optional Puma master-process integration. Requiring Woods itself never
+    # loads Puma or starts a watcher; only `plugin :woods` installs these hooks.
+    class PumaAdapter
+      SUPPORTED_MAJORS = [6, 7, 8].freeze
+      FALLBACK = 'Run bin/woods-watch through your development process manager instead.'
+
+      # @param launcher [Puma::Launcher] configured master launcher
+      # @param puma_version [String] loaded Puma version
+      # @param platform [String] Ruby platform used for supported-mode checks
+      def initialize(launcher, puma_version: ::Puma::Const::PUMA_VERSION, platform: RUBY_PLATFORM)
+        @launcher = launcher
+        @puma_version = puma_version
+        @platform = platform
+        @master_pid = Process.pid
+        # Puma has already chdir'd before plugin start. Expanding its raw
+        # relative `directory` option here would apply that directory twice.
+        @root = Dir.pwd
+        @started = false
+        @installed = false
+      end
+
+      # Register master-only lifecycle callbacks without starting extraction.
+      # @return [void]
+      def install
+        return if @installed
+
+        @installed = true
+        unless supported?
+          log("Puma #{@puma_version} on #{@platform} is unsupported by the Woods plugin. #{FALLBACK}")
+          return
+        end
+
+        hook(:after_booted, :on_booted) { start }
+        hook(:before_restart, :on_restart) { stop }
+        hook(:after_stopped, :on_stopped) { stop }
+      end
+
+      # Start at most once after Puma has finalized its environment and booted.
+      # @return [void]
+      def start
+        return unless Process.pid == @master_pid
+        return if @started || @launcher.options[:environment].to_s != 'development'
+
+        @started = true
+        unless File.file?(File.join(@root, 'bin/woods-watch'))
+          log('Missing bin/woods-watch; run bin/rails generate woods:watch --mode=puma. ' \
+              'Automatic maintenance is inactive.')
+          return
+        end
+
+        @child = PumaChild.new(root: @root, environment: 'development', logger: @launcher.log_writer)
+        pid = @child.start
+        log("Started launcher #{pid}; index readiness is reported separately by woods-watch.")
+      rescue SystemCallError => e
+        log("Could not start launcher (#{e.class}); automatic maintenance is inactive. #{FALLBACK}")
+      end
+
+      # Stop only the launcher owned by this master process.
+      # @return [void]
+      def stop
+        @child&.stop if Process.pid == @master_pid
+      end
+
+      private
+
+      def supported?
+        SUPPORTED_MAJORS.include?(@puma_version.to_s.split('.').first.to_i) &&
+          Process.respond_to?(:fork) && !@platform.match?(/mswin|mingw|cygwin|java/)
+      end
+
+      def hook(current, legacy, &block)
+        events = @launcher.events
+        events.public_send(events.respond_to?(current) ? current : legacy, &block)
+      end
+
+      def log(message)
+        @launcher.log_writer.log("[woods-watch] #{message}")
+      end
+    end
+  end
+end

data/lib/woods/watch/puma_child.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'rbconfig'
+require_relative 'managed_process'
+
+module Woods
+  module Watch
+    # Owns one foreground launcher. Retry policy belongs to that launcher, never
+    # to Puma; a failed launcher must not terminate or restart the web server.
+    class PumaChild
+      # The launcher gives its extraction child ten seconds to stop. Allow its
+      # guardian to finish that cleanup before escalating against the launcher.
+      STOP_GRACE = 15
+
+      # @param root [String] application root containing bin/woods-watch
+      # @param environment [String] finalized Puma environment
+      # @param logger [#log] Puma's log writer
+      # @param stop_grace [Numeric] graceful owned-process shutdown seconds
+      def initialize(root:, environment:, logger:, stop_grace: STOP_GRACE)
+        @root = root
+        @environment = environment
+        @logger = logger
+        @stop_grace = stop_grace
+        @stopping = false
+      end
+
+      # @return [Integer] owned guardian PID, not proof of index readiness
+      def start
+        @process = ManagedProcess.new(command: [RbConfig.ruby, File.join(@root, 'bin/woods-watch')],
+                                      root: @root, env: child_environment, shutdown_timeout: @stop_grace, events: false)
+        @process.start
+        @observer = Thread.new { observe }
+        @observer.name = 'woods-puma-launcher' if @observer.respond_to?(:name=)
+        @process.pid
+      end
+
+      # @return [void]
+      def stop
+        @stopping = true
+        # Puma can invoke stopped/restart callbacks from a signal trap.
+        # Only request and join here; the observer owns locks and IO cleanup.
+        (@observer || Thread.new { @process&.stop }).join
+      end
+
+      private
+
+      def child_environment
+        { 'APP_ENV' => @environment, 'RACK_ENV' => @environment, 'RAILS_ENV' => @environment }
+      end
+
+      def observe
+        until @stopping
+          unless @process.alive?
+            @process.stop
+            @logger.log('[woods-watch] Puma launcher stopped unexpectedly; automatic maintenance is inactive. ' \
+                        'Fix the launcher configuration and restart Puma, or run bin/woods-watch separately.')
+            return
+          end
+          sleep 0.1
+        end
+      ensure
+        @process.stop
+      end
+    end
+  end
+end