exekutor 0.1.0

data/lib/exekutor/hook.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Exekutor
+  # Defines hooks for Exekutor.
+  #
+  # @example Define and register hooks
+  #    class ExekutorHooks
+  #      include Exekutor::Hook
+  #      around_job_execution :instrument
+  #      after_job_failure {|_job, error| report_error error }
+  #      after_fatal_error :report_error
+  #
+  #      def instrument(job)
+  #        ErrorMonitoring.monitor_transaction { yield }
+  #      end
+  #
+  #      def report_error(error)
+  #        ErrorMonitoring.report error
+  #      end
+  #    end
+  #
+  #    Exekutor.hooks.register ExekutorHooks
+  module Hook
+    extend ActiveSupport::Concern
+
+    CALLBACK_NAMES = %i[
+      before_enqueue around_enqueue after_enqueue before_job_execution around_job_execution after_job_execution
+      on_job_failure on_fatal_error before_startup after_startup before_shutdown after_shutdown
+    ].freeze
+    private_constant "CALLBACK_NAMES"
+
+    included do
+      class_attribute :__callbacks, default: Hash.new { |h, k| h[k] = [] }
+
+      private_class_method :add_callback!
+    end
+
+    # Gets the registered callbacks
+    # @return [Hash<Symbol,Array<Proc>>] the callbacks
+    def callbacks
+      instance = self
+      __callbacks.transform_values do |callbacks|
+        callbacks.map do |method, callback|
+          if method
+            method(method)
+          elsif callback.arity.zero?
+            -> { instance.instance_exec(&callback) }
+          else
+            ->(*args) { instance.instance_exec(*args, &callback) }
+          end
+        end
+      end
+    end
+
+    class_methods do
+
+      # @!method before_enqueue
+      #   Registers a callback to be called before a job is enqueued.
+      #   @param methods [Symbol] the method(s) to call
+      #   @yield the block to call
+      #   @yieldparam job [ActiveJob::Base] the job to enqueue
+      #   @return [void]
+
+      # @!method after_enqueue
+      #   Registers a callback to be called after a job is enqueued.
+      #   @param methods [Symbol] the method(s) to call
+      #   @yield the block to call
+      #   @yieldparam job [ActiveJob::Base] the enqueued job
+      #   @return [void]
+
+      # @!method around_enqueue
+      #   Registers a callback to be called when a job is enqueued. You must call +yield+ from the callback.
+      #   @param methods [Symbol] the method(s) to call
+      #   @yield the block to call
+      #   @yieldparam job [ActiveJob::Base] the job to enqueue
+      #   @return [void]
+
+      # @!method before_job_execution
+      #   Registers a callback to be called before a job is executed.
+      #   @param methods [Symbol] the method(s) to call
+      #   @yield the block to call
+      #   @yieldparam job [Hash] the job to execute
+      #   @return [void]
+
+      # @!method after_job_execution
+      #   Registers a callback to be called after a job is executed.
+      #   @param methods [Symbol] the method(s) to call
+      #   @yield the block to call
+      #   @yieldparam job [Hash] the executed job
+      #   @return [void]
+
+      # @!method around_job_execution
+      #   Registers a callback to be called when a job is executed. You must call +yield+ from the callback.
+      #   @param methods [Symbol] the method(s) to call
+      #   @yield the block to call
+      #   @yieldparam job [Hash] the job to execute
+      #   @return [void]
+
+      # @!method on_job_failure
+      #   Registers a callback to be called when a job raises an error.
+      #   @param methods [Symbol] the method(s) to call
+      #   @yield the block to call
+      #   @yieldparam job [Hash] the job that was executed
+      #   @yieldparam error [StandardError] the error that was raised
+      #   @return [void]
+
+      # @!method on_fatal_error
+      #   Registers a callback to be called when an error is raised from a worker outside a job.
+      #   @param methods [Symbol] the method(s) to call
+      #   @yield the block to call
+      #   @yieldparam error [StandardError] the error that was raised
+      #   @return [void]
+
+      # @!method before_startup
+      #   Registers a callback to be called before a worker is starting up.
+      #   @param methods [Symbol] the method(s) to call
+      #   @yield the block to call
+      #   @yieldparam worker [Worker] the worker
+      #   @return [void]
+
+      # @!method after_startup
+      #   Registers a callback to be called after a worker has started up.
+      #   @param methods [Symbol] the method(s) to call
+      #   @yield the block to call
+      #   @yieldparam worker [Worker] the worker
+      #   @return [void]
+
+      # @!method before_shutdown
+      #   Registers a callback to be called before a worker is shutting down.
+      #   @param methods [Symbol] the method(s) to call
+      #   @yield the block to call
+      #   @yieldparam worker [Worker] the worker
+      #   @return [void]
+
+      # @!method after_shutdown
+      #   Registers a callback to be called after a worker has shutdown.
+      #   @param methods [Symbol] the method(s) to call
+      #   @yield the block to call
+      #   @yieldparam worker [Worker] the worker
+      #   @return [void]
+
+      CALLBACK_NAMES.each do |name|
+        module_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def #{name}(*methods, &callback)
+            add_callback! :#{name}, methods, callback
+          end
+        RUBY
+      end
+
+      # Adds a callback.
+      # @param type [Symbol] the callback to register
+      # @param methods [Symbol] the method(s) to call
+      # @yield the block to call
+      def add_callback(type, *methods, &callback)
+        unless CALLBACK_NAMES.include? type
+          raise Error, "Invalid callback type: #{type} (Expected one of: #{CALLBACK_NAMES.map(&:inspect).join(", ")}"
+        end
+
+        add_callback! type, methods, callback
+        true
+      end
+
+      def add_callback!(type, methods, callback)
+        raise Error, "No method or callback block supplied" if methods.blank? && callback.nil?
+        raise Error, "Either a method or a callback block must be supplied" if methods.present? && callback.present?
+
+        methods&.each { |method| __callbacks[type] << [method, nil] }
+        __callbacks[type] << [nil, callback] if callback.present?
+      end
+    end
+  end
+end

