procrastinator 0.6.1 → 0.9.0

data/lib/procrastinator/queue_worker.rb

@@ -1,116 +1,136 @@
+# frozen_string_literal: true
+
 module Procrastinator
+   # A QueueWorker checks for tasks to run from the loader defined in the provided config and executes them,
+   # updating information in the task loader as necessary.
+   #
+   # @author Robin Miller
    class QueueWorker
-      DEFAULT_TIMEOUT       = 3600 # in seconds; one hour total
-      DEFAULT_MAX_ATTEMPTS  = 20
-      DEFAULT_UPDATE_PERIOD = 10 # seconds
-      DEFAULT_MAX_TASKS     = 10
-
-      attr_reader :name, :timeout, :max_attempts, :update_period, :max_tasks
-
-      # Timeout is in seconds
-      def initialize(name:,
-                     persister:,
-                     log_dir: nil,
-                     log_level: Logger::INFO,
-                     max_attempts: DEFAULT_MAX_ATTEMPTS,
-                     timeout: DEFAULT_TIMEOUT,
-                     update_period: DEFAULT_UPDATE_PERIOD,
-                     max_tasks: DEFAULT_MAX_TASKS)
-         raise ArgumentError.new('Queue name may not be nil') unless name
-         raise ArgumentError.new('Persister may not be nil') unless persister
-
-         raise(MalformedTaskPersisterError.new('The supplied IO object must respond to #read_tasks')) unless persister.respond_to? :read_tasks
-         raise(MalformedTaskPersisterError.new('The supplied IO object must respond to #update_task')) unless persister.respond_to? :update_task
-         raise(MalformedTaskPersisterError.new('The supplied IO object must respond to #delete_task')) unless persister.respond_to? :delete_task
-
-         @name          = name.to_s.gsub(/\s/, '_').to_sym
-         @timeout       = timeout
-         @max_attempts  = max_attempts
-         @update_period = update_period
-         @max_tasks     = max_tasks
-         @persister     = persister
-         @log_dir       = log_dir
-         @log_level     = log_level
+      extend Forwardable
 
-         start_log
+      def_delegators :@queue, :name
+
+      # expected methods for all persistence strategies
+      PERSISTER_METHODS = [:read, :update, :delete].freeze
+
+      def initialize(queue:, config:, scheduler: nil)
+         @queue     = queue
+         @config    = config
+         @scheduler = scheduler
+
+         @logger = nil
       end
 
       def work
+         start_log
+
          begin
             loop do
-               sleep(@update_period)
+               sleep(@queue.update_period)
 
                act
             end
          rescue StandardError => e
+            raise if @config.test_mode? || !@logger
+
             @logger.fatal(e)
-            # raise e
          end
       end
 
       def act
-         # shuffling and re-sorting to avoid worst case O(n^2) on quicksort (which is default ruby sort)
-         # when receiving already sorted data. Ideally, we'd use a better algo, but this will do for now
-         tasks = @persister.read_tasks(@name).reject { |t| t[:run_at].nil? }.shuffle.sort_by { |t| t[:run_at] }
+         persister = @config.loader
 
-         tasks.first(@max_tasks).each do |task_data|
-            if Time.now.to_i >= task_data[:run_at].to_i
-               task_data.merge!(logger: @logger) if @logger
+         tasks = fetch_tasks(persister)
 
-               tw = TaskWorker.new(task_data)
+         tasks.each do |metadata|
+            tw = build_worker(metadata)
 
-               tw.work
+            tw.work
 
-               if tw.successful?
-                  @persister.delete_task(task_data[:id])
-               else
-                  @persister.update_task(tw.to_hash.merge(queue: @name))
-               end
+            if tw.successful?
+               persister.delete(metadata.id)
+            else
+               persister.update(metadata.id, tw.to_h.merge(queue: @queue.name.to_s))
             end
          end
       end
 
       def long_name
