wheneverd 0.2.1 → 0.4.0

data/lib/wheneverd/dsl/period_strategy/array_strategy.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "../calendar_symbol_period_list"
+
+module Wheneverd
+  module DSL
+    module PeriodStrategy
+      # Strategy for parsing Array period values.
+      #
+      # Handles arrays of calendar symbols like [:monday, :wednesday, :friday].
+      class ArrayStrategy < Base
+        def handles?(period)
+          period.is_a?(Array)
+        end
+
+        def parse(periods, at_times:)
+          bases = CalendarSymbolPeriodList.validate(
+            periods,
+            allowed_symbols: CALENDAR_SYMBOLS,
+            path: path
+          ).map(&:to_s)
+
+          specs = bases.flat_map { |base| build_calendar_specs(base, at_times) }.uniq
+          calendar_trigger(on_calendar: specs)
+        end
+      end
+    end
+  end
+end

data/lib/wheneverd/dsl/period_strategy/base.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  module DSL
+    module PeriodStrategy
+      # Base class for period parsing strategies.
+      #
+      # Each strategy handles a specific type of period value (Duration, String, Symbol, Array)
+      # and converts it into a trigger object.
+      class Base
+        DAY_SECONDS = 60 * 60 * 24
+
+        CALENDAR_SYMBOLS = %i[
+          hour day month year weekday weekend
+          monday tuesday wednesday thursday friday saturday sunday
+        ].freeze
+
+        attr_reader :path
+
+        # @param path [String] schedule path for error reporting
+        def initialize(path:)
+          @path = path
+        end
+
+        # Check if this strategy handles the given period type.
+        #
+        # @param period [Object] the period value
+        # @return [Boolean]
+        def handles?(_period)
+          raise NotImplementedError, "#{self.class} must implement #handles?"
+        end
+
+        # Parse the period into a trigger.
+        #
+        # @param period [Object] the period value
+        # @param at_times [Array<String>] normalized at: times
+        # @return [Wheneverd::Trigger::Interval, Wheneverd::Trigger::Calendar]
+        # @raise [Wheneverd::DSL::InvalidPeriodError]
+        def parse(_period, at_times:)
+          raise NotImplementedError, "#{self.class} must implement #parse"
+        end
+
+        protected
+
+        def raise_period_error(message)
+          raise InvalidPeriodError.new(message, path: path)
+        end
+
+        def build_calendar_specs(base, at_times)
+          return [base] if at_times.empty?
+
+          at_times.map { |t| "#{base}@#{t}" }
+        end
+
+        def calendar_trigger(on_calendar:)
+          Wheneverd::Trigger::Calendar.new(on_calendar: on_calendar)
+        end
+
+        def interval_trigger(seconds:)
+          Wheneverd::Trigger::Interval.new(seconds: seconds)
+        end
+      end
+    end
+  end
+end

data/lib/wheneverd/dsl/period_strategy/duration_strategy.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  module DSL
+    module PeriodStrategy
+      # Strategy for parsing Duration period values.
+      #
+      # Duration values produce Interval triggers, except for 1.day with at: times
+      # which produces a Calendar trigger for daily scheduling.
+      class DurationStrategy < Base
+        def handles?(period)
+          period.is_a?(Wheneverd::Duration)
+        end
+
+        def parse(duration, at_times:)
+          if at_times.any?
+            return daily_calendar_trigger(at_times) if duration.to_i == DAY_SECONDS
+
+            raise_period_error("at: is only supported with calendar periods")
+          end
+
+          interval_trigger(seconds: duration.to_i)
+        end
+
+        private
+
+        def daily_calendar_trigger(at_times)
+          calendar_trigger(on_calendar: build_calendar_specs("day", at_times))
+        end
+      end
+    end
+  end
+end