data/lib/exekutor/info/worker.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "../internal/base_record"
+
+module Exekutor
+  # Module for the Worker active record class
+  module Info
+    # Active record class for a worker instance
+    class Worker < Internal::BaseRecord
+      self.implicit_order_column = :started_at
+      enum status: { initializing: "i", running: "r", shutting_down: "s", crashed: "c" }
+
+      # Registers a heartbeat for this worker, if necessary
+      def heartbeat!
+        now = Time.now.change(sec: 0)
+        touch :last_heartbeat_at, time: now if self.last_heartbeat_at.nil? || now >= self.last_heartbeat_at + 1.minute
+      end
+    end
+  end
+end

data/lib/exekutor/internal/base_record.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+module Exekutor
+  # @private
+  module Internal
+    # The base class for Exekutor active record classes
+    class BaseRecord < Exekutor.config.base_record_class
+      self.abstract_class = true
+      self.table_name_prefix = "exekutor_"
+    end
+  end
+end

data/lib/exekutor/internal/callbacks.rb

@@ -0,0 +1,138 @@
+module Exekutor
+  module Internal
+    # Mixin to define callbacks on a class
+    #
+    # @example Define and call callbacks
+    #    class MyClass
+    #      include Exekutor::Internal::Callbacks
+    #
+    #      define_callbacks :on_event, :before_another_event, :after_another_event
+    #
+    #      def emit_event
+    #        run_callbacks :on, :event, "Callback arg"
+    #      end
+    #
+    #      def emit_another_event
+    #        with_callbacks :another_event, self do |self_arg|
+    #          puts "another event"
+    #        end
+    #      end
+    #    end
+    #    MyClass.new.on_event(12) {|str, int| puts "event happened: #{str}, #{int}" }
+    module Callbacks
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :__callback_names, instance_writer: false, default: []
+        attr_reader :__callbacks
+        protected :__callbacks
+      end
+
+      # Adds a callback.
+      # @param type [Symbol] the type of callback to add
+      # @param args [Any] the args to forward to the callback
+      # @yield the block to call
+      # @yieldparam *args [Any] the callback args, appended by the specified args
+      def add_callback(type, *args, &callback)
+        unless __callback_names.include? type
+          raise Error, "Invalid callback type: #{type} (Expected one of: #{__callback_names.map(&:inspect).join(", ")}"
+        end
+        raise Error, "No callback block supplied" if callback.nil?
+
+        add_callback! type, args, callback
+        true
+      end
+
+      protected
+
+      # Runs all callbacks for the specified type and action.
+      # @param type [:on, :before, :around, :after] the type of the callback
+      # @param action [Symbol] the name of the callback
+      # @param args [Any] the callback args
+      def run_callbacks(type, action, *args)
+        callbacks = __callbacks && __callbacks[:"#{type}_#{action}"]
+        unless callbacks
+          yield(*args) if block_given?
+          return
+        end
+        if type == :around
+          # Chain all callbacks together, ending with the original given block
+          callbacks.inject(-> { yield(*args) }) do |next_callback, (callback, extra_args)|
+            callback_args = if callback.arity.zero?
+                              []
+                            else
+                              args + extra_args
+                            end
+            lambda do
+              has_yielded = false
+              callback.call(*callback_args) { has_yielded = true; next_callback.call }
+              raise MissingYield, "Callback did not yield!" unless has_yielded
+            rescue StandardError => err
+              raise if err.is_a? MissingYield
+              Exekutor.on_fatal_error err, "[Executor] Callback error!"
+              next_callback.call
+            end
+          end.call
+          return
+        end
+        iterator = type == :after ? :each : :reverse_each
+        callbacks.send(iterator) do |(callback, extra_args)|
+          if callback.arity.zero?
+            callback.call
+          else
+            callback.call(*(args + extra_args))
+          end
+        rescue StandardError => err
+          Exekutor.on_fatal_error err, "[Executor] Callback error!"
+        end
+        nil
+      end
+
+      # Runs :before, :around, and :after callbacks for the specified action.
+      def with_callbacks(action, *args)
+        run_callbacks :before, action, *args
+        run_callbacks(:around, action, *args) { |*fargs| yield(*fargs) }
+        run_callbacks :after, action, *args
+        nil
+      end
+
+      private
+
+      def add_callback!(type, args, callback)
+        @__callbacks ||= Concurrent::Hash.new
+        __callbacks[type] ||= Concurrent::Array.new
+        __callbacks[type] << [callback, args]
+      end
+
+      class_methods do
+        # Defines the specified callbacks on this class. Also defines a method with the given name to register the callback.
+        # @param callbacks [Symbol] the callback names to define. Must start with +on_+, +before_+, +after_+, or +around_+.
+        # @param freeze [Boolean] if true, freezes the callbacks so that no other callbacks can be defined
+        # @raise [Error] if a callback name is invalid or if the callbacks are frozen
+        def define_callbacks(*callbacks, freeze: true)
+          raise Error, "Callbacks are frozen, no other callbacks may be defined" if __callback_names.frozen?
+          callbacks.each do |name|
+            unless /^(on_)|(before_)|(after_)|(around_)[a-z]+/.match? name.to_s
+              raise Error, "Callback name must start with `on_`, `before_`, `after_`, or `around_`"
+            end
+
+            __callback_names << name
+            module_eval <<-RUBY, __FILE__, __LINE__ + 1
+              def #{name}(*args, &callback)
+                add_callback! :#{name}, args, callback
+              end
+            RUBY
+          end
+
+          __callback_names.freeze if freeze
+        end
+      end
+
+      # Raised when registering a callback fails
+      class Error < Exekutor::Error; end
+
+      # Raised when an around callback does not yield
+      class MissingYield < Exekutor::Error; end
+    end
+  end
+end

