(MODULES-10893) Fix Last Day Of Month Trigger

Prior to this change, attempting to create a trigger that will run on
the last day of each selected month will fail. The error claims that a
a value is out of range

```
OLE error code:0 in <Unknown>
      <No Description>
    HRESULT error code:0x8002000a
      Out of present range.
```

Microsoft [documentation] claims in one place that the correct way to
specify the last day of a month is to effectively translate a bitmask
value of day 32 and pass that into the `{get:set}_DaysOfMonth` method
on the trigger object. The module was previously coded to do exactly
this. The provider and it's helpers would catch the string value 'last'
in the `on` property of a `monthly` trigger and translate it into the
bit mask. This is what resulted in the error, because it turns out that
the position for day 32 in the bit mast is outside the acceptable range
of values for this property.

This PR changes strategy and instead relies on a different section
of the documentation in which an entirely different property on the
trigger object called [RunOnLastDayOfMonth] is set.

The code now catches the string value 'last' in the `on` property of
the trigger, and sets this boolean on the trigger object.

Testing has shown this to be an effective method of managing this
property of a trigger.

[documentation]: https://docs.microsoft.com/en-gb/windows/win32/api/taskschd/nf-taskschd-imonthlytrigger-get_daysofmonth
[RunOnLastDayOfMonth]: https://docs.microsoft.com/en-gb/windows/win32/api/taskschd/nf-taskschd-imonthlytrigger-put_runonlastdayofmonth

Author: RandomNoun7

.travis.yml

@@ -13,7 +13,7 @@ before_install:
   - gem --version
   - bundle -v
 script:
-  - 'SIMPLECOV=yes bundle exec rake $CHECK'
+  - 'bundle exec rake $CHECK'
 bundler_args: --without system_tests
 rvm:
   - 2.5.7

README.md

@@ -301,6 +301,9 @@ For all triggers:
     Each month must be an integer between 1 and 12.
   * `on` (Required) — Which days of the month the task should run, as an array.
     Each day must be an integer between 1 and 31.
+    * The string `last` may be used in the array for this property to trigger a
+    task to run on the last day of each selected month. This feature is only
+    available for tasks with compatibility level `2` or higher.
 * For monthly (by weekday) triggers:
   * `months` — Which months the task should run, as an array. Defaults to all months. Each month must be an integer between 1 and 12.
   * `day_of_week` (Required) — Which day of the week the task should run, as an array with only one element.

lib/puppet/type/scheduled_task.rb

@@ -163,6 +163,7 @@ def insync?(current)
             all months. Each month must be an integer between 1 and 12.
           * `on` **(Required)** --- Which days of the month the task should run,
             as an array. Each day must be an integer between 1 and 31 or the string `last`.
+            The string `last` is only supported for tasks with level 2 compatibility or higher.
       * For `monthly` (by weekday) triggers:
           * `months` --- Which months the task should run, as an array. Defaults to
             all months. Each month must be an integer between 1 and 12.

lib/puppet_x/puppetlabs/scheduled_task/trigger.rb

@@ -5,7 +5,8 @@
 # @api private
 # PuppetX::PuppetLabs::ScheduledTask module
 module PuppetX::PuppetLabs::ScheduledTask
-  # This module is used to manage the triggers for the Task Scheduler V2 API
+  # @api private
+  # PuppetX::PuppetLabs::ScheduledTask::Trigger module
   module Trigger
     # Gets or sets the amount of time that is allowed to complete the task.
     class Duration
@@ -389,42 +390,46 @@ def self.bitmask_to_names(bitmask)
 
       # Defines the day of the month the task will run.
       class Days
-        # 32 bits for 31 possible days to set + value 'last'
-        MAX_VALUE = 0b11111111111111111111111111111111
+        # 32 bit mask, but only 31 days can be set.
+        # This is contrary to the V2 IMonthlyTrigger::DaysOfMonth documentation
+        # referenced below, but in testing, setting the last bit of the bit
+        # mask does not set 'last' day of month as that documentation suggests.
+        # Instead it results in an error. That feature will be handled instead
+        # by the RunOnLastDayOfMonth property of the trigger object.
+        # V2 IMonthlyTrigger::RunOnLastDayOfMonth
+        # https://docs.microsoft.com/en-us/windows/win32/api/taskschd/nf-taskschd-imonthlytrigger-put_runonlastdayofmonth
+        MAX_VALUE = 0b01111111111111111111111111111111
 
         # V1 MONTHLYDATE structure
         # https://msdn.microsoft.com/en-us/library/windows/desktop/aa381918(v=vs.85).aspx
         # V2 IMonthlyTrigger::DaysOfMonth
         # https://msdn.microsoft.com/en-us/library/windows/desktop/aa380735(v=vs.85).aspx
         def self.indexes_to_bitmask(day_indexes)
