exekutor 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94b3158b3e0df0ca892836df74beb23ccfd8bddf5a1377a46b5ebd881cb5bee8
-  data.tar.gz: a24e415df40ba9bf69d6972da2fb6461f60c655976d81f87ff36f2e365da42a6
+  metadata.gz: d5b178052eb277168916a76f663ba53882204481f740a7c30bc309d243de79cf
+  data.tar.gz: bfb648002d86bf278b41b5f7ca6fde0f1d3cb39954c445eec0e268bf72120efe
 SHA512:
-  metadata.gz: 8de1e356a03b80f1e7dd82802956902531f76111cbea7210ee61eeeb34dbccc22120e5127f24ec9112328bfcb0f175f593f7ab4a9e6f347165b168503c4dbf49
-  data.tar.gz: 33c945b0e29d611d2e25d98985e75df68494bb3463d014efda5a60c7402acb711541a465b6e4db10afcbb8f2db4b86d9d2c2fd3d6b23a140bf324eefbeb8cf51
+  metadata.gz: e2d7a7787f83dc362aeca814d511d0584e5e3e2af24209f1bfc00bd1efbae47d9226bc91e5615a0c7b38b5a515ad64146ec43d74e6cb3b757f3144fcc100d05e
+  data.tar.gz: 651ee14b261990adfe498e017afd6ea0e3e382e12f7bf4a352d01dd4d203938f62f2223159e7930bd517ee5fd68f191b2d0ad9189c13670158064e8381278b5b

data/lib/exekutor/configuration.rb

@@ -180,18 +180,19 @@ module Exekutor
 
     # @!macro
     #   @!method $1
-    #     The polling interval in seconds. When set, the worker will poll the database with this interval to check for
+    #     The polling interval. When set, the worker will poll the database with this interval to check for
     #     any pending jobs that a listener might have missed (if enabled).
     #     === Default value:
-    #     60
-    #     @return [Integer]
+    #     60 seconds
+    #     @return [ActiveSupport::Duration]
     #   @!method $1=(value)
-    #     Sets the polling interval in seconds. Set to +nil+ to disable polling. If the listener is disabled, this value
-    #     should be reasonably low so jobs don't have to wait in the queue too long; if it is enabled, this value can
-    #     be reasonably high.
-    #     @param value [Integer] the interval
+    #     Sets the polling interval. Set to +nil+ to disable polling. If the listener is disabled, this value
+    #     should be reasonably low so jobs don't have to wait in the queue too long; if the listener is enabled, this
+    #     value can be reasonably high.
+    #     @param value [ActiveSupport::Duration] the interval
     #     @return [self]
-    define_option :polling_interval, default: 60, type: [Integer, nil], range: 1...(1.day.to_i)
+    define_option :polling_interval, default: 1.minute, type: [ActiveSupport::Duration, nil],
+                  range: (1.second)...(1.day)
 
     # @!macro
     #   @!method $1
@@ -239,21 +240,22 @@ module Exekutor
 
     # @!macro
     #   @!method $1
-    #     The maximum number of seconds a thread may be idle before being stopped.
+    #     The maximum duration a thread may be idle before being stopped.
     #     === Default value:
-    #     60
-    #     @return [Integer]
+    #     60 seconds
+    #     @return [ActiveSupport::Duration]
     #   @!method $1=(value)
-    #     Sets the maximum number of seconds a thread may be idle before being stopped
-    #     @param value [Integer] the number of threads
+    #     Sets the maximum duration a thread may be idle before being stopped
+    #     @param value [ActiveSupport::Duration] the number of threads
     #     @return [self]
-    define_option :max_execution_thread_idletime, default: 60, type: Integer, range: 1..(1.day.to_i)
+    define_option :max_execution_thread_idletime, default: 1.minute, type: ActiveSupport::Duration,
+                  range: (1.second)..(1.day)
 
     # @!macro
     #   @!method $1?
     #     The rack handler for the status server
     #     === Default value:
-    #     webrick
+    #     +"webrick"+
     #     @return [String]
     #   @!method $1=(value)
     #     Sets the rack handler for the status server. The handler should respond to +#shutdown+ or +#stop+.
@@ -263,18 +265,46 @@ module Exekutor
 
     # @!macro
     #   @!method $1?
-    #     The heartbeat timeout for the `/live` endpoint of the status server, in minutes. If the heartbeat of a worker
+    #     The port number for the status server
+    #     === Default value:
+    #     +nil+ (ie. the status server is disabled)
+    #     @return [Integer]
+    #   @!method $1=(value)
+    #     Sets the port number for the status server.
+    #     @param value [Integer] the port number
+    #     @return [self]
+    define_option :status_server_port, default: nil, type: Integer
+
+    # @!macro
+    #   @!method $1?
+    #     The heartbeat timeout for the `/live` endpoint of the status server. If the heartbeat of a worker
     #     is older than this timeout, the status server will respond with a 503 status indicating the service is
     #     down.
     #     === Default value:
-    #     30
-    #     @return [Integer]
+    #     30 minutes
+    #     @return [ActiveSupport::Duration]
+    #   @!method $1=(value)
+    #     Sets the heartbeat timeout for the `/live` endpoint of the status server. Must be between 1 minute
+    #     and 24 hours.
+    #     @param value [ActiveSupport::Duration] The timeout in minutes
+    #     @return [self]
+    define_option :healthcheck_timeout, default: 30.minutes, type: ActiveSupport::Duration,
+                  range: (1.minute)..(1.day)
+
+    # @!macro
+    #   @!method $1?
+    #     Whether the priority should be inverted. If true, the job with the highest value as the priority is the most
+    #     important. If false, the job with the lowest value as the priority is the most important.
+    #     === Default value:
+    #     false
+    #     @return [Boolean]
     #   @!method $1=(value)
