woods 2.0.0.beta3 → 2.0.0

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Woods
+  module Watch
+    class Installation
+      # Validates portable ownership before any current file is changed.
+      class Receipt
+        attr_reader :data
+
+        # @param document [Woods::AgentConfiguration::Document] portable receipt
+        def initialize(document)
+          @data = document.content && document.json
+          validate! if data
+        end
+
+        # @return [Array<String>] portable paths recorded by this installation
+        def paths
+          return [] unless data
+
+          data.fetch('files').keys + data.fetch('sections').keys
+        end
+
+        # @param document [Woods::AgentConfiguration::Document] owned file
+        # @param expected [Hash] prior content fingerprint and mode
+        # @return [void]
+        def self.verify_file!(document, expected)
+          return if document.fingerprint == expected
+
+          raise Conflict, "Owned watcher file was edited or removed: #{document.path}"
+        end
+
+        private
+
+        def validate!
+          unless data['schema_version'] == 1 && data['selection'].is_a?(Hash) &&
+                 %w[procfile puma external].include?(data.dig('selection', 'mode')) &&
+                 data['files'].is_a?(Hash) && data['sections'].is_a?(Hash)
+            raise Conflict, 'Malformed watcher installation receipt; restore its owned metadata'
+          end
+
+          validate_files!
+          validate_sections!
+        end
+
+        def validate_files!
+          data.fetch('files').each do |path, record|
+            next if path == Layout::WRAPPER && valid_file_record?(record)
+
+            raise Conflict, 'Invalid owned watcher executable in receipt'
+          end
+        end
+
+        def validate_sections!
+          data.fetch('sections').each do |path, record|
+            valid_path = path == Layout::PUMA || Layout::PROCFILE.match?(path)
+            next if valid_path && valid_section_record?(record)
+
+            raise Conflict, 'Invalid owned watcher section in receipt'
+          end
+        end
+
+        def valid_file_record?(record)
+          record.is_a?(Hash) && record['exists'] == true && record['mode'] == 0o755 &&
+            record['sha256'].is_a?(String) && record['sha256'].match?(/\A[0-9a-f]{64}\z/)
+        end
+
+        def valid_section_record?(record)
+          record.is_a?(Hash) && [true, false].include?(record['created_file']) &&
+            record['owned_text'].is_a?(String) && record['owned_text'].include?(Templates::START) &&
+            record['owned_text'].include?(Templates::FINISH)
+        end
+      end
+    end
+  end
+end

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