cogworker 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5aad05a1deaf85505c91f0b6ebe11199fc918b6b3e3831efa5ddb753381cf824
+  data.tar.gz: 760b88ec2cc3075f4bbfe152062bc8f1e24b71ce2c71984f9702c0cbdb7da81f
+SHA512:
+  metadata.gz: fc050c6eff33d2fcc5f61629d46e88452912d3f798c49b49fdc53d21ca525403a575e89e13c9e34307cba312eab7307baebc80a187661a032592fb31eb797854
+  data.tar.gz: a9ef2e674633abe4085b6e6e21eb74c3ec735b3ab7c4f6305f274172049e41058477b03e5a5e8105cc6b0afdeadcafc9babba07bbdd81855b54532585a9a946e

data/exe/cogworker

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'cogworker'
+
+Cogworker::CLI.new.run(ARGV)

data/exe/cogworkerswarm

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'cogworker'
+
+Cogworker::Swarm.new(ARGV).run

data/lib/cogworker/basic_fetch.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Cogworker
+  # Pops jobs off Redis lists. Queue names repeated in the process's queue
+  # list represent weight; since BRPOP itself scans its key list
+  # strictly left-to-right, weighting is implemented by shuffling the
+  # (already-expanded, so repeats survive) key list before every fetch cycle
+  # — the more often a name appears, the more likely it lands first.
+  class BasicFetch
+    TIMEOUT = 2 # seconds; also how often a stopped/quieted processor notices and exits its fetch loop.
+
+    def initialize(queues)
+      @queue_keys = Array(queues).map { |q| RedisKeys.queue(q) }
+    end
+
+    def retrieve_work
+      keys = @queue_keys.shuffle
+      result = Cogworker.config.redis { |c| c.brpop(*keys, timeout: TIMEOUT) }
+      return nil unless result
+
+      queue_key, raw_job = result
+      UnitOfWork.new(queue_key.delete_prefix(RedisKeys::QUEUE_PREFIX), raw_job)
+    end
+
+    UnitOfWork = Struct.new(:queue, :raw_job)
+  end
+end

data/lib/cogworker/cli.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+module Cogworker
+  # Shared flag parsing + boot sequence for both the single-process and
+  # swarm-child entry points: `-e/--environment`, `-c/--concurrency`,
+  # `-r/--require <file>`, `-C/--config <file>`, `-L/--logfile <file>`,
+  # `-q/--queue <name>[,<weight>]` (repeatable).
+  class CLI
+    def self.parse(argv)
+      options = { queues: [], require_path: nil, environment: ENV['APP_ENV'] || ENV['RACK_ENV'] || 'development' }
+
+      OptionParser.new do |o|
+        o.on('-e ENV', '--environment ENV') { |v| options[:environment] = v }
+        o.on('-c INT', '--concurrency INT', Integer) { |v| options[:concurrency] = v }
+        o.on('-r PATH', '--require PATH') { |v| options[:require_path] = v }
+        o.on('-C PATH', '--config PATH') { |v| options[:config_path] = v }
+        o.on('-L PATH', '--logfile PATH') { |v| options[:logfile] = v }
+        o.on('-q QUEUE', '--queue QUEUE') { |v| options[:queues].concat(parse_queue_weight(v)) }
+      end.parse!(argv.dup)
+
+      options
+    end
+
+    def self.parse_queue_weight(value)
+      name, weight = value.split(',')
+      Array.new([weight.to_i, 1].max, name)
+    end
+
+    # Boots one OS process fully: applies config, requires app code, and
+    # blocks running the Launcher loop until a stop signal is handled.
+    # `argv` is parsed independently per call so a swarm parent can boot each
+    # forked child with the exact same flags it was started with.
+    def run(argv)
+      options = self.class.parse(argv)
+      file_config = ConfigLoader.load(options[:config_path])
+
+      Cogworker.server_process!
+      Cogworker.config.concurrency = options[:concurrency] || file_config[:concurrency]&.to_i || Cogworker.config.concurrency
+      Cogworker.config.queues = options[:queues].any? ? options[:queues] : (file_config[:queues] || Cogworker.config.queues)
+
+      redirect_logfile(options[:logfile]) if options[:logfile]
+      require_app_code(options[:require_path]) if options[:require_path]
+
+      Launcher.new.run
+    end
+
+    private
+
+    def redirect_logfile(path)
+      Cogworker.logger = Logging.default_logger(File.open(path, 'a'))
+    end
+
+    def require_app_code(path)
+      expanded = File.expand_path(path)
+      if File.directory?(expanded)
+        require File.join(expanded, 'config/environment')
+      else
+        require expanded
+      end
+    end
+  end
+end