-    #     Sets the heartbeat timeout for the `/live` endpoint of the status server, in minutes. Must be between 2
-    #     and 1440 (24 hours).
-    #     @param value [Integer] The timeout in minutes
+    #     Sets whether the the priority should be inverted. When true, the job with the highest value as the priority is
+    #     the most important; when false, the job with the lowest value as the priority is the most important.
+    #     @param value [Boolean] whether the job with the highest priority value is the most important.
     #     @return [self]
-    define_option :healthcheck_timeout, default: 30, type: Integer, range: 2..1440
+    define_option :inverse_priority, reader: :inverse_priority?, type: [TrueClass, FalseClass], required: true,
+                  default: false
 
     # @!macro
     #   @!method $1?
@@ -294,13 +324,14 @@ module Exekutor
       {
         min_threads: min_execution_threads,
         max_threads: max_execution_threads,
-        max_thread_idletime: max_execution_thread_idletime
+        max_thread_idletime: max_execution_thread_idletime.to_f
       }.tap do |opts|
         opts[:set_db_connection_name] = set_db_connection_name? unless set_db_connection_name.nil?
         %i[enable_listener delete_completed_jobs delete_discarded_jobs delete_failed_jobs].each do |option|
           opts[option] = send(:"#{option}?") ? true : false
         end
-        %i[polling_interval polling_jitter status_server_handler healthcheck_timeout].each do |option|
+        %i[polling_interval polling_jitter status_server_handler status_server_port healthcheck_timeout]
+          .each do |option|
           opts[option] = send(option)
         end
       end

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

@@ -35,9 +35,11 @@ module Exekutor
           cmd.flag %i[env environment], desc: "The Rails environment"
           cmd.flag %i[q queue], default_value: Manager::DEFAULT_QUEUE, multiple: true,
                    desc: "Queue to work from"
+          cmd.flag %i[p priority], type: String, default_value: Manager::DEFAULT_PRIORITIES,
+                   desc: "The job priorities to execute, specified as `min` or `min:max`"
           cmd.flag %i[t threads], type: String, default_value: Manager::DEFAULT_THREADS,
                    desc: "The number of threads for executing jobs, specified as `min:max`"
-          cmd.flag %i[p poll_interval], type: Integer, default_value: DefaultOptionValue.new(value: 60),
+          cmd.flag %i[i poll_interval], type: Integer, default_value: DefaultOptionValue.new(value: 60),
                    desc: "Interval between polls for available jobs (in seconds)"
           cmd.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 " \

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

@@ -101,7 +101,7 @@ module Exekutor
           table = Terminal::Table.new headings: ["id", "Status", "Last heartbeat"]
           table.title = host if many_hosts
           worker_count = 0
-          Exekutor::Info::Worker.where(hostname: host).each do |worker|
+          Exekutor::Info::Worker.where(hostname: host).find_each do |worker|
             worker_count += 1
             table << worker_info_row(worker)
           end

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

@@ -23,6 +23,7 @@ module Exekutor
         # @option options [String] :environment The Rails environment to load
         # @option options [String] :queue The queue(s) to watch
         # @option options [String] :threads The number of threads to use for job execution
+        # @option options [String] :priority The priorities to execute
         # @option options [Integer] :poll_interval The interval in seconds for job polling
         # @return [Void]
         def start(options)
@@ -76,7 +77,7 @@ module Exekutor
         def worker_options(config_file, cli_overrides)
           worker_options = DEFAULT_CONFIGURATION.dup
 
-          load_config_files(config_file, worker_options)
+          ConfigLoader.new(config_file, @global_options).load_config(worker_options)
 
           worker_options.merge! Exekutor.config.worker_options
           worker_options.merge! @global_options.slice(:identifier)
@@ -97,16 +98,22 @@ module Exekutor
                                       .reject { |_, value| value.is_a? DefaultOptionValue }
                                       .transform_keys(poll_interval: :polling_interval)
 
-          min_threads, max_threads = parse_thread_limitations(cli_options[:threads])
+          min_threads, max_threads = parse_integer_range(cli_options[:threads])
           if min_threads
             worker_options[:min_threads] = min_threads
             worker_options[:max_threads] = max_threads || min_threads
           end
 
+          min_priority, max_priority = parse_integer_range(cli_options[:priority])
+          if min_threads
+            worker_options[:min_priority] = min_priority
+            worker_options[:max_priority] = max_priority if max_priority
+          end
+
           worker_options
         end
 
-        def parse_thread_limitations(threads)
+        def parse_integer_range(threads)
           return if threads.blank? || threads.is_a?(DefaultOptionValue)
 
           if threads.is_a?(Integer)
@@ -116,37 +123,6 @@ module Exekutor
           end
         end
 
-        def load_config_files(config_files, worker_options)
-          config_files = if config_files.is_a? DefaultConfigFileValue
-                           config_files.to_a(@global_options[:identifier])
-                         else
-                           config_files&.map { |path| File.expand_path(path, Rails.root) }
-                         end
-
-          config_files&.each { |path| load_config_file(path, worker_options) }
-        end
-
-        def load_config_file(path, worker_options)
-          puts "Loading config file: #{path}" if verbose?
-          config = begin
-                     YAML.safe_load(File.read(path), symbolize_names: true)
-                   rescue StandardError => e
-                     raise Error, "Cannot read config file: #{path} (#{e})"
-                   end
-          unless config.keys == [:exekutor]
-            raise Error, "Config should have an `exekutor` root node: #{path} (Found: #{config.keys.join(", ")})"
-          end
-
-          # Remove worker specific options before calling Exekutor.config.set
-          worker_options.merge! config[:exekutor].extract!(:queue, :status_server_port)
-
-          begin
-            Exekutor.config.set(**config[:exekutor])
-          rescue StandardError => e
-            raise Error, "Cannot load config file: #{path} (#{e})"
-          end
-        end
-
         def start_and_join_worker(worker_options, is_daemonized)
           worker = Worker.new(worker_options)
           %w[INT TERM QUIT].each do |signal|
