Add SchedulerAgent, which periodically runs other agents.

.env.example

@@ -104,6 +104,12 @@ ALLOW_JSONPATH_EVAL=false
 # when you trust everyone using your Huginn installation.
 ENABLE_INSECURE_AGENTS=false
 
+# Enable this setting to allow second precision schedule in
+# SchedulerAgent.  By default, the use of the "second" field is
+# restricted so that any value other than a single zero (which means
+# "on the minute") is disallowed.
+ENABLE_SECOND_PRECISION_SCHEDULE=false
+
 # Use Graphviz for generating diagrams instead of using Google Chart
 # Tools.  Specify a dot(1) command path built with SVG support
 # enabled.

app/assets/javascripts/application.js.coffee.erb

@@ -22,14 +22,13 @@ window.setupJsonEditor = ($editors = $(".live-json-editor")) ->
   return editors
 
 hideSchedule = ->
-  $(".schedule-region select").hide()
+  $(".schedule-region .can-be-scheduled").hide()
   $(".schedule-region .cannot-be-scheduled").show()
 
 showSchedule = (defaultSchedule = null) ->
-  $(".schedule-region select").show()
   if defaultSchedule?
     $(".schedule-region select").val(defaultSchedule).change()
-  $(".schedule-region select").show()
+  $(".schedule-region .can-be-scheduled").show()
   $(".schedule-region .cannot-be-scheduled").hide()
 
 hideLinks = ->
@@ -43,6 +42,16 @@ showLinks = ->
   $(".link-region .cannot-receive-events").hide()
   showEventDescriptions()
 
+hideChains = ->
+  $(".chain-region .select2-container").hide()
+  $(".chain-region .propagate-immediately").hide()
+  $(".chain-region .cannot-receive-events").show()
+
+showChains = ->
+  $(".chain-region .select2-container").show()
+  $(".chain-region .propagate-immediately").show()
+  $(".chain-region .cannot-receive-events").hide()
+
 hideEventCreation = ->
   $(".event-related-region").hide()
 
@@ -161,6 +170,11 @@ $(document).ready ->
         else
           hideLinks()
 
+        if json.can_control_other_agents
+          showChains()
+        else
+          hideChains()
+
         if json.can_create_events
           showEventCreation()
         else
@@ -191,6 +205,12 @@ $(document).ready ->
     else
       hideLinks()
 
+  if $(".chain-region")
+    if $(".chain-region").data("can-control-other-agents") == true
+      showChains()
+    else
+      hideChains()
+
   if $(".event-related-region")
     if $(".event-related-region").data("can-create-events") == true
       showEventCreation()

app/concerns/agent_controller_concern.rb

@@ -0,0 +1,45 @@
+module AgentControllerConcern
+  extend ActiveSupport::Concern
+
+  included do
+    validate :validate_control_action
+  end
+
+  def default_options
+    {
+      'action' => 'run',
+    }
+  end
+
+  def control_action
+    options['action'].presence || 'run'
+  end
+
+  def validate_control_action
+    case control_action
+    when 'run', 'enable', 'disable'
+    else
+      errors.add(:base, 'invalid action')
+    end
+  end
+
+  def control_targets!
+    targets.active.each { |target|
+      begin
+        case control_action
+        when 'run'
+          log "Agent run queued for '#{target.name}'"
+          Agent.async_check(target.id)
+        when 'enable'
+          log "Enabling the Agent '#{target.name}'"
+          target.update!(disable: false) if target.disabled?
+        when 'disable'
+          log "Disabling the Agent '#{target.name}'"
+          target.update!(disable: true) unless target.disabled?
+        end
+      rescue => e
+        log "Failed to #{control_action} '#{target.name}': #{e.message}"
+      end
+    }
+  end
+end

app/helpers/agent_helper.rb

@@ -15,4 +15,14 @@ def scenario_links(agent)
   def agent_show_class(agent)
     agent.short_type.underscore.dasherize
   end
-end
+
+  def agent_schedule(agent, delimiter = ', ')
+    return 'n/a' unless agent.can_be_scheduled?
+
+    controllers = agent.controllers
+    [
+      *(CGI.escape_html(agent.schedule.humanize.titleize) unless agent.schedule == 'never' && agent.controllers.count > 0),
+      *controllers.map { |agent| link_to(agent.name, agent_path(agent)) },
+    ].join(delimiter).html_safe
+  end
+end

app/helpers/dot_helper.rb