data/lib/exekutor/internal/cli/app.rb

@@ -0,0 +1,173 @@
+require "gli"
+require "rainbow"
+require_relative "cleanup"
+require_relative "info"
+require_relative "manager"
+
+module Exekutor
+  # @private
+  module Internal
+    # The internal command line interface for Exekutor
+    # @private
+    module CLI
+      # Converts the command line arguments to Manager calls
+      # @private
+      class App
+        extend GLI::App
+
+        program_desc "Exekutor CLI"
+        version Exekutor::VERSION
+
+        default_command :start
+
+        flag %i[id identifier], default_value: nil,
+             desc: "Descriptor of the worker instance, is used in the pid file and shown in the worker info"
+        flag %i[pid pidfile], default_value: Manager::DEFAULT_PIDFILE,
+             desc: "Path to write daemonized Process ID"
+
+        switch %i[v verbose], negatable: false, desc: "Enable more output"
+        switch %i[quiet], negatable: false, desc: "Enable less output"
+
+        # Defines start command flags
+        def self.define_start_options(c)
+          c.flag %i[env environment], desc: "The Rails environment"
+          c.flag %i[q queue], default_value: Manager::DEFAULT_QUEUE, multiple: true,
+                 desc: "Queue to work from"
+          c.flag %i[t threads], type: String, default_value: Manager::DEFAULT_THREADS,
+                 desc: "The number of threads for executing jobs, specified as `min:max`"
+          c.flag %i[p poll_interval], type: Integer, default_value: DefaultOptionValue.new( value: 60),
+                 desc: "Interval between polls for available jobs (in seconds)"
+          c.flag %i[cfg configfile], type: String, default_value: Manager::DEFAULT_CONFIG_FILES, multiple: true,
+                 desc: "The YAML configuration file to load. If specifying multiple files, the last file takes precedence"
+        end
+        private_class_method :define_start_options
+
+        # Defines stop command flags
+        def self.define_stop_options(c)
+          c.flag %i[timeout shutdown_timeout], default_value: Manager::DEFAULT_FOREVER,
+                 desc: "Number of seconds to wait for jobs to finish when shutting down before killing the worker. (in seconds)"
+        end
+        private_class_method :define_stop_options
+
+        desc "Starts a worker"
+        long_desc <<~TEXT
+          Starts a new worker to execute jobs from your ActiveJob queue. If the worker is daemonized this command will
+          return immediately.
+        TEXT
+        command :start do |c|
+          c.switch %i[d daemon daemonize], negatable: false,
+                   desc: "Run as a background daemon (default: false)"
+
+          define_start_options(c)
+
+          c.action do |global_options, options|
+            Manager.new(global_options).start(options)
+          end
+        end
+
+        desc "Stops a daemonized worker"
+        long_desc <<~TEXT
+          Stops a daemonized worker. This uses the PID file to send a shutdown command to a running worker. If the worker 
+          does not exit within the shutdown timeout it will kill the process.
+        TEXT
+        command :stop do |c|
+          c.switch :all, negatable: false, desc: "Stops all workers with default pid files."
+          define_stop_options c
+
+          c.action do |global_options, options|
+            if options[:all]
+              puts "The identifier option is ignored for --all" unless global_options[:identifier].nil? || global_options[:quiet]
+              pidfile_pattern = if options[:pidfile].nil? || options[:pidfile] == Manager::DEFAULT_PIDFILE
+                                  "tmp/pids/exekutor*.pid"
+                                else
+                                  options[:pidfile]
+                                end
+              pidfiles = Dir[pidfile_pattern]
+              if pidfiles.any?
+                pidfiles.each do |pidfile|
+                  Manager.new(global_options.merge(pidfile: pidfile)).stop(options)
+                end
+              else
+                puts "There are no running workers (No pidfiles found for `#{pidfile_pattern}`)"
+              end
+            else
+              Manager.new(global_options).stop(options)
+            end
+          end
+        end
+
+        desc "Restarts a daemonized worker"
+        long_desc <<~TEXT
+          Restarts a daemonized worker. Will issue the stop command if a worker is running and wait for the active worker
+          to exit before starting a new worker. If no worker is currently running, a new worker will be started.
+        TEXT
+        command :restart do |c|
+          define_stop_options c
+          define_start_options c
+
+          c.action do |global_options, options|
+            Manager.new(global_options).restart(options.slice(:shutdown_timeout),
+                                                options.reject { |k, _| k == :shutdown_timeout })
+          end
+        end
+
+        desc "Prints worker and job info"
+        long_desc <<~TEXT
+          Prints info about workers and pending jobs.
+        TEXT
+        command :info do |c|
+          c.flag %i[env environment], desc: "The Rails environment."
+
+          c.action do |global_options, options|
+            Info.new(global_options).print(options)
+          end
+        end
+
+        desc "Cleans up workers and jobs"
+        long_desc <<~TEXT
+          Cleans up the finished jobs and stale workers
+        TEXT
+        command :cleanup do |c|
+          c.flag %i[env environment], desc: "The Rails environment."
+
+          c.flag %i[t timeout],
+                 desc: "The global timeout in hours. Workers and jobs before the timeout will be purged"
+          c.flag %i[worker_timeout],
+                 default_value: 4,
+                 desc: "The worker timeout in hours. Workers where the last heartbeat is before the timeout will be deleted."
+          c.flag %i[job_timeout],
+                 default_value: 48,
+                 desc: "The job timeout in hours. Jobs where scheduled at is before the timeout will be purged."
+          c.flag %i[s job_status],
+                 default_value: Cleanup::DEFAULT_STATUSES, multiple: true,
+                 desc: "The statuses to purge. Only jobs with this status will be purged."
+
+          c.default_command :all
+
+          c.desc "Cleans up both the workers and the jobs"
+          c.command(:all) do |ac|
+            ac.action do |global_options, options|
+              Cleanup.new(global_options).tap do |cleaner|
+                cleaner.cleanup_workers(options.merge(print_header: true))
+                cleaner.cleanup_jobs(options.merge(print_header: true))
+              end
+            end
+          end
+          c.desc "Cleans up the workers table"
+          c.command(:workers, :w) do |wc|
+            wc.action do |global_options, options|
+              Cleanup.new(global_options).cleanup_workers(options)
+            end
+          end
+          c.desc "Cleans up the jobs table"
+          c.command(:jobs, :j) do |jc|
+            jc.action do |global_options, options|
+              Cleanup.new(global_options).cleanup_jobs(options)
+            end
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/exekutor/internal/cli/application_loader.rb

