procrastinator 0.9.0 → 1.0.0.pre.rc3

data/lib/procrastinator/scheduler.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'stringio'
+
 module Procrastinator
    # A Scheduler object provides the API for client applications to manage delayed tasks.
    #
@@ -7,33 +9,24 @@ module Procrastinator
    #
    # @author Robin Miller
    class Scheduler
-      extend Forwardable
-
-      def_delegators :@queue_manager, :act
-
-      def initialize(config, queue_manager)
-         @config        = config
-         @queue_manager = queue_manager
+      def initialize(config)
+         @config = config
       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 queue_name [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 data [Hash, Array, String, Integer] Optional simple data object to be provided to the task on 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?
+      def delay(queue_name = nil, data: nil, run_at: Time.now, expire_at: nil)
+         raise ArgumentError, <<~ERR unless queue_name.nil? || queue_name.is_a?(Symbol)
+            must provide a queue name as the first argument. Received: #{ queue_name }
+         ERR
 
-         verify_queue_data!(queue, data)
+         queue = @config.queue(name: queue_name)
 
-         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))
+         queue.create(run_at: run_at, expire_at: expire_at, data: data)
       end
 
       # Alters an existing task to run at a new time, expire at a new time, or both.
@@ -54,7 +47,7 @@ module Procrastinator
          UpdateProxy.new(@config, identifier: identifier.merge(queue: queue.to_s))
       end
 
-      # Removes an existing task, as located by the givne identifying information.
+      # Removes an existing task, as located by the given identifying information.
       #
       # The identifier can include any data field stored in the task loader. Often this is the information in :data.
       #
@@ -63,109 +56,335 @@ module Procrastinator
       #
       # @see TaskMetaData
       def cancel(queue, identifier)
-         tasks = loader.read(identifier.merge(queue: queue.to_s))
+         queue = @config.queue(name: queue)
+
+         tasks = queue.read(identifier.merge(queue: queue.name.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])
+         queue.delete(tasks.first[:id])
+      end
+
+      # Spawns a new worker thread for each queue defined in the config
+      #
+      # @param queue_names [Array<String,Symbol>] Names of specific queues to act upon.
+      #                                           Omit or leave empty to act on all queues.
+      def work(*queue_names)
+         queue_names = @config.queues if queue_names.empty?
+
+         workers = queue_names.collect do |queue_name|
+            QueueWorker.new(queue: queue_name, config: @config)
+         end
+
+         WorkProxy.new(workers, @config)
       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
+         def initialize(queue, identifier:)
+            @queue      = queue
             @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)
+            task = @queue.fetch_task(@identifier)
 
-            new_data = {
-                  attempts:      0,
-                  last_error:    nil,
-                  last_error_at: nil
-            }
+            raise ArgumentError, 'you must provide at least :run_at or :expire_at' if run_at.nil? && expire_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
+            task.reschedule(expire_at: expire_at) if expire_at
+            task.reschedule(run_at: run_at) if run_at
 
-            @config.loader.update(task[:id], new_data)
+            new_data = task.to_h
+            new_data.delete(:queue)
+            new_data.delete(:data)
+            @queue.update(new_data.delete(:id), new_data)
          end
 
          alias at to
+      end
+
+      # Serial work style
+      #
+      # @see WorkProxy
+      module SerialWorking
+         # Work off the given number of tasks for each queue and return
+         # @param steps [integer] The number of tasks to complete.
+         def serially(steps: 1)
+            steps.times do
+               workers.each(&:work_one)
+            end
+         end
+      end
+
+      # Threaded work style
+      #
+      # @see WorkProxy
+      module ThreadedWorking
+         PROG_NAME = 'Procrastinator'
+
+         # Work off jobs per queue, each in its own thread.
+         #
+         # @param timeout Maximum number of seconds to run for. If nil, will run indefinitely.
+         def threaded(timeout: nil)
+            open_log
+            shutdown_on_interrupt
+
+            begin
+               @threads = spawn_threads
+
+               @logger.info "Procrastinator running. Process ID: #{ Process.pid }"
+               @threads.each do |thread|
+                  thread.join(timeout)
+               end
+            rescue StandardError => e
+               thread_crash(e)
+            ensure
+               @logger&.info 'Halting worker threads...'
+               shutdown!
+               @logger&.info 'Threads halted.'
+            end
+         end
 
          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?
+         def spawn_threads
+            @logger.info "Starting workers for queues: #{ @workers.collect(&:name).join(', ') }"
+
+            @workers.collect do |worker|
+               @logger.debug "Spawning thread: #{ worker.name }"
+               Thread.new(worker) do |w|
+                  Thread.current.abort_on_exception = true
+                  Thread.current.thread_variable_set(:name, w.name)
+
+                  begin
+                     worker.work!
+                  ensure
+                     worker.halt
+                  end
+               end
+            end
+         end
+
+         def thread_crash(error)
+            crashed_threads = (@threads || []).select { |t| t.status.nil? }.collect do |thread|
+               "Crashed thread: #{ thread.thread_variable_get(:name) }"
+            end
+
+            @logger.fatal <<~MSG
+               Crash detected in queue worker thread.
+                  #{ crashed_threads.join("\n") }
+                  #{ error.message }
+                  #{ error.backtrace.join("\n\t") }"
+            MSG
          end
 