-         "#{@name}-queue-worker"
+         name = "#{ @queue.name }-queue-worker"
+
+         name = "#{ @config.prefix }-#{ name }" if @config.prefix
+
+         name
       end
 
       # Starts a log file and stores the logger within this queue worker.
       #
       # Separate from init because logging is context-dependent
       def start_log
-         if @log_dir
-            log_path = Pathname.new("#{@log_dir}/#{long_name}.log")
+         return if @logger || !@config.log_dir
 
-            log_path.dirname.mkpath
-            File.open(log_path.to_path, 'a+') do |f|
-               f.write ''
-            end
+         @logger = Logger.new(log_target, level: @config.log_level)
 
-            @logger = Logger.new(log_path.to_path)
+         msg = <<~MSG
+            ======================================================================
+            Started worker process, #{ long_name }, to work off queue #{ @queue.name }.
+            Worker pid=#{ Process.pid }; parent pid=#{ Process.ppid }.
+            ======================================================================
+         MSG
 
-            @logger.level = @log_level
+         @logger.info("\n#{ msg }")
+      end
+
+      private
+
+      def build_worker(metadata)
+         start_log
 
-            @logger.info(['',
-                          '===================================',
-                          "Started worker process, #{long_name}, to work off queue #{@name}.",
-                          "Worker pid=#{Process.pid}; parent pid=#{Process.ppid}.",
-                          '==================================='].join("\n"))
+         TaskWorker.new(metadata:  metadata,
+                        queue:     @queue,
+                        scheduler: @scheduler,
+                        context:   @config.context,
+                        logger:    @logger)
+      end
+
+      def log_target
+         return $stdout if @config.test_mode?
+
+         log_path = @config.log_dir + "#{ long_name }.log"
+
+         write_log_file(log_path)
+
+         log_path.to_path
+      end
+
+      def write_log_file(log_path)
+         @config.log_dir.mkpath
+         File.open(log_path.to_path, 'a+') do |f|
+            f.write ''
          end
       end
 
-      # Logs a termination due to parent process termination
-      #
-      # == Parameters:
-      # @param ppid the parent's process id
-      # @param pid the child's process id
-      #
-      def log_parent_exit(ppid:, pid:)
-         raise RuntimeError.new('Cannot log when logger not defined. Call #start_log first.') unless @logger
+      def fetch_tasks(persister)
+         tasks = persister.read(queue: @queue.name).map(&:to_h).reject { |t| t[:run_at].nil? }
+
+         tasks = sort_tasks(tasks)
+
+         metas = tasks.collect do |t|
+            TaskMetaData.new(t.delete_if { |key| !TaskMetaData::EXPECTED_DATA.include?(key) })
+         end
+
+         metas.select(&:runnable?)
+      end
 
-         @logger.error("Terminated worker process (pid=#{pid}) due to main process (ppid=#{ppid}) disappearing.")
+      def sort_tasks(tasks)
+         # shuffling and re-sorting to avoid worst case O(n^2) when receiving already sorted data
+         # on quicksort (which is default ruby sort). It is not unreasonable that the persister could return sorted
+         # results
+         # Ideally, we'd use a better algo than qsort for this, but this will do for now
+         tasks.shuffle.sort_by { |t| t[:run_at] }.first(@queue.max_tasks)
       end
    end
 
    class MalformedTaskPersisterError < StandardError
    end
-end
+end

