woods 2.0.0.beta3 → 2.0.0

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

data/lib/woods/watch/supervision_records.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Woods
+  module Watch
+    # Bounded readers and liveness correlation for persisted supervision records.
+    module SupervisionRecords
+      # Read bounded records without granting signal or writer-lock authority.
+      # @param index [String] published index root
+      # @return [Hash] supervision records with separately evaluated liveness
+      def self.read(index)
+        directory = File.join(index, SupervisionStatus::DIRECTORY)
+        return { records: [] } unless readable_directory?(directory)
+
+        names = Dir.each_child(directory).take(SupervisionStatus::MAX_SCAN + 1)
+        records = names.first(SupervisionStatus::MAX_SCAN).filter_map do |name|
+          read_record(File.join(directory, name)) if /\A[a-f0-9]{32}\.json\z/.match?(name)
+        end
+        records.sort_by! { |record| [record['alive'] ? 0 : 1, -Time.iso8601(record['updated_at']).to_f] }
+        correlate(records.first(SupervisionStatus::MAX_RECORDS), index)
+        truncated = names.size > SupervisionStatus::MAX_SCAN || records.size > SupervisionStatus::MAX_RECORDS
+        { records: records.first(SupervisionStatus::MAX_RECORDS), truncated: truncated }
+      rescue SystemCallError
+        { records: [] }
+      end
+
+      def self.readable_directory?(directory)
+        File.directory?(directory) && !File.symlink?(directory)
+      end
+      private_class_method :readable_directory?
+
+      def self.read_record(path)
+        bytes = bounded_read(path)
+        return unless bytes
+
+        record = JSON.parse(bytes)
+        return unless valid_record?(record, path)
+
+        age = Time.now - Time.iso8601(record['updated_at'])
+        record['alive'] = record['state'] != 'stopped' &&
+                          age.between?(-30, SupervisionStatus::STALE_AFTER) && local_alive?(record)
+        record
+      rescue SystemCallError, JSON::ParserError, TypeError, ArgumentError
+        nil
+      end
+      private_class_method :read_record
+
+      def self.bounded_read(path)
+        return if File.symlink?(path)
+
+        flags = File::RDONLY | File::NONBLOCK
+        flags |= File::NOFOLLOW if File.const_defined?(:NOFOLLOW)
+        bytes = File.open(path, flags) { |file| file.read(SupervisionStatus::MAX_BYTES + 1) if file.stat.file? }
+        bytes if bytes && bytes.bytesize <= SupervisionStatus::MAX_BYTES
+      end
+      private_class_method :bounded_read
+
+      def self.valid_record?(record, path)
+        record.is_a?(Hash) && record['version'] == 1 && record['launcher'] == File.basename(path, '.json') &&
+          SupervisionStatus::STATES.include?(record['state'])
+      end
+      private_class_method :valid_record?
+
+      def self.local_alive?(record)
+        unless record['host'] == Status.host_identity && record['pid'].is_a?(Integer) && record['pid'].positive?
+          return false
+        end
+
+        Process.kill(0, record['pid'])
+        true
+      rescue Errno::ESRCH
+        false
+      rescue Errno::EPERM
+        true
+      end
+      private_class_method :local_alive?
+
+      def self.correlate(records, index)
+        status = Status.new(output_dir: index)
+        daemon = status.read
+        daemon_alive = daemon.is_a?(Hash) && status.alive?
+        records.each do |record|
+          record['active_child'] = daemon_alive && matches_child?(record, daemon)
+        end
+      rescue SystemCallError, TypeError, NoMethodError
+        records.each { |record| record['active_child'] = false }
+      end
+      private_class_method :correlate
+
+      def self.matches_child?(record, daemon)
+        record['alive'] && record['child_pid'] == daemon['pid'] && record['host'] == daemon['host']
+      end
+      private_class_method :matches_child?
+    end
+  end
+end