-         def validate_run_at(run_at, saved_expire_at, expire_at)
-            return unless run_at
+         def shutdown_on_interrupt
+            Signal.trap('INT') do
+               warn "\n" # just to separate the shutdown log item
+               shutdown!
+            end
+         end
+
+         def shutdown!
+            (@threads || []).select(&:alive?).each(&:kill)
+         end
+
+         def open_log(quiet: false)
+            return if @logger
 
-            after_new_expire = expire_at && run_at.to_i > expire_at.to_i
+            log_devs = []
 
-            raise "given run_at (#{ run_at }) is later than given expire_at (#{ expire_at })" if after_new_expire
+            log_devs << StringIO.new if quiet && !@config.log_level
+            log_devs << $stderr unless quiet
+            log_devs << log_path.open('a') if @config.log_level
 
-            after_old_expire = saved_expire_at && run_at.to_i > saved_expire_at
+            multi      = MultiIO.new(*log_devs)
+            multi.sync = true
 
-            raise "given run_at (#{ run_at }) is later than saved expire_at (#{ saved_expire_at })" if after_old_expire
+            @logger = Logger.new(multi,
+                                 progname:  PROG_NAME.downcase,
+                                 level:     @config.log_level || Logger::INFO,
+                                 formatter: Config::DEFAULT_LOG_FORMATTER)
          end
 
-         def fetch_task(identifier)
-            tasks = @config.loader.read(identifier)
+         def log_path
+            path = @config.log_dir / "#{ PROG_NAME.downcase }.log"
+            path.dirname.mkpath
+            # FileUtils.touch(log_path)
+            path
+         end
 
-            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
+         # IO Multiplexer that forwards calls to a list of IO streams.
+         class MultiIO
+            def initialize(*stream)
+               @streams = stream
+            end
+
+            (IO.methods << :path << :sync=).uniq.each do |method_name|
+               define_method(method_name) do |*args|
+                  able_streams(method_name).collect do |stream|
+                     stream.send(method_name, *args)
+                  end.last # forces consistent return result type for callers (but may lose some info)
+               end
+            end
 
-            tasks.first
+            private
+
+            def able_streams(method_name)
+               @streams.select { |stream| stream.respond_to?(method_name) }
+            end
          end
       end
 
-      private
+      # Daemonized work style
+      #
+      # @see WorkProxy
+      module DaemonWorking
+         PID_EXT         = '.pid'
+         DEFAULT_PID_DIR = Pathname.new('/var/run/').freeze
+
+         # 15 chars is linux limit
+         MAX_PROC_LEN = 15
+
+         # Consumes the current process and turns it into a background daemon and proceed as #threaded.
+         # Additional logging is recorded in the directory specified by the Procrastinator.setup configuration.
+         #
+         # If pid_path ends with extension '.pid', the basename will be requested as process title (depending on OS
+         # support). An extensionless path is assumed to be a directory and a default filename (and proctitle) is used.
+         #
+         # @param pid_path [Pathname, File, String, nil] Path to where the process ID file is to be kept.
+         def daemonized!(pid_path = nil)
+            spawn_daemon(pid_path)
+
+            threaded
+         end
 
-      # 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
+         # Normalizes the given pid path, including conversion to absolute path and defaults.
+         #
+         # @param pid_path [Pathname, File, String, nil] path to normalize
+         def self.normalize_pid(pid_path)
+            normalized = Pathname.new(pid_path || DEFAULT_PID_DIR)
+            normalized /= "#{ PROG_NAME.downcase }#{ PID_EXT }" unless normalized.extname == PID_EXT
 
-      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
+            normalized.expand_path
+         end
 
-         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
+         # Stops the procrastinator process denoted by the provided pid file
+         def self.halt!(pid_path)
+            pid_path = normalize_pid pid_path
 
-      def verify_queue_data!(queue_name, data)
-         queue = @config.queue(name: queue_name)
+            Process.kill('TERM', pid_path.read.to_i)
+         end
+
+         def self.running?(pid_path)
+            pid = normalize_pid(pid_path).read.to_i
+
+            # this raises Errno::ESRCH when no process found, therefore if found we should exit
+            Process.getpgid pid
 
-         unless queue
-            queue_list = @config.queues_string
-            raise ArgumentError, "there is no :#{ queue_name } queue registered. Defined queues are: #{ queue_list }"
+            true
+         rescue Errno::ENOENT, Errno::ESRCH
+            false
          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."
