wheneverd 0.1.0

data/lib/wheneverd/systemd/cron_parser.rb

@@ -0,0 +1,352 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  module Systemd
+    # Converts 5-field cron expressions into systemd `OnCalendar=` specs.
+    module CronParser
+      # @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
+
+        values << "#{date} #{time}" unless dom_any
+
+        values
+      end
+
+      # @param cron_5_fields [String]
+      # @return [String] systemd `OnCalendar=` value (only when cron translates to a single value)
+      # @raise [Wheneverd::Systemd::UnsupportedCronError]
+      def self.to_on_calendar(cron_5_fields)
+        values = to_on_calendar_values(cron_5_fields)
+        return values.fetch(0) if values.length == 1
+
+        message =
+          "Unsupported cron #{cron_5_fields.to_s.strip.inspect}: " \
+          "requires multiple OnCalendar values"
+        raise UnsupportedCronError, message
+      end
+
+      def self.split_fields(input)
+        parts = input.split(/\s+/)
+        validate_parts_length(parts, input: input)
+
+        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
+        )
+      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
+
+        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
+
+        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
+
+        if step
+          sequence.each_with_index { |day, idx| present[day] = true if (idx % step).zero? }
+        else
+          sequence.each { |day| present[day] = true }
+        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
+
+        unless /\A[A-Za-z]+\z/.match?(raw)
+          raise UnsupportedCronError, "Unsupported cron #{input.inspect}: invalid day-of-week token"
+        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
+
+        tokens.join(",")
+      end
+      private_class_method :format_dow_set
+    end
+  end
+end

data/lib/wheneverd/systemd/errors.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  module Systemd
+    # Base error class for systemd rendering and system interactions.
+    class Error < Wheneverd::Error; end
+
+    # Raised when an identifier is invalid for use in unit file names.
+    class InvalidIdentifierError < Error; end
+
+    # Raised when a human-friendly time string cannot be parsed.
+    class InvalidTimeError < Error; end
+
+    # Raised when a calendar spec cannot be mapped to a valid `OnCalendar=` value.
+    class InvalidCalendarSpecError < Error; end
+
+    # Raised when the provided cron expression is outside the supported subset.
+    class UnsupportedCronError < Error; end
+
+    # Raised when a `systemctl` invocation fails.
+    class SystemctlError < Error; end
+  end
+end

data/lib/wheneverd/systemd/renderer.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  module Systemd
+    # A rendered systemd unit (service or timer).
+    #
+    # @!attribute [r] path_basename
+    #   @return [String] file name, e.g. `"wheneverd-myapp-0123abcd4567.timer"`
+    # @!attribute [r] kind
+    #   @return [Symbol] `:service` or `:timer`
+    # @!attribute [r] contents
+    #   @return [String] unit file contents
+    Unit = Struct.new(:path_basename, :kind, :contents, keyword_init: true)
+
+    # Renders a {Wheneverd::Schedule} into systemd units.
+    #
+    # Each job in each entry becomes a `*.service` plus matching `*.timer`.
+    #
+    # Unit file names are generated as:
+    #
+    #   `wheneverd-<identifier>-<stable_id>.{service,timer}`
+    #
+    # The stable ID is derived from the job's trigger + command so reordering schedule blocks
+    # does not rename units. If there are duplicate jobs with identical trigger + command, a stable
+    # `-N` suffix is appended to avoid collisions.
+    #
+    # The identifier is sanitized for use in filenames (invalid characters become `-`).
+    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.
+      #
+      # @param schedule [Wheneverd::Schedule]
+      # @param identifier [String] used to namespace unit file names
+      # @return [Array<Unit>]
+      def self.render(schedule, identifier:)
+        validate_schedule(schedule)
+        id = sanitize_identifier(identifier)
+        render_schedule(schedule, id)
+      end
+
+      def self.validate_schedule(schedule)
+        return if schedule.is_a?(Wheneverd::Schedule)
+
+        raise ArgumentError, "schedule must be a Wheneverd::Schedule (got #{schedule.class})"
+      end
+      private_class_method :validate_schedule
+
+      def self.render_schedule(schedule, id)
+        stable_ids = Wheneverd::Systemd::UnitNamer.stable_ids_for(schedule)
+        stable_id_index = 0
+
+        schedule.entries.flat_map do |entry|
+          entry.jobs.flat_map do |job|
+            stable_id = stable_ids.fetch(stable_id_index)
+            stable_id_index += 1
+            base = "wheneverd-#{id}-#{stable_id}"
+            render_job(base, entry.trigger, job)
+          end
+        end
+      end
+      private_class_method :render_schedule
+
+      def self.render_job(base, trigger, job)
+        service = build_service_unit("#{base}.service", job)
+        timer = build_timer_unit("#{base}.timer", trigger)
+        [service, timer]
+      end
+      private_class_method :render_job
+
+      def self.build_service_unit(path_basename, job)
+        Unit.new(
+          path_basename: path_basename,
+          kind: :service,
+          contents: service_contents(path_basename, job.command)
+        )
+      end
+      private_class_method :build_service_unit
+
+      def self.build_timer_unit(path_basename, trigger)
+        timer_lines = timer_lines_for(trigger)
+
+        Unit.new(
+          path_basename: path_basename,
+          kind: :timer,
+          contents: timer_contents(path_basename, timer_lines)
+        )
+      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/systemctl.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Wheneverd
+  module Systemd
+    # Thin wrapper around `systemctl` that raises on non-zero exit status.
+    class Systemctl
+      # Run `systemctl` and return stdout/stderr.
+      #
+      # @param args [Array<String>]
+      # @param user [Boolean] use `--user` (default: true)
+      # @return [Array(String, String)] stdout and stderr
+      # @raise [Wheneverd::Systemd::SystemctlError]
+      def self.run(*args, user: true)
+        cmd = ["systemctl"]
+        cmd << "--user" if user
+        cmd << "--no-pager"
+        cmd.concat(args.flatten.map(&:to_s))
+
+        stdout, stderr, status = Open3.capture3(*cmd)
+        raise SystemctlError, format_error(cmd, status, stdout, stderr) unless status.success?
+
+        [stdout, stderr]
+      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?
+        "systemctl failed (#{details.join(', ')})"
+      end
+      private_class_method :format_error
+    end
+  end
+end