@@ -258,6 +234,73 @@ module Exekutor
           end
         end
 
+        # Takes care of loading YAML configuration
+        class ConfigLoader
+          def initialize(files, options)
+            @config_files = files
+            @options = options
+          end
+
+          def load_config(worker_options)
+            each_file do |path|
+              config = load_config_file(path)
+              convert_duration_options! config
+
+              worker_options.merge! extract_worker_options!(config)
+              apply_config_file(config)
+            end
+            Exekutor.config
+          end
+
+          private
+
+          WORKER_OPTIONS = %i[queues min_priority max_priority min_threads max_threads max_thread_idletime
+                              wait_for_termination].freeze
+
+          def each_file(&block)
+            if @config_files.is_a? DefaultConfigFileValue
+              @config_files.to_a(@options[:identifier]).each(&block)
+            elsif @config_files.is_a? String
+              yield File.expand_path(@config_files, Rails.root)
+            else
+              @config_files.map { |path| File.expand_path(path, Rails.root) }.each(&block)
+            end
+          end
+
+          def extract_worker_options!(config)
+            config.extract!(*WORKER_OPTIONS)
+          end
+
+          def load_config_file(path)
+            puts "Loading config file: #{path}" if @options[:verbose]
+            config = begin
+                       YAML.safe_load(File.read(path), symbolize_names: true)
+                     rescue StandardError => e
+                       raise Error, "Cannot read config file: #{path} (#{e})"
+                     end
+            unless config.keys == [:exekutor]
+              raise Error, "Config should have an `exekutor` root node: #{path} (Found: #{config.keys.join(", ")})"
+            end
+
+            config[:exekutor]
+          end
+
+          def apply_config_file(config)
+            Exekutor.config.set(**config)
+          rescue StandardError => e
+            raise Error, "Cannot load config file (#{e})"
+          end
+
+          def convert_duration_options!(config)
+            { polling_interval: :seconds, max_execution_thread_idletime: :seconds, healthcheck_timeout: :minutes }
+              .each do |duration_option, duration_interval|
+              if config[duration_option].is_a? Numeric
+                config[duration_option] = config[duration_option].send(duration_interval)
+              end
+            end
+          end
+        end
+
         # The default value for the pid file
         class DefaultPidFileValue < DefaultOptionValue
           def initialize
@@ -278,7 +321,7 @@ module Exekutor
         # The default value for the config file
         class DefaultConfigFileValue < DefaultOptionValue
           def initialize
-            super <<~DESC
+            super(<<~DESC)
               "config/exekutor.yml", overridden by "config/exekutor.%{identifier}.yml" if an identifier is specified
             DESC
           end
@@ -316,6 +359,7 @@ module Exekutor
           "Minimum: 1, Maximum: Active record pool size minus 1, with a minimum of 1"
         ).freeze
         DEFAULT_QUEUE = DefaultOptionValue.new("All queues").freeze
+        DEFAULT_PRIORITIES = DefaultOptionValue.new("All priorities").freeze
         DEFAULT_FOREVER = DefaultOptionValue.new("Forever").freeze
 
         DEFAULT_CONFIGURATION = { set_db_connection_name: true }.freeze

data/lib/exekutor/internal/configuration_builder.rb

@@ -26,7 +26,7 @@ module Exekutor
         end
 
         options.each do |name, value|
-          send "#{name}=", value
+          send :"#{name}=", value
         end
         self
       end
@@ -54,7 +54,7 @@ module Exekutor
         private
 
         def define_writer(name, required, type, enum, range)
-          define_method "#{name}=" do |value|
+          define_method :"#{name}=" do |value|
             validate_option_presence! name, value if required
             validate_option_type! name, value, *type if type.present?
             validate_option_enum! name, value, *enum if enum.present?
@@ -93,7 +93,9 @@ module Exekutor
         return if allowed_types.include?(value.class)
 
         raise error_class, "##{name} should be an instance of #{
-          allowed_types.to_sentence(last_word_connector: ", or ")} (Actual: #{value.class})"
+          allowed_types.map { |c| c == NilClass || c.nil? ? "nil" : c }
+                       .to_sentence(two_words_connector: " or ", last_word_connector: ", or ")
+        } (Actual: #{value.class})"
       end
 
       # Validates whether the value is a valid enum option
@@ -101,8 +103,10 @@ module Exekutor
       def validate_option_enum!(name, value, *allowed_values)
         return if allowed_values.include?(value)
 
-        raise error_class, "##{name} should be one of #{allowed_values.map(&:inspect)
-                                                                      .to_sentence(last_word_connector: ", or ")}"
+        raise error_class, "##{name} should be one of #{
+          allowed_values.map(&:inspect)
+                        .to_sentence(two_words_connector: " or ", last_word_connector: ", or ")
+        }"
       end
 
       # Validates whether the value falls in the allowed range
@@ -110,8 +114,10 @@ module Exekutor
       def validate_option_range!(name, value, allowed_range)
         return if allowed_range.include?(value)
 
