wheneverd 0.3.0 → 0.5.0

data/lib/wheneverd/systemd/cron_parser.rb

@@ -1,42 +1,39 @@
 # frozen_string_literal: true
 
+require_relative "cron_parser/field_parser"
+require_relative "cron_parser/dow_parser"
+
 module Wheneverd
   module Systemd
     # Converts 5-field cron expressions into systemd `OnCalendar=` specs.
+    #
+    # Uses {FieldParser} for parsing numeric fields (minute, hour, day-of-month, month)
+    # and {DowParser} for day-of-week parsing and formatting.
     module CronParser
+      MONTH_NAMES = {
+        "jan" => 1,
+        "feb" => 2,
+        "mar" => 3,
+        "apr" => 4,
+        "may" => 5,
+        "jun" => 6,
+        "jul" => 7,
+        "aug" => 8,
+        "sep" => 9,
+        "oct" => 10,
+        "nov" => 11,
+        "dec" => 12
+      }.freeze
+
       # @param cron_5_fields [String]
       # @return [Array<String>] systemd `OnCalendar=` values
       # @raise [Wheneverd::Systemd::UnsupportedCronError]
       def self.to_on_calendar_values(cron_5_fields)
         input = cron_5_fields.to_s.strip
-        minute_str, hour_str, dom_str, month_str, dow_str = split_fields(input)
-
-        minute = parse_numeric_expression(minute_str, 0..59, field: "minute", input: input, pad: 2)
-        hour = parse_numeric_expression(hour_str, 0..23, field: "hour", input: input, pad: 2)
-        dom = parse_numeric_expression(dom_str, 1..31, field: "day-of-month", input: input, pad: 0)
-        month = parse_month_expression(month_str, input: input)
-        dow_set = parse_dow_set(dow_str, input: input)
-
-        time = "#{hour}:#{minute}:00"
-        dom_any = dom == "*"
-        month_any = month == "*"
-
-        date = "*-#{month_any ? '*' : month}-#{dom_any ? '*' : dom}"
-
-        if dow_set.nil? && dom_any
-          return ["*-#{month_any ? '*' : month}-* #{time}"]
-        end
-
-        values = []
-
-        if dow_set
-          dow = format_dow_set(dow_set)
-          values << "#{dow} *-#{month_any ? '*' : month}-* #{time}"
-        end
+        fields = split_fields(input)
 
-        values << "#{date} #{time}" unless dom_any
-
-        values
+        parsed = parse_all_fields(fields, input)
+        format_on_calendar_values(parsed)
       end
 
       # @param cron_5_fields [String]
@@ -52,301 +49,57 @@ module Wheneverd
         raise UnsupportedCronError, message
       end
 
+      ParsedFields = Struct.new(:minute, :hour, :dom, :month, :dow_set, keyword_init: true)
+
       def self.split_fields(input)
         parts = input.split(/\s+/)
-        validate_parts_length(parts, input: input)
+        unless parts.length == 5
+          raise UnsupportedCronError, "Unsupported cron #{input.inspect}: expected 5 fields"
+        end
 
         parts
       end
       private_class_method :split_fields
 