data/lib/woods/watch/supervision_status.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require_relative 'status'
+require_relative 'supervision_records'
+
+module Woods
+  module Watch
+    # Independent owner records: a parked duplicate cannot overwrite the
+    # daemon heartbeat or make incremental hooks defer to an inactive writer.
+    class SupervisionStatus
+      DIRECTORY = 'watch_supervisors'
+      MAX_RECORDS = 32
+      MAX_SCAN = 256
+      MAX_BYTES = 8192
+      STALE_AFTER = 30
+      STATES = %w[starting booting reconciling ready degraded retrying parked stopped].freeze
+      FIELDS = %i[state reason attempt child_pid retry_at].freeze
+
+      # @param index [String] application-resolved output directory
+      # @param token [String] unguessable launcher identity
+      def initialize(index:, token:)
+        raise ArgumentError, 'invalid launcher token' unless /\A[a-f0-9]{32}\z/.match?(token)
+
+        @token = token
+        @directory = File.join(index, DIRECTORY)
+        @path = File.join(@directory, "#{token}.json")
+      end
+
+      # @param fields [Hash] state, owned child, attempt and bounded reason
+      # @return [void]
+      def write(**fields)
+        validate_fields!(fields)
+        verify_ownership!
+        data = { version: 1, launcher: @token, pid: Process.pid, host: Status.host_identity,
+                 updated_at: Time.now.utc.iso8601 }.merge(fields)
+        bytes = JSON.generate(data)
+        raise ArgumentError, 'oversized supervision record' if bytes.bytesize > MAX_BYTES
+
+        AtomicFile.write(@path, bytes, mode: 0o644)
+        prune_stale
+      end
+
+      # @param index [String] published index root
+      # @return [Hash] bounded supervision diagnostics
+      def self.read(index)
+        SupervisionRecords.read(index)
+      end
+
+      def self.read_record(path)
+        SupervisionRecords.send(:read_record, path)
+      end
+      private_class_method :read_record
+
+      def self.local_alive?(record)
+        SupervisionRecords.send(:local_alive?, record)
+      end
+      private_class_method :local_alive?
+
+      private
+
+      def verify_ownership!
+        raise ArgumentError, 'invalid supervision directory' if File.symlink?(@directory)
+        return unless File.exist?(@path) || File.symlink?(@path)
+
+        previous = self.class.send(:read_record, @path)
+        return if previous && previous['pid'] == Process.pid && previous['host'] == Status.host_identity
+
+        raise ArgumentError, 'supervision record belongs to another owner'
+      end
+
+      def validate_fields!(fields)
+        valid = (fields.keys - FIELDS).empty? && STATES.include?(fields[:state]) &&
+                fields[:reason].is_a?(String) && /\A[a-z_]{1,80}\z/.match?(fields[:reason]) &&
+                fields[:attempt].is_a?(String) && /\A[a-f0-9]{32}\z/.match?(fields[:attempt])
+        raise ArgumentError, 'invalid supervision fields' unless valid
+      end
+
+      def prune_stale
+        records = self.class.read(File.dirname(@directory))[:records]
+        records.each do |record|
+          next unless expired?(record) && removable?(record)
+
+          path = File.join(@directory, "#{record['launcher']}.json")
+          current = self.class.send(:read_record, path)
+          stored = record.except('active_child')
+          File.unlink(path) if current == stored
+        end
+      rescue SystemCallError
+        nil
+      end
+
+      def expired?(record)
+        record['launcher'] != @token && !record['alive'] &&
+          Time.now - Time.iso8601(record['updated_at']) > STALE_AFTER
+      end
+
+      def removable?(record)
+        record['state'] == 'stopped' ||
+          (record['host'] == Status.host_identity && !self.class.send(:local_alive?, record))
+      end
+    end
+  end
+end