-        raise error_class, "##{name} should be between #{allowed_range.first} and #{allowed_range.last}#{
-          " (exclusive)" if allowed_range.respond_to?(:exclude_end?) && allowed_range.exclude_end?}"
+        raise error_class, <<~MSG
+            ##{name} should be between #{allowed_range.first.inspect} and #{allowed_range.last.inspect}#{
+          " (exclusive)" if allowed_range.respond_to?(:exclude_end?) && allowed_range.exclude_end?}
+        MSG
       end
 
       protected

data/lib/exekutor/internal/listener.rb

@@ -24,11 +24,14 @@ module Exekutor
       # @param pool [ThreadPoolExecutor] the thread pool to use
       # @param wait_timeout [Integer] the time to listen for notifications
       # @param set_db_connection_name [Boolean] whether to set the application name on the DB connection
-      def initialize(worker_id:, provider:, pool:, queues: nil, wait_timeout: 60, set_db_connection_name: false)
+      def initialize(worker_id:, provider:, pool:, queues: nil, min_priority: nil, max_priority: nil, wait_timeout: 60,
+                     set_db_connection_name: false)
         super()
         @config = {
           worker_id: worker_id,
-          queues: queues || [],
+          queues: queues.presence,
+          min_priority: min_priority,
+          max_priority: max_priority,
           wait_timeout: wait_timeout,
           set_db_connection_name: set_db_connection_name
         }
@@ -67,11 +70,22 @@ module Exekutor
         PROVIDER_CHANNEL % @config[:worker_id]
       end
 
-      # Whether this listener is listening to the given queue
-      # @return [Boolean]
+      # @return [Boolean] Whether the job matches the configured queues and priority range
+      def job_filter_match?(job_info)
+        listening_to_queue?(job_info["q"]) && listening_to_priority?(job_info["p"].to_i)
+      end
+
+      # @return [Boolean] Whether this listener is listening to the given queue
       def listening_to_queue?(queue)
         queues = @config[:queues]
-        queues.empty? || queues.include?(queue)
+        queues.nil? || queues.include?(queue)
+      end
+
+      # @return [Boolean] Whether this listener is listening to the given priority
+      def listening_to_priority?(priority)
+        minimum = @config[:min_priority]
+        maximum = @config[:max_priority]
+        (minimum.nil? || minimum <= priority) && (maximum.nil? || maximum >= priority)
       end
 
       # Starts the listener thread
@@ -129,8 +143,9 @@ module Exekutor
                          JobParser.parse(payload)
                        rescue StandardError => e
                          logger.error e.message
+                         nil
                        end
-            next unless job_info && listening_to_queue?(job_info["q"])
+            next unless job_info && job_filter_match?(job_info)
 
             @provider.update_earliest_scheduled_at(job_info["t"].to_f)
           end
@@ -177,7 +192,7 @@ module Exekutor
 
       # Parses a NOTIFY payload to a job
       class JobParser
-        JOB_INFO_KEYS = %w[id q t].freeze
+        JOB_INFO_KEYS = %w[id q p t].freeze
 
         def self.parse(payload)
           job_info = begin

data/lib/exekutor/internal/logger.rb

@@ -82,6 +82,7 @@ module Exekutor
   # @return [String] The given error class, message, and cleaned backtrace as a string
   def self.strferr(err)
     raise ArgumentError, "err must not be nil" if err.nil?
+    return err if err.is_a? String
 
     "#{err.class} – #{err.message}\nat #{
       err.backtrace ? backtrace_cleaner.clean(err.backtrace).join("\n   ") : "unknown location"

data/lib/exekutor/internal/provider.rb

@@ -25,16 +25,16 @@ module Exekutor
       # @param reserver [Reserver] the job reserver
       # @param executor [Executor] the job executor
       # @param pool [ThreadPoolExecutor] the thread pool to use
-      # @param polling_interval [Integer] the polling interval
+      # @param polling_interval [ActiveSupport::Duration] the polling interval
       # @param interval_jitter [Float] the polling interval jitter
