woods 2.0.0.beta4 → 2.0.0

data/lib/woods/watch/installation/recovery.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Woods
+  module Watch
+    class Installation
+      # Replays only validated local transaction state; never discovers or boots Rails.
+      class Recovery
+        # @param root [String] selected canonical application directory
+        def initialize(root:)
+          @root = root
+        end
+
+        # @param pretend [Boolean] check journal and current snapshots without writes
+        # @return [String] recovery status
+        def call(pretend: false)
+          journal = read_journal
+          return 'nothing_to_recover' unless journal
+
+          layout = recovery_layout(journal)
+          applier = Woods::AgentConfiguration::Applier.new(layout: layout)
+          return applier.recover unless pretend
+
+          verify_preview(applier, layout, journal)
+          'recovery_preview_verified'
+        rescue KeyError, TypeError, ArgumentError => e
+          raise Conflict, "Invalid watcher recovery journal: #{e.message}"
+        end
+
+        private
+
+        def read_journal
+          layout = Layout.new(@root, 'Procfile.dev')
+          document = Woods::AgentConfiguration::Document.new("#{layout.receipt_path}.pending")
+          document.content && document.json
+        end
+
+        def recovery_layout(journal)
+          plan = journal.fetch('plan')
+          identity = plan.fetch('layout')
+          raise Conflict, 'Recovery journal belongs to another application' unless identity.fetch('root') == @root
+
+          layout = Layout.new(@root, identity.fetch('procfile'))
+          paths = plan.fetch('changes').map do |change|
+            path = change.fetch('path')
+            raise Conflict, 'Recovery target is outside the application' unless path.start_with?("#{@root}/")
+
+            path.delete_prefix("#{@root}/")
+          end
+          layout.include_previous(paths)
+          layout
+        end
+
+        def verify_preview(applier, layout, journal)
+          plan = Woods::AgentConfiguration::Plan.allocate
+          plan.instance_variable_set(:@data, journal.fetch('plan'))
+          plan.validate!(layout)
+          changes = plan.data.fetch('changes')
+          applier.send(:validate_originals!, journal.fetch('originals'), changes)
+          changes.each { |change| applier.send(:validate_recovery_snapshot!, change) }
+        end
+      end
+    end
+  end
+end

data/lib/woods/watch/installation/templates.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Woods
+  module Watch
+    class Installation
+      # Small generated fragments; runtime identities never enter committed files.
+      module Templates
+        START = '# woods:watch:managed:start'
+        FINISH = '# woods:watch:managed:end'
+
+        module_function
+
+        # @param child_command [Array<String>] explicit task argv
+        # @return [String] application-relative executable source
+        def wrapper(child_command)
+          <<~RUBY
+            #!/usr/bin/env ruby
+            # frozen_string_literal: true
+
+            # Generated by Woods; use woods:watch --operation update to change owned setup.
+            root = File.expand_path('..', __dir__)
+            ENV['BUNDLE_GEMFILE'] ||= File.join(root, 'Gemfile')
+            require 'bundler/setup'
+            Dir.chdir(root)
+            exec Gem.ruby, Gem.bin_path('woods', 'woods-watch'), '--root', root,
+                 *ARGV, '--', *#{child_command.inspect}
+          RUBY
+        end
+
+        # @param mode [String] procfile or puma
+        # @return [String] owned startup directive
+        def directive(mode)
+          return 'woods: bin/woods-watch' unless mode == 'puma'
+
+          'plugin :woods if Gem.loaded_specs["woods"]&.full_require_paths&.any? ' \
+            '{ |path| File.file?(File.join(path, "puma/plugin/woods.rb")) }'
+        end
+
+        # @param mode [String] selected startup mode
+        # @param text [String] surrounding file contents
+        # @param previous [String, nil] existing receipt-owned block
+        # @param update [Boolean] refresh an existing block in place
+        # @return [String] exact appended owned block including separator
+        def section(mode, text, previous: nil, update: false)
+          if previous
+            return previous unless update
+
+            return previous.partition(START).first + section(mode, previous)
+          end
+
+          newline = text.include?("\r\n") ? "\r\n" : "\n"
+          separator = text.empty? || text.end_with?(newline) ? '' : newline
+          separator + [START, directive(mode), FINISH, ''].join(newline)
+        end
+      end
+    end
+  end
+end

data/lib/woods/watch/installation.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../agent_configuration/applier'
+require_relative '../agent_configuration/plan'
+require_relative 'installation/layout'
+require_relative 'installation/options'
+require_relative 'installation/planner'
+require_relative 'installation/probe'
+require_relative 'installation/recovery'
+
+module Woods
+  module Watch
+    # Plans and applies portable, explicitly owned watcher startup configuration.
+    class Installation
+      Conflict = Woods::AgentConfiguration::Conflict
+
+      # @param root [String] application directory
+      # @param options [Hash] mode, operation, child/manager argv and preflight options
+      def initialize(root:, **options)
+        @options = Options.new(root: root, **options)
+        @layout = Layout.new(@options.root, @options.procfile)
+      end
+
+      # Preview all edits without creating files or starting a watcher.
+      # @return [Woods::AgentConfiguration::Plan]
+      def plan
+        @options.validate!
+        Planner.new(layout: @layout, options: @options).call
+      end
+
+      # Apply a fresh or previously reviewed plan using conflict-checked writes.
+      # @param reviewed_plan [Woods::AgentConfiguration::Plan, nil] optional preview
+      # @return [String] applied or already_applied
+      def apply(reviewed_plan = nil)
+        selected = reviewed_plan || plan
+        return 'already_applied' if selected.data.fetch('changes').empty?
+
+        Woods::AgentConfiguration::Applier.new(layout: @layout).apply(selected)
+      end
+
+      # Explain which process must own this installation.
+      # @return [String]
+      def handoff
+        @options.handoff
+      end
+
+      # Recover an interrupted transaction without booting the application.
+      # @param pretend [Boolean] validate the journal without restoring files
+      # @return [String] recovery outcome
+      def recover(pretend: false)
+        Recovery.new(root: @options.root).call(pretend: pretend)
+      end
+    end
+  end
+end

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