data/lib/procrastinator/scheduler.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Procrastinator
+   # A Scheduler object provides the API for client applications to manage delayed tasks.
+   #
+   # Use #delay to schedule new tasks, #reschedule to alter existing tasks, and #cancel to remove unwanted tasks.
+   #
+   # @author Robin Miller
+   class Scheduler
+      extend Forwardable
+
+      def_delegators :@queue_manager, :act
+
+      def initialize(config, queue_manager)
+         @config        = config
+         @queue_manager = queue_manager
+      end
+
+      # Records a new task to be executed at the given time.
+      #
+      # @param queue [Symbol] the symbol identifier for the queue to add a new task on
+      # @param run_at [Time, Integer] Optional time when this task should be executed. Defaults to the current time.
+      # @param data [Hash, Array] Optional simple data object to be provided to the task upon execution.
+      # @param expire_at [Time, Integer] Optional time when the task should be abandoned
+      def delay(queue = nil, data: nil, run_at: Time.now.to_i, expire_at: nil)
+         verify_queue_arg!(queue)
+
+         queue = @config.queue.name if @config.single_queue?
+
+         verify_queue_data!(queue, data)
+
+         loader.create(queue:          queue.to_s,
+                       run_at:         run_at.to_i,
+                       initial_run_at: run_at.to_i,
+                       expire_at:      expire_at.nil? ? nil : expire_at.to_i,
+                       data:           YAML.dump(data))
+      end
+
+      # Alters an existing task to run at a new time, expire at a new time, or both.
+      #
+      # Call #to on the result and pass in the new :run_at and/or :expire_at.
+      #
+      # Example:
+      #
+      # scheduler.reschedule(:alerts, data: {user_id: 5}).to(run_at: Time.now, expire_at: Time.now + 10)
+      #
+      # The identifier can include any data field stored in the task loader. Often this is the information in :data.
+      #
+      # @param queue [Symbol] the symbol identifier for the queue to add a new task on
+      # @param identifier [Hash] Some identifying information to find the appropriate task.
+      #
+      # @see TaskMetaData
+      def reschedule(queue, identifier)
+         UpdateProxy.new(@config, identifier: identifier.merge(queue: queue.to_s))
+      end
+
+      # Removes an existing task, as located by the givne identifying information.
+      #
+      # The identifier can include any data field stored in the task loader. Often this is the information in :data.
+      #
+      # @param queue [Symbol] the symbol identifier for the queue to add a new task on
+      # @param identifier [Hash] Some identifying information to find the appropriate task.
+      #
+      # @see TaskMetaData
+      def cancel(queue, identifier)
+         tasks = loader.read(identifier.merge(queue: queue.to_s))
+
+         raise "no task matches search: #{ identifier }" if tasks.empty?
+         raise "multiple tasks match search: #{ identifier }" if tasks.size > 1
+
+         loader.delete(tasks.first[:id])
+      end
+
+      # Provides a more natural syntax for rescheduling tasks
+      #
+      # @see Scheduler#reschedule
+      class UpdateProxy
+         def initialize(config, identifier:)
+            identifier[:data] = YAML.dump(identifier[:data]) if identifier[:data]
+
+            @config     = config
+            @identifier = identifier
+         end
+
+         def to(run_at: nil, expire_at: nil)
+            task = fetch_task(@identifier)
+
+            verify_time_provided(run_at, expire_at)
+            validate_run_at(run_at, task[:expire_at], expire_at)
+
+            new_data = {
+                  attempts:      0,
+                  last_error:    nil,
+                  last_error_at: nil
+            }
+
+            new_data = new_data.merge(run_at: run_at.to_i, initial_run_at: run_at.to_i) if run_at
+            new_data = new_data.merge(expire_at: expire_at.to_i) if expire_at
+
+            @config.loader.update(task[:id], new_data)
+         end
+
+         alias at to
+
+         private
+
+         def verify_time_provided(run_at, expire_at)
+            raise ArgumentError, 'you must provide at least :run_at or :expire_at' if run_at.nil? && expire_at.nil?
+         end
+
+         def validate_run_at(run_at, saved_expire_at, expire_at)
+            return unless run_at
+
+            after_new_expire = expire_at && run_at.to_i > expire_at.to_i
+
+            raise "given run_at (#{ run_at }) is later than given expire_at (#{ expire_at })" if after_new_expire
+
+            after_old_expire = saved_expire_at && run_at.to_i > saved_expire_at
+
+            raise "given run_at (#{ run_at }) is later than saved expire_at (#{ saved_expire_at })" if after_old_expire
+         end
+
+         def fetch_task(identifier)
+            tasks = @config.loader.read(identifier)
+
+            raise "no task found matching #{ identifier }" if tasks.nil? || tasks.empty?
+            raise "too many (#{ tasks.size }) tasks match #{ identifier }. Found: #{ tasks }" if tasks.size > 1
+
+            tasks.first
+         end
+      end
+
+      private
+
+      # Scheduler must always get the loader indirectly. If it saves the loader to an instance variable,
+      # then that could hold a reference to a bad (ie. gone) connection on the previous process
+      def loader
+         @config.loader
+      end
+
+      def verify_queue_arg!(queue_name)
+         raise ArgumentError, <<~ERR if !queue_name.nil? && !queue_name.is_a?(Symbol)
+            must provide a queue name as the first argument. Received: #{ queue_name }
+         ERR
+
+         raise ArgumentError, <<~ERR if queue_name.nil? && !@config.single_queue?
+            queue must be specified when more than one is registered. Defined queues are: #{ @config.queues_string }
+         ERR
+      end
+
+      def verify_queue_data!(queue_name, data)
+         queue = @config.queue(name: queue_name)
+
+         unless queue
+            queue_list = @config.queues_string
+            raise ArgumentError, "there is no :#{ queue_name } queue registered. Defined queues are: #{ queue_list }"
+         end
+
+         if data.nil?
+            if queue.task_class.method_defined?(:data=)
+               raise ArgumentError, "task #{ queue.task_class } expects to receive :data. Provide :data to #delay."
+            end
+         elsif !queue.task_class.method_defined?(:data=)
+            raise ArgumentError, <<~ERROR
+               task #{ queue.task_class } does not import :data. Add this in your class definition:
+                     task_attr :data
+            ERROR
+         end
+      end
+   end
+end