-      def initialize(reserver:, executor:, pool:, polling_interval: 60,
+      def initialize(reserver:, executor:, pool:, polling_interval: 60.seconds,
                      interval_jitter: polling_interval.to_i > 1 ? polling_interval * 0.1 : 0)
         super()
         @reserver = reserver
         @executor = executor
         @pool = pool
 
-        @polling_interval = polling_interval.freeze
+        @polling_interval = polling_interval.to_i.freeze
         @interval_jitter = interval_jitter.to_f.freeze
 
         @event = Concurrent::Event.new

data/lib/exekutor/internal/reserver.rb

@@ -11,9 +11,9 @@ module Exekutor
       # Creates a new Reserver
       # @param worker_id [String] the id of the worker
       # @param queues [Array<String>] the queues to watch
-      def initialize(worker_id, queues)
+      def initialize(worker_id, queues: nil, min_priority: nil, max_priority: nil)
         @worker_id = worker_id
-        @queue_filter_sql = build_queue_filter_sql(queues)
+        @reserve_filter_sql = build_filter_sql(queues: queues, min_priority: min_priority, max_priority: max_priority)
         @json_serializer = Exekutor.config.load_json_serializer
       end
 
@@ -26,8 +26,8 @@ module Exekutor
         results = Exekutor::Job.connection.exec_query <<~SQL, ACTION_NAME, [@worker_id, limit], prepare: true
           UPDATE exekutor_jobs SET worker_id = $1, status = 'e' WHERE id IN (
              SELECT id FROM exekutor_jobs
-                WHERE scheduled_at <= now() AND "status"='p' #{@queue_filter_sql}
-                ORDER BY priority, scheduled_at, enqueued_at
+                WHERE scheduled_at <= now() AND "status"='p'#{" AND #{@reserve_filter_sql}" if @reserve_filter_sql}
+                ORDER BY priority#{" DESC" if Exekutor.config.inverse_priority?}, scheduled_at, enqueued_at
                 FOR UPDATE SKIP LOCKED
                 LIMIT $2
           ) RETURNING "id", "payload", "options", "scheduled_at"
@@ -51,7 +51,7 @@ module Exekutor
       # @return [Time,nil] The earliest scheduled at, or nil if the queues are empty
       def earliest_scheduled_at
         jobs = Exekutor::Job.pending
-        jobs.where! @queue_filter_sql.gsub(/^\s*AND\s+/, "") unless @queue_filter_sql.nil?
+        jobs.where! @reserve_filter_sql unless @reserve_filter_sql.nil?
         jobs.minimum(:scheduled_at)
       end
 
@@ -72,6 +72,16 @@ module Exekutor
         @json_serializer.load str unless str.nil?
       end
 
+      # Builds SQL filter for the given queues and priorities
+      def build_filter_sql(queues:, min_priority:, max_priority:)
+        filters = [
+          build_queue_filter_sql(queues),
+          build_priority_filter_sql(min_priority, max_priority)
+        ]
+        filters.compact!
+        filters.join(" AND ") unless filters.empty?
+      end
+
       # Builds SQL filter for the given queues
       def build_queue_filter_sql(queues)
         return nil if queues.nil? || (queues.is_a?(Array) && queues.empty?)
@@ -79,11 +89,32 @@ module Exekutor
         queues = queues.first if queues.is_a?(Array) && queues.one?
         validate_queues! queues
 
-        if queues.is_a? Array
-          Exekutor::Job.sanitize_sql_for_conditions(["AND queue IN (?)", queues])
-        else
-          Exekutor::Job.sanitize_sql_for_conditions(["AND queue = ?", queues])
-        end
+        conditions = if queues.is_a? Array
+                       ["queue IN (?)", queues]
+                     else
+                       ["queue = ?", queues]
+                     end
+        Exekutor::Job.sanitize_sql_for_conditions conditions
+      end
+
+      # Builds SQL filter for the given priorities
+      def build_priority_filter_sql(minimum, maximum)
+        minimum = coerce_priority(minimum)
+        maximum = coerce_priority(maximum)
+
+        conditions = if minimum && maximum
+                       ["priority BETWEEN ? AND ?", minimum, maximum]
+                     elsif minimum
+                       ["priority >= ?", minimum]
+                     elsif maximum
+                       ["priority <= ?", maximum]
+                     end
+        Exekutor::Job.sanitize_sql_for_conditions conditions if conditions
+      end
+
+      # @return [Integer,nil] returns nil unless +priority+ is between 1 and 32,766
+      def coerce_priority(priority)
+        priority if priority && (1..32_766).cover?(priority)
       end
 
       # Raises an error if the queues value is invalid
@@ -96,7 +127,8 @@ module Exekutor
         when String, Symbol
           raise ArgumentError, "queue name cannot be empty" unless valid_queue_name? queues
         else
-          raise ArgumentError, "queues must be nil, a String, Symbol, or an array of Strings or Symbols"
+          raise ArgumentError,
+                "queues must be nil, a String, Symbol, or an array of Strings or Symbols (Actual: #{queues.class})"
         end
       end
 

data/lib/exekutor/internal/status_server.rb

@@ -23,7 +23,7 @@ module Exekutor
 
       DEFAULT_HANDLER = "webrick"
 
-      def initialize(worker:, pool:, port:, handler: DEFAULT_HANDLER, heartbeat_timeout: 30)
+      def initialize(worker:, pool:, port:, handler: DEFAULT_HANDLER, heartbeat_timeout: 30.minutes)
         super()
         @worker = worker
         @pool = pool
@@ -52,12 +52,13 @@ module Exekutor
         return unless @thread_running.value
 
         server = @server.value
-        if server.respond_to? :shutdown
-          server.shutdown
-        elsif server.respond_to? :stop
-          server.stop
+        shutdown_method = %i[shutdown stop].find { |method| server.respond_to? method }
+        if shutdown_method
+          server.send(shutdown_method)
+          Exekutor.say "Status server stopped"
         elsif server
-          Exekutor.say! "Cannot shutdown status server, #{server.class.name} does not respond to shutdown or stop"
+          Exekutor.print_error "Cannot shutdown status server, " \
+                               "#{server.class.name} does not respond to `shutdown` or `stop`"
         end
       end
 
@@ -67,7 +68,7 @@ module Exekutor
       def run(worker, port)
         return unless state == :started && @thread_running.make_true
 
-        Exekutor.say "Starting status server at 0.0.0.0:#{port}… (Timeout: #{@heartbeat_timeout} minutes)"
+        Exekutor.say "Starting status server at 0.0.0.0:#{port}… (Timeout: #{@heartbeat_timeout.inspect})"
         @handler.run(App.new(worker, @heartbeat_timeout), Port: port, Host: "0.0.0.0", Silent: true,
                      Logger: ::Logger.new(File.open(File::NULL, "w")), AccessLog: []) do |server|
           @server.set server
@@ -107,7 +108,7 @@ module Exekutor
         private
 
         def flatlined?(last_heartbeat = @worker.last_heartbeat)
-          last_heartbeat.nil? || last_heartbeat < @heartbeat_timeout.minutes.ago
+          last_heartbeat.nil? || last_heartbeat < @heartbeat_timeout.ago
         end
 
         def render_threads

data/lib/exekutor/queue.rb

@@ -17,18 +17,18 @@ module Exekutor
     MAX_NAME_LENGTH = 63
 
     # Adds a job to the queue, scheduled to perform immediately
-    # @param jobs [Array<ActiveJob::Base>] the jobs to enqueue
-    # @return [void]
-    def push(*jobs)
-      create_records(jobs)
+    # @param jobs [ActiveJob::Base,Array<ActiveJob::Base>] the jobs to enqueue
+    # @return [Integer] the number of enqueued jobs
+    def push(jobs)
+      create_records Array.wrap(jobs)
     end
 
     # Adds a job to the queue, scheduled to be performed at the indicated time
-    # @param jobs [Array<ActiveJob::Base>] the jobs to enqueue
+    # @param jobs [ActiveJob::Base,Array<ActiveJob::Base>] the jobs to enqueue
     # @param timestamp [Time,Date,Integer,Float] when the job should be performed
-    # @return [void]
-    def schedule_at(*jobs, timestamp)
-      create_records(jobs, scheduled_at: timestamp)
+    # @return [Integer] the number of enqueued jobs
+    def schedule_at(jobs, timestamp)
+      create_records(Array.wrap(jobs), scheduled_at: timestamp)
     end
 
     private
@@ -38,16 +38,22 @@ module Exekutor
     # @param scheduled_at [Time,Date,Integer,Float] when the job should be performed
     # @return [void]
     def create_records(jobs, scheduled_at: nil)
-      unless jobs.is_a?(Array) && jobs.all?(ActiveJob::Base)
-        raise ArgumentError, "jobs must be an array with ActiveJob items"
+      raise ArgumentError, "jobs must be an array with ActiveJob items (Actual: #{jobs.class})" unless jobs.is_a?(Array)
+
+      unless jobs.all?(ActiveJob::Base)
+        raise ArgumentError, "jobs must be an array with ActiveJob items (Found: #{
+          jobs.map { |job| job.class unless job.is_a? ActiveJob::Base }.compact.join(", ")
+        })"
       end
 
       scheduled_at = parse_scheduled_at(scheduled_at)
       json_serializer = Exekutor.config.load_json_serializer
 
