gemstack 0.2.5 → 0.3.0

data/lib/gemstack/inflector.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module GemStack
+  # English inflections used by conventions (routes, generators, constants).
+  #
+  #   Inflector.pluralize("category")      # => "categories"
+  #   Inflector.camelize("inventory_item") # => "InventoryItem"
+  #   Inflector.underscore("InventoryItem")# => "inventory_item"
+  #
+  # Extend with Inflector.irregular("person", "people") or
+  # Inflector.uncountable("equipment") — typically in config/app.rb.
+  module Inflector
+    PLURALS = [
+      [/(quiz)\z/i, '\1zes'],
+      [/\A(ox)\z/i, '\1en'],
+      [/(matr|vert|ind)(?:ix|ex)\z/i, '\1ices'],
+      [/(x|ch|ss|sh|zz)\z/i, '\1es'],
+      [/([^aeiouy]|qu)y\z/i, '\1ies'],
+      [/(?:([^f])fe|([lr])f)\z/i, '\1\2ves'],
+      [/sis\z/i, "ses"],
+      [/([ti])um\z/i, '\1a'],
+      [/(buffal|tomat|potat|her|ech)o\z/i, '\1oes'],
+      [/(bu|mis|ga|alia|statu|stat|vir|octop|cact)us\z/i, '\1uses'],
+      [/s\z/i, "s"],
+      [/\z/, "s"]
+    ].freeze
+
+    SINGULARS = [
+      [/(quiz)zes\z/i, '\1'],
+      [/(matr)ices\z/i, '\1ix'],
+      [/(vert|ind)ices\z/i, '\1ex'],
+      [/\A(ox)en/i, '\1'],
+      [/(alias|status|bus|campus|virus|octopus|cactus)(es)?\z/i, '\1'],
+      [/(x|ch|ss|sh|zz)es\z/i, '\1'],
+      [/(m)ovies\z/i, '\1ovie'],
+      [/([^aeiouy]|qu)ies\z/i, '\1y'],
+      [/([lr])ves\z/i, '\1f'],
+      [/([^f])ves\z/i, '\1fe'],
+      [/(analy|ba|diagno|parenthe|progno|synop|the)ses\z/i, '\1sis'],
+      [/(buffal|tomat|potat|her|ech)oes\z/i, '\1o'],
+      [/([ti])a\z/i, '\1um'],
+      [/ss\z/i, "ss"],
+      [/s\z/i, ""]
+    ].freeze
+
+    DEFAULT_IRREGULARS = {
+      "person" => "people", "man" => "men", "woman" => "women", "child" => "children",
+      "mouse" => "mice", "goose" => "geese", "tooth" => "teeth", "foot" => "feet"
+    }.freeze
+
+    DEFAULT_UNCOUNTABLES = %w[equipment information rice money species series fish sheep deer news data].freeze
+
+    @irregulars = DEFAULT_IRREGULARS.dup
+    @uncountables = DEFAULT_UNCOUNTABLES.dup
+
+    class << self
+      def irregular(singular, plural)
+        @irregulars[singular.downcase] = plural.downcase
+      end
+
+      def uncountable(*words)
+        @uncountables.concat(words.flatten.map(&:downcase))
+      end
+
+      def pluralize(word)
+        inflect(word.to_s, @irregulars, PLURALS)
+      end
+
+      def singularize(word)
+        inflect(word.to_s, @irregulars.invert, SINGULARS)
+      end
+
+      # "inventory_item" / "inventory-item" => "InventoryItem";
+      # "admin/products" => "Admin::Products"
+      def camelize(term)
+        term.to_s.split("/").map do |part|
+          part.split(/[_-]/).map { |w| w[0] ? w[0].upcase + w[1..] : w }.join
+        end.join("::")
+      end
+
+      # "InventoryItem" => "inventory_item"; "Admin::Products" => "admin/products"
+      def underscore(term)
+        term.to_s.gsub("::", "/")
+            .gsub(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+            .tr("-", "_")
+            .downcase
+      end
+
+      def dasherize(term) = underscore(term).tr("_", "-")
+
+      # "inventory_item" => "Inventory item"
+      def humanize(term)
+        words = underscore(term).delete_suffix("_id").tr("_", " ")
+        words[0] ? words[0].upcase + words[1..] : words
+      end
+
+      # "inventory_items" => "InventoryItem"
+      def classify(term) = camelize(singularize(term.to_s))
+
+      # "InventoryItem" => "inventory_items"
+      def tableize(term) = pluralize(underscore(term))
+
+      private
+
+      # irregulars maps source form => target form (e.g. "person" => "people").
+      def inflect(word, irregulars, rules)
+        return word if word.empty?
+
+        prefix, last = split_last_word(word)
+        lower = last.downcase
+        return word if @uncountables.include?(lower) || irregulars.value?(lower)
+        return prefix + match_case(last, irregulars[lower]) if irregulars.key?(lower)
+
+        rules.each do |pattern, replacement|
+          return prefix + last.sub(pattern, replacement) if last.match?(pattern)
+        end
+        word
+      end
+
+      # Only the final word is inflected: "line_item" => ["line_", "item"],
+      # "LineItem" => ["Line", "Item"].
+      def split_last_word(word)
+        match = word.match(/\A(.*[_\-\s])([^_\-\s]+)\z/m) || word.match(/\A(.*[a-z\d])([A-Z][^A-Z]*)\z/)
+        match ? [match[1], match[2]] : ["", word]
+      end
+
+      def match_case(original, replacement)
+        original[0] == original[0].upcase ? replacement[0].upcase + replacement[1..] : replacement
+      end
+    end
+  end
+end

data/lib/gemstack/job.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module GemStack
+  # Base class for background jobs. See GemStack::Jobs.
+  #
+  #   class ImportProducts < GemStack::Job
+  #     queue :imports
+  #     priority 10                                          # lower runs first (default 100)
+  #     retry_on Faraday::TimeoutError, attempts: 5, wait: :exponential
+  #     discard_on GemStack::NotFound                        # the record is gone; nothing to do
+  #
+  #     def perform(import_id, options = {})
+  #       ...
+  #     end
+  #   end
+  #
+  #   ImportProducts.perform_later(import.id)                       # => job id
+  #   ImportProducts.set(wait: 300, queue: "slow").perform_later(1)  # in 5 minutes
+  #   ImportProducts.set(at: Time.now + 3600).perform_later(1)
+  #   ImportProducts.perform_now(1)                                 # synchronously
+  #
+  # Arguments must be JSON values (strings, numbers, booleans, nil, arrays,
+  # hashes with string or symbol keys). Pass ids, not records. Hash keys come
+  # back as strings.
+  class Job
+    RetryRule = Struct.new(:classes, :attempts, :wait)
+
+    class << self
+      def queue(name = nil)
+        @queue = name.to_s if name
+        @queue || (superclass.respond_to?(:queue) ? superclass.queue : Jobs.config.default_queue)
+      end
+
+      def priority(value = nil)
+        @priority = Integer(value) if value
+        @priority || (superclass.respond_to?(:priority) ? superclass.priority : Jobs.config.default_priority)
+      end
+
+      # retry_on Net::ReadTimeout, attempts: 5, wait: 30          # fixed seconds
+      # retry_on StandardError, wait: :exponential                 # default
+      # retry_on Api::RateLimited, wait: ->(attempt) { attempt * 60 }
+      # The first matching rule (most recently declared first) decides.
+      def retry_on(*classes, attempts: nil, wait: :exponential)
+        retry_rules.unshift(RetryRule.new(classes, attempts, wait))
+      end
+
+      # Errors that mean the job should simply be dropped (logged, not retried).
+      def discard_on(*classes)
+        discard_classes.concat(classes)
+      end
+
+      def retry_rules = @retry_rules ||= superclass.respond_to?(:retry_rules) ? superclass.retry_rules.dup : []
+
+      def discard_classes
+        @discard_classes ||= superclass.respond_to?(:discard_classes) ? superclass.discard_classes.dup : []
+      end
+
+      def perform_later(*) = Enqueuer.new(self).perform_later(*)
+      def set(**) = Enqueuer.new(self, **)
+
+      def perform_now(*args)
+        new.perform(*Jobs::Arguments.load(Jobs::Arguments.dump(args)))
+      end
+
+      # [max attempts, seconds to wait before the next attempt] for an error
+      # raised on attempt number `attempt` (1-based); nil wait = give up.
+      def retry_decision(error, attempt)
+        rule = retry_rules.find { |r| r.classes.any? { |klass| error.is_a?(klass) } }
+        max = rule&.attempts || Jobs.config.default_max_attempts
+        return [max, nil] if attempt >= max
+
+        [max, backoff(rule&.wait || :exponential, attempt)]
+      end
+
+      def discard?(error) = discard_classes.any? { |klass| error.is_a?(klass) }
+
+      private
+
+      # Sidekiq's curve: 16s, 31s, 96s, 271s, … ≈ 4 hours over 10 attempts.
+      def backoff(wait, attempt)
+        case wait
+        when :exponential then (attempt**4) + 15 + (rand(10) * attempt)
+        when Proc then Float(wait.call(attempt))
+        else Float(wait)
+        end
+      end
+    end
+
+    # Builds the payload for a (possibly customised) enqueue.
+    class Enqueuer
+      def initialize(job_class, wait: nil, at: nil, queue: nil, priority: nil)
+        @job_class = job_class
+        @run_at = at || (wait && (Time.now + Float(wait)))
+        @queue = queue&.to_s
+        @priority = priority
+      end
+
+      def perform_later(*args)
+        payload = {
+          "job_class" => @job_class.name,
+          "queue" => @queue || @job_class.queue,
+          "priority" => @priority || @job_class.priority,
+          "args" => Jobs::Arguments.dump(args),
+          "run_at" => @run_at
+        }
+        raise ArgumentError, "anonymous job classes can't be enqueued" unless payload["job_class"]
+
+        id = Jobs.adapter.enqueue(payload)
+        Jobs.instrument(:enqueued, job_class: payload["job_class"], job_id: id, queue: payload["queue"],
+                                   run_at: payload["run_at"])
+        id
+      end
+    end
+
+    # Subclasses implement this.
+    def perform(*)
+      raise NotImplementedError, "#{self.class.name}#perform is not implemented"
+    end
+
+    # Set by the executor for the running job.
+    attr_accessor :job_id, :attempt
+  end
+
+  module Jobs
+    # Validates and converts arguments to/from their JSON form.
+    module Arguments
+      module_function
+
+      def dump(args) = args.map { |arg| dump_value(arg, "argument") }
+
+      def load(json) = json
+
+      def dump_value(value, path)
+        case value
+        when String, Integer, true, false, nil then value
+        when Float then value.finite? ? value : invalid(value, path)
+        when Symbol then value.name
+        when Array then value.each_with_index.map { |v, i| dump_value(v, "#{path}[#{i}]") }
+        when Hash
+          value.to_h do |key, v|
+            invalid(key, "#{path} key") unless key.is_a?(String) || key.is_a?(Symbol)
+            [key.to_s, dump_value(v, "#{path}[#{key.inspect}]")]
+          end
+        else invalid(value, path)
+        end
+      end
+
+      def invalid(value, path)
+        hint = value.respond_to?(:pk) || value.respond_to?(:id) ? " — pass its id instead" : ""
+        raise SerializationError, "#{path} #{value.class} can't be serialized to JSON#{hint}"
+      end
+    end
+  end
+end

data/lib/gemstack/jobs/adapters/async.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Jobs
+    module Adapters
+      # An in-process thread pool with an in-memory schedule (retries and
+      # `set(wait:)` work). Jobs are lost when the process exits, so it is
+      # meant for development and apps without a database — use :postgres
+      # or :sidekiq in production.
+      class Async
+        include AfterCommit
+
+        Entry = Struct.new(:run_at, :sequence, :payload)
+
+        def initialize(concurrency: Jobs.config.concurrency)
+          @concurrency = concurrency
+          @entries = []
+          @mutex = Mutex.new
+          @available = ConditionVariable.new
+          @sequence = 0
+          @running = 0
+          @threads = nil
+        end
+
+        def enqueue(payload)
+          id = SecureRandom.uuid
+          after_commit { schedule(payload.merge("id" => id, "attempts" => 0), payload["run_at"] || Time.now) }
+          id
+        end
+
+        # Blocks until no jobs are queued or running (mainly for tests).
+        def drain(timeout: 10)
+          deadline = monotonic + timeout
+          sleep 0.01 until @mutex.synchronize { @entries.empty? && @running.zero? } || monotonic > deadline
+        end
+
+        def shutdown
+          @mutex.synchronize do
+            @stopping = true
+            @available.broadcast
+          end
+          @threads&.each { |thread| thread.join(Jobs.config.shutdown_timeout) }
+          @threads = nil
+        end
+
+        private
+
+        def schedule(payload, run_at)
+          worker_threads
+          @mutex.synchronize do
+            @sequence += 1
+            @entries << Entry.new(run_at, @sequence, payload)
+            @entries.sort_by! { |e| [e.run_at, e.payload["priority"] || 100, e.sequence] }
+            @available.broadcast
+          end
+        end
+
+        # Started lazily on the first job; shutdown joins them.
+        def worker_threads
+          @mutex.synchronize do
+            @threads ||= Array.new(@concurrency) { Thread.new { work } } # rubocop:disable Naming/MemoizedInstanceVariableName
+          end
+        end
+
+        def work
+          loop do
+            entry = next_entry or break
+            outcome = Executor.execute(entry.payload)
+            schedule(entry.payload.merge("attempts" => outcome.attempt), outcome.run_at) if outcome.status == :retry
+          ensure
+            @mutex.synchronize { @running -= 1 } if entry
+          end
+        end
+
+        def next_entry
+          @mutex.synchronize do
+            loop do
+              return nil if @stopping
+
+              first = @entries.first
+              if first && first.run_at <= Time.now
+                @running += 1
+                return @entries.shift
+              end
+              @available.wait(@mutex, first ? [first.run_at - Time.now, 0.01].max : nil)
+            end
+          end
+        end
+
+        def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/gemstack/jobs/adapters/database.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Jobs
+    # The migration new apps get (and `gemstack jobs:install` writes). Kept
+    # as source text so the app owns a plain, readable migration while tests
+    # and the generator share one definition.
+    module Migration
+      SOURCE = <<~RUBY
+        # frozen_string_literal: true
+
+        # The GemStack job queue (docs/background-jobs.md), for PostgreSQL, MySQL and
+        # SQLite. Workers claim rows one at a time (FOR UPDATE SKIP LOCKED where the
+        # database has it); finished jobs are deleted, exhausted ones keep failed_at.
+        Sequel.migration do
+          up do
+            partial = database_type != :mysql # MySQL has no partial indexes
+            ready = partial ? { where: Sequel.lit("failed_at IS NULL AND locked_at IS NULL") } : {}
+            create_table(:gemstack_jobs) do
+              primary_key :id, type: :Bignum
+              String :queue, null: false, default: "default"
+              Integer :priority, null: false, default: 100
+              String :job_class, null: false
+              column :args, :jsonb, null: false # json on MySQL and SQLite
+              column :run_at, :timestamptz, null: false
+              Integer :attempts, null: false, default: 0
+              String :last_error, text: true
+              column :locked_at, :timestamptz
+              String :locked_by
+              column :failed_at, :timestamptz
+              column :created_at, :timestamptz, null: false
+
+              # The fetch query: ready jobs by queue, in priority/run_at order.
+              index %i[queue priority run_at id], name: :gemstack_jobs_ready, **ready
+              index :locked_at, name: :gemstack_jobs_locked
+              index :failed_at, name: :gemstack_jobs_failed
+            end
+          end
+
+          down do
+            drop_table(:gemstack_jobs)
+          end
+        end
+      RUBY
+
+      def self.apply(db, direction = :up)
+        Sequel.extension :migration
+        eval(SOURCE, TOPLEVEL_BINDING, "gemstack_jobs_migration.rb").apply(db, direction) # rubocop:disable Security/Eval
+      end
+    end
+
+    module Adapters
+      # The default adapter: jobs are rows in the application's database
+      # — PostgreSQL, MySQL or SQLite.
+      #
+      # - Enqueueing is an INSERT on the current connection, so inside
+      #   GemStack.transaction a job exists only if the transaction commits.
+      # - Workers claim one job at a time in a short transaction: with
+      #   FOR UPDATE SKIP LOCKED on PostgreSQL and MySQL 8, so workers never
+      #   block each other; on SQLite by taking the write lock up front.
+      # - PostgreSQL also NOTIFYs idle workers at once; elsewhere (and as a
+      #   safety net) workers poll every config.jobs.poll_interval.
+      # - Times are set from Ruby, in UTC, so the database clock and time zone
+      #   never matter.
+      class Database
+        CHANNEL = "gemstack_jobs"
+
+        def initialize(db: nil, table: Jobs.config.table)
+          @db = db
+          @table = table
+        end
+
+        def db
+          @db || begin
+            require "gemstack/db"
+            GemStack::DB.connection
+          end
+        end
+
+        def dataset = db[@table]
+        def postgres? = db.database_type == :postgres
+
+        def enqueue(payload)
+          now = Time.now
+          args = postgres? ? Sequel.pg_jsonb_wrap(payload["args"]) : JSON.generate(payload["args"])
+          id = dataset.insert(job_class: payload["job_class"], queue: payload["queue"], priority: payload["priority"],
+                              args: args, run_at: payload["run_at"] || now, created_at: now)
+          db.notify(CHANNEL, payload: payload["queue"]) if postgres?
+          id
+        end
+
+        # Claims the next ready job for these queues ("*" = all). Returns a
+        # payload Hash or nil.
+        def claim(queues, worker)
+          now = Time.now
+          db.transaction(**claim_options) do
+            ready = dataset.where(failed_at: nil, locked_at: nil).where { run_at <= now }
+            ready = ready.where(queue: queues) unless queues.include?("*")
+            ready = ready.order(:priority, :run_at, :id).limit(1)
+            ready = ready.for_update.skip_locked if ready.supports_skip_locked?
+            row = ready.select(*returned_columns).first
+            dataset.where(id: row[:id]).update(locked_at: now, locked_by: worker) if row
+            row && payload_for(row)
+          end
+        end
+
+        def complete(id) = dataset.where(id: id).delete
+
+        def reschedule(id, run_at:, attempts:, error:)
+          dataset.where(id: id).update(locked_at: nil, locked_by: nil, run_at: run_at, attempts: attempts,
+                                       last_error: describe(error))
+        end
+
+        def fail(id, attempts:, error:)
+          return complete(id) unless Jobs.config.keep_failed
+
+          dataset.where(id: id).update(locked_at: nil, locked_by: nil, failed_at: Time.now,
+                                       attempts: attempts, last_error: describe(error))
+        end
+
+        # Releases this worker's claimed jobs (graceful shutdown).
+        def release(worker) = dataset.where(locked_by: worker).update(locked_at: nil, locked_by: nil)
+
+        # Releases jobs locked longer than `timeout` seconds (their worker died).
+        def release_stale(timeout)
+          cutoff = Time.now - Float(timeout)
+          dataset.where { locked_at < cutoff }.update(locked_at: nil, locked_by: nil)
+        end
+
+        # Failed jobs back to the queue: all, or the given ids.
+        def retry_failed(ids = nil)
+          failed = dataset.exclude(failed_at: nil)
+          failed = failed.where(id: ids) if ids
+          failed.update(failed_at: nil, attempts: 0, run_at: Time.now, last_error: nil)
+        end
+
+        def discard_failed(ids = nil)
+          failed = dataset.exclude(failed_at: nil)
+          failed = failed.where(id: ids) if ids
+          failed.delete
+        end
+
+        def failed(limit: 20)
+          dataset.exclude(failed_at: nil).order(Sequel.desc(:failed_at)).limit(limit)
+                 .select(:id, :queue, :job_class, :attempts, :failed_at, :last_error).all
+        end
+
+        # { "default" => { ready:, scheduled:, running:, failed: }, ... }
+        def stats
+          now = Time.now
+          states = Sequel.case(
+            [[Sequel.~(failed_at: nil), "failed"], [Sequel.~(locked_at: nil), "running"],
+             [Sequel[:run_at] > now, "scheduled"]], "ready"
+          )
+          dataset.group_and_count(:queue, states.as(:state)).all.each_with_object({}) do |row, result|
+            (result[row[:queue]] ||= { ready: 0, scheduled: 0, running: 0, failed: 0 })[row[:state].to_sym] =
+              row[:count]
+          end
+        end
+
+        private
+
+        # SQLite: take the write lock when the transaction starts, so two
+        # workers can't both read the same ready row.
+        def claim_options = db.database_type == :sqlite ? { mode: :immediate } : {}
+
+        # args as text, parsed with the json gem: jobs receive plain Hash/Array
+        # values rather than Sequel's JSONB wrappers. (Lazy: Sequel may not be loaded.)
+        def returned_columns
+          @returned_columns ||= [:id, :job_class, :queue, :priority, :attempts,
+                                 postgres? ? Sequel.cast(:args, :text).as(:args_json) : Sequel.as(:args, :args_json)]
+        end
+
+        def payload_for(row)
+          { "id" => row[:id], "job_class" => row[:job_class], "queue" => row[:queue],
+            "priority" => row[:priority], "args" => JSON.parse(row[:args_json].to_s), "attempts" => row[:attempts] }
+        end
+
+        def describe(error)
+          "#{error.class}: #{error.message}\n#{Array(error.backtrace).first(20).join("\n")}"[0, 10_000]
+        end
+      end
+
+      # The adapter's name before it supported MySQL and SQLite; `adapter: :postgres` still works.
+      Postgres = Database
+    end
+  end
+end

data/lib/gemstack/jobs/adapters/inline.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Jobs
+    module Adapters
+      # Runs jobs immediately, in the caller's thread, ignoring schedules and
+      # retries. Errors propagate, so nothing is silently swallowed. Handy for
+      # scripts and debugging.
+      class Inline
+        def enqueue(payload)
+          id = SecureRandom.uuid
+          job = Executor.resolve(payload["job_class"]).new
+          job.job_id = id
+          job.attempt = 1
+          job.perform(*Arguments.load(payload["args"]))
+          id
+        end
+      end
+
+      # Defers a block until the surrounding database transaction commits
+      # (when gemstack/db is loaded), so a job never runs before — or without —
+      # the data it depends on. The :postgres adapter gets this for free by
+      # inserting into the same transaction.
+      module AfterCommit
+        def after_commit(&)
+          db = defined?(GemStack::DB) && GemStack::DB.connected? ? GemStack::DB.connection : nil
+          return yield unless db&.in_transaction?
+
+          db.after_commit(&)
+        end
+      end
+    end
+  end
+end

data/lib/gemstack/jobs/adapters/sidekiq.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Jobs
+    module Adapters
+      # Runs GemStack jobs on Sidekiq (for teams already running Redis +
+      # Sidekiq). Add `gem "sidekiq"`, set `config.jobs.adapter = :sidekiq`,
+      # and run `bundle exec sidekiq -r ./config/sidekiq.rb` (see docs/background-jobs.md).
+      #
+      # GemStack's executor still decides retries and discards, so job
+      # classes behave identically on every adapter; Sidekiq's own retries
+      # are off and exhausted jobs go to Sidekiq's Dead set.
+      class Sidekiq
+        include AfterCommit
+
+        def initialize
+          require "sidekiq"
+          Runner.define!
+        rescue LoadError
+          raise ConfigurationError, 'the :sidekiq job adapter needs `gem "sidekiq"` in the Gemfile'
+        end
+
+        def enqueue(payload)
+          jid = SecureRandom.hex(12)
+          after_commit { Runner.push(payload.merge("attempts" => 0), jid: jid) }
+          jid
+        end
+
+        # The Sidekiq job class that executes GemStack payloads.
+        module Runner
+          module_function
+
+          def define!
+            return if defined?(GemStack::Jobs::SidekiqRunner)
+
+            klass = Class.new do
+              include ::Sidekiq::Job
+
+              sidekiq_options retry: 0 # exhausted jobs → Dead set; GemStack schedules retries itself
+
+              def perform(payload)
+                payload = payload.merge("id" => jid)
+                outcome = Executor.execute(payload)
+                case outcome.status
+                when :retry then Runner.push(payload.merge("attempts" => outcome.attempt), at: outcome.run_at)
+                when :failed then raise outcome.error
+                end
+              end
+            end
+            GemStack::Jobs.const_set(:SidekiqRunner, klass)
+          end
+
+          def push(payload, at: nil, jid: nil)
+            item = { "class" => GemStack::Jobs::SidekiqRunner, "queue" => payload["queue"],
+                     "args" => [payload.except("run_at", "id")] }
+            item["jid"] = jid if jid
+            run_at = at || payload["run_at"]
+            item["at"] = run_at.to_f if run_at
+            ::Sidekiq::Client.push(item)
+          end
+        end
+      end
+    end
+  end
+end