data/lib/wheneverd/dsl/period_strategy/string_strategy.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  module DSL
+    module PeriodStrategy
+      # Strategy for parsing String period values.
+      #
+      # Handles interval strings (e.g., "5m", "1h") and cron expressions.
+      class StringStrategy < Base
+        INTERVAL_PATTERN = /\A-?\d+[smhdw]\z/.freeze
+
+        def handles?(period)
+          period.is_a?(String)
+        end
+
+        def parse(str, at_times:)
+          period_str = str.strip
+
+          return parse_interval(period_str, at_times: at_times) if interval_string?(period_str)
+
+          return parse_cron(period_str, at_times: at_times) if cron_string?(period_str)
+
+          raise_period_error("Unrecognized period #{period_str.inspect}")
+        end
+
+        private
+
+        def parse_interval(period_str, at_times:)
+          raise_period_error("at: is not supported for interval periods") if at_times.any?
+
+          seconds = Wheneverd::Interval.parse(period_str)
+          interval_trigger(seconds: seconds)
+        end
+
+        def parse_cron(period_str, at_times:)
+          raise_period_error("at: is not supported for cron periods") if at_times.any?
+
+          calendar_trigger(on_calendar: ["cron:#{period_str}"])
+        end
+
+        def interval_string?(str)
+          INTERVAL_PATTERN.match?(str)
+        end
+
+        def cron_string?(str)
+          str.split(/\s+/).length == 5
+        end
+      end
+    end
+  end
+end

data/lib/wheneverd/dsl/period_strategy/symbol_strategy.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  module DSL
+    module PeriodStrategy
+      # Strategy for parsing Symbol period values.
+      #
+      # Handles calendar symbols like :day, :monday, :weekend, etc.
+      class SymbolStrategy < Base
+        REBOOT_NOT_SUPPORTED_MESSAGE =
+          "The :reboot period is not supported; use an interval or calendar period instead"
+
+        def handles?(period)
+          period.is_a?(Symbol)
+        end
+
+        def parse(sym, at_times:)
+          raise_period_error(REBOOT_NOT_SUPPORTED_MESSAGE) if sym == :reboot
+
+          if CALENDAR_SYMBOLS.include?(sym)
+            return calendar_trigger(
+              on_calendar: build_calendar_specs(sym.to_s, at_times)
+            )
+          end
+
+          raise_period_error("Unknown period symbol: #{sym.inspect}")
+        end
+      end
+    end
+  end
+end

data/lib/wheneverd/dsl/period_strategy.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "period_strategy/base"
+require_relative "period_strategy/duration_strategy"
+require_relative "period_strategy/string_strategy"
+require_relative "period_strategy/symbol_strategy"
+require_relative "period_strategy/array_strategy"
+
+module Wheneverd
+  module DSL
+    # Period parsing strategies for converting DSL period values into triggers.
+    #
+    # Each strategy handles a specific type of period value and converts it
+    # into the appropriate trigger type.
+    module PeriodStrategy
+      # Default strategies in order of precedence.
+      DEFAULT_STRATEGIES = [
+        DurationStrategy,
+        ArrayStrategy,
+        StringStrategy,
+        SymbolStrategy
+      ].freeze
+
+      # Find the strategy that handles the given period type.
+      #
+      # @param period [Object] the period value
+      # @param path [String] schedule path for error reporting
+      # @return [Base] the strategy instance
+      # @raise [Wheneverd::DSL::InvalidPeriodError] if no strategy handles the period
+      def self.for(period, path:)
+        strategy_class = DEFAULT_STRATEGIES.find do |klass|
+          klass.new(path: path).handles?(period)
+        end
+
+        if strategy_class.nil?
+          raise InvalidPeriodError.new("Unsupported period type: #{period.class}", path: path)
+        end
+
+        strategy_class.new(path: path)
+      end
+    end
+  end
+end

data/lib/wheneverd/duration.rb

@@ -11,13 +11,7 @@ module Wheneverd
 
     # @param seconds [Integer] duration in seconds (must be positive)
     def initialize(seconds)
-      unless seconds.is_a?(Integer)
-        raise ArgumentError, "Duration seconds must be an Integer (got #{seconds.class})"
-      end
-
-      raise ArgumentError, "Duration seconds must be positive (got #{seconds})" if seconds <= 0
-
-      @seconds = seconds
+      @seconds = Validation.positive_integer(seconds, name: "Duration seconds")
     end
 
     def to_i

