wheneverd 0.3.0 → 0.5.0

data/lib/wheneverd/dsl/period_parser.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "calendar_symbol_period_list"
+require_relative "period_strategy"
 
 module Wheneverd
   module DSL
@@ -8,24 +8,12 @@ module Wheneverd
     #
     # Supported period forms are described in the README.
     #
-    # Notes:
-    #
-    # - Interval strings and {Wheneverd::Duration} values produce monotonic triggers
-    #   ({Wheneverd::Trigger::Interval}).
-    # - Calendar symbol periods and cron strings produce calendar triggers
-    #   ({Wheneverd::Trigger::Calendar}).
-    # - The `at:` option is only valid for calendar triggers, with a convenience exception for
-    #   `every 1.day, at: ...` which is treated as a daily calendar trigger.
+    # Uses a strategy pattern to delegate parsing to specialized strategy classes:
+    # - {PeriodStrategy::DurationStrategy} for Duration values
+    # - {PeriodStrategy::StringStrategy} for interval strings and cron expressions
+    # - {PeriodStrategy::SymbolStrategy} for calendar symbols
+    # - {PeriodStrategy::ArrayStrategy} for arrays of calendar symbols
     class PeriodParser
-      DAY_SECONDS = 60 * 60 * 24
-      REBOOT_NOT_SUPPORTED_MESSAGE =
-        "The :reboot period is not supported; use an interval or calendar period instead"
-
-      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
@@ -38,98 +26,11 @@ module Wheneverd
       # @return [Wheneverd::Trigger::Interval, Wheneverd::Trigger::Calendar]
       def trigger_for(period, at:)
         at_times = AtNormalizer.normalize(at, path: path)
-        trigger_for_period(period, at_times: at_times)
+        strategy = PeriodStrategy.for(period, path: path)
+        strategy.parse(period, at_times: at_times)
       rescue Wheneverd::InvalidIntervalError => e
         raise InvalidPeriodError.new(e.message, path: path)
       end