data/lib/procrastinator/task.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Procrastinator
+   # Module to be included by user-defined task classes. It provides some extra error checking and a convenient way
+   # for the task class to access additional information (data, logger, etc) from Procrastinator.
+   #
+   # If you are averse to including this in your task class, you can just declare an attr_accessor for the
+   # information you want Procrastinator to feed your task.
+   #
+   # @author Robin Miller
+   module Task
+      KNOWN_ATTRIBUTES = [:logger, :context, :data, :scheduler].freeze
+
+      def self.included(base)
+         base.extend(TaskClassMethods)
+      end
+
+      def respond_to_missing?(name, include_private)
+         super
+      end
+
+      def method_missing(method_name, *args, &block)
+         if KNOWN_ATTRIBUTES.include?(method_name)
+            raise NameError, "To access Procrastinator::Task attribute :#{ method_name }, " \
+                             "call task_attr(:#{ method_name }) in your class definition."
+         end
+
+         super
+      end
+
+      # Module that provides the task_attr class method for task definitions to declare their expected information.
+      module TaskClassMethods
+         def task_attr(*fields)
+            attr_list = KNOWN_ATTRIBUTES.collect { |a| ':' + a.to_s }.join(', ')
+
+            fields.each do |field|
+               err = "Unknown Procrastinator::Task attribute :#{ field }. " \
+                     "Importable attributes are: #{ attr_list }"
+               raise ArgumentError, err unless KNOWN_ATTRIBUTES.include?(field)
+            end
+
+            attr_accessor(*fields)
+         end
+      end
+   end
+end