@@ -138,7 +138,9 @@ def agent_node(agent)
       def agent_edge(agent, receiver)
         edge(agent_id[agent],
              agent_id[receiver],
-             style: ('dashed' unless receiver.propagate_immediately),
+             style: ('dashed' unless agent.can_control_other_agents? || !receiver.propagate_immediately?),
+             label: (" #{agent.control_action}s " if agent.can_control_other_agents?),
+             arrowhead: ('empty' if agent.can_control_other_agents?),
              color: (@disabled if agent.disabled? || receiver.disabled?))
       end
 
@@ -151,10 +153,17 @@ def agent_edge(agent, receiver)
                   fontsize: 10,
                   fontname: ('Helvetica' if rich)
 
+        statement 'edge',
+                  fontsize: 10,
+                  fontname: ('Helvetica' if rich)
+
         agents.each.with_index { |agent, index|
           agent_node(agent)
 
-          agent.receivers.each { |receiver|
+          [
+            *agent.receivers,
+            *(agent.targets if agent.can_control_other_agents?)
+          ].each { |receiver|
             agent_edge(agent, receiver) if agents.include?(receiver)
           }
         }

app/models/agent.rb

@@ -25,13 +25,15 @@ class Agent < ActiveRecord::Base
 
   EVENT_RETENTION_SCHEDULES = [["Forever", 0], ["1 day", 1], *([2, 3, 4, 5, 7, 14, 21, 30, 45, 90, 180, 365].map {|n| ["#{n} days", n] })]
 
-  attr_accessible :options, :memory, :name, :type, :schedule, :disabled, :source_ids, :scenario_ids, :keep_events_for, :propagate_immediately
+  attr_accessible :options, :memory, :name, :type, :schedule, :controller_ids, :target_ids, :disabled, :source_ids, :scenario_ids, :keep_events_for, :propagate_immediately
 
   json_serialize :options, :memory
 
   validates_presence_of :name, :user
   validates_inclusion_of :keep_events_for, :in => EVENT_RETENTION_SCHEDULES.map(&:last)
   validate :sources_are_owned
+  validate :controllers_are_owned
+  validate :targets_are_owned
   validate :scenarios_are_owned
   validate :validate_schedule
   validate :validate_options
@@ -52,6 +54,10 @@ class Agent < ActiveRecord::Base
   has_many :links_as_receiver, :dependent => :delete_all, :foreign_key => "receiver_id", :class_name => "Link", :inverse_of => :receiver
   has_many :sources, :through => :links_as_receiver, :class_name => "Agent", :inverse_of => :receivers
   has_many :receivers, :through => :links_as_source, :class_name => "Agent", :inverse_of => :sources
+  has_many :chains_as_controller, dependent: :delete_all, foreign_key: 'controller_id', class_name: 'Chain', inverse_of: :controller
+  has_many :chains_as_target, dependent: :delete_all, foreign_key: 'target_id', class_name: 'Chain', inverse_of: :target
+  has_many :controllers, through: :chains_as_target, class_name: "Agent", inverse_of: :targets
+  has_many :targets, through: :chains_as_controller, class_name: "Agent", inverse_of: :controllers
   has_many :scenario_memberships, :dependent => :destroy, :inverse_of => :agent
   has_many :scenarios, :through => :scenario_memberships, :inverse_of => :agents
 
@@ -176,6 +182,10 @@ def can_create_events?
     !cannot_create_events?
   end
 
+  def can_control_other_agents?
+    self.class.can_control_other_agents?
+  end
+
   def log(message, options = {})
     puts "Agent##{id}: #{message}" unless Rails.env.test?
     AgentLog.log_for_agent(self, message, options)
@@ -218,6 +228,14 @@ def sources_are_owned
     errors.add(:sources, "must be owned by you") unless sources.all? {|s| s.user == user }
   end
 
+  def controllers_are_owned
+    errors.add(:controllers, "must be owned by you") unless controllers.all? {|s| s.user == user }
+  end
+
+  def targets_are_owned
+    errors.add(:targets, "must be owned by you") unless targets.all? {|s| s.user == user }
+  end
+
   def scenarios_are_owned
     errors.add(:scenarios, "must be owned by you") unless scenarios.all? {|s| s.user == user }
   end
@@ -249,7 +267,7 @@ def boolify(option_value)
 
   class << self
     def build_clone(original)
-      new(original.slice(:type, :options, :schedule, :source_ids, :keep_events_for, :propagate_immediately)) { |clone|
+      new(original.slice(:type, :options, :schedule, :controller_ids, :source_ids, :keep_events_for, :propagate_immediately)) { |clone|
         # Give it a unique name
         2.upto(count) do |i|
           name = '%s (%d)' % [original.name, i]
@@ -290,6 +308,10 @@ def cannot_receive_events?
       !!@cannot_receive_events
     end
 
+    def can_control_other_agents?
+      include? AgentControllerConcern
+    end
+
     # Find all Agents that have received Events since the last execution of this method.  Update those Agents with
     # their new `last_checked_event_id` and queue each of the Agents to be called with #receive using `async_receive`.
     # This is called by bin/schedule.rb periodically.
@@ -399,6 +421,8 @@ def type
     :sources,
     :receivers,
     :schedule,
+    :controllers,
+    :targets,
     :disabled,
     :keep_events_for,
     :propagate_immediately,

app/models/agents/scheduler_agent.rb

@@ -0,0 +1,115 @@
+require 'rufus-scheduler'
+
+module Agents
+  class SchedulerAgent < Agent
+    include AgentControllerConcern
+
+    cannot_be_scheduled!
+    cannot_receive_events!
+    cannot_create_events!
+
+    @@second_precision_enabled = ENV['ENABLE_SECOND_PRECISION_SCHEDULE'] == 'true'
+
+    cattr_reader :second_precision_enabled
+
+    description <<-MD % { seconds: (<<-MD_SECONDS if second_precision_enabled) }
+      This agent periodically takes an action on target Agents according to a user-defined schedule.
+
+      # Action types
+
+      Set `action` to one of the action types below:
+
+      * `run`: This is the default.  Target Agents are run at intervals.
+
+      * `disable`: Target Agents are disabled (if not) at intervals.
+
+      * `enable`: Target Agents are enabled (if not) at intervals.
+
+      # Targets
+
+      Select Agents that you want to run periodically by this SchedulerAgent.
+
+      # Schedule
+
+      Set `schedule` to a schedule specification in the [cron](http://en.wikipedia.org/wiki/Cron) format.
+      For example:
+
+      * `0 22 * * 1-5`: every day of the week at 22:00 (10pm)
+
+      * `*/10 8-11 * * *`: every 10 minutes from 8:00 to and not including 12:00
+
+      This variant has several extensions as explained below.
+
+      ## Timezones
+
+      You can optionally specify a timezone (default: `#{Time.zone.name}`) after the day-of-week field.
+
+      * `0 22 * * 1-5 Europe/Paris`: every day of the week when it's 22:00 in Paris
+
+      * `0 22 * * 1-5 Etc/GMT+2`: every day of the week when it's 22:00 in GMT+2
+
+      %{seconds}
+
+      ## Last day of month
+
+      `L` signifies "last day of month" in `day-of-month`.
+
+      * `0 22 L * *`: every month on the last day at 22:00
+
+      ## Weekday names
+
+      You can use three letter names instead of numbers in the `weekdays` field.
+
+      * `0 22 * * Sat,Sun`: every Saturday and Sunday, at 22:00
+
+      ## Nth weekday of the month
+
+      You can specify "nth weekday of the month" like this.
+
+      * `0 22 * * Sun#1,Sun#2`: every first and second Sunday of the month, at 22:00
+
+      * `0 22 * * Sun#L1`: every last Sunday of the month, at 22:00
+    MD
+
+      ## Seconds
+
+      You can optionally specify seconds before the minute field.
+
+      * `*/30 * * * * *`: every 30 seconds
+
+    MD_SECONDS
+
+    def default_options
+      super.update({
+        'schedule' => '0 * * * *',
+      })
+    end
+
+    def working?
+      true
+    end
+
+    def check!
+      control_targets!
+    end
+
+    def validate_options
+      if (spec = options['schedule']).present?
+        begin
+          cron = Rufus::Scheduler::CronLine.new(spec)
+          if !second_precision_enabled && cron.seconds != [0]
+            errors.add(:base, "second precision schedule is not allowed in this service")
+          end
+        rescue ArgumentError
+          errors.add(:base, "invalid schedule")
+        end
+      else
+        errors.add(:base, "schedule is missing")
+      end
+    end
+
+    before_save do
+      self.memory.delete('scheduled_at') if self.options_changed?
+    end
+  end
+end

app/models/chain.rb

@@ -0,0 +1,7 @@
+# A Chain connects Agents in a run chain from the `controller` to the `target`.
+class Chain < ActiveRecord::Base
+  attr_accessible :controller_id, :target_id
+
+  belongs_to :controller, class_name: 'Agent', inverse_of: :chains_as_controller
+  belongs_to :target, class_name: 'Agent', inverse_of: :chains_as_target
+end