-
-      private
-
-      def trigger_for_period(period, at_times:)
-        return duration_trigger_for(period, at_times: at_times) if period.is_a?(Wheneverd::Duration)
-        return array_trigger_for(period, at_times: at_times) if period.is_a?(Array)
-        return string_trigger_for(period, at_times: at_times) if period.is_a?(String)
-        return symbol_trigger_for(period, at_times: at_times) if period.is_a?(Symbol)
-
-        raise InvalidPeriodError.new("Unsupported period type: #{period.class}", path: path)
-      end
-
-      def duration_trigger_for(duration, at_times:)
-        if at_times.any?
-          return daily_calendar_trigger(at_times) if duration.to_i == DAY_SECONDS
-
-          raise InvalidPeriodError.new("at: is only supported with calendar periods", path: path)
-        end
-
-        Wheneverd::Trigger::Interval.new(seconds: duration.to_i)
-      end
-
-      def daily_calendar_trigger(at_times)
-        Wheneverd::Trigger::Calendar.new(on_calendar: build_calendar_specs("day", at_times))
-      end
-
-      def string_trigger_for(str, at_times:)
-        period_str = str.strip
-
-        return interval_trigger(period_str, at_times: at_times) if interval_string?(period_str)
-
-        return cron_trigger(period_str, at_times: at_times) if cron_string?(period_str)
-
-        raise InvalidPeriodError.new("Unrecognized period #{period_str.inspect}", path: path)
-      end
-
-      def interval_trigger(period_str, at_times:)
-        if at_times.any?
-          raise InvalidPeriodError.new("at: is not supported for interval periods", path: path)
-        end
-
-        seconds = Wheneverd::Interval.parse(period_str)
-        Wheneverd::Trigger::Interval.new(seconds: seconds)
-      end
-
-      def cron_trigger(period_str, at_times:)
-        if at_times.any?
-          raise InvalidPeriodError.new("at: is not supported for cron periods", path: path)
-        end
-
-        Wheneverd::Trigger::Calendar.new(on_calendar: ["cron:#{period_str}"])
-      end
-
-      def symbol_trigger_for(sym, at_times:)
-        raise InvalidPeriodError.new(REBOOT_NOT_SUPPORTED_MESSAGE, path: path) if sym == :reboot
-
-        if CALENDAR_SYMBOLS.include?(sym)
-          return Wheneverd::Trigger::Calendar.new(
-            on_calendar: build_calendar_specs(sym.to_s, at_times)
-          )
-        end
-
-        raise InvalidPeriodError.new("Unknown period symbol: #{sym.inspect}", path: path)
-      end
-
-      def array_trigger_for(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
-        Wheneverd::Trigger::Calendar.new(on_calendar: specs)
-      end
-
-      def build_calendar_specs(base, at_times)
-        return [base] if at_times.empty?
-
-        at_times.map { |t| "#{base}@#{t}" }
-      end
-
-      def interval_string?(str)
-        /\A-?\d+[smhdw]\z/.match?(str)
-      end
-
-      def cron_string?(str)
-        str.split(/\s+/).length == 5
-      end
     end
   end
 end

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/schedule.rb

@@ -8,9 +8,14 @@ module Wheneverd
     # @return [Array<Entry>]
     attr_reader :entries
 
+    # @return [Array<Wheneverd::Service>]
+    attr_reader :services
+
     # @param entries [Array<Entry>]
-    def initialize(entries: [])
+    # @param services [Array<Wheneverd::Service>]
+    def initialize(entries: [], services: [])
       @entries = entries.dup
+      @services = services.dup
     end
 
     # Append an entry to the schedule.
@@ -21,5 +26,14 @@ module Wheneverd
       entries << entry
       self
     end
+
+    # Append a long-running service to the schedule.
+    #
+    # @param service [Wheneverd::Service]
+    # @return [Schedule] self
+    def add_service(service)
+      services << service
+      self
+    end
   end
 end

data/lib/wheneverd/service.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  # A long-running systemd user service managed alongside scheduled timers.
+  class Service
+    SAFE_SETTING_NAME = /\A[A-Za-z][A-Za-z0-9]*\z/.freeze
+
+    # @return [String]
+    attr_reader :name
+
+    # @return [Wheneverd::Job::Command]
+    attr_reader :command
+
+    # @return [String]
+    attr_reader :restart
+
+    # @return [String]
+    attr_reader :restart_sec
+
+    # @return [Array<String>]
+    attr_reader :service_lines
+
+    # @param name [String] stable service name within the schedule
+    # @param command [String, Array<String>] command to run as ExecStart
+    # @param restart [String] systemd Restart= value
+    # @param restart_sec [String] systemd RestartSec= value
+    # @param service [Hash, Array<String>] extra [Service] lines
+    def initialize(name:, command:, restart: "always", restart_sec: "5s", service: {})
+      @name = normalize_name(name)
+      @command = Wheneverd::Job::Command.new(command: command)
+      @restart = normalize_required_value(restart, "restart")
+      @restart_sec = normalize_required_value(restart_sec, "restart_sec")
+      @service_lines = normalize_service_lines(service)
+    end
+
+    # Stable signature used for unit naming.
+    #
+    # @return [String]
+    def signature
+      [
+        "service:#{name}",
+        command.signature,
+        "restart:#{restart}",
+        "restart_sec:#{restart_sec}",
+        *service_lines
+      ].join("\n")
+    end
+
+    private
+
+    def normalize_name(value)
+      str = value.to_s.strip
+      raise InvalidCommandError, "Service name must not be empty" if str.empty?
+
+      str
+    end
+
+    def normalize_required_value(value, field)
+      str = value.to_s.strip
+      raise InvalidCommandError, "Service #{field} must not be empty" if str.empty?
+
+      str
+    end
+
+    def normalize_service_lines(value)
+      case value
+      when Hash
+        value.map { |key, setting| normalize_service_setting(key, setting) }
+      when Array
+        value.map { |line| normalize_service_line(line) }
+      else
+        raise InvalidCommandError, "Service extra settings must be a Hash or Array"
+      end
+    end
+
+    def normalize_service_setting(key, value)
+      setting_name = key.to_s.strip
+      unless SAFE_SETTING_NAME.match?(setting_name)
+        raise InvalidCommandError, "Invalid service setting name: #{setting_name.inspect}"
+      end
+
+      "#{setting_name}=#{normalize_service_setting_value(value)}"
+    end
+
+    def normalize_service_setting_value(value)
+      str = value.to_s.strip
+      raise InvalidCommandError, "Service setting values must not be empty" if str.empty?
+      if str.match?(/[\0\r\n]/)
+        raise InvalidCommandError, "Service setting values must not include NUL or newlines"
+      end
+
+      str
+    end
+
+    def normalize_service_line(line)
+      str = line.to_s.strip
+      raise InvalidCommandError, "Service lines must not be empty" if str.empty?
+      if str.match?(/[\0\r\n]/) || !str.include?("=")
+        raise InvalidCommandError, "Service lines must be single KEY=VALUE lines"
+      end
+
+      str
+    end
+  end
+end