-          day_indexes = [day_indexes].flatten.map do |m|
-            # The special "day" of 'last' is represented by day "number"
-            # 32. 'last' has the special meaning of "the last day of the
-            # month", no matter how many days there are in the month.
-            # raises if unable to convert
-            (m.is_a?(String) && m.casecmp('last').zero?) ? 32 : Integer(m)
+          if day_indexes.nil? || (day_indexes.is_a?(Hash) && day_indexes.empty?)
+            raise TypeError, 'Day indexes value must not be nil or an empty hash.'
           end
 
-          invalid_days = day_indexes.reject { |i| i.between?(1, 32) }
+          integer_days = [day_indexes].flatten.select { |i| i.is_a?(Integer) }
+          invalid_days = integer_days.reject { |i| i.between?(1, 31) }
+
           unless invalid_days.empty?
-            raise ArgumentError, "Day indexes value #{invalid_days.join(', ')} is invalid. Integers must be in the range 1-31, or 'last'"
+            raise ArgumentError, "Day indexes value #{invalid_days.join(', ')} is invalid. Integers must be in the range 1-31"
           end
-
-          day_indexes.reduce(0) { |bitmask, day_index| bitmask | 1 << day_index - 1 }
+          integer_days.reduce(0) { |bitmask, day_index| bitmask | 1 << day_index - 1 }
         end
 
         # Converts bitmask to index
-        def self.bitmask_to_indexes(bitmask)
+        def self.bitmask_to_indexes(bitmask, run_on_last_day_of_month = nil)
           bitmask = Integer(bitmask)
           if bitmask.negative? || bitmask > MAX_VALUE
             raise ArgumentError, "bitmask must be specified as an integer from 0 to #{MAX_VALUE.to_s(10)}"
           end
 
-          bit_index(bitmask).map do |bit_index|
-            # Day 32 has the special meaning of "the last day of the
-            # month", no matter how many days there are in the month.
-            (bit_index == 31) ? 'last' : bit_index + 1
-          end
+          indexes = bit_index(bitmask).map { |bit_index| bit_index + 1 }
+
+          indexes << 'last' if run_on_last_day_of_month
+
+          indexes
         end
 
         # Returns bit index
@@ -435,6 +440,14 @@ def self.bit_index(bitmask)
             (bitmask & bit_to_check) == bit_to_check
           end
         end
+
+        def self.last_day_of_month?(day_indexes)
+          invalid_day_names = [day_indexes].flatten.select { |i| i.is_a?(String) && (i != 'last') }
+          unless invalid_day_names.empty?
+            raise ArgumentError, "Only 'last' is allowed as a day name. All other values must be integers between 1 and 31."
+          end
+          [day_indexes].flatten.include? 'last'
+        end
       end
 
       # Gets or sets the months of the year during which the task runs.
@@ -705,16 +718,16 @@ def self.to_manifest_hash(i_trigger)
           manifest_hash['schedule'] = 'daily'
           manifest_hash['every'] = i_trigger.DaysInterval
         when Type::TASK_TRIGGER_WEEKLY
-          manifest_hash.merge!('schedule' => 'weekly',
+          manifest_hash.merge!('schedule'    => 'weekly',
                                'every'       => i_trigger.WeeksInterval,
                                'day_of_week' => Day.bitmask_to_names(i_trigger.DaysOfWeek))
         when Type::TASK_TRIGGER_MONTHLY
           manifest_hash.merge!('schedule' => 'monthly',
                                'months'   => Month.bitmask_to_indexes(i_trigger.MonthsOfYear),
-                               'on'       => Days.bitmask_to_indexes(i_trigger.DaysOfMonth))
+                               'on'       => Days.bitmask_to_indexes(i_trigger.DaysOfMonth, i_trigger.RunOnLastDayOfMonth))
         when Type::TASK_TRIGGER_MONTHLYDOW
           occurrences = V2::WeeksOfMonth.bitmask_to_names(i_trigger.WeeksOfMonth)
-          manifest_hash.merge!('schedule' => 'monthly',
+          manifest_hash.merge!('schedule'         => 'monthly',
                                'months'           => Month.bitmask_to_indexes(i_trigger.MonthsOfYear),
                                # HACK: choose only the first week selected when converting - this LOSES information
                                'which_occurrence' => occurrences.first || '',
@@ -783,6 +796,7 @@ def self.append_trigger(definition, manifest_hash)
 
         when Type::TASK_TRIGGER_MONTHLY
           # https://msdn.microsoft.com/en-us/library/windows/desktop/aa382062(v=vs.85).aspx
+          i_trigger.RunOnLastDayOfMonth = Days.last_day_of_month?(manifest_hash['on'])
           i_trigger.DaysOfMonth = Days.indexes_to_bitmask(manifest_hash['on'])
           i_trigger.MonthsOfYear = Month.indexes_to_bitmask(manifest_hash['months'] || Month.indexes)