+      inserted_records = nil
       Internal::Hooks.run :enqueue, jobs do
-        insert_job_records(jobs, scheduled_at, json_serializer)
+        inserted_records = insert_job_records(jobs, scheduled_at, json_serializer)
       end
+      inserted_records
     end
 
     # Converts the given value to an epoch timestamp. Returns the current epoch timestamp if the given value is nil
@@ -78,22 +84,37 @@ module Exekutor
     # @param json_serializer [#dump] the serializer to use to convert hashes into JSON
     def insert_job_records(jobs, scheduled_at, json_serializer)
       if jobs.one?
-        sql_binds = job_sql_binds(jobs.first, scheduled_at, json_serializer)
-        Exekutor::Job.connection.exec_query <<~SQL, ACTION_NAME, sql_binds, prepare: true
-          INSERT INTO exekutor_jobs ("queue", "priority", "scheduled_at", "active_job_id", "payload", "options") VALUES ($1, $2, to_timestamp($3), $4, $5, $6) RETURNING id;
-        SQL
+        insert_singular_job(jobs.first, json_serializer, scheduled_at)
       else
         insert_statements = jobs.map do |job|
           Exekutor::Job.sanitize_sql_for_assignment(
             ["(?, ?, to_timestamp(?), ?, ?::jsonb, ?::jsonb)", *job_sql_binds(job, scheduled_at, json_serializer)]
           )
         end
-        Exekutor::Job.connection.insert <<~SQL, ACTION_NAME
-          INSERT INTO exekutor_jobs ("queue", "priority", "scheduled_at", "active_job_id", "payload", "options") VALUES #{insert_statements.join(",")}
-        SQL
+        begin
+          pg_result = Exekutor::Job.connection.execute <<~SQL, ACTION_NAME
+            INSERT INTO exekutor_jobs ("queue", "priority", "scheduled_at", "active_job_id", "payload", "options") VALUES #{insert_statements.join(",")}
+          SQL
+          inserted_records = pg_result.cmd_tuples
+        ensure
+          pg_result.clear
+        end
+        inserted_records
       end
     end
 
+    # Fires off an INSERT INTO query for the given job using a prepared statement
+    # @param job [ActiveJob::Base] the job to insert
+    # @param scheduled_at [Integer,Float] the scheduled execution time for the jobs as an epoch timestamp
+    # @param json_serializer [#dump] the serializer to use to convert hashes into JSON
+    def insert_singular_job(job, json_serializer, scheduled_at)
+      sql_binds = job_sql_binds(job, scheduled_at, json_serializer)
+      ar_result = Exekutor::Job.connection.exec_query <<~SQL, ACTION_NAME, sql_binds, prepare: true
+        INSERT INTO exekutor_jobs ("queue", "priority", "scheduled_at", "active_job_id", "payload", "options") VALUES ($1, $2, to_timestamp($3), $4, $5, $6) RETURNING id;
+      SQL
+      ar_result.length
+    end
+
     # Converts the specified job to SQL bind parameters to insert it into the database
     # @param job [ActiveJob::Base] the job to insert
     # @param scheduled_at [Float] the epoch timestamp for when the job should be executed
@@ -124,7 +145,7 @@ module Exekutor
     def exekutor_options(job)
       return nil unless job.respond_to?(:exekutor_options)
 
-      options = job.exekutor_options.stringify_keys
+      options = job.exekutor_options&.stringify_keys
       if options && options["queue_timeout"]
         options["start_execution_before"] = Time.now.to_f + options.delete("queue_timeout").to_f
       end

data/lib/exekutor/version.rb

@@ -2,5 +2,5 @@
 
 module Exekutor
   # The current version of Exekutor
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/lib/exekutor/worker.rb