-      def self.validate_parts_length(parts, input:)
-        return if parts.length == 5
-
-        raise UnsupportedCronError, "Unsupported cron #{input.inspect}: expected 5 fields"
-      end
-      private_class_method :validate_parts_length
-
-      MONTH_NAMES = {
-        "jan" => 1,
-        "feb" => 2,
-        "mar" => 3,
-        "apr" => 4,
-        "may" => 5,
-        "jun" => 6,
-        "jul" => 7,
-        "aug" => 8,
-        "sep" => 9,
-        "oct" => 10,
-        "nov" => 11,
-        "dec" => 12
-      }.freeze
-
-      DOW_NAMES = {
-        "sun" => 0,
-        "mon" => 1,
-        "tue" => 2,
-        "wed" => 3,
-        "thu" => 4,
-        "fri" => 5,
-        "sat" => 6
-      }.freeze
-
-      DOW_SYSTEMD = {
-        0 => "Sun",
-        1 => "Mon",
-        2 => "Tue",
-        3 => "Wed",
-        4 => "Thu",
-        5 => "Fri",
-        6 => "Sat"
-      }.freeze
-
-      DOW_ORDER = [1, 2, 3, 4, 5, 6, 0].freeze
-
-      def self.parse_month_expression(month_str, input:)
-        parse_mapped_numeric_expression(
-          month_str,
-          1..12,
-          field: "month",
-          input: input,
-          names: MONTH_NAMES
+      def self.parse_all_fields(fields, input)
+        minute_str, hour_str, dom_str, month_str, dow_str = fields
+
+        ParsedFields.new(
+          minute: FieldParser.parse_numeric(minute_str, 0..59, field: "minute", input: input,
+                                                               pad: 2),
+          hour: FieldParser.parse_numeric(hour_str, 0..23, field: "hour", input: input, pad: 2),
+          dom: FieldParser.parse_numeric(dom_str, 1..31, field: "day-of-month", input: input,
+                                                         pad: 0),
+          month: FieldParser.parse_mapped(month_str, 1..12, field: "month", input: input,
+                                                            names: MONTH_NAMES),
+          dow_set: DowParser.parse(dow_str, input: input)
         )
       end
-      private_class_method :parse_month_expression
-
-      def self.parse_numeric_expression(str, range, field:, input:, pad:)
-        expr = parse_mapped_numeric_expression(str, range, field: field, input: input, names: {})
-        return expr if pad <= 0 || expr == "*"
-
-        pad_expression_numbers(expr, pad: pad)
-      end
-      private_class_method :parse_numeric_expression
-
-      def self.parse_mapped_numeric_expression(str, range, field:, input:, names:)
-        raw = str.to_s.strip
-        if raw.empty?
-          raise UnsupportedCronError,
-                "Unsupported cron #{input.inspect}: #{field} is empty"
-        end
-
-        parts = raw.split(",").map(&:strip)
-        return "*" if parts.any? { |part| part == "*" }
-
-        parts.map do |part|
-          mapped_part_to_systemd(part, range, field: field, input: input, names: names)
-        end.join(",")
-      end
-      private_class_method :parse_mapped_numeric_expression
-
-      def self.mapped_part_to_systemd(part, range, field:, input:, names:)
-        base, step_str = part.split("/", 2)
-        step = if step_str.nil?
-                 nil
-               else
-                 parse_positive_int(step_str, field: field, input: input,
-                                              label: "step")
-               end
-
-        base_expr =
-          if base == "*"
-            range.begin.to_s
-          elsif (match = /\A(?<start>[^-]+)-(?<finish>[^-]+)\z/.match(base))
-            start_value = parse_mapped_value(match[:start], range, field: field, input: input,
-                                                                   names: names)
-            finish_value = parse_mapped_value(match[:finish], range, field: field, input: input,
-                                                                     names: names)
-            unless start_value <= finish_value
-              raise UnsupportedCronError,
-                    "Unsupported cron #{input.inspect}: invalid #{field} range"
-            end
-
-            "#{start_value}..#{finish_value}"
-          else
-            parse_mapped_value(base, range, field: field, input: input, names: names).to_s
-          end
-
-        return base_expr if step.nil?
-
-        "#{base_expr}/#{step}"
-      end
-      private_class_method :mapped_part_to_systemd
-
-      def self.parse_mapped_value(token, range, field:, input:, names:)
-        raw = token.to_s.strip
-        if raw.empty?
-          raise UnsupportedCronError,
-                "Unsupported cron #{input.inspect}: empty #{field} token"
-        end
-
-        if /\A\d+\z/.match?(raw)
-          value = Integer(raw, 10)
-          unless range.cover?(value)
-            raise UnsupportedCronError, "Unsupported cron #{input.inspect}: #{field} out of range"
-          end
-
-          return value
-        end
-
-        key = raw.downcase
-        if names.key?(key)
-          value = names.fetch(key)
-          return value if range.cover?(value)
-        end
-
-        raise UnsupportedCronError, "Unsupported cron #{input.inspect}: invalid #{field} token"
-      end
-      private_class_method :parse_mapped_value
-
-      def self.pad_expression_numbers(expr, pad:)
-        expr.gsub(%r{(?<![/\d])\d+}) { |m| m.rjust(pad, "0") }
-      end
-      private_class_method :pad_expression_numbers
-
-      def self.parse_positive_int(str, field:, input:, label:)
-        unless /\A\d+\z/.match?(str)
-          raise UnsupportedCronError,
-                "Unsupported cron #{input.inspect}: #{field} #{label} must be a number"
-        end
-
-        value = Integer(str, 10)
-        unless value.positive?
-          raise UnsupportedCronError,
-                "Unsupported cron #{input.inspect}: #{field} #{label} must be positive"
-        end
-
-        value
-      end
-      private_class_method :parse_positive_int
-
-      def self.parse_dow_set(dow_str, input:)
-        raw = dow_str.to_s.strip
-        if raw.empty?
-          raise UnsupportedCronError,
-                "Unsupported cron #{input.inspect}: day-of-week is empty"
-        end
-        return nil if raw == "*"
-
-        present = Array.new(7, false)
-
-        raw.split(",").map(&:strip).each do |part|
-          apply_dow_part(present, part, input: input)
-        end
-
-        days = present.each_index.select { |idx| present[idx] }
-        return nil if days.length == 7
-
-        days
-      end
-      private_class_method :parse_dow_set
-
-      def self.apply_dow_part(present, part, input:)
-        if part.empty?
-          raise UnsupportedCronError,
-                "Unsupported cron #{input.inspect}: invalid day-of-week token"
-        end
+      private_class_method :parse_all_fields
 
-        base, step_str = part.split("/", 2)
-        step = if step_str.nil?
-                 nil
-               else
-                 parse_positive_int(step_str, field: "day-of-week",
-                                              input: input, label: "step")
-               end
+      def self.format_on_calendar_values(parsed)
+        time = "#{parsed.hour}:#{parsed.minute}:00"
+        dom_any = parsed.dom == "*"
+        month_any = parsed.month == "*"
 
-        sequence =
-          if base == "*"
-            (0..6).to_a
-          elsif (match = /\A(?<start>[^-]+)-(?<finish>[^-]+)\z/.match(base))
-            dow_range_sequence(match[:start], match[:finish], input: input)
-          else
-            start_day = parse_dow_value(base, input: input)
-            start_day = 0 if start_day == 7
-            step ? (start_day..6).to_a : [start_day]
-          end
+        date = "*-#{month_any ? '*' : parsed.month}-#{dom_any ? '*' : parsed.dom}"
 
-        if step
-          sequence.each_with_index { |day, idx| present[day] = true if (idx % step).zero? }
-        else
-          sequence.each { |day| present[day] = true }
+        if parsed.dow_set.nil? && dom_any
+          return ["*-#{month_any ? '*' : parsed.month}-* #{time}"]
         end
-      end
-      private_class_method :apply_dow_part
-
-      def self.dow_range_sequence(start_token, finish_token, input:)
-        start_raw = parse_dow_value(start_token, input: input)
-        finish_raw = parse_dow_value(finish_token, input: input)
-
-        start_day = start_raw == 7 ? 0 : start_raw
-        finish_day = finish_raw == 7 ? 0 : finish_raw
-
-        return (0..6).to_a if start_raw.zero? && finish_raw == 7
-
-        return (start_day..6).to_a + [0] if finish_raw == 7 && !start_raw.zero?
-
-        return (start_day..finish_day).to_a if start_day <= finish_day
-
-        (start_day..6).to_a + (0..finish_day).to_a
-      end
-      private_class_method :dow_range_sequence
 
-      def self.parse_dow_value(token, input:)
-        raw = token.to_s.strip
-        if raw.empty?
-          raise UnsupportedCronError,
-                "Unsupported cron #{input.inspect}: invalid day-of-week token"
-        end
-
-        if /\A\d+\z/.match?(raw)
-          value = Integer(raw, 10)
-          return value if value.between?(0, 7)
-
-          raise UnsupportedCronError, "Unsupported cron #{input.inspect}: day-of-week out of range"
-        end
+        values = []
 
-        unless /\A[A-Za-z]+\z/.match?(raw)
-          raise UnsupportedCronError, "Unsupported cron #{input.inspect}: invalid day-of-week token"
+        if parsed.dow_set
+          dow = DowParser.format(parsed.dow_set)
+          values << "#{dow} *-#{month_any ? '*' : parsed.month}-* #{time}"
         end
 
-        key = raw.downcase
-        key = key[0, 3] if key.length > 3
-        return DOW_NAMES.fetch(key) if DOW_NAMES.key?(key)
-
-        raise UnsupportedCronError, "Unsupported cron #{input.inspect}: invalid day-of-week token"
-      end
-      private_class_method :parse_dow_value
-
-      def self.format_dow_set(days)
-        present = Array.new(7, false)
-        days.each { |day| present[day] = true }
-
-        tokens = []
-        i = 0
-        while i < DOW_ORDER.length
-          day = DOW_ORDER.fetch(i)
-          unless present.fetch(day)
-            i += 1
-            next
-          end
-
-          start = day
-          j = i
-          j += 1 while (j + 1) < DOW_ORDER.length && present.fetch(DOW_ORDER.fetch(j + 1))
-          finish = DOW_ORDER.fetch(j)
-
-          token =
-            if start == finish
-              DOW_SYSTEMD.fetch(start)
-            else
-              "#{DOW_SYSTEMD.fetch(start)}..#{DOW_SYSTEMD.fetch(finish)}"
-            end
-          tokens << token
-          i = j + 1
-        end
+        values << "#{date} #{time}" unless dom_any
 
-        tokens.join(",")
+        values
       end
-      private_class_method :format_dow_set
+      private_class_method :format_on_calendar_values
     end
   end
 end

data/lib/wheneverd/systemd/renderer.rb

@@ -10,7 +10,7 @@ module Wheneverd
     #   @return [Symbol] `:service` or `:timer`
     # @!attribute [r] contents
     #   @return [String] unit file contents
-    Unit = Struct.new(:path_basename, :kind, :contents, keyword_init: true)
+    Unit = Struct.new(:path_basename, :kind, :contents, :activation, keyword_init: true)
 
     # Renders a {Wheneverd::Schedule} into systemd units.
     #
@@ -25,10 +25,10 @@ module Wheneverd
     # `-N` suffix is appended to avoid collisions.
     #
     # The identifier is sanitized for use in filenames (invalid characters become `-`).
+    #
+    # Uses {UnitContentBuilder} for generating unit file contents.
     class Renderer
       MARKER_PREFIX = "# Generated by wheneverd (wheneverd)"
-      SERVICE_SECTION = ["[Service]", "Type=oneshot"].freeze
-      TIMER_SUFFIX = ["Persistent=true", "", "[Install]", "WantedBy=timers.target", ""].freeze
 
       # Render a schedule to `systemd` units.
       #
@@ -37,7 +37,7 @@ module Wheneverd
       # @return [Array<Unit>]
       def self.render(schedule, identifier:)
         validate_schedule(schedule)
-        id = sanitize_identifier(identifier)
+        id = UnitPathUtils.sanitize_identifier(identifier)
         render_schedule(schedule, id)
       end
 
@@ -52,7 +52,7 @@ module Wheneverd
         stable_ids = Wheneverd::Systemd::UnitNamer.stable_ids_for(schedule)
         stable_id_index = 0
 
-        schedule.entries.flat_map do |entry|
+        units = schedule.entries.flat_map do |entry|
           entry.jobs.flat_map do |job|
             stable_id = stable_ids.fetch(stable_id_index)
             stable_id_index += 1
@@ -60,9 +60,20 @@ module Wheneverd
             render_job(base, entry.trigger, job)
           end
         end
+        units.concat(render_services(schedule.services, id))
+        units
       end
       private_class_method :render_schedule
 
+      def self.render_services(services, id)
+        services.map do |service|
+          stable_id = Wheneverd::Systemd::UnitNamer.stable_id_for(service.signature)
+          base = "wheneverd-#{id}-#{stable_id}"
+          build_standalone_service_unit("#{base}.service", service)
+        end
+      end
+      private_class_method :render_services
+
       def self.render_job(base, trigger, job)
         service = build_service_unit("#{base}.service", job)
         timer = build_timer_unit("#{base}.timer", trigger)
@@ -74,78 +85,32 @@ module Wheneverd
         Unit.new(
           path_basename: path_basename,
           kind: :service,
-          contents: service_contents(path_basename, job.command)
+          contents: UnitContentBuilder.service_contents(path_basename, job.command),
+          activation: :timer_managed
         )
       end
       private_class_method :build_service_unit
 
+      def self.build_standalone_service_unit(path_basename, service)
+        Unit.new(
+          path_basename: path_basename,
+          kind: :service,
+          contents: UnitContentBuilder.standalone_service_contents(path_basename, service),
+          activation: :service
+        )
+      end
+      private_class_method :build_standalone_service_unit
+
       def self.build_timer_unit(path_basename, trigger)
+        timer_lines = UnitContentBuilder.timer_lines_for(trigger)
         Unit.new(
           path_basename: path_basename,
           kind: :timer,
-          contents: timer_contents(path_basename, timer_lines_for(trigger))
+          contents: UnitContentBuilder.timer_contents(path_basename, timer_lines),
+          activation: :timer
         )
       end
       private_class_method :build_timer_unit
-
-      def self.timer_lines_for(trigger)
-        case trigger
-        when Wheneverd::Trigger::Interval
-          ["OnActiveSec=#{trigger.seconds}", "OnUnitActiveSec=#{trigger.seconds}"]
-        when Wheneverd::Trigger::Boot
-          ["OnBootSec=#{trigger.seconds}"]
-        when Wheneverd::Trigger::Calendar then calendar_timer_lines(trigger)
-        else raise ArgumentError, "Unsupported trigger type: #{trigger.class}"
-        end
-      end
-      private_class_method :timer_lines_for
-
-      def self.calendar_timer_lines(trigger)
-        trigger.on_calendar.flat_map do |spec|
-          CalendarSpec.to_on_calendar_values(spec).map { |value| "OnCalendar=#{value}" }
-        end
-      end
-      private_class_method :calendar_timer_lines
-
-      def self.service_contents(path_basename, command)
-        ([
-          marker,
-          "[Unit]",
-          "Description=wheneverd job #{path_basename}",
-          ""
-        ] + SERVICE_SECTION + ["ExecStart=#{command}", ""]).join("\n")
-      end
-      private_class_method :service_contents
-
-      def self.timer_contents(path_basename, timer_lines)
-        ([
-          marker,
-          "[Unit]",
-          "Description=wheneverd timer #{path_basename}",
-          "",
-          "[Timer]"
-        ] + timer_lines + TIMER_SUFFIX).join("\n")
-      end
-      private_class_method :timer_contents
-
-      def self.marker
-        "#{MARKER_PREFIX} #{Wheneverd::VERSION}; do not edit."
-      end
-      private_class_method :marker
-
-      def self.sanitize_identifier(identifier)
-        raw = identifier.to_s.strip
-        raise InvalidIdentifierError, "identifier must not be empty" if raw.empty?
-
-        sanitized = raw.gsub(/[^A-Za-z0-9_-]/, "-").gsub(/-+/, "-").gsub(/\A-|-+\z/, "")
-        if sanitized.empty?
-          raise InvalidIdentifierError,
-                "identifier must include at least one alphanumeric character"
-        end
-
-        sanitized
-      end
-      private_class_method :sanitize_identifier
     end
   end
 end

data/lib/wheneverd/systemd/unit_content_builder.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  module Systemd
+    # Builds the text content for systemd unit files.
+    #
+    # Handles the structure of service and timer unit files, including
+    # the marker header, sections, and proper formatting.
+    module UnitContentBuilder
+      SERVICE_SECTION = ["[Service]", "Type=oneshot"].freeze
+      TIMER_SUFFIX = ["Persistent=true", "", "[Install]", "WantedBy=timers.target", ""].freeze
+
+      # Build service unit file contents.
+      #
+      # @param path_basename [String] unit file name for description
+      # @param command [String] ExecStart command
+      # @return [String] complete unit file contents
+      def self.service_contents(path_basename, command)
+        build_unit(
+          description: "wheneverd job #{path_basename}",
+          sections: SERVICE_SECTION + ["ExecStart=#{command}", ""]
+        )
+      end
+
+      # Build a long-running service unit file.
+      #
+      # @param path_basename [String] unit file name for description
+      # @param service [Wheneverd::Service]
+      # @return [String] complete unit file contents
+      def self.standalone_service_contents(path_basename, service)
+        build_unit(
+          description: "wheneverd service #{path_basename}",
+          sections: [
+            "[Service]",
+            "Type=simple",
+            "ExecStart=#{service.command.command}",
+            "Restart=#{service.restart}",
+            "RestartSec=#{service.restart_sec}",
+            *service.service_lines,
+            "",
+            "[Install]",
+            "WantedBy=default.target",
+            ""
+          ]
+        )
+      end
+
+      # Build timer unit file contents.
+      #
+      # @param path_basename [String] unit file name for description
+      # @param timer_lines [Array<String>] timer configuration lines (OnCalendar, OnActiveSec, etc.)
+      # @return [String] complete unit file contents
+      def self.timer_contents(path_basename, timer_lines)
+        build_unit(
+          description: "wheneverd timer #{path_basename}",
+          sections: ["[Timer]"] + timer_lines + TIMER_SUFFIX
+        )
+      end
+
+      # Build timer lines for a trigger.
+      #
+      # @param trigger [Wheneverd::Trigger::Base] the trigger
+      # @return [Array<String>] timer configuration lines
+      # @raise [ArgumentError] if trigger type is unsupported
+      def self.timer_lines_for(trigger)
+        # Calendar triggers need special handling to convert DSL specs to systemd specs
+        return calendar_timer_lines(trigger) if trigger.is_a?(Wheneverd::Trigger::Calendar)
+
+        unless trigger.respond_to?(:systemd_timer_lines)
+          raise ArgumentError, "Unsupported trigger type: #{trigger.class}"
+        end
+
+        trigger.systemd_timer_lines
+      end
+
+      def self.calendar_timer_lines(trigger)
+        trigger.on_calendar.flat_map do |spec|
+          CalendarSpec.to_on_calendar_values(spec).map { |value| "OnCalendar=#{value}" }
+        end
+      end
+      private_class_method :calendar_timer_lines
+
+      def self.build_unit(description:, sections:)
+        ([
+          marker,
+          "[Unit]",
+          "Description=#{description}",
+          ""
+        ] + sections).join("\n")
+      end
+      private_class_method :build_unit
+
+      def self.marker
+        "#{Renderer::MARKER_PREFIX} #{Wheneverd::VERSION}; do not edit."
+      end
+      private_class_method :marker
+    end
+  end
+end