data/lib/wheneverd/errors.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 module Wheneverd
+  # Base error class for wheneverd exceptions.
+  class Error < StandardError; end
+
   # Raised when {Wheneverd::Interval.parse} cannot parse or validate an interval string.
   class InvalidIntervalError < Error; end
 

data/lib/wheneverd/interval.rb

@@ -21,17 +21,32 @@ module Wheneverd
     # @return [Integer] seconds
     # @raise [Wheneverd::InvalidIntervalError] if the input is invalid
     def self.parse(str)
-      input = str.to_s.strip
+      input = normalize_input(str)
+      match = parse_match(input)
+      n = parse_number(match[:n], input)
+      n * MULTIPLIERS.fetch(match[:unit])
+    end
+
+    def self.normalize_input(str)
+      str.to_s.strip
+    end
+    private_class_method :normalize_input
+
+    def self.parse_match(input)
       match = FORMAT.match(input)
-      unless match
-        raise InvalidIntervalError,
-              "Invalid interval #{input.inspect}; expected <n>s|m|h|d|w (example: \"5m\")"
-      end
+      return match if match
+
+      raise InvalidIntervalError,
+            "Invalid interval #{input.inspect}; expected <n>s|m|h|d|w (example: \"5m\")"
+    end
+    private_class_method :parse_match
 
-      n = Integer(match[:n], 10)
+    def self.parse_number(number_str, input)
+      n = Integer(number_str, 10)
       raise InvalidIntervalError, "Interval must be positive (got #{input.inspect})" if n <= 0
 
-      n * MULTIPLIERS.fetch(match[:unit])
+      n
     end
+    private_class_method :parse_number
   end
 end

data/lib/wheneverd/job/command.rb

@@ -4,25 +4,105 @@ module Wheneverd
   module Job
     # A oneshot command job rendered as `ExecStart=` in a `systemd` service unit.
     #
-    # Note that the command is inserted into `ExecStart=` as-is. If you need shell features like
-    # pipes, redirects, or environment variable expansion, wrap the command explicitly:
+    # This job accepts either:
+    #
+    # - A String (inserted into `ExecStart=` as-is, after stripping surrounding whitespace), or
+    # - An argv Array (formatted/escaped into a systemd-compatible `ExecStart=` string).
+    #
+    # If you need shell features like pipes, redirects, or environment variable expansion, wrap
+    # the command explicitly:
     #
     # @example
     #   command "/bin/bash -lc 'echo hello | sed -e s/hello/hi/'"
+    #
+    # @example argv form (safer argument handling)
+    #   command ["/bin/bash", "-lc", "echo hello | sed -e s/hello/hi/"]
     class Command
+      SAFE_UNQUOTED = %r{\A[A-Za-z0-9_@%+=:,./-]+\z}.freeze
+
+      # Rendered `ExecStart=` value.
+      #
       # @return [String]
       attr_reader :command
 
-      # @param command [String] non-empty command to run
+      # Original argv form (when constructed with an Array).
+      #
+      # @return [Array<String>, nil]
+      attr_reader :argv
+
+      # Stable signature used for unit naming.
+      #
+      # @return [String]
+      attr_reader :signature
+
+      # @param command [String, Array<String>] non-empty command to run
       def initialize(command:)
-        unless command.is_a?(String)
-          raise InvalidCommandError, "Command must be a String (got #{command.class})"
+        @argv = nil
+        @signature = nil
+        @command = nil
+
+        case command
+        when String then init_string(command)
+        when Array then init_argv(command)
+        else
+          raise InvalidCommandError,
+                "Command must be a String or an Array (got #{command.class})"
         end
+      end
+
+      private
+
+      def init_string(command)
+        stripped = command.strip
+        raise InvalidCommandError, "Command must not be empty" if stripped.empty?
+
+        @command = stripped
+        @signature = "command:#{@command}"
+      end
+
+      def init_argv(argv)
+        normalized = normalize_argv(argv)
+        @argv = normalized
+        @command = format_execstart(normalized)
+        @signature = ["command:argv", normalized.join("\n")].join("\n")
+      end
 