@@ -23,17 +23,17 @@ module Exekutor
     # @option config [Array<String>] :queues the queues to work on
     # @option config [Integer] :min_threads the minimum number of execution threads that should be active
     # @option config [Integer] :max_threads the maximum number of execution threads that may be active
-    # @option config [Integer] :max_thread_idletime the maximum number of seconds a thread may be idle before being
-    #   stopped
-    # @option config [Integer] :polling_interval the polling interval in seconds
+    # @option config [ActiveSupport::Duration] :max_thread_idletime the maximum duration a thread may be idle before
+    #   being stopped
+    # @option config [ActiveSupport::Duration] :polling_interval the polling interval
     # @option config [Float] :poling_jitter the polling jitter
     # @option config [Boolean] :set_db_connection_name whether the DB connection name should be set
     # @option config [Integer,Boolean] :wait_for_termination how long the worker should wait on jobs to be completed
     #   before exiting
     # @option config [Integer] :status_server_port the port to run the status server on
     # @option config [String] :status_server_handler The name of the rack handler to use for the status server
-    # @option config [Integer] :healthcheck_timeout The timeout of a worker in minutes before the healthcheck server
-    #   deems it as down
+    # @option config [ActiveSupport::Duration] :healthcheck_timeout The timeout of a worker in minutes before the
+    #   healthcheck server deems it as down
     def initialize(config = {})
       super()
       @config = config
@@ -178,7 +178,7 @@ module Exekutor
     end
 
     def create_provider(worker_options, executor, thread_pool)
-      @reserver = Internal::Reserver.new @record.id, worker_options[:queues]
+      @reserver = Internal::Reserver.new @record.id, **worker_options.slice(:queues, :min_priority, :max_priority)
       provider = Internal::Provider.new reserver: @reserver, executor: executor, pool: thread_pool,
                                         **provider_options(worker_options)
 

data/lib/generators/exekutor/configuration_generator.rb

@@ -12,11 +12,12 @@ module Exekutor
     # Creates the configuration file at +config/exekutor.yml+. Uses the current worker configuration as the base.
     def create_configuration_file
       config = { queues: %w[queues to watch] }.merge(Exekutor.config.worker_options)
-      config[:status_port] = 8765
+      config[:status_port] = 12_677
       config[:set_db_connection_name] = true
       config[:wait_for_termination] = 120
-      create_file "config/exekutor#{".#{options[:identifier]}" if options[:identifier]}.yml",
-                  { "exekutor" => config.stringify_keys }.to_yaml
+
+      filename = "config/exekutor#{".#{options[:identifier]}" if options[:identifier]}.yml"
+      create_file filename, { "exekutor" => config.stringify_keys }.to_yaml
     end
   end
 end

data/lib/generators/exekutor/install_generator.rb

@@ -43,11 +43,9 @@ module Exekutor
     def create_fx_files
       return unless defined?(Fx)
 
-      %w[job_notifier requeue_orphaned_jobs].each do |function|
-        copy_file "functions/#{function}.sql", Fx::Definition.new(name: function, version: 1).full_path
-      end
-      %w[notify_workers requeue_orphaned_jobs].each do |trigger|
-        copy_file "triggers/#{trigger}.sql", Fx::Definition.new(name: trigger, version: 1, type: "trigger").full_path
+      %w[exekutor_broadcast_job_enqueued exekutor_requeue_orphaned_jobs].each do |name|
+        copy_file "functions/#{name}.sql", Fx::Definition.new(name: name, version: 1).full_path
+        copy_file "triggers/#{name}.sql", Fx::Definition.new(name: name, version: 1, type: "trigger").full_path
       end
     end
   end

data/lib/generators/exekutor/templates/install/functions/exekutor_broadcast_job_enqueued.sql

@@ -0,0 +1,10 @@
+CREATE
+OR REPLACE FUNCTION exekutor_broadcast_job_enqueued() RETURNS TRIGGER AS $$
+BEGIN
+    PERFORM
+pg_notify('exekutor::job_enqueued',
+    CONCAT('id:', NEW.id,';q:', NEW.queue,';p:', NEW.priority, ';t:', extract ('epoch' from NEW.scheduled_at)));
+RETURN NULL;
+END;
+      $$
+LANGUAGE plpgsql

data/lib/generators/exekutor/templates/install/functions/exekutor_requeue_orphaned_jobs.sql

@@ -0,0 +1,11 @@
+CREATE
+OR REPLACE FUNCTION exekutor_requeue_orphaned_jobs() RETURNS TRIGGER AS $$
+BEGIN
+UPDATE exekutor_jobs
+SET status = 'p'
+WHERE worker_id = OLD.id
+  AND status = 'e';
+RETURN OLD;
+END;
+      $$
+LANGUAGE plpgsql

data/lib/generators/exekutor/templates/install/migrations/create_exekutor_schema.rb.erb

@@ -42,40 +42,40 @@ class CreateExekutorSchema < ActiveRecord::Migration[<%= migration_version %>]
       t.jsonb :error, null: false
     end
       <% if defined? Fx %>
-    create_function :job_notifier
-    create_trigger :notify_workers
+    create_function :exekutor_broadcast_job_enqueued
+    create_trigger :exekutor_broadcast_job_enqueued, on: :exekutor_jobs
 
-    create_function :requeue_orphaned_jobs
-    create_trigger :requeue_orphaned_jobs
+    create_function :exekutor_requeue_orphaned_jobs
+    create_trigger :exekutor_requeue_orphaned_jobs, on: :exekutor_workers
       <% else %>
     reversible do |direction|
       direction.up do
         execute <<~SQL
-          <%= function_sql "job_notifier" %>
+          <%= function_sql "exekutor_broadcast_job_enqueued" %>
         SQL
         execute <<~SQL