+         private
+
+         def spawn_daemon(pid_path)
+            pid_path = DaemonWorking.normalize_pid pid_path
+
+            open_log quiet: true
+            @logger.info "Starting #{ PROG_NAME } daemon..."
+
+            print_debug_context
+
+            # "You, search from the spastic dentistry department down through disembowelment.
+            #  You, cover children's dance recitals through holiday weekend IKEA. Go."
+            Process.daemon
+
+            manage_pid pid_path
+            rename_process pid_path
+         rescue StandardError => e
+            @logger&.fatal ([e.message] + e.backtrace).join("\n")
+            raise e
+         end
+
+         def manage_pid(pid_path)
+            ensure_unique(pid_path)
+
+            @logger.debug "Managing pid at path: #{ pid_path }"
+            pid_path.dirname.mkpath
+            pid_path.write Process.pid.to_s
+
+            at_exit do
+               if pid_path.exist?
+                  @logger.debug "Cleaning up pid file #{ pid_path }"
+                  pid_path.delete
+               end
+               @logger.info "Procrastinator (pid #{ Process.pid }) halted."
             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
+
+         def ensure_unique(pid_path)
+            return unless pid_path.exist?
+
+            @logger.debug "Checking pid file #{ pid_path }"
+
+            if DaemonWorking.running? pid_path
+               hint = 'Either terminate that process or remove the pid file (if coincidental).'
+               msg  = "Another process (pid #{ pid_path.read }) already exists for #{ pid_path }. #{ hint }"
+               @logger.fatal msg
+               raise ProcessExistsError, msg
+            else
+               @logger.warn "Replacing old pid file of defunct process (pid #{ pid_path.read }) at #{ pid_path }."
+            end
+         end
+
+         def print_debug_context
+            @logger.debug "Ruby Path: #{ ENV.fetch 'RUBY_ROOT' }"
+            @logger.debug "Bundler Path: #{ ENV.fetch 'BUNDLE_BIN_PATH' }"
+            # LOGNAME is the posix standard and is set by cron, so probably reliable.
+            @logger.debug "Runtime User: #{ ENV.fetch('LOGNAME') || ENV.fetch('USERNAME') }"
+         end
+
+         def rename_process(pid_path)
+            name = pid_path.basename(PID_EXT).to_s
+
+            if name.size > MAX_PROC_LEN
+               @logger.warn "Process name is longer than max length (#{ MAX_PROC_LEN }). Trimming to fit."
+               name = name[0, MAX_PROC_LEN]
+            end
+
+            if system('pidof', name, out: File::NULL)
+               @logger.warn "Another process is already named '#{ name }'. Consider the 'name:' keyword to distinguish."
+            end
+
+            @logger.debug "Renaming process to: #{ name }"
+            Process.setproctitle name
+         end
+
+         include ThreadedWorking
       end
+
+      # DSL grammar object to enable chaining #work with the three work modes.
+      #
+      # @see Scheduler#work
+      class WorkProxy
+         include SerialWorking
+         include ThreadedWorking
+         include DaemonWorking
+
+         attr_reader :workers
+
+         def initialize(workers, config)
+            @workers = workers
+            @config  = config
+         end
+      end
+   end
+
+   class ProcessExistsError < RuntimeError
    end
 end

data/lib/procrastinator/task.rb

@@ -1,46 +1,64 @@
 # frozen_string_literal: true
 
+require 'forwardable'
+require 'time'
+
 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.
+   # Wraps a task handler and task metadata
    #
    # @author Robin Miller
-   module Task
-      KNOWN_ATTRIBUTES = [:logger, :context, :data, :scheduler].freeze
+   class Task
+      extend Forwardable
 
-      def self.included(base)
-         base.extend(TaskClassMethods)
-      end
+      def_delegators :@metadata,
+                     :id, :run_at, :initial_run_at, :expire_at,
+                     :attempts, :last_fail_at, :last_error,
+                     :data, :to_h, :serialized_data,
+                     :queue, :reschedule
 
-      def respond_to_missing?(name, include_private)
-         super
+      def initialize(metadata, handler)
+         @metadata = metadata
+         @handler  = handler
       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."
+      def run
+         raise ExpiredError, "task is over its expiry time of #{ @metadata.expire_at.iso8601 }" if @metadata.expired?
+
+         @metadata.add_attempt
+         result = Timeout.timeout(queue.timeout) do
+            @handler.run
          end
+         @metadata.clear_fails
 
-         super
+         try_hook(:success, result)
       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(', ')
+      alias call run
 
-            fields.each do |field|
-               err = "Unknown Procrastinator::Task attribute :#{ field }. " \
-                     "Importable attributes are: #{ attr_list }"
-               raise ArgumentError, err unless KNOWN_ATTRIBUTES.include?(field)
-            end
+      # Records a failure in metadata and attempts to run the handler's #fail hook if present.
+      #
+      # @param error [StandardError] - the error that caused the failure
+      def fail(error)
+         hook = @metadata.failure(error)
 
-            attr_accessor(*fields)
-         end
+         try_hook(hook, error)
+         hook
+      end
+
+      def try_hook(method, *params)
+         @handler.send(method, *params) if @handler.respond_to? method
+      rescue StandardError => e
+         warn "#{ method.to_s.capitalize } hook error: #{ e.message }"
+      end
+
+      def to_s
+         "#{ @metadata.queue.name }##{ id } [#{ serialized_data }]"
+      end
+
+      class ExpiredError < RuntimeError
+      end
+
+      class AttemptsExhaustedError < RuntimeError
       end
    end
 end