data/lib/wheneverd/systemd/time_parser.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  module Systemd
+    # Parses human-friendly times into `HH:MM:SS` for systemd `OnCalendar=` specs.
+    module TimeParser
+      # @param str [String]
+      # @return [String] time in `HH:MM:SS` format
+      # @raise [Wheneverd::Systemd::InvalidTimeError]
+      def self.parse(str)
+        input = str.to_s.strip
+        raise InvalidTimeError, "Invalid time: empty" if input.empty?
+
+        if (match = /\A(?<h>\d{1,2}):(?<m>\d{2})(?::(?<s>\d{2}))?\z/.match(input))
+          return parse_24h(match)
+        end
+
+        if (match = /\A(?<h>\d{1,2})(?::(?<m>\d{2}))?\s*(?<ampm>am|pm)\z/i.match(input))
+          return parse_12h(match)
+        end
+
+        raise InvalidTimeError, "Invalid time: #{input.inspect}"
+      end
+
+      def self.parse_24h(match)
+        hour = Integer(match[:h], 10)
+        minute = Integer(match[:m], 10)
+        second = match[:s] ? Integer(match[:s], 10) : 0
+
+        validate_parts(hour, minute, second)
+
+        format("%<hour>02d:%<minute>02d:%<second>02d", hour: hour, minute: minute, second: second)
+      end
+      private_class_method :parse_24h
+
+      def self.parse_12h(match)
+        hour12 = Integer(match[:h], 10)
+        minute = match[:m] ? Integer(match[:m], 10) : 0
+        second = 0
+
+        unless hour12.between?(1, 12)
+          raise InvalidTimeError, "Invalid time hour: #{hour12} (expected 1..12)"
+        end
+
+        validate_parts(0, minute, second)
+
+        hour24 = hour24_from_12h(hour12, match[:ampm].downcase)
+
+        format("%<hour>02d:%<minute>02d:%<second>02d", hour: hour24, minute: minute, second: second)
+      end
+      private_class_method :parse_12h
+
+      def self.hour24_from_12h(hour12, ampm)
+        hour24 = hour12 % 12
+        hour24 += 12 if ampm == "pm"
+        hour24
+      end
+      private_class_method :hour24_from_12h
+
+      def self.validate_parts(hour, minute, second)
+        validate_part("hour", hour, 0..23)
+        validate_part("minute", minute, 0..59)
+        validate_part("second", second, 0..59)
+      end
+      private_class_method :validate_parts
+
+      def self.validate_part(name, value, range)
+        return if range.cover?(value)
+
+        raise InvalidTimeError, "Invalid time #{name}: #{value} (expected #{range})"
+      end
+      private_class_method :validate_part
+    end
+  end
+end