data/lib/cogworker/client.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Cogworker
+  # Enqueues jobs: normalizes the job hash, runs the client middleware
+  # chain, then pushes onto the target queue or schedule ZSET.
+  class Client
+    class << self
+      # Cogworker::Client.push(hash) — the single funnel every enqueue path
+      # (perform_async/perform_in/perform_at, and direct calls) goes through.
+      def push(item)
+        job = JobUtil.normalize_item(item)
+        queue = job['queue']
+
+        Cogworker.config.client_chain.invoke(job['class'], job, queue, Cogworker.config.redis_pool) do
+          dispatch(job)
+        end
+
+        # UniqueJobs::ClientMiddleware sets this when the job was a
+        # duplicate of an already-enqueued/running `unique: :until_executed`
+        # job and never actually reached `dispatch` — nil signals "nothing
+        # was pushed", same as `job['jid']` would be meaningless otherwise.
+        job['unique_skipped'] ? nil : job['jid']
+      end
+
+      def push_bulk(items)
+        items.map { |item| push(item) }
+      end
+
+      private
+
+      # Testing.fake?/.inline? divert the enqueue entirely; both still ran
+      # the client middleware chain above them in #push, same as the real
+      # push would.
+      def dispatch(job)
+        if Testing.fake?
+          Testing.jobs_for(job['class']) << job
+        elsif Testing.inline?
+          Testing.perform_inline(job)
+        else
+          raw_push(job)
+        end
+      end
+
+      def raw_push(job)
+        Cogworker.config.redis do |conn|
+          if job['at']
+            conn.zadd(RedisKeys::SCHEDULE, job['at'].to_f, JSON.generate(job))
+          else
+            job['enqueued_at'] = Time.now.to_f
+            conn.multi do |pipeline|
+              pipeline.sadd(RedisKeys::QUEUES, job['queue'])
+              pipeline.lpush(RedisKeys.queue(job['queue']), JSON.generate(job))
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cogworker/component.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Cogworker
+  # Mixin giving any class `#identity`/`#logger`, delegating to the
+  # process-global `Cogworker.identity`/`Cogworker.logger`. Deliberately global
+  # (not instance-scoped config injection): each OS process — including every
+  # cogworkerswarm child — has exactly one Cogworker::Config, so a singleton-backed
+  # mixin is sufficient and keeps `include Cogworker::Component` usable with zero
+  # wiring, as existing custom middleware (e.g. WorkerKiller) expects.
+  module Component
+    def identity
+      Cogworker.identity
+    end
+
+    def logger
+      Cogworker.logger
+    end
+  end
+end