data/lib/procrastinator/task_meta_data.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Procrastinator
+   # TaskMetaData objects are State Patterns that record information about the work done on a particular task.
+   #
+   # It contains the specific information needed to run a task instance. Users define a task class, which describes
+   # the "how" of a task and TaskMetaData represents the "what" and "when".
+   #
+   # It contains task-specific data, timing information, and error records.
+   #
+   # All of its state is read-only.
+   #
+   # @author Robin Miller
+   #
+   # @!attribute [r] :id
+   #    @return [Integer] the unique identifier for this task
+   # @!attribute [r] :run_at
+   #    @return [Integer] Linux epoch timestamp of when to attempt this task next
+   # @!attribute [r] :initial_run_at
+   #    @return [Integer] Linux epoch timestamp of the original value for run_at
+   # @!attribute [r] :expire_at
+   #    @return [Integer] Linux epoch timestamp of when to consider this task obsolete
+   # @!attribute [r] :attempts
+   #    @return [Integer] The number of times this task has been attempted
+   # @!attribute [r] :last_error
+   #    @return [String] The message and stack trace of the error encountered on the most recent failed attempt
+   # @!attribute [r] :last_fail_at
+   #    @return [Integer] Linux epoch timestamp of when the last_error was recorded
+   # @!attribute [r] :data
+   #    @return [String] User-provided data serialized to string using YAML
+   class TaskMetaData
+      # These are the attributes expected to be in the persistence mechanism
+      EXPECTED_DATA = [:id, :run_at, :initial_run_at, :expire_at, :attempts, :last_error, :last_fail_at, :data].freeze
+
+      attr_reader(*EXPECTED_DATA)
+
+      def initialize(id: nil,
+                     run_at: nil,
+                     initial_run_at: nil,
+                     expire_at: nil,
+                     attempts: 0,
+                     last_error: nil,
+                     last_fail_at: nil,
+                     data: nil)
+         @id             = id
+         @run_at         = run_at.nil? ? nil : run_at.to_i
+         @initial_run_at = initial_run_at.to_i
+         @expire_at      = expire_at.nil? ? nil : expire_at.to_i
+         @attempts       = attempts || 0
+         @last_error     = last_error
+         @last_fail_at   = last_fail_at
+         @data           = data ? YAML.safe_load(data, [Symbol, Date]) : nil
+      end
+
+      def init_task(queue)
+         @data ? queue.task_class.new(@data) : queue.task_class.new
+      end
+
+      def add_attempt
+         @attempts += 1
+      end
+
+      def clear_fails
+         @last_error   = nil
+         @last_fail_at = nil
+      end
+
+      def fail(msg, final: false)
+         @last_fail_at = Time.now.to_i
+         @last_error   = msg
+         @run_at       = nil if final
+      end
+
+      def final_fail?(queue)
+         too_many_fails?(queue) || expired?
+      end
+
+      def expired?
+         !@expire_at.nil? && Time.now.to_i > @expire_at
+      end
+
+      def too_many_fails?(queue)
+         !queue.max_attempts.nil? && @attempts >= queue.max_attempts
+      end
+
+      def runnable?
+         !(@run_at.nil? || Time.now.to_i < @run_at)
+      end
+
+      def successful?
+         raise 'you cannot check for success before running #work' if !expired? && @attempts <= 0
+
+         !expired? && @last_error.nil? && @last_fail_at.nil?
+      end
+
+      # TODO: This cop for ** is currently incorrect. This disable can be removed once they fix it.
+      # rubocop:disable Layout/SpaceAroundOperators
+      def reschedule
+         # (30 + n_attempts^4) seconds is chosen to rapidly expand
+         # but with the baseline of 30s to avoid hitting the disk too frequently.
+         @run_at += 30 + (@attempts ** 4) unless @run_at.nil?
+      end
+
+      # rubocop:enable Layout/SpaceAroundOperators
+
+      def serialized_data
+         YAML.dump(@data)
+      end
+
+      def verify_expiry!
+         raise TaskExpiredError, "task is over its expiry time of #{ @expire_at }" if expired?
+      end
+
+      def to_h
+         {id:             @id,
+          run_at:         @run_at,
+          initial_run_at: @initial_run_at,
+          expire_at:      @expire_at,
+          attempts:       @attempts,
+          last_fail_at:   @last_fail_at,
+          last_error:     @last_error,
+          data:           serialized_data}
+      end
+   end
+
+   class TaskExpiredError < StandardError
+   end
+end