ruby_raider 4.0.1 → 4.1.0

data/lib/utilities/flows/next_run.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'date'
+require_relative 'schedule'
+
+module RubyRaider
+  module Flows
+    # When a schedule next runs, in local time, as launchd, schtasks, systemd and cron count it.
+    # A day, weekday or week rule whose time falls in a spring-forward gap runs at the first minute
+    # after the gap; one that falls in a fall-back hour runs at its first occurrence only.
+    # An hour rule runs at every real instant whose local minute matches, so twice in a fall-back hour.
+    module NextRun
+      WDAYS = %w[sun mon tue wed thu fri sat].freeze
+      # The longest stretch to search: a week rule, plus a day of slack
+      SEARCH_DAYS = 8
+      # The minutes to search for an hour rule: an hour, plus an hour of offset change
+      SEARCH_MINUTES = 120
+
+      module_function
+
+      def after(schedule, now)
+        local_now = now.getlocal
+        schedule.every == 'hour' ? next_minute(schedule.minute, local_now) : next_day(schedule, local_now)
+      end
+
+      def next_minute(minute, now)
+        time = Time.at(now.to_i - now.sec + 60).localtime
+        SEARCH_MINUTES.times do
+          return time if time.min == minute
+
+          time += 60
+        end
+        raise Error, "No local time with minute #{minute} after #{now}"
+      end
+
+      def next_day(schedule, now)
+        today = Date.new(now.year, now.month, now.day)
+        (0..SEARCH_DAYS).each do |offset|
+          date = today + offset
+          next unless schedule.days.include?(WDAYS[date.wday])
+
+          time = local(date, schedule.hour, schedule.minute)
+          return time if time > now
+        end
+        raise Error, "No run for #{schedule.rule_text} after #{now}"
+      end
+
+      # The first instant whose local wall clock reaches date hour:minute
+      def local(date, hour, minute)
+        wanted = [date.year, date.month, date.day, hour, minute]
+        time = Time.local(*wanted)
+        time += 60 while (wall(time) <=> wanted).negative?
+        time -= 60 until (wall(time - 60) <=> wanted).negative?
+        earlier = time - 3600
+        wall(earlier) == wanted ? earlier : time
+      end
+
+      def wall(time) = [time.year, time.month, time.day, time.hour, time.min]
+    end
+  end
+end