data/lib/cogworker/config.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Cogworker
+  # Process-global configuration, built once and mutated in place by
+  # (possibly several, per the real init code) `configure_server`/
+  # `configure_client` calls, so every block sees and extends the same
+  # server/client middleware chains.
+  class Config
+    attr_reader :server_chain, :client_chain, :periodic_manager, :redis_options
+    attr_accessor :concurrency, :queues, :periodic_catch_up, :unique_lock_ttl
+
+    def initialize
+      @server_chain = Middleware::Chain.new
+      @client_chain = Middleware::Chain.new
+      @periodic_manager = Periodic::Manager.new
+      @redis_options = {}
+      @concurrency = 10
+      @queues = ['default']
+      # Default true: an entry's most-recently-due slot fires immediately on
+      # a process's first tick, same as always. Set to false to skip that
+      # one-time catch-up fire instead — see Periodic::Ticker#priming_first_slot?
+      # for why a cold start against an empty/reset Redis otherwise fires
+      # every registered entry at once.
+      @periodic_catch_up = true
+      # Safety-net TTL (seconds) on a regular `unique: :until_executed`
+      # job's lock — `UniqueJobs::ReleaseMiddleware` is what actually clears
+      # it on success/terminal failure; this only bounds how long a lock
+      # can stay stuck if a process dies mid-job before that ever runs
+      # (same class of gap as a crashed process losing its in-flight job
+      # generally — see the Status section of CLAUDE.md). 24h by default;
+      # set higher/lower to match how long a unique job might legitimately
+      # run plus however long its retries can take.
+      @unique_lock_ttl = 24 * 60 * 60
+      register_default_middleware
+    end
+
+    def redis=(options)
+      @redis_options = options
+    end
+
+    def redis_pool
+      @redis_pool ||= RedisConnection.create(@redis_options.merge(size: concurrency + 5))
+    end
+
+    def redis(&block)
+      pool = redis_pool
+      if block_given?
+        pool.with(&block)
+      else
+        pool
+      end
+    end
+
+    def server_middleware
+      yield server_chain if block_given?
+      server_chain
+    end
+
+    def client_middleware
+      yield client_chain if block_given?
+      client_chain
+    end
+
+    # `config.periodic(&PERIODIC_JOBS)` — the block receives the manager and
+    # registers cron entries synchronously as it runs. No-op-safe: an app
+    # that never calls this simply has an empty periodic_manager, and the
+    # Ticker (started later, per process) has nothing to do.
+    def periodic(&block)
+      block&.call(periodic_manager)
+      periodic_manager
+    end
+
+    private
+
+    # Always present, regardless of whether config.periodic/a unique job is
+    # ever used — each is a no-op for a job that doesn't carry its own
+    # marker (`periodic_pjid`/`unique: :until_executed`).
+    def register_default_middleware
+      @server_chain.add(Periodic::ReleaseMiddleware)
+      @client_chain.add(UniqueJobs::ClientMiddleware)
+      @server_chain.add(UniqueJobs::ReleaseMiddleware)
+    end
+  end
+end

data/lib/cogworker/config_loader.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'erb'
+
+module Cogworker
+  # Loads the process config file (`:concurrency:`/`:queues:` YAML, symbol
+  # keys, ERB-interpolated before parsing — e.g. `<%= ENV["CONCURRENCY"] %>`).
+  # A queue name repeated in `:queues:` is weight, not a duplicate: the
+  # repetition survives untouched here and is what BasicFetch's per-cycle
+  # shuffle uses to weight fetches.
+  module ConfigLoader
+    module_function
+
+    def load(path)
+      return {} unless path
+
+      erb_result = ERB.new(File.read(path)).result
+      YAML.safe_load(erb_result, permitted_classes: [Symbol], aliases: true) || {}
+    end
+  end
+end