@@ -0,0 +1,36 @@
+module Exekutor
+  module Internal
+    module CLI
+      # Helper methods to load the Rails application
+      module ApplicationLoader
+        # The message to print when loading the Rails application
+        LOADING_MESSAGE = "Loading Rails environment…"
+
+        # Loads the Rails application
+        # @param environment [String] the environment to load (eg. development, production)
+        # @param path [String] the path to the environment file
+        # @param print_message [Boolean] whether to print a loading message to STDOUT
+        def load_application(environment, path = "config/environment.rb", print_message: false)
+          return if @application_loaded
+          if print_message
+            printf LOADING_MESSAGE
+            @loading_message_printed = true
+          end
+          ENV["RAILS_ENV"] = environment unless environment.nil?
+          require File.expand_path(path)
+          @application_loaded = true
+        end
+
+        # Clears the loading message if it was printed
+        def clear_application_loading_message
+          if @loading_message_printed
+            printf "\r#{" " * LOADING_MESSAGE.length}\r"
+            @loading_message_printed = false
+          end
+        end
+
+      end
+    end
+  end
+
+end

data/lib/exekutor/internal/cli/cleanup.rb

@@ -0,0 +1,96 @@
+require_relative "application_loader"
+require_relative "default_option_value"
+require "terminal-table"
+
+module Exekutor
+  # @private
+  module Internal
+    module CLI
+      # Cleanup for the CLI
+      # @private
+      class Cleanup
+        include ApplicationLoader
+
+        def initialize(options)
+          @global_options = options
+        end
+
+        # Cleans up the workers table
+        # @see Exekutor::Cleanup
+        def cleanup_workers(options)
+          load_application options[:environment], print_message: !quiet?
+
+          ActiveSupport.on_load(:active_record, yield: true) do
+            # Use system time zone
+            Time.zone = Time.new.zone
+
+            clear_application_loading_message unless quiet?
+            timeout = options[:timeout] || options[:worker_timeout] || 4
+            workers = cleaner.cleanup_workers timeout: timeout.hours
+            return if quiet?
+
+            puts Rainbow("Workers").bright.blue if options[:print_header]
+            if workers.present?
+              puts "Purged #{workers.size} worker#{"s" if workers.many?}"
+              if verbose?
+                table = Terminal::Table.new
+                table.headings = ["id", "Last heartbeat"]
+                workers.each { |w| table << [w.id.split("-").first << "…", w.last_heartbeat_at] }
+                puts table
+              end
+            else
+              puts "Nothing purged"
+            end
+          end
+        end
+
+        # Cleans up the jobs table
+        # @see Exekutor::Cleanup
+        def cleanup_jobs(options)
+          load_application options[:environment], print_message: !quiet?
+
+          ActiveSupport.on_load(:active_record, yield: true) do
+            # Use system time zone
+            Time.zone = Time.new.zone
+
+            clear_application_loading_message unless quiet?
+            timeout = options[:timeout] || options[:job_timeout] || 48
+            status = if options[:job_status].is_a? Array
+                       options[:job_status]
+                     elsif options[:job_status] && options[:job_status] != DEFAULT_STATUSES
+                       options[:job_status]
+                     end
+            purged_count = cleaner.cleanup_jobs before: timeout.hours.ago, status: status
+            return if quiet?
+
+            puts Rainbow("Jobs").bright.blue if options[:print_header]
+            if purged_count.zero?
+              puts "Nothing purged"
+            else
+              puts "Purged #{purged_count} job#{"s" if purged_count > 1}"
+            end
+          end
+        end
+
+        private
+
+        # @return [Boolean] Whether quiet mode is enabled. Overrides verbose mode.
+        def quiet?
+          !!@global_options[:quiet]
+        end
+
+        # @return [Boolean] Whether verbose mode is enabled. Always returns false if quiet mode is enabled.
+        def verbose?
+          !quiet? && !!@global_options[:verbose]
+        end
+
+        def cleaner
+          @delegate ||= ::Exekutor::Cleanup.new
+        end
+
+        DEFAULT_STATUSES = DefaultOptionValue.new("All except :pending").freeze
+      end
+    end
+
+  end
+end