-          <%= trigger_sql "notify_workers" %>
+          <%= trigger_sql "exekutor_broadcast_job_enqueued" %>
         SQL
 
         execute <<~SQL
-          <%= function_sql "requeue_orphaned_jobs" %>
+          <%= function_sql "exekutor_requeue_orphaned_jobs" %>
         SQL
         execute <<~SQL
-          <%= trigger_sql "requeue_orphaned_jobs" %>
+          <%= trigger_sql "exekutor_requeue_orphaned_jobs" %>
         SQL
       end
       direction.down do
         execute <<~SQL
-          DROP TRIGGER requeue_orphaned_jobs ON exekutor_workers
+          DROP TRIGGER exekutor_requeue_orphaned_jobs ON exekutor_workers
         SQL
         execute <<~SQL
-          DROP FUNCTION requeue_orphaned_jobs
+          DROP FUNCTION exekutor_requeue_orphaned_jobs
         SQL
         execute <<~SQL
-          DROP TRIGGER notify_exekutor_workers ON exekutor_jobs
+          DROP TRIGGER exekutor_broadcast_job_enqueued ON exekutor_jobs
         SQL
         execute <<~SQL
-          DROP FUNCTION exekutor_job_notifier
+          DROP FUNCTION exekutor_broadcast_job_enqueued
         SQL
       end
     end

data/lib/generators/exekutor/templates/install/triggers/exekutor_broadcast_job_enqueued.sql

@@ -0,0 +1,7 @@
+CREATE TRIGGER exekutor_broadcast_job_enqueued
+    AFTER INSERT OR
+UPDATE OF queue, scheduled_at, status
+ON exekutor_jobs
+    FOR EACH ROW
+    WHEN (NEW.status = 'p')
+    EXECUTE FUNCTION exekutor_broadcast_job_enqueued()

data/lib/generators/exekutor/templates/install/triggers/exekutor_requeue_orphaned_jobs.sql

@@ -0,0 +1,5 @@
+CREATE TRIGGER exekutor_requeue_orphaned_jobs
+    BEFORE DELETE
+    ON exekutor_workers
+    FOR EACH ROW
+EXECUTE FUNCTION exekutor_requeue_orphaned_jobs()

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exekutor
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Roy
@@ -34,7 +34,7 @@ cert_chain:
   LMMHpsz0vpxVqcs8USL9494hQUWRVlYd1F2PJeWtdKi0bU8dCduphJd8cTvCtS2l
   CAY756btGBLeeWMBZ/DRMj1Cz3ifI9DV+KHqXg==
   -----END CERTIFICATE-----
-date: 2023-05-14 00:00:00.000000000 Z
+date: 2023-12-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activejob
@@ -410,12 +410,12 @@ files:
 - lib/exekutor/worker.rb
 - lib/generators/exekutor/configuration_generator.rb
 - lib/generators/exekutor/install_generator.rb
-- lib/generators/exekutor/templates/install/functions/job_notifier.sql
-- lib/generators/exekutor/templates/install/functions/requeue_orphaned_jobs.sql
+- lib/generators/exekutor/templates/install/functions/exekutor_broadcast_job_enqueued.sql
+- lib/generators/exekutor/templates/install/functions/exekutor_requeue_orphaned_jobs.sql
 - lib/generators/exekutor/templates/install/initializers/exekutor.rb.erb
 - lib/generators/exekutor/templates/install/migrations/create_exekutor_schema.rb.erb
-- lib/generators/exekutor/templates/install/triggers/notify_workers.sql
-- lib/generators/exekutor/templates/install/triggers/requeue_orphaned_jobs.sql
+- lib/generators/exekutor/templates/install/triggers/exekutor_broadcast_job_enqueued.sql
+- lib/generators/exekutor/templates/install/triggers/exekutor_requeue_orphaned_jobs.sql
 homepage: https://github.com/devdicated/exekutor
 licenses:
 - MIT

data/lib/generators/exekutor/templates/install/functions/job_notifier.sql

@@ -1,7 +0,0 @@
-CREATE OR REPLACE FUNCTION exekutor_job_notifier() RETURNS TRIGGER AS $$
-  BEGIN
-          PERFORM pg_notify('exekutor::job_enqueued',
-                            CONCAT('id:', NEW.id,';q:', NEW.queue,';t:', extract ('epoch' from NEW.scheduled_at)));
-  RETURN NULL;
-  END;
-      $$ LANGUAGE plpgsql

data/lib/generators/exekutor/templates/install/functions/requeue_orphaned_jobs.sql

@@ -1,7 +0,0 @@
-CREATE OR REPLACE FUNCTION requeue_orphaned_jobs() RETURNS TRIGGER AS $$ BEGIN
-  UPDATE exekutor_jobs
-  SET status = 'p'
-  WHERE worker_id = OLD.id
-    AND status = 'e';
-  RETURN OLD; END;
-      $$ LANGUAGE plpgsql

data/lib/generators/exekutor/templates/install/triggers/notify_workers.sql

@@ -1,6 +0,0 @@
-CREATE TRIGGER notify_exekutor_workers
-  AFTER INSERT OR UPDATE OF queue, scheduled_at, status
-                  ON exekutor_jobs
-                    FOR EACH ROW
-                    WHEN (NEW.status = 'p')
-                    EXECUTE FUNCTION exekutor_job_notifier()

data/lib/generators/exekutor/templates/install/triggers/requeue_orphaned_jobs.sql

@@ -1,5 +0,0 @@
-CREATE TRIGGER requeue_orphaned_jobs
-  BEFORE DELETE
-  ON exekutor_workers
-  FOR EACH ROW
-  EXECUTE FUNCTION requeue_orphaned_jobs()