postburner 1.0.0.pre.11 → 1.0.0.pre.12

data/app/models/postburner/schedule.rb

@@ -0,0 +1,703 @@
+# frozen_string_literal: true
+
+module Postburner
+  # Schedule model for recurring job execution with fixed-rate, grid-aligned scheduling.
+  #
+  # Postburner's scheduler provides predictable execution times with no drift, like
+  # subscription billing. Executions are calculated as anchor + N*interval, maintaining
+  # alignment to the grid regardless of actual execution times.
+  #
+  # ## Architecture
+  #
+  # The scheduler uses **immediate enqueue** combined with a **watchdog safety net**:
+  #
+  # 1. When an execution is created, it's immediately enqueued to Beanstalkd's delayed
+  #    queue with the appropriate delay until run_at
+  # 2. For Postburner::Job-based schedules, a before_attempt callback creates the next
+  #    execution when the current job runs - providing immediate pickup without waiting
+  # 3. A lightweight watchdog in the 'scheduler' tube acts as a safety net, ensuring
+  #    every schedule has a future execution queued
+  #
+  # This design requires no dedicated scheduler process - existing workers handle everything.
+  #
+  # ## Scheduling Modes
+  #
+  # **Anchor-based (recommended):** Define a start time, interval, and unit (like subscriptions)
+  # - Supports: seconds, minutes, hours, days, weeks, months, years
+  # - Grid-aligned: Always snaps to anchor + N*interval, never drifts
+  # - Example: Daily at 9:00 AM, weekly on Saturday, monthly on the 1st
+  #
+  # **Cron-based:** Use standard cron expressions (requires fugit gem)
+  # - Power user feature for complex schedules
+  # - Example: Weekdays at 8 AM, every 15 minutes, etc.
+  #
+  # ## Database Fields
+  #
+  # - `name` - Unique identifier for the schedule
+  # - `job_class` - ActiveJob or Postburner::Job class name
+  # - `anchor` - Start time for interval calculation (anchor mode)
+  # - `interval` - Number of interval units (anchor mode)
+  # - `interval_unit` - Unit type: seconds/minutes/hours/days/weeks/months/years
+  # - `cron` - Cron expression (cron mode)
+  # - `timezone` - Timezone for calculations (default: UTC)
+  # - `args` - JSONB arguments passed to each job execution
+  # - `queue` - Override default queue name
+  # - `priority` - Override default Beanstalkd priority
+  # - `enabled` - Enable/disable schedule
+  # - `catch_up` - Skip missed executions (false) or run all (true)
+  # - `last_audit_at` - Last time watchdog processed this schedule
+  #
+  # ## Catch-Up Policy
+  #
+  # The catch_up attribute controls behavior when worker is down:
+  # - `catch_up: false` (default) - Skip missed executions, resume from next future time
+  # - `catch_up: true` - Run all missed executions when worker restarts
+  #
+  # ## Configuration
+  #
+  # Add to config/postburner.yml:
+  #   production:
+  #     default_scheduler_interval: 300  # Check every 5 minutes
+  #     default_scheduler_priority: 100  # Watchdog priority
+  #
+  # ## Starting Schedules
+  #
+  # **Explicit start (immediate):**
+  #   schedule.start!  # Creates and enqueues first execution to Beanstalkd
+  #
+  # **Auto-bootstrap (eventual):**
+  #   # Watchdog auto-bootstraps on next run (adds up to one interval of delay)
+  #
+  # @example Anchor-based schedule (daily at 9:30 AM)
+  #   schedule = Postburner::Schedule.create!(
+  #     name: 'daily_cleanup',
+  #     job_class: 'CleanupJob',
+  #     anchor: Time.zone.parse('2025-01-01 09:30:00'),
+  #     interval: 1,
+  #     interval_unit: 'days',
+  #     timezone: 'America/New_York',
+  #     args: { report_type: 'daily' }
+  #   )
+  #   schedule.start!  # Optional: immediate pickup
+  #
+  # @example Cron-based schedule (weekdays at 8 AM)
+  #   schedule = Postburner::Schedule.create!(
+  #     name: 'weekday_standup',
+  #     job_class: 'StandupReminderJob',
+  #     cron: '0 8 * * 1-5',
+  #     timezone: 'America/Chicago'
+  #   )
+  #
+  # @example With catch-up enabled
+  #   schedule = Postburner::Schedule.create!(
+  #     name: 'billing_job',
+  #     job_class: 'BillingJob',
+  #     interval: 1,
+  #     interval_unit: 'hours',
+  #     catch_up: true  # Run all missed hours if worker was down
+  #   )
+  #
+  # @see Postburner::ScheduleExecution
+  # @see Postburner::Scheduler
+  #
+  class Schedule < ApplicationRecord
+    has_many :executions,
+      class_name: 'Postburner::ScheduleExecution',
+      dependent: :destroy
+
+    # Validations
+    validates :name, presence: true, uniqueness: true
+    validates :job_class, presence: true
+    validates :timezone, presence: true
+    validate :validate_scheduling_mode!
+    validate :validate_job_class_exists!
+    validate :validate_cron_expression!, if: :cron?
+
+    # Scopes
+    scope :enabled, -> { where(enabled: true) }
+    scope :disabled, -> { where(enabled: false) }
+    scope :anchor_based, -> { where.not(anchor: nil) }
+    scope :cron_based, -> { where.not(cron: nil) }
+
+    # Start the schedule by creating the first execution.
+    #
+    # Use this when you need the schedule to be picked up immediately
+    # (within the next scheduler interval). Without calling start!, the
+    # scheduler will auto-bootstrap the schedule on its next run, but
+    # that adds an extra interval of delay.
+    #
+    # This is an idempotent operation - calling it multiple times will
+    # only create the first execution once.
+    #
+    # @return [ScheduleExecution, nil] The created execution, or nil if already started
+    # @raise [ActiveRecord::RecordInvalid] If execution creation fails
+    #
+    # @example Start a new schedule
+    #   schedule = Postburner::Schedule.create!(
+    #     name: 'daily_cleanup',
+    #     job_class: 'CleanupJob',
+    #     anchor: Time.zone.now,
+    #     interval: 1,
+    #     interval_unit: 'days',
+    #     timezone: 'UTC'
+    #   )
+    #   schedule.start!  # Creates and enqueues first execution
+    #
+    def start!
+      return nil if started?
+
+      create_execution!
+    end
+
+    # Create the next execution if one doesn't already exist.
+    #
+    # Idempotent method that ensures exactly one future execution is scheduled.
+    # Used by Postburner::Job callback to provide immediate pickup without waiting
+    # for the scheduler watchdog. Safe to call multiple times - will only create
+    # an execution if none exists in the future.
+    #
+    # The catch_up attribute controls behavior when worker is down:
+    # - catch_up: true  -> calculates from last execution (may be in past, runs immediately)
+    # - catch_up: false -> calculates from Time.current (skips missed executions)
+    #
+    # @param after [ScheduleExecution, Time, nil] The execution or time to calculate next from.
+    #   If nil, behavior depends on catch_up setting. If ScheduleExecution, uses its run_at.
+    # @return [ScheduleExecution, nil] The created execution, or nil if one already exists
+    #   or if a race condition occurred
+    #
+    # @example Create next execution after current
+    #   last_execution = schedule.executions.last
+    #   schedule.create_next_execution!(after: last_execution)
+    #
+    # @example With catch_up disabled (default)
+    #   schedule.catch_up = false
+    #   schedule.create_next_execution!  # Calculates from Time.current
+    #
+    # @note This method handles race conditions gracefully - if two threads/processes
+    #   try to create an execution simultaneously, one will succeed and the other
+    #   will return nil with a warning logged.
+    #
+    def create_next_execution!(after: nil)
+      # Check if a future execution already exists (any status - including skipped).
+      #
+      # TIME PRECISION: When called from a job callback during time travel
+      # (e.g., ImmediateTestQueue), Time.current and execution.run_at can differ
+      # by microseconds:
+      #
+      #   Time.current         = 2025-12-29 06:54:58.000000 UTC  (traveled, truncated)
+      #   execution.run_at     = 2025-12-29 06:54:58.185940 UTC  (database precision)
+      #
+      # Using Time.current would incorrectly find the CURRENT execution as "future"
+      # (since 185940µs > 0µs), causing this method to return nil. By using
+      # after.run_at when an execution is provided, we correctly exclude the
+      # current execution from the future check.
+      check_time = after.is_a?(ScheduleExecution) ? after.run_at : Time.current
+      return nil if executions.where('run_at > ?', check_time).exists?
+
+      # Determine base time for calculating next execution.
+      #
+      # TIME PRECISION: When after is a current/future ScheduleExecution, we
+      # must use its run_at for calculation. If we used Time.current instead
+      # (which may be microseconds behind), next_run_at() could return the SAME
+      # time as the current execution, causing a duplicate key error.
+      #
+      # For past executions, respect the catch_up setting:
+      #   catch_up: true  -> calculate from last execution (runs missed jobs)
+      #   catch_up: false -> calculate from Time.current (skips missed jobs)
+      after_time = if after.is_a?(ScheduleExecution) && after.run_at >= Time.current
+                     after.run_at
+                   elsif catch_up
+                     after.is_a?(ScheduleExecution) ? after.run_at : after
+                   else
+                     Time.current
+                   end
+
+      create_execution!(after: after_time)
+    rescue ActiveRecord::RecordNotUnique, ActiveRecord::RecordInvalid => e
+      # Race condition - another process/thread created it between our check and insert
+      # RecordNotUnique: PostgreSQL constraint violation
+      # RecordInvalid: Rails validation error (uniqueness validation catches it first)
+      Rails.logger.warn "[Postburner::Schedule] Expected race condition creating next execution for '#{name}' (job: #{id}): #{e.message}"
+      nil
+    end
+
+    # Calculate next N run times.
+    #
+    # Uses either cron or anchor-based calculation depending on schedule mode.
+    # All times are calculated in the schedule's timezone and returned as Time objects.
+    #
+    # @param after [Time, nil] Calculate times after this time (default: Time.current)
+    # @param count [Integer] Number of times to calculate (default: 1)
+    # @return [Array<Time>] Array of future run times in schedule's timezone
+    #
+    # @example Preview next 5 runs
+    #   schedule.next_run_at_times(count: 5)
+    #   # => [2025-12-29 09:00:00 UTC, 2025-12-30 09:00:00 UTC, ...]
+    #
+    # @example Calculate from specific time
+    #   schedule.next_run_at_times(after: 1.week.from_now, count: 3)
+    #
+    def next_run_at_times(after: nil, count: 1)
+      after ||= Time.current
+      times = []
+
+      if cron?
+        # Cron-based calculation
+        times = calculate_cron_times(after: after, count: count)
+      else
+        # Anchor-based calculation
+        times = calculate_anchor_times(after: after, count: count)
+      end
+
+      times
+    end
+
+    # Calculate the single next run time.
+    #
+    # Convenience method that returns only the next run time instead of an array.
+    # Equivalent to calling next_run_at_times(after: after, count: 1).first
+    #
+    # @param after [Time, nil] Calculate time after this (default: Time.current)
+    # @return [Time, nil] Next run time, or nil if no more runs
+    #
+    # @example Get next run time
+    #   schedule.next_run_at
+    #   # => 2025-12-29 09:00:00 UTC
+    #
+    def next_run_at(after: nil)
+      next_run_at_times(after: after, count: 1).first
+    end
+
+    # Check if the schedule has been started.
+    #
+    # A schedule is considered started if it has any executions
+    # (pending, scheduled, or skipped).
+    #
+    # @return [Boolean] true if schedule has any executions, false otherwise
+    #
+    # @example Check if schedule is started
+    #   schedule.started?  # => false
+    #   schedule.start!
+    #   schedule.started?  # => true
+    #
+    def started?
+      executions.exists?
+    end
+
+    # Check if schedule uses cron mode.
+    #
+    # @return [Boolean] true if cron expression is set, false otherwise
+    def cron?
+      cron.present?
+    end
+
+    # Check if schedule uses anchor mode.
+    #
+    # @return [Boolean] true if anchor time is set, false otherwise
+    def anchor?
+      anchor.present?
+    end
+
+    # Get timezone object.
+    #
+    # Returns an ActiveSupport::TimeZone instance for the schedule's timezone.
+    # The timezone object is cached in an instance variable.
+    #
+    # @return [ActiveSupport::TimeZone] The timezone object
+    #
+    # @example
+    #   schedule.timezone = 'America/New_York'
+    #   schedule.tz  # => #<ActiveSupport::TimeZone:0x... @name="America/New_York">
+    #
+    def tz
+      @tz ||= Time.find_zone(timezone)
+    end
+
+    # Attributes to cache in schedule executions.
+    #
+    # Returns a hash of schedule attributes that are cached in each ScheduleExecution's
+    # cached_schedule column. This allows executions to run even if the schedule is
+    # modified or deleted after creation.
+    #
+    # @return [Hash] Hash of schedule attributes to cache
+    #
+    # @api private
+    #
+    def cacheable_attributes
+      {
+        name: name,
+        job_class: job_class,
+        args: args,
+        queue: queue,
+        priority: priority,
+        timezone: timezone,
+        anchor: anchor,
+        interval: interval,
+        interval_unit: interval_unit,
+        cron: cron,
+        catch_up: catch_up
+      }
+    end
+
+    private
+
+    # Create and save an execution, then enqueue it to Beanstalkd.
+    #
+    # The execution is enqueued immediately with appropriate delay - Beanstalkd's
+    # delayed queue will hold it until run_at. This ensures all future executions
+    # are already queued and ready to go.
+    #
+    # @param after [Time, ScheduleExecution, nil] Calculate after this time/execution
+    # @return [ScheduleExecution, nil] The created execution, or nil if no more runs
+    #
+    # @api private
+    #
+    def create_execution!(after: nil)
+      execution = build_execution(after: after)
+      return nil if execution.nil?
+
+      execution.save!
+      execution.enqueue!
+      execution
+    end
+
+    # Build an execution record (does not save).
+    #
+    # Calculates the next two run times and builds an execution with run_at
+    # and next_run_at set. The execution is not persisted to the database.
+    #
+    # @param after [Time, ScheduleExecution, nil] Calculate after this time/execution
+    # @return [ScheduleExecution, nil] The built execution, or nil if schedule has no more runs
+    #
+    # @api private
+    #
+    def build_execution(after: nil)
+      after_time = after.is_a?(ScheduleExecution) ? after.run_at : after
+      times = next_run_at_times(after: after_time, count: 2)
+
+      return nil if times.empty?
+
+      run_at = times[0]
+      next_run_at = times[1] # May be nil if count is 1 or no more runs
+
+      executions.build(
+        run_at: run_at,
+        next_run_at: next_run_at,
+        cached_schedule: cacheable_attributes
+      )
+    end
+
+    # Validate that exactly one scheduling mode is configured.
+    #
+    # Ensures either anchor+interval+interval_unit OR cron is set, but not both.
+    # Also validates that anchor mode has all required fields and interval_unit is valid.
+    #
+    # @return [void]
+    #
+    # @api private
+    #
+    def validate_scheduling_mode!
+      if anchor.blank? && cron.blank?
+        errors.add(:base, 'Must specify either anchor+interval+interval_unit OR cron')
+      end
+
+      if anchor.present? && cron.present?
+        errors.add(:base, 'Cannot specify both anchor and cron modes')
+      end
+
+      if anchor.present?
+        if interval.blank?
+          errors.add(:interval, 'must be present when using anchor mode')
+        end
+
+        if interval_unit.blank?
+          errors.add(:interval_unit, 'must be present when using anchor mode')
+        end
+
+        unless valid_interval_unit?
+          errors.add(:interval_unit, 'must be one of: seconds, minutes, hours, days, weeks, months, years')
+        end
+      end
+    end
+
+    # Validate job class exists.
+    #
+    # Checks that job_class can be constantized and is either an ActiveJob::Base
+    # or Postburner::Job subclass.
+    #
+    # @return [void]
+    #
+    # @api private
+    #
+    def validate_job_class_exists!
+      return if job_class.blank?
+
+      # Try to constantize - if it fails, we'll add an error
+      klass = job_class.safe_constantize
+
+      if klass.nil?
+        errors.add(:job_class, "class '#{job_class}' does not exist")
+        return
+      end
+
+      # Check if it's a valid job class
+      # Use <= to include the class itself, not just subclasses
+      unless klass <= ::ActiveJob::Base || klass <= Postburner::Job
+        errors.add(:job_class, 'must be an ActiveJob or Postburner::Job subclass')
+      end
+    end
+
+    # Validate cron expression syntax.
+    #
+    # Uses the fugit gem to parse and validate cron expressions.
+    # Logs a warning if fugit is not available.
+    #
+    # @return [void]
+    #
+    # @api private
+    #
+    def validate_cron_expression!
+      return if cron.blank?
+
+      begin
+        require 'fugit'
+        parsed = Fugit::Cron.parse(cron)
+
+        if parsed.nil?
+          errors.add(:cron, 'is not a valid cron expression')
+        end
+      rescue LoadError
+        # fugit gem not loaded, skip validation
+        Rails.logger.warn "[Postburner::Schedule] fugit gem not available for cron validation"
+      rescue => e
+        errors.add(:cron, "validation error: #{e.message}")
+      end
+    end
+
+    # Check if interval_unit is valid.
+    #
+    # @return [Boolean] true if interval_unit is blank or one of the valid units
+    #
+    # @api private
+    #
+    def valid_interval_unit?
+      return true if interval_unit.blank?
+
+      %w[seconds minutes hours days weeks months years].include?(interval_unit)
+    end
+
+    # Calculate next run times using cron expression.
+    #
+    # Uses fugit gem to parse cron expression and calculate future run times.
+    # All calculations are performed in the schedule's timezone.
+    #
+    # @param after [Time] Calculate times after this time
+    # @param count [Integer] Number of times to calculate
+    # @return [Array<Time>] Array of future run times
+    # @raise [RuntimeError] If cron expression is invalid or fugit gem is not available
+    #
+    # @api private
+    #
+    def calculate_cron_times(after:, count:)
+      require 'fugit'
+
+      cron_parser = Fugit::Cron.parse(cron)
+      raise "Invalid cron expression: #{cron}" if cron_parser.nil?
+
+      times = []
+      current_time = tz.at(after.to_f)
+
+      count.times do
+        next_time = cron_parser.next_time(current_time)
+        break if next_time.nil?
+
+        times << next_time.to_time
+        current_time = next_time
+      end
+
+      times
+    rescue LoadError
+      raise "fugit gem is required for cron-based schedules. Add 'gem \"fugit\"' to your Gemfile"
+    end
+
+    # Calculate next run times using anchor and interval.
+    #
+    # Grid-aligned scheduling that maintains fixed intervals from anchor point.
+    # Never drifts - always calculates N*interval from anchor.
+    #
+    # @param after [Time] Calculate times after this time
+    # @param count [Integer] Number of times to calculate
+    # @return [Array<Time>] Array of future run times
+    #
+    # @api private
+    #
+    def calculate_anchor_times(after:, count:)
+      times = []
+      current_time = after
+
+      count.times do
+        next_time = calculate_next_anchor_time(current_time)
+        break if next_time.nil?
+
+        times << next_time
+        current_time = next_time
+      end
+
+      times
+    end
+
+    # Calculate next grid-aligned time from anchor.
+    #
+    # Snaps to the grid defined by anchor + N*interval, never drifts.
+    # This is like subscription billing - always on the anchor date/time.
+    #
+    # Delegates to specific calculation methods based on interval_unit:
+    # - Fixed intervals (seconds-weeks): calculate_next_fixed_interval_time
+    # - Months: calculate_next_month_time
+    # - Years: calculate_next_year_time
+    #
+    # @param from_time [Time] Calculate next time after this
+    # @return [Time] Next grid-aligned time
+    # @raise [RuntimeError] If interval_unit is unsupported
+    #
+    # @api private
+    #
+    def calculate_next_anchor_time(from_time)
+      from_time ||= tz.at(anchor.to_f)
+      anchor_time = tz.at(anchor.to_f)
+
+      case interval_unit
+      when 'seconds', 'minutes', 'hours', 'days', 'weeks'
+        calculate_next_fixed_interval_time(from_time, anchor_time)
+      when 'months'
+        calculate_next_month_time(from_time, anchor_time)
+      when 'years'
+        calculate_next_year_time(from_time, anchor_time)
+      else
+        raise "Unsupported interval unit: #{interval_unit}"
+      end
+    end
+
+    # Calculate next time for fixed-duration intervals (seconds through weeks).
+    #
+    # Uses integer arithmetic to avoid floating point precision issues.
+    # Finds the smallest N such that anchor + N*interval > from_time.
+    #
+    # @param from_time [Time] Calculate next time after this
+    # @param anchor_time [Time] The anchor point for grid alignment
+    # @return [Time] Next grid-aligned time
+    #
+    # @api private
+    #
+    def calculate_next_fixed_interval_time(from_time, anchor_time)
+      interval_seconds = case interval_unit
+                         when 'seconds' then interval
+                         when 'minutes' then interval * 60
+                         when 'hours' then interval * 3600
+                         when 'days' then interval * 86400
+                         when 'weeks' then interval * 604800
+                         end
+
+      # Use integer seconds to avoid floating point precision issues
+      elapsed = (from_time.to_i - anchor_time.to_i)
+
+      # Find the next grid point strictly AFTER from_time
+      # We need to find the smallest N such that anchor + N*interval > from_time
+      # That means N > elapsed/interval, so N = floor(elapsed/interval) + 1
+      intervals_passed = (elapsed / interval_seconds) + 1
+
+      # Handle case where from_time is before anchor
+      intervals_passed = 1 if intervals_passed < 1
+
+      anchor_time + (intervals_passed * interval_seconds)
+    end
+
+    # Calculate next time for month-based intervals.
+    #
+    # Handles variable month lengths like Flex subscription billing.
+    # Always snaps to the anchor's day-of-month (or end of month if shorter).
+    #
+    # Uses Rails Duration for month arithmetic with day adjustment.
+    # This ensures "snap back" behavior - e.g., Jan 31 -> Feb 28 -> Mar 31.
+    #
+    # @param from_time [Time] Calculate next time after this
+    # @param anchor_time [Time] The anchor point for grid alignment
+    # @return [Time] Next grid-aligned time
+    #
+    # @example Snap back behavior
+    #   anchor = Time.zone.parse('2025-01-31 09:00:00')
+    #   # Next runs: Jan 31, Feb 28 (or 29), Mar 31, Apr 30, May 31, ...
+    #
+    # @api private
+    #
+    def calculate_next_month_time(from_time, anchor_time)
+      requested_day = anchor_time.day
+
+      # Estimate starting interval based on months difference
+      months_diff = (from_time.year - anchor_time.year) * 12 + (from_time.month - anchor_time.month)
+      n = (months_diff.to_f / interval).floor
+      n = 0 if n < 0
+
+      # Find the first grid point strictly AFTER from_time
+      loop do
+        grid_point = month_grid_point_at(anchor_time, n, requested_day)
+        return grid_point if grid_point > from_time
+        n += 1
+      end
+    end
+
+    # Calculate the monthly grid point for a specific interval number.
+    #
+    # Uses Rails Duration for month arithmetic and adjusts day to match anchor.
+    # This ensures "snap back" behavior - e.g., Jan 31 -> Feb 28 -> Mar 31.
+    #
+    # @param anchor_time [Time] The anchor time
+    # @param n [Integer] Number of intervals from anchor
+    # @param requested_day [Integer] The day of month from anchor
+    # @return [Time] The grid point time
+    #
+    # @api private
+    #
+    def month_grid_point_at(anchor_time, n, requested_day)
+      # Use Rails Duration for month arithmetic (handles variable month lengths)
+      next_time = anchor_time + (n * interval).months
+
+      # Adjust day to match anchor's day (or end of month if shorter)
+      # This is the Flex pattern for "snap back" behavior
+      if next_time.end_of_month.day >= requested_day
+        next_time.change(day: requested_day)
+      else
+        next_time.change(day: next_time.end_of_month.day)
+      end
+    end
+
+    # Calculate next time for year-based intervals.
+    #
+    # Uses Rails Duration for year arithmetic (handles leap years automatically).
+    # Finds the smallest N such that anchor + N*interval > from_time.
+    #
+    # @param from_time [Time] Calculate next time after this
+    # @param anchor_time [Time] The anchor point for grid alignment
+    # @return [Time] Next grid-aligned time
+    #
+    # @example Leap year handling
+    #   anchor = Time.zone.parse('2024-02-29 09:00:00')  # Leap year
+    #   # Next run: 2025-02-28 (Rails Duration handles Feb 29 -> Feb 28)
+    #
+    # @api private
+    #
+    def calculate_next_year_time(from_time, anchor_time)
+      years_diff = from_time.year - anchor_time.year
+      n = (years_diff.to_f / interval).floor
+      n = 0 if n < 0
+
+      # Find the first grid point strictly AFTER from_time
+      loop do
+        # Rails Duration handles Feb 29 -> Feb 28 automatically
+        grid_point = anchor_time + (n * interval).years
+        return grid_point if grid_point > from_time
+        n += 1
+      end
+    end
+  end
+end