-        command_stripped = command.strip
-        raise InvalidCommandError, "Command must not be empty" if command_stripped.empty?
+      def normalize_argv(argv)
+        raise InvalidCommandError, "Command argv must not be empty" if argv.empty?
+
+        elements = argv.map { |arg| validate_argv_element(arg) }
+        elements[0] = elements[0].strip
+        raise InvalidCommandError, "Command argv executable must not be empty" if elements[0].empty?
+
+        elements
+      end
+
+      def validate_argv_element(arg)
+        unless arg.is_a?(String)
+          raise InvalidCommandError, "Command argv elements must be Strings (got #{arg.class})"
+        end
+
+        if arg.match?(/[\0\r\n]/)
+          raise InvalidCommandError,
+                "Command argv elements must not include NUL or newlines"
+        end
+
+        arg
+      end
+
+      def format_execstart(argv)
+        argv.map { |arg| format_exec_arg(arg) }.join(" ")
+      end
+
+      def format_exec_arg(arg)
+        return "\"\"" if arg.empty?
+        return arg if SAFE_UNQUOTED.match?(arg)
+
+        "\"#{escape_exec_arg(arg)}\""
+      end
 
-        @command = command_stripped
+      def escape_exec_arg(arg)
+        arg.gsub(/[\\"]/) { |m| "\\#{m}" }
       end
     end
   end

data/lib/wheneverd/systemd/analyze.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Wheneverd
+  module Systemd
+    # Thin wrapper around `systemd-analyze`.
+    class Analyze
+      DEFAULT_SYSTEMD_ANALYZE = "systemd-analyze"
+
+      # Run `systemd-analyze calendar <value>`.
+      #
+      # @param value [String] an `OnCalendar=` value
+      # @param systemd_analyze [String] path to the `systemd-analyze` executable
+      # @return [Array(String, String)] stdout and stderr
+      # @raise [Wheneverd::Systemd::SystemdAnalyzeError]
+      def self.calendar(value, systemd_analyze: DEFAULT_SYSTEMD_ANALYZE)
+        run(systemd_analyze, "calendar", value.to_s)
+      end
+
+      # Run `systemd-analyze verify` for unit files.
+      #
+      # @param paths [Array<String>] unit file paths to verify
+      # @param user [Boolean] verify user units with `--user` (default: true)
+      # @param systemd_analyze [String] path to the `systemd-analyze` executable
+      # @return [Array(String, String)] stdout and stderr
+      # @raise [Wheneverd::Systemd::SystemdAnalyzeError]
+      def self.verify(paths, user: true, systemd_analyze: DEFAULT_SYSTEMD_ANALYZE)
+        run(systemd_analyze, "verify", *Array(paths).map(&:to_s), user: user)
+      end
+
+      def self.run(systemd_analyze, *args, user: false)
+        cmd = [systemd_analyze.to_s]
+        cmd << "--user" if user
+        cmd.concat(args.flatten.map(&:to_s))
+
+        stdout, stderr, status = Open3.capture3(*cmd)
+        raise SystemdAnalyzeError, format_error(cmd, status, stdout, stderr) unless status.success?
+
+        [stdout, stderr]
+      rescue Errno::ENOENT
+        raise SystemdAnalyzeError, "systemd-analyze not found (tried: #{systemd_analyze})"
+      end
+
+      def self.format_error(cmd, status, stdout, stderr)
+        details = []
+        details << "command: #{cmd.join(' ')}"
+        details << "status: #{status.exitstatus}"
+        details << "stdout: #{stdout.strip}" unless stdout.to_s.strip.empty?
+        details << "stderr: #{stderr.strip}" unless stderr.to_s.strip.empty?
+        "systemd-analyze failed (#{details.join(', ')})"
+      end
+      private_class_method :format_error
+    end
+  end
+end