data/lib/utilities/flows/notifier.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'rbconfig'
+require_relative 'project'
+require_relative 'os/command_runner'
+
+module RubyRaider
+  module Flows
+    # A desktop notification for `raider flow run --notify`. The title and message only ever travel as argv
+    # items after `--` (osascript, notify-send: so a title like -e is not read as an option or a script) or as
+    # environment values (PowerShell), so a hostile flow name or step title can't run as AppleScript or PowerShell. Never raises: a notification
+    # that can't be shown must not change how the run ends.
+    # :reek:TooManyConstants { max_constants: 7 } -- the fixed command of each OS, the message cap and the timeout
+    # :reek:TooManyInstanceVariables { max_instance_variables: 5 } -- the injected runner, OS, stream and PowerShell path, and the warned flag
+    class Notifier
+      MAX = 200
+      TIMEOUT = 15
+      OSASCRIPT = ['/usr/bin/osascript', '-e', 'on run argv', '-e',
+                   'display notification (item 2 of argv) with title (item 1 of argv)', '-e', 'end run', '--'].freeze
+      NOTIFY_SEND = ['notify-send', '--app-name=Ruby Raider', '--'].freeze
+      MARKUP = { '&' => '&amp;', '<' => '&lt;', '>' => '&gt;' }.freeze
+      # Reads the text from the environment and sets it as XML text nodes; one line with no double quotes, so
+      # Windows command-line quoting can't split it. Shown under PowerShell's own app id, which Windows accepts.
+      TOAST_SCRIPT = [
+        "$ErrorActionPreference = 'Stop'",
+        '$null = [Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime]',
+        '$xml = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02)',
+        "$texts = $xml.GetElementsByTagName('text')",
+        '$null = $texts.Item(0).AppendChild($xml.CreateTextNode($env:RAIDER_NOTIFY_TITLE))',
+        '$null = $texts.Item(1).AppendChild($xml.CreateTextNode($env:RAIDER_NOTIFY_MESSAGE))',
+        '$toast = [Windows.UI.Notifications.ToastNotification]::new($xml)',
+        "[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\\WindowsPowerShell\\v1.0\\powershell.exe').Show($toast)"
+      ].join('; ').freeze
+      POWERSHELL_ARGS = ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', TOAST_SCRIPT].freeze
+
+      def self.powershell = File.join(ENV.fetch('SystemRoot', 'C:\\Windows'), 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe')
+
+      def initialize(runner: Os::CommandRunner.new, host_os: RbConfig::CONFIG['host_os'], err: $stderr, powershell: Notifier.powershell)
+        @runner = runner
+        @host_os = host_os
+        @err = err
+        @powershell = powershell
+        @warned = false
+      end
+
+      # True when the notification was handed to the desktop
+      def notify(title, message)
+        title = clean(title)
+        message = clean(message)
+        result = case @host_os
+                 when /darwin/ then @runner.call(*OSASCRIPT, title, message, timeout: TIMEOUT)
+                 when /linux/ then @runner.call(*NOTIFY_SEND, title, message.gsub(/[&<>]/, MARKUP), timeout: TIMEOUT)
+                 when /mswin|mingw|cygwin/
+                   @runner.call(@powershell, *POWERSHELL_ARGS, env: { 'RAIDER_NOTIFY_TITLE' => title, 'RAIDER_NOTIFY_MESSAGE' => message },
+                                                               timeout: TIMEOUT)
+                 end
+        return false unless result
+        return true if result.success?
+
+        failed(result.stderr)
+      rescue StandardError => e
+        failed(e.message)
+      end
+
+      private
+
+      def clean(text) = Flows.printable(text)[0, MAX].to_s
+
+      def failed(reason)
+        @err.puts("Could not show a desktop notification: #{Flows.printable(reason.strip)}") unless @warned
+        @warned = true
+        false
+      end
+    end
+  end
+end

data/lib/utilities/flows/os/command_runner.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module RubyRaider
+  module Flows
+    module Os
+      # Runs an OS scheduler command (launchctl, schtasks, systemctl, crontab) with no shell. Adapters
+      # take one, so tests pass a double and never touch the real scheduler.
+      class CommandRunner
+        MISSING = 127
+        TIMED_OUT = 124
+
+        # What a command printed and how it exited
+        class Result
+          attr_reader :stdout, :stderr, :exitstatus
+
+          def initialize(stdout:, stderr:, exitstatus:)
+            @stdout = stdout
+            @stderr = stderr
+            @exitstatus = exitstatus
+            freeze
+          end
+
+          def success? = exitstatus.zero?
+        end
+
+        # [command, command] as the first item keeps even a lone string out of a shell; env adds to the inherited
+        # one. With a timeout (seconds) a command still running then is killed and fails.
+        def call(*argv, stdin_data: nil, env: {}, timeout: nil)
+          command = argv.first.to_s
+          Open3.popen3(env, [command, command], *argv.drop(1).map(&:to_s)) do |stdin, stdout, stderr, wait|
+            readers = [stdout, stderr].map { |io| reader(io) }
+            feed(stdin, stdin_data)
+            next timed_out(command, timeout, wait) unless wait.join(timeout)
+
+            status = wait.value
+            Result.new(stdout: readers[0].value, stderr: readers[1].value, exitstatus: status.exitstatus || (128 + status.termsig.to_i))
+          end
+        rescue SystemCallError => e
+          Result.new(stdout: '', stderr: "Could not run #{command}: #{e.message}", exitstatus: MISSING)
+        end
+
+        private
+
+        # Read in a thread, so a full pipe can't block the command; quiet when the pipe is closed under it
+        def reader(io)
+          thread = Thread.new { io.read.to_s }
+          thread.report_on_exception = false
+          thread
+        end
+
+        def feed(stdin, data)
+          stdin.write(data.to_s)
+        rescue Errno::EPIPE
+          nil
+        ensure
+          stdin.close
+        end
+
+        def timed_out(command, timeout, wait)
+          begin
+            Process.kill('KILL', wait.pid)
+          rescue SystemCallError
+            nil
+          end
+          wait.join
+          Result.new(stdout: '', stderr: "#{command} took longer than #{timeout} s", exitstatus: TIMED_OUT)
+        end
+      end
+    end
+  end
+end

data/lib/utilities/flows/os/cron.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+require_relative 'command_runner'
+require_relative '../schedule'
+
+module RubyRaider
+  module Flows
+    module Os
+      # Linux without a systemd user manager: one tagged block per schedule in the user's crontab, read with
+      # `crontab -l` and written back with `crontab -`. Every value goes through Shellwords.escape, which also
+      # escapes % as \% (cron would turn a bare % into a newline). Lines that are not ours keep every byte.
+      class Cron
+        CRONTAB = 'crontab'
+        TAG = '# raider-flow '
+        # Debian's vixie cron cuts a command at MAX_COMMAND (1000) bytes without a word; stay under it
+        MAX_LINE = 990
+        OS_ID = /\A#{Regexp.escape(Schedule::OS_ID_PREFIX)}\.[0-9a-f]{10}\.([a-z0-9_]{1,60})\z/
+
+        def initialize(runner: CommandRunner.new)
+          @runner = runner
+        end
+
+        def label = 'cron'
+
+        def missed_runs_note = '(cron: missed runs are skipped)'
+
+        # Minute hour day-of-month month day-of-week (the system time zone), then the command for /bin/sh
+        def line(schedule)
+          ruby = schedule.ruby
+          raise Error, "cron can not run ruby from #{Flows.printable(ruby)}: env would read the = as a variable" if ruby.include?('=')
+
+          env = schedule.env.map { |key, value| "#{key}=#{value}" }
+          command = ['cd', escape(schedule.working_directory), '&&', '/usr/bin/env', *[*env, *schedule.argv].map { |word| escape(word) },
+                     '>>', escape(schedule.log_path), '2>&1']
+          "#{fields(schedule)} #{command.join(' ')}"
+        end
+
+        # Our block goes first: above any SHELL=, CRON_TZ= or MAILTO= line, and with no byte of the rest changed
+        def install(schedule)
+          os_id = schedule.os_id
+          entry = line(schedule)
+          raise Error, "cron can not run #{schedule.name}: its crontab line is #{entry.bytesize} bytes, over #{MAX_LINE}" if entry.bytesize > MAX_LINE
+
+          rest, = without(read, os_id)
+          save("#{TAG}#{os_id}\n#{entry}\n#{rest}")
+          true
+        end
+
+        # True when our block was there and is gone, false when it was already gone
+        def remove(os_id)
+          tag = checked_os_id(os_id)
+          rest, found = without(read, tag)
+          save(rest) if found
+          found
+        end
+
+        def present?(os_id)
+          tag = checked_os_id(os_id)
+          without(read, tag).last
+        end
+
+        # True when crontab -l answers (an empty crontab counts)
+        def usable?
+          read
+          true
+        rescue Error
+          false
+        end
+
+        private
+
+        def fields(schedule)
+          minute = schedule.minute
+          return "#{minute} * * * *" if schedule.every == 'hour'
+
+          day = case schedule.every
+                when 'weekday' then '1-5'
+                when 'week' then weekday(schedule.on.to_s).to_s
+                else '*'
+                end
+          "#{minute} #{schedule.hour} * * #{day}"
+        end
+
+        # cron counts Sunday as 0
+        def weekday(day)
+          index = Schedule::DAYS.index(day)
+          raise Error, "Invalid day #{day.inspect}" unless index
+
+          (index + 1) % 7
+        end
+
+        def escape(word) = Shellwords.escape(word)
+
+        # The crontab without any of our tag lines, each with the line after it when that line is our command,
+        # and whether a tag was there
+        def without(table, os_id)
+          tag = "#{TAG}#{os_id}"
+          name = OS_ID.match(os_id).to_a[1]
+          kept = []
+          found = after_tag = false
+          table.lines.each do |text|
+            ours = text.chomp == tag || (after_tag && our_command?(text, name))
+            after_tag = text.chomp == tag
+            found ||= after_tag
+            kept << text unless ours
+          end
+          [kept.join, found]
+        end
+
+        # The line under our tag runs `raider flow run <name> --project ... --trigger schedule`
+        def our_command?(text, name) = text.include?(" exec raider flow run #{name} --project ") && text.include?(' --trigger schedule')
+
+        def read
+          result = @runner.call(CRONTAB, '-l')
+          return result.stdout if result.success?
+
+          stderr = result.stderr
+          return '' if stderr.match?(/no crontab/i)
+
+          raise Error, "cron could not read the crontab: #{Flows.printable(stderr.strip)}"
+        end
+
+        def save(table)
+          result = @runner.call(CRONTAB, '-', stdin_data: table)
+          raise Error, "cron could not save the crontab: #{Flows.printable(result.stderr.strip)}" unless result.success?
+        end
+
+        def checked_os_id(os_id)
+          return os_id if os_id.is_a?(String) && (match = OS_ID.match(os_id)) && Flows.valid_name?(match[1])
+
+          raise Error, "Invalid os_id #{Flows.printable(os_id.inspect)}: not a flow schedule"
+        end
+      end
+    end
+  end
+end

data/lib/utilities/flows/os/launchd.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'securerandom'
+require_relative 'command_runner'
+require_relative '../schedule'
+
+module RubyRaider
+  module Flows
+    module Os
+      # macOS: a LaunchAgent plist in ~/Library/LaunchAgents per schedule, loaded into the user's GUI
+      # domain with launchctl. Every value in the plist goes through one XML escaper.
+      # :reek:TooManyConstants { max_constants: 6 } -- the two tools, NOFOLLOW, the XML escapes and header, the os_id rule
+      class Launchd
+        LAUNCHCTL = '/bin/launchctl'
+        PLUTIL = '/usr/bin/plutil'
+        NOFOLLOW = defined?(File::NOFOLLOW) ? File::NOFOLLOW : 0
+        ESCAPES = { '&' => '&amp;', '<' => '&lt;', '>' => '&gt;', '"' => '&quot;', "'" => '&apos;' }.freeze
+        HEADER = <<~XML
+          <?xml version="1.0" encoding="UTF-8"?>
+          <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+          <plist version="1.0">
+        XML
+        OS_ID = /\A#{Regexp.escape(Schedule::OS_ID_PREFIX)}\.[0-9a-f]{10}\.([a-z0-9_]{1,60})\z/
+
+        def initialize(runner: CommandRunner.new, home: Dir.home, uid: Process.uid)
+          @runner = runner
+          @home = home
+          @uid = uid
+        end
+
+        def label = 'launchd'
+
+        # The LaunchAgent plist for the schedule (local time, no RunAtLoad)
+        def plist(schedule)
+          path = schedule.log_path
+          entries = [
+            ['Label', string(schedule.os_id)],
+            ['ProgramArguments', array(schedule.argv.map { |arg| string(arg) })],
+            ['WorkingDirectory', string(schedule.working_directory)],
+            ['StandardOutPath', string(path)],
+            ['StandardErrorPath', string(path)],
+            ['EnvironmentVariables', dict(schedule.env.map { |key, value| [key, string(value)] })],
+            ['StartCalendarInterval', calendar(schedule)]
+          ]
+          "#{HEADER}#{dict(entries).join("\n")}\n</plist>\n"
+        end
+
+        def plist_path(os_id) = File.join(agents_dir, "#{checked_os_id(os_id)}.plist")
+
+        # Writes the plist (linted before it replaces anything), then reloads the service
+        def install(schedule)
+          os_id = schedule.os_id
+          path = plist_path(os_id)
+          write(path, plist(schedule))
+          launchctl('bootout', service(os_id))
+          result = launchctl('bootstrap', domain, path)
+          return true if result.success?
+
+          raise Error, "launchd could not load #{os_id}: #{Flows.printable(result.stderr.strip)}#{discard(path)}"
+        end
+
+        # True when a plist or a loaded service was removed, false when it was already gone
+        def remove(os_id)
+          path = plist_path(os_id)
+          unloaded = launchctl('bootout', service(os_id)).success?
+          unlink(path) || unloaded
+        end
+
+        def present?(os_id) = launchctl('print', service(checked_os_id(os_id))).success?
+
+        private
+
+        def launchctl(*args) = @runner.call(LAUNCHCTL, *args)
+
+        def domain = "gui/#{@uid}"
+
+        def service(os_id) = "#{domain}/#{os_id}"
+
+        # True when the plist was there; a plist that stays behind is an error, not "already gone"
+        def unlink(path)
+          File.unlink(path)
+          true
+        rescue Errno::ENOENT
+          false
+        rescue SystemCallError => e
+          raise Error, "Could not remove #{path}: #{e.message}"
+        end
+
+        def agents_dir = File.join(@home, 'Library', 'LaunchAgents')
+
+        def checked_os_id(os_id)
+          return os_id if os_id.is_a?(String) && (match = OS_ID.match(os_id)) && Flows.valid_name?(match[1])
+
+          raise Error, "Invalid os_id #{Flows.printable(os_id.inspect)}: not a flow schedule"
+        end
+
+        def escape(text) = text.to_s.gsub(/[&<>"']/, ESCAPES)
+
+        def string(text) = ["<string>#{escape(text)}</string>"]
+
+        def integer(number) = ["<integer>#{Integer(number)}</integer>"]
+
+        def array(items) = ['<array>', *indent(items.flatten), '</array>']
+
+        def dict(pairs)
+          body = pairs.flat_map { |key, value| ["<key>#{escape(key)}</key>", *value] }
+          ['<dict>', *indent(body), '</dict>']
+        end
+
+        def indent(lines) = lines.map { |line| "\t#{line}" }
+
+        # Schedule::DAYS runs mon..sun
+        def calendar(schedule)
+          time = [['Hour', integer(schedule.hour)], ['Minute', integer(schedule.minute)]]
+          case schedule.every
+          when 'hour' then dict([['Minute', integer(schedule.minute)]])
+          when 'day' then dict(time)
+          else
+            days = schedule.days.map { |day| dict([['Weekday', integer(weekday(day))], *time]) }
+            schedule.every == 'week' ? days.first : array(days)
+          end
+        end
+
+        # launchd counts Sunday as 0
+        def weekday(day)
+          index = Schedule::DAYS.index(day)
+          raise Error, "Invalid day #{day.inspect}" unless index
+
+          (index + 1) % 7
+        end
+
+        # Removes the plist a failed bootstrap left; returns what to add to the error when it stays behind
+        def discard(path)
+          unlink(path)
+          ''
+        rescue Error => e
+          "; also: #{e.message}"
+        end
+
+        # Temp file in the same folder, checked with plutil, then renamed over the old plist
+        def write(path, text)
+          dir = File.dirname(path)
+          FileUtils.mkdir_p(dir)
+          temp = File.join(dir, ".#{File.basename(path)}.#{SecureRandom.hex(6)}.tmp")
+          File.open(temp, File::WRONLY | File::CREAT | File::EXCL | NOFOLLOW, 0o644) do |file|
+            file.write(text)
+            file.flush
+            file.fsync
+            file.chmod(0o644)
+          end
+          lint = @runner.call(PLUTIL, '-lint', temp)
+          raise Error, "launchd plist for #{File.basename(path)} is invalid: #{Flows.printable("#{lint.stdout} #{lint.stderr}".strip)}" unless lint.success?
+
+          File.rename(temp, path)
+        rescue SystemCallError => e
+          raise Error, "Could not write #{path}: #{e.message}"
+        ensure
+          FileUtils.rm_f(temp) if temp && File.exist?(temp)
+        end
+      end
+    end
+  end
+end

data/lib/utilities/flows/os/linux.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative 'command_runner'
+require_relative 'systemd'
+require_relative 'cron'
+
+module RubyRaider
+  module Flows
+    module Os
+      # Linux: systemd user timers when the user's systemd manager answers, cron otherwise. A schedule made over
+      # ssh (no user bus, so cron) must still go when unscheduled from a desktop session, so remove and present?
+      # also look in the other scheduler when it answers. The reverse (a systemd timer, unscheduled where no user
+      # bus answers) can only be seen from its unit files, and can only be removed where systemctl --user works.
+      class Linux
+        def self.pick(runner = CommandRunner.new) = new(runner: runner)
+
+        def initialize(runner: CommandRunner.new, systemd: Systemd.new(runner: runner), cron: Cron.new(runner: runner))
+          # systemd is the other one only when it answers, so with cron first there is no other one
+          @systemd = systemd
+          @primary, @other = systemd.usable? ? [systemd, cron] : [cron, nil]
+        end
+
+        def label = @primary.label
+
+        def missed_runs_note = @primary.missed_runs_note
+
+        def install(schedule) = @primary.install(schedule)
+
+        # True when either scheduler removed something
+        def remove(os_id)
+          removed = @primary.remove(os_id)
+          other = @other
+          other_removed = other&.usable? ? other.remove(os_id) : false
+          refuse_stranded(os_id)
+          removed || other_removed
+        end
+
+        # True when either scheduler has it, or systemd unit files are there though systemd does not answer
+        def present?(os_id) = @primary.present?(os_id) || other_present?(os_id) || stranded?(os_id)
+
+        private
+
+        def stranded?(os_id) = @primary != @systemd && @systemd.unit_files?(os_id)
+
+        # Raises so the schedules.yml entry stays until the timer can really go
+        def refuse_stranded(os_id)
+          return unless stranded?(os_id)
+
+          raise Error, "This schedule is a systemd timer; run raider flow unschedule #{os_id.split('.').last} " \
+                       'from a session where systemctl --user works'
+        end
+
+        # The other scheduler failing counts as not there
+        def other_present?(os_id)
+          other = @other
+          other&.usable? ? other.present?(os_id) : false
+        rescue Error
+          false
+        end
+      end
+    end
+  end
+end