data/lib/woods/watch/supervisor.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require_relative 'managed_process'
+require_relative 'lifecycle'
+require_relative 'supervision_status'
+require_relative 'supervisor_reporting'
+
+module Woods
+  module Watch
+    # Foreground retry owner shared by Procfile and Puma installations.
+    # It never retries configuration conflicts or silently takes over ownership.
+    class Supervisor # rubocop:disable Metrics/ClassLength -- retry, park and shutdown share one foreground attempt state
+      include SupervisorReporting
+
+      RETRY_DELAYS = [1, 2, 4, 8, 16, 30].freeze
+
+      # @param command [Array<String>] fresh application invocation on each attempt
+      # @param root [String] application root
+      # @param env [Hash] application environment
+      # @param logger [#puts] diagnostic destination (stderr by default)
+      # @param boot_timeout [Numeric] pre-identity boot deadline
+      # @param shutdown_timeout [Numeric] graceful application shutdown
+      # @param retry_delays [Array<Numeric>] bounded retry schedule
+      # rubocop:disable-next Metrics/ParameterLists -- independently injectable process policy and diagnostics
+      def initialize(command:, root:, env: ENV.to_h, logger: $stderr, boot_timeout: 300,
+                     shutdown_timeout: 10, retry_delays: RETRY_DELAYS)
+        raise ArgumentError, 'WOODS_WATCH_IDLE_TIMEOUT must be unset for managed watching' unless
+          env['WOODS_WATCH_IDLE_TIMEOUT'].to_s.empty?
+
+        @command = command
+        @root = File.realpath(root)
+        @env = env
+        @logger = logger
+        @boot_timeout = boot_timeout
+        @shutdown_timeout = shutdown_timeout
+        @retry_delays = retry_delays
+        @token = SecureRandom.hex(16)
+        @attempts = @failures = 0
+        @stopping = false
+      end
+
+      # @return [String, nil] honest lifecycle state
+      attr_reader :state, :attempts
+
+      # @return [Integer] zero after owner-requested shutdown
+      def run
+        until @stopping
+          run_attempt
+          break if @stopping
+
+          reason = retry_reason
+          reason ? retry_after(reason) : park(@protocol.terminal || 'incompatible_or_stopped_task')
+        end
+        0
+      ensure
+        @process&.stop
+        publish('stopped', 'owner_stopped')
+      end
+
+      # Signal-safe request; process cleanup occurs on the run thread.
+      # @return [void]
+      def stop
+        @stopping = true
+      end
+
+      private
+
+      def run_attempt
+        prepare_attempt
+        @process.start
+        monitor_attempt
+      rescue ArgumentError => e
+        @invalid = true
+        @logger.puts("[woods-watch] incompatible lifecycle: #{e.message}")
+      ensure
+        @process&.stop
+      end
+
+      def prepare_attempt
+        retire_status
+        @attempts += 1
+        @attempt = SecureRandom.hex(16)
+        @invalid = @timed_out = false
+        @ready_at = nil
+        @started_at = monotonic
+        @protocol = Lifecycle.new(launcher: @token, attempt: @attempt, root: @root)
+        @process = ManagedProcess.new(command: @command, root: @root, env: @env, events: true,
+                                      launcher: @token, attempt: @attempt, shutdown_timeout: @shutdown_timeout)
+        publish('starting', 'boot_pending')
+      end
+
+      def monitor_attempt
+        loop do
+          consume_events
+          break if @stopping || @protocol.finished? || !@process.alive?
+
+          if !@protocol.booted? && monotonic - @started_at >= @boot_timeout
+            @timed_out = true
+            break
+          end
+          raise ArgumentError, 'lifecycle stream ended while task was running' if @process.eof?
+
+          heartbeat
+          sleep 0.05
+        end
+        consume_events
+      end
+
+      def consume_events
+        @process.read_events.each do |line|
+          record = @protocol.accept(line)
+          @status = SupervisionStatus.new(index: @protocol.index, token: @token) if record['event'] == 'identity'
+          track_readiness(record) if record['event'] == 'startup'
+          publish(@protocol.state, @protocol.reason) if @protocol.state && !%w[exit terminal].include?(record['event'])
+        end
+      end
+
+      def track_readiness(record)
+        @ready_at = record['state'] == 'ready' ? (@ready_at || monotonic) : nil
+      end
+
+      def retry_reason
+        return if parked_outcome?
+        return 'boot_timeout' if @timed_out
+        return 'restart_required' if @protocol.terminal == 'restart_required' && @protocol.exit_code == 75
+        return if [0, 127].include?(@protocol.exit_code)
+
+        'child_failed'
+      end
+
+      def parked_outcome?
+        @invalid || %w[already_running unsupported_environment].include?(@protocol.terminal)
+      end
+
+      def retry_after(reason)
+        @failures = 0 if @ready_at && monotonic - @ready_at >= 60
+        delay = @retry_delays.fetch([@failures, @retry_delays.size - 1].min)
+        @failures += 1
+        publish('retrying', reason, retry_at: (Time.now + delay).utc.iso8601)
+        wait_until(monotonic + delay)
+      end
+
+      def park(reason)
+        publish('parked', reason)
+        @logger.puts('[woods-watch] restart the owner after correcting configuration; no automatic takeover')
+        wait_until(Float::INFINITY)
+      end
+
+      def wait_until(deadline)
+        until @stopping || monotonic >= deadline
+          heartbeat
+          sleep 0.05
+        end
+      end
+
+      def monotonic
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end