data/lib/cogworker/heartbeat.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'redis'
+
+module Cogworker
+  # Publishes this process's presence (for ProcessSet) and listens for
+  # remote quiet!/stop! requests (for Process#quiet!/#stop! issued by another
+  # process, e.g. a self-targeting WorkerKiller or the Web UI). Both the
+  # heartbeat loop and the pub/sub subscriber must only start *after* a
+  # cogworkerswarm fork, never before, in the parent — otherwise the thread
+  # simply doesn't exist in the child, and a lock that thread held could
+  # leave the child permanently deadlocked.
+  class Heartbeat
+    INTERVAL = 5
+    TTL = 60
+
+    def initialize(manager)
+      @manager = manager
+    end
+
+    def start!
+      @stopping = false
+      @beat_thread = Thread.new { beat_loop }
+      @signal_thread = Thread.new { subscribe_loop }
+    end
+
+    # Tears down both background threads, not just the Redis keys — leaving
+    # them running would leak a thread (and a dedicated pub/sub connection)
+    # per Heartbeat instance for the remaining life of the process.
+    def stop!
+      @stopping = true
+      @beat_thread&.kill
+      @subscribe_client&.unsubscribe
+      @signal_thread&.kill
+      cleanup_presence!
+    rescue StandardError
+      nil
+    end
+
+    private
+
+    def cleanup_presence!
+      Cogworker.config.redis do |c|
+        c.del(RedisKeys.process(Cogworker.identity), RedisKeys.workers(Cogworker.identity))
+        c.srem(RedisKeys::PROCESSES, Cogworker.identity)
+      end
+    end
+
+    def beat_loop
+      loop do
+        beat
+        sleep(INTERVAL)
+      end
+    rescue StandardError => e
+      Cogworker.logger.error { "Heartbeat died: #{e.class}: #{e.message}" }
+    end
+
+    def beat
+      identity = Cogworker.identity
+      info = {
+        'hostname' => Cogworker.hostname,
+        'pid' => ::Process.pid,
+        'concurrency' => Cogworker.config.concurrency,
+        'queues' => @manager.queues,
+        'started_at' => (@started_at ||= Time.now.to_f),
+        'rss_kb' => current_rss_kb
+      }
+
+      Cogworker.config.redis do |c|
+        c.sadd(RedisKeys::PROCESSES, identity)
+        c.hset(RedisKeys.process(identity),
+               'info', JSON.generate(info),
+               'busy', @manager.busy_count.to_s,
+               'quiet', @manager.quiet?.to_s)
+        c.expire(RedisKeys.process(identity), TTL)
+        c.expire(RedisKeys.workers(identity), TTL)
+      end
+    end
+
+    # Current resident set size, in KB — read straight from the kernel
+    # (`/proc/self/status`, present on any real Linux deployment target)
+    # when available, since that's a plain file read with no extra process;
+    # `ps` (a real fork+exec every heartbeat) is only the fallback for
+    # platforms without `/proc` (macOS in local dev). `nil` — not `0` — on
+    # any failure, so the Web UI can render "n/a" rather than a misleading
+    # "0M" if this ever can't be measured.
+    def current_rss_kb
+      proc_status = '/proc/self/status'
+      if File.readable?(proc_status)
+        matched = File.read(proc_status)[/^VmRSS:\s+(\d+)\s+kB/, 1]
+        return matched.to_i if matched
+      end
+
+      out = `ps -o rss= -p #{::Process.pid} 2>/dev/null`.strip
+      out.empty? ? nil : out.to_i
+    rescue StandardError
+      nil
+    end
+
+    # Uses its own dedicated (non-pooled) Redis client: SUBSCRIBE blocks the
+    # connection for as long as the subscription is open, which would starve
+    # the shared job-execution pool if it borrowed a connection from there.
+    def subscribe_loop
+      @subscribe_client = ::Redis.new(RedisConnection.client_options(Cogworker.config.redis_options))
+      @subscribe_client.subscribe(RedisKeys.signal(Cogworker.identity)) do |on|
+        on.message do |_channel, message|
+          dispatch(message)
+        end
+      end
+    rescue StandardError => e
+      return if @stopping
+
+      Cogworker.logger.error { "Signal subscriber died: #{e.class}: #{e.message}" }
+      sleep(1)
+      retry
+    end
+
+    def dispatch(message)
+      case message
+      when 'quiet' then @manager.quiet!
+      when 'stop' then remote_stop!
+      else Cogworker.logger.warn { "Unknown signal message: #{message}" }
+      end
+    end
+
+    # A *remote* stop (published by another process — typically the Web
+    # UI's `Process#stop!` — as opposed to this process's own `TERM`/`INT`,
+    # handled by `Launcher#stop!`/`#watch_signals` on the main thread) has
+    # to actually end this OS process, not just quiesce the Manager
+    # forever: nothing here naturally returns from a running `Launcher#run`
+    # loop the way breaking out of `watch_signals` does — this dispatch
+    # runs on the pub/sub subscriber's own background thread, so without an
+    # explicit exit the process would otherwise sit there, still
+    # heartbeating, permanently "quiet", never picking up work again,
+    # until someone `kill`s it for real or the swarm is restarted.
+    # `::Process.exit!` (not `Kernel#exit`, which only raises `SystemExit`
+    # on the *calling* thread and wouldn't actually end the process from
+    # here) terminates immediately and unconditionally, from any thread —
+    # deliberately *after* `@manager.stop!` has already drained in-flight
+    # work and `cleanup_presence!` has already removed this process from
+    # Redis, so both happen before the process can vanish out from under
+    # them.
+    def remote_stop!
+      @manager.stop!
+      cleanup_presence!
+      ::Process.exit!(true)
+    end
+  end
+end

data/lib/cogworker/history/middleware.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Cogworker
+  module History
+    # Server middleware: times every run and records it via Storage,
+    # success or failure, regardless of what other middleware/worker code does.
+    class Middleware
+      def call(_worker, job, queue)
+        started_at = Time.now.to_f
+        yield
+        Storage.record(job, queue, started_at, Time.now.to_f, 'success')
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        Storage.record(job, queue, started_at, Time.now.to_f, 'failed', error: e)
+        raise e
+      end
+    end
+  end
+end

data/lib/cogworker/history/storage.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Cogworker
+  module History
+    # Three parallel ZSETs (score = finished_at), so any of the three
+    # filters (all/success/failed) is a plain `ZREVRANGE` — no per-request
+    # `ZUNIONSTORE`/scan needed. Each is trimmed to `History.max_entries`
+    # independently on every write, oldest first.
+    module Storage
+      LIST_KEYS = {
+        'all' => 'cogworker:history:all',
+        'success' => 'cogworker:history:success',
+        'failed' => 'cogworker:history:failed'
+      }.freeze
+
+      module_function
+
+      def record(job, queue, started_at, finished_at, status, error: nil)
+        entry = {
+          'jid' => job['jid'], 'class' => job['class'], 'queue' => queue, 'args' => job['args'],
+          'status' => status, 'started_at' => started_at, 'finished_at' => finished_at
+        }
+        if error
+          entry['error_class'] = error.class.name
+          entry['error_message'] = error.message.to_s[0, 10_000]
+          entry['backtrace'] = (error.backtrace || []).first(200)
+        end
+
+        raw = JSON.generate(entry)
+        max = Cogworker::History.max_entries
+        Cogworker.config.redis do |c|
+          write_and_trim(c, LIST_KEYS.fetch('all'), raw, finished_at, max)
+          write_and_trim(c, LIST_KEYS.fetch(status), raw, finished_at, max)
+        end
+      end
+
+      # Newest-first page of `count`/`status` entries: `[entries, total]`.
+      def page(status, page_number, per_page)
+        key = LIST_KEYS.fetch(status, LIST_KEYS.fetch('all'))
+        start = [(page_number - 1), 0].max * per_page
+        stop = start + per_page - 1
+
+        Cogworker.config.redis do |c|
+          total = c.zcard(key)
+          raw_entries = c.zrevrange(key, start, stop)
+          [raw_entries.map { |raw| JSON.parse(raw) }, total]
+        end
+      end
+
+      def write_and_trim(conn, key, raw, score, max)
+        conn.zadd(key, score, raw)
+        conn.zremrangebyrank(key, 0, -(max + 1))
+      end
+
+      # Success/failed counts per UTC calendar day, for the last `days` days
+      # (today included) — `{ 'YYYY-MM-DD' => { 'success' => n, 'failed' => n } }`,
+      # a day with no entries simply absent from the Hash. Reads the shared
+      # "all" list once (rather than "success" and "failed" separately) since
+      # every entry already carries its own `status`. Bucketing uses UTC,
+      # not the viewer's browser timezone (unlike `Layout.time_tag`
+      # elsewhere) — this is a server-rendered daily aggregate, not a single
+      # instant, so there's no one "browser day" to convert into.
+      # Same caveat as any other read of this list: only entries still
+      # within `History.max_entries` are counted, so a very busy queue's
+      # oldest requested days may already have been trimmed away.
+      def daily_counts(days)
+        since = Time.now.to_f - (days * 86_400)
+        Cogworker.config.redis do |c|
+          c.zrangebyscore(LIST_KEYS.fetch('all'), since, '+inf').each_with_object({}) do |raw, counts|
+            entry = JSON.parse(raw)
+            day = Time.at(entry['finished_at']).utc.strftime('%Y-%m-%d')
+            bucket = (counts[day] ||= { 'success' => 0, 'failed' => 0 })
+            bucket[entry['status']] += 1 if bucket.key?(entry['status'])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cogworker/history.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Cogworker
+  # Execution history: every job run (success and failure alike) is recorded
+  # with its full args, timing, and — on failure — error class/message/
+  # backtrace. Distinct from the Status layer (`Cogworker::Status`), which
+  # tracks *current* per-jid state with a TTL; History is an append-only,
+  # length-capped log meant for browsing/auditing past runs.
+  module History
+    DEFAULT_MAX_ENTRIES = 1000
+
+    class << self
+      # How many entries are retained (oldest trimmed first), independently
+      # for the "all", "success", and "failed" lists — read fresh on every
+      # write, so changing it takes effect immediately, no need to rebuild
+      # the middleware chain. Configurable via
+      # `configure_server_middleware(config, max_entries: N)`, or directly:
+      # `Cogworker::History.max_entries = 5000`.
+      attr_writer :max_entries
+
+      def max_entries
+        @max_entries ||= DEFAULT_MAX_ENTRIES
+      end
+    end
+
+    module_function
+
+    def configure_server_middleware(config, max_entries: DEFAULT_MAX_ENTRIES)
+      self.max_entries = max_entries
+      config.server_middleware { |chain| chain.add(Middleware) }
+    end
+  end
+end

data/lib/cogworker/job.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Cogworker
+  # `include Cogworker::Worker` (alias `Cogworker::Job`) DSL.
+  module Job
+    def self.included(base)
+      base.include(Component)
+      base.extend(ClassMethods)
+      base.include(InstanceMethods)
+    end
+
+    # `cogworker_options`/`perform_async`/`perform_in`/`perform_at`, extended
+    # onto the including class.
+    module ClassMethods
+      # Accepts a plain Hash (both `key: value` and `:key => value` call-site
+      # syntax already collect into the same Hash literal in Ruby — nothing
+      # special to implement). Merges into the class's option set rather than
+      # replacing it, and never filters keys: arbitrary custom options (e.g.
+      # `lock_run: :while_executing`) ride along unchanged into the job hash.
+      def cogworker_options(opts = {})
+        cogworker_options_hash.merge!(opts.transform_keys(&:to_sym))
+        cogworker_options_hash
+      end
+
+      def cogworker_options_hash
+        @cogworker_options_hash ||= if superclass.respond_to?(:cogworker_options_hash)
+                                      superclass.cogworker_options_hash.dup
+                                    else
+                                      {}
+                                    end
+      end
+
+      def perform_async(*args)
+        Client.push(job_payload('args' => args))
+      end
+
+      def perform_in(interval, *args)
+        ts = interval_to_ts(interval)
+        Client.push(job_payload('args' => args, 'at' => ts))
+      end
+      alias perform_at perform_in
+
+      # `SomeJob.jobs`/`SomeJob.clear` — reads/clears this class's entries in
+      # `Cogworker::Testing`'s fake queue (empty outside `Testing.fake!`).
+      def jobs
+        Testing.jobs_for(name)
+      end
+
+      def clear
+        Testing.jobs_for(name).clear
+      end
+
+      private
+
+      def job_payload(extra)
+        cogworker_options_hash.transform_keys(&:to_s).merge('class' => name).merge(extra)
+      end
+
+      def interval_to_ts(interval)
+        numeric = interval.respond_to?(:to_f) ? interval.to_f : interval.to_time.to_f
+        # A value below a billion is treated as "seconds from now"
+        # (perform_in), anything
+        # at or above it as an absolute unix timestamp (perform_at, or a
+        # Time passed straight through — Time#to_f is already an epoch
+        # timestamp, always well above the threshold).
+        numeric < 1_000_000_000 ? Time.now.to_f + numeric : numeric
+      end
+    end
+
+    # `jid`, included onto the including class's instances.
+    module InstanceMethods
+      attr_accessor :jid
+    end
+  end
+end