stampeded 0.3.1-aarch64-linux-gnu

data/lib/stampeded/continuable_ext.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Stampeded
+  module ContinuableExt
+    PROGRESS_EVERY = 1.0
+
+    def checkpoint!
+      stampeded_save_progress(force: queue_adapter.stopping?) if Current.context
+      super
+    end
+
+    private
+
+    def resume_job(exception)
+      return super unless Current.context
+
+      stampeded_save_progress(force: true)
+      raise exception unless exception.is_a?(ActiveJob::Continuation::Interrupt)
+
+      if max_resumptions && resumptions >= max_resumptions
+        raise ActiveJob::Continuation::ResumeLimitError, "Job was resumed a maximum of #{max_resumptions} times"
+      end
+
+      raise Requeue, exception.message
+    end
+
+    def stampeded_save_progress(force:)
+      progress = continuation.to_h
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      fresh = progress["completed"] == @stampeded_saved_steps && now - (@stampeded_saved_at || -PROGRESS_EVERY) < PROGRESS_EVERY
+      return if fresh && !force
+
+      Current.context.checkpoint!("activejob" => { "continuation" => progress, "resumptions" => resumptions })
+      @stampeded_saved_steps = progress["completed"]
+      @stampeded_saved_at = now
+    end
+  end
+end
+
+ActiveSupport.on_load(:active_job_continuable) { prepend Stampeded::ContinuableExt }

data/lib/stampeded/current.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Stampeded
+  module Current
+    KEY = :__stampeded_job_context
+
+    module_function
+
+    def context = Thread.current[KEY]
+
+    def with(context)
+      previous = Thread.current[KEY]
+      Thread.current[KEY] = context
+      yield
+    ensure
+      Thread.current[KEY] = previous
+    end
+  end
+end

data/lib/stampeded/daemon.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Stampeded
+  module Daemon
+    BINARY = "stampeded"
+
+    module_function
+
+    def platform
+      %i[cpu os].map { |m| Gem::Platform.local.public_send(m) }.join("-")
+    end
+
+    def executable
+      if (dir = ENV.fetch("STAMPEDED_INSTALL_DIR", nil))
+        path = File.expand_path(File.join(dir, BINARY))
+        raise DaemonNotFound, "STAMPEDED_INSTALL_DIR is set to #{dir}, but #{path} is not executable" \
+          unless File.executable?(path)
+
+        return path
+      end
+
+      path = bundled_path
+      return path if path && File.executable?(path)
+
+      raise DaemonNotFound, <<~MSG
+        Could not find the stampeded daemon: there is no build for #{platform}.
+        Build it and point at it:
+
+          cargo build --release --bin stampeded
+          export STAMPEDED_INSTALL_DIR=/path/to/stampeded/target/release
+
+        The daemon is OPTIONAL: without it jobs still run, with no scheduler,
+        reaper, pruner or dashboard.
+      MSG
+    end
+
+    def bundled_path
+      File.expand_path(File.join("../..", "libexec", BINARY), __dir__)
+    end
+
+    def available?
+      !executable.nil?
+    rescue DaemonNotFound
+      false
+    end
+
+    def exec!(*args)
+      Kernel.exec(executable, *args)
+    end
+  end
+end

data/lib/stampeded/envelope.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Stampeded
+  module Envelope
+    module_function
+
+    def tasks
+      @tasks ||= {}
+    end
+
+    def register(task, job_class)
+      name = task.to_s
+      raise ArgumentError, "a task name cannot be blank" if name.strip.empty?
+
+      owner = tasks[name]
+      if owner && owner != job_class.name
+        raise ArgumentError, "task #{name.inspect} is already #{owner}'s; #{job_class.name} cannot claim it too"
+      end
+
+      tasks[name] = job_class.name
+    end
+
+    def from_active_job(job)
+      task = job.class.try(:stampeded_task)
+      context = job.serialize.except("arguments", "provider_job_id")
+      kwargs = standard_arguments(job.arguments)
+
+      if kwargs
+        [task || job.class.name, kwargs, { "activejob" => context }]
+      elsif task
+        raise PortableArgumentsError.new(job.class.name, task)
+      else
+        context["arguments"] = ActiveJob::Arguments.serialize(job.arguments)
+        [job.class.name, {}, { "activejob" => context }]
+      end
+    end
+
+    def to_active_job_payload(id:, queue:, task:, args:, meta:, checkpoint: nil)
+      context = meta.fetch("activejob", {})
+      job_class = context["job_class"] || tasks[task] || task
+
+      arguments =
+        context.fetch("arguments") do
+          kwargs = args.transform_keys(&:to_sym)
+          kwargs.empty? ? [] : ActiveJob::Arguments.serialize([Hash.ruby2_keywords_hash(kwargs)])
+        end
+
+      context.merge(
+        "job_class" => job_class,
+        "job_id" => context["job_id"] || id,
+        "queue_name" => queue,
+        "arguments" => arguments,
+        "executions" => context["executions"] || 0,
+        "exception_executions" => context["exception_executions"] || {},
+        "enqueued_at" => context["enqueued_at"] || Time.now.utc.iso8601
+      ).merge(continuation(checkpoint))
+    end
+
+    def continuation(checkpoint)
+      return {} unless checkpoint.is_a?(Hash) && checkpoint["activejob"].is_a?(Hash)
+
+      checkpoint["activejob"].slice("continuation", "resumptions")
+    end
+
+    def standard_arguments(arguments)
+      return {} if arguments.empty?
+      return nil unless arguments.size == 1
+
+      kwargs = arguments.first
+      return nil unless kwargs.is_a?(Hash) && Hash.ruby2_keywords_hash?(kwargs)
+      return nil unless plain?(kwargs)
+
+      JSON.parse(JSON.generate(kwargs))
+    end
+
+    def plain?(value)
+      case value
+      when String, Integer, true, false, nil then true
+      when Float then value.finite?
+      when Array then value.all? { plain?(it) }
+      when Hash then value.all? { |k, v| (k.is_a?(String) || k.is_a?(Symbol)) && plain?(v) }
+      else false
+      end
+    end
+  end
+end

data/lib/stampeded/errors.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Stampeded
+  Error = Class.new(StandardError)
+
+  class RetryConflict < Error
+    def initialize(job_class)
+      super(<<~MSG)
+        #{job_class} declares `retry_on`; Stampeded owns retries:
+
+          class #{job_class} < ApplicationJob
+            stampeded max_attempts: 5, backoff_base_ms: 1_000, backoff_max_ms: 300_000
+          end
+
+        For a specific delay: raise Stampeded::RetryIn.new(seconds). `discard_on` is fine.
+      MSG
+    end
+  end
+
+  class PortableArgumentsError < Error
+    def initialize(job_class, task)
+      super(<<~MSG)
+        #{job_class} is task #{task.inspect}: pass keyword arguments with
+        plain JSON values (strings, numbers, booleans, nil, arrays, hashes),
+        ids rather than records, ISO 8601 strings rather than times:
+
+          #{job_class}.perform_later(document_id: document.id)
+      MSG
+    end
+  end
+
+  class DaemonNotFound < Error; end
+  class LibraryNotFound < Error; end
+  class SchemaMissing < Error
+    def initialize(cause = nil)
+      super(<<~MSG)
+        The Stampeded schema is not installed in this database.
+
+        In Rails:
+
+            bin/rails stampeded:install
+
+        Elsewhere:
+
+            Stampeded::Schema.install!
+
+        Postgres 18 or newer is required.
+        #{"\nUnderlying error: #{cause.message.lines.first&.strip}" if cause}
+      MSG
+    end
+  end
+
+  class UnknownTask < Error; end
+
+  class Requeue < Exception; end
+  class RetryIn < Error
+    attr_reader :seconds
+
+    def initialize(seconds, message = nil)
+      @seconds = Float(seconds)
+      raise ArgumentError, "RetryIn needs a non-negative delay, got #{seconds.inspect}" if @seconds.negative?
+
+      super(message || "retry in #{@seconds}s")
+    end
+
+    def delay_ms = (@seconds * 1000).round
+  end
+end

data/lib/stampeded/job.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module Stampeded
+  class Job
+    ATTRIBUTES = %w[
+      id queue task args meta state priority attempt max_attempts
+      interruptions max_interruptions deferrals max_deferrals
+      tenant_id destination dead_letter_queue expire_seconds
+      scheduled_at last_error failure_kind
+    ].freeze
+
+    attr_reader :row
+
+    def initialize(row, decoded: false)
+      @row = row
+      @decoded = decoded
+    end
+
+    def id       = row["id"]
+    def queue    = row["queue"]
+    def task     = row["task"]
+    def state    = row["state"]
+    def terminal?  = Lifecycle.terminal?(state)
+    def claimable? = Lifecycle.claimable?(state)
+
+    def available_events = Lifecycle.events_from(state)
+
+    def respond_to_missing?(name, include_private = false) = state_predicate?(name) || super
+
+    def method_missing(name, *args)
+      return super unless args.empty? && state_predicate?(name)
+
+      state.to_s == name.to_s.delete_suffix("?")
+    end
+    def attempt  = row["attempt"].to_i
+    def max_attempts = row["max_attempts"].to_i
+    def interruptions = row["interruptions"].to_i
+    def deferrals = row["deferrals"].to_i
+    def tenant_id = row["tenant_id"]
+    def destination = row["destination"]
+
+    def args
+      @args ||= decode(row["args"])
+    end
+
+    def meta
+      @meta ||= decode(row["meta"])
+    end
+
+    def checkpoint
+      return @checkpoint if defined?(@checkpoint)
+
+      raw = row["checkpoint"]
+      @checkpoint = raw.nil? ? nil : decode(raw)
+    end
+
+    def resumed? = !checkpoint.nil?
+
+    def checkpoint_seq = row["checkpoint_seq"].to_i
+    def attempts_remaining = [max_attempts - attempt, 0].max
+
+    def last_attempt? = attempts_remaining.zero?
+
+    def to_h = ATTRIBUTES.to_h { |a| [a, row[a]] }
+
+    def inspect
+      "#<Stampeded::Job #{id} #{queue}/#{task} attempt=#{attempt}/#{max_attempts}>"
+    end
+
+    private
+
+    def state_predicate?(name) = name.end_with?("?") && Lifecycle.states.include?(name.to_s.delete_suffix("?").to_sym)
+
+    def decode(value)
+      case value
+      when nil then {}
+      when String then @decoded ? value : JSON.parse(value)
+      else value
+      end
+    end
+  end
+end

data/lib/stampeded/job_context.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Stampeded
+  class JobContext
+    extend Forwardable
+    def_delegators :@job, :id, :queue, :task, :args, :meta, :attempt, :max_attempts,
+                   :attempts_remaining, :last_attempt?, :tenant_id, :destination,
+                   :checkpoint, :resumed?, :checkpoint_seq, :row
+
+    attr_reader :job, :worker_id
+
+    def initialize(job, worker_id)
+      @job = job
+      @worker_id = worker_id
+    end
+
+    def checkpoint!(state = nil, conn: nil, **rest)
+      state ||= rest
+      raise ArgumentError, "checkpoint! needs some state" if state.nil? || state.empty?
+
+      sql = "SELECT stampeded_checkpoint($1, $2, $3, $4, $5)"
+      params = [job.queue, job.id, worker_id, job.attempt, JSON.generate(state)]
+
+      seq =
+        if conn
+          conn.exec_params(sql, params)[0]["stampeded_checkpoint"]
+        else
+          Connection.with { |c| c.exec_params(sql, params)[0]["stampeded_checkpoint"] }
+        end
+
+      !seq.nil?
+    end
+
+    def steps
+      @steps ||= Steps.new(self)
+    end
+
+    def step(name, cursor: nil, &) = steps.step(name, cursor: cursor, &)
+    def touch!
+      ok = Connection.own do |c|
+        c.exec_params("SELECT stampeded_touch($1, $2, $3, $4)",
+                      [job.queue, job.id, worker_id, job.attempt])[0]["stampeded_touch"]
+      end
+      Stampeded.truthy?(ok)
+    end
+  end
+end

data/lib/stampeded/lifecycle.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Stampeded
+  module Lifecycle
+    module_function
+
+    def states = @states ||= native.lifecycle_states
+
+    def events = @events ||= native.lifecycle_events
+
+    def apply(from, event) = native.lifecycle_apply(from, event)
+
+    def legal?(from, event)
+      !apply(from, event).nil?
+    rescue Error
+      false
+    end
+
+    def events_from(state) = events.select { legal?(state, it) }
+
+    def terminal?(state) = events_from(state).empty?
+
+    def claimable?(state) = legal?(state, :claim)
+
+    def native
+      require "stampeded/native"
+      Native
+    end
+  end
+end

data/lib/stampeded/native.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+require "ffi"
+require "json"
+
+module Stampeded
+  module Native
+    extend FFI::Library
+
+    OK    = 0
+    NONE  = 1
+    ERROR = -1
+
+    LIBRARY = FFI.map_library_name("stampeded_ffi")
+
+    def self.library_path
+      if (dir = ENV.fetch("STAMPEDED_INSTALL_DIR", nil))
+        path = File.expand_path(File.join(dir, LIBRARY))
+        raise LibraryNotFound, "STAMPEDED_INSTALL_DIR is set to #{dir}, but #{path} does not exist" \
+          unless File.file?(path)
+
+        return path
+      end
+
+      path = File.expand_path(File.join("../..", "libexec", LIBRARY), __dir__)
+      return path if File.file?(path)
+
+      raise LibraryNotFound, <<~MSG
+        Could not find #{LIBRARY} for #{Daemon.platform}. Build it and point at it:
+
+          cargo build --release -p stampeded-ffi
+          export STAMPEDED_INSTALL_DIR=/path/to/stampeded/target/release
+      MSG
+    end
+
+    ffi_lib library_path
+
+    class PullerOptions < FFI::Struct
+      layout :queues, :pointer,
+             :except_queues, :pointer,
+             :max_leases, :uint32,
+             :batch_size, :uint32,
+             :poll_interval_ms, :uint32,
+             :heartbeat_interval_ms, :uint32
+    end
+
+    attach_function :stampeded_version, [], :string
+    attach_function :stampeded_last_error, [], :string
+    attach_function :stampeded_log_init, [:string], :int32
+
+    attach_function :stampeded_connect, [:string], :pointer, blocking: true
+    attach_function :stampeded_client_free, [:pointer], :void, blocking: true
+
+    attach_function :stampeded_puller_start, [:pointer, PullerOptions.by_ref], :pointer, blocking: true
+    attach_function :stampeded_puller_worker_id, [:pointer], :string
+    attach_function :stampeded_puller_next, %i[pointer uint32 pointer], :int32, blocking: true
+    attach_function :stampeded_puller_stop, %i[pointer uint32], :int32, blocking: true
+    attach_function :stampeded_puller_free, [:pointer], :void, blocking: true
+
+    attach_function :stampeded_lease_job, [:pointer], :string
+    attach_function :stampeded_lease_complete, [:pointer], :int32, blocking: true
+    attach_function :stampeded_lease_fail, %i[pointer string int64], :int32, blocking: true
+    attach_function :stampeded_lease_timed_out, %i[pointer string], :int32, blocking: true
+    attach_function :stampeded_lease_requeue, [:pointer], :int32, blocking: true
+    attach_function :stampeded_lease_discard, %i[pointer string], :int32, blocking: true
+    attach_function :stampeded_lease_free, [:pointer], :void, blocking: true
+
+    attach_function :stampeded_lifecycle_states, [], :string
+    attach_function :stampeded_lifecycle_events, [], :string
+    attach_function :stampeded_lifecycle_apply, %i[string string pointer], :int32
+    attach_function :stampeded_cron_check, %i[string string pointer], :int32
+
+    attach_function :stampeded_steps_load, [:string], :pointer
+    attach_function :stampeded_steps_free, [:pointer], :void
+    attach_function :stampeded_steps_completed, %i[pointer string], :int32
+    attach_function :stampeded_steps_value, %i[pointer string], :string
+    attach_function :stampeded_steps_cursor, %i[pointer string], :string
+    attach_function :stampeded_steps_complete, %i[pointer string string], :int32
+    attach_function :stampeded_steps_set_cursor, %i[pointer string string], :int32
+    attach_function :stampeded_steps_json, [:pointer], :string
+
+    module_function
+
+    def version = stampeded_version
+    def log_init(filter)
+      status = stampeded_log_init(filter)
+      raise Error, last_error if status == ERROR
+
+      status == OK
+    end
+
+    def last_error = stampeded_last_error || "unknown error"
+
+    def ms(seconds) = (seconds.to_f * 1000).round.clamp(0, 0xFFFF_FFFF)
+    def text(value) = value.to_s.encode("UTF-8", invalid: :replace, undef: :replace).delete("\0")
+
+    def lifecycle_states = stampeded_lifecycle_states.split(",").map(&:to_sym)
+
+    def lifecycle_events = stampeded_lifecycle_events.split(",").map(&:to_sym)
+
+    def lifecycle_apply(state, event)
+      out = FFI::MemoryPointer.new(:pointer)
+      case stampeded_lifecycle_apply(state.to_s, event.to_s, out)
+      when OK then out.read_pointer.read_string.to_sym
+      when NONE then nil
+      else raise Error, last_error
+      end
+    end
+
+    def cron_check(expr, timezone)
+      out = FFI::MemoryPointer.new(:pointer)
+      raise Error, last_error if stampeded_cron_check(text(expr), text(timezone), out) == ERROR
+
+      out.read_pointer.read_string
+    end
+
+    class Steps
+      def initialize(checkpoint)
+        pointer = Native.stampeded_steps_load(checkpoint.nil? ? nil : JSON.generate(checkpoint))
+        raise Error, Native.last_error if pointer.null?
+
+        @pointer = FFI::AutoPointer.new(pointer, Native.method(:stampeded_steps_free))
+      end
+
+      def completed?(name) = check(Native.stampeded_steps_completed(@pointer, name.to_s)) == OK
+
+      def value(name) = decode(Native.stampeded_steps_value(@pointer, name.to_s))
+
+      def cursor(name) = decode(Native.stampeded_steps_cursor(@pointer, name.to_s))
+
+      def complete(name, json) = check(Native.stampeded_steps_complete(@pointer, name.to_s, json))
+
+      def set_cursor(name, json) = check(Native.stampeded_steps_set_cursor(@pointer, name.to_s, json))
+
+      def to_h = JSON.parse(Native.stampeded_steps_json(@pointer))
+
+      private
+
+      def check(status)
+        raise Error, Native.last_error if status == ERROR
+
+        status
+      end
+
+      def decode(json) = json && JSON.parse(json)
+    end
+    class Puller
+      attr_reader :worker_id
+
+      def initialize(url:, queues:, except:, max_leases:, batch_size:, poll_interval:, heartbeat_interval:)
+        @client = Native.stampeded_connect(url)
+        raise Error, Native.last_error if @client.null?
+
+        options = PullerOptions.new
+        queue_spec  = FFI::MemoryPointer.from_string(Native.text(queues))
+        except_spec = except && FFI::MemoryPointer.from_string(Native.text(except))
+        options[:queues]                = queue_spec
+        options[:except_queues]         = except_spec || FFI::Pointer::NULL
+        options[:max_leases]            = max_leases
+        options[:batch_size]            = batch_size
+        options[:poll_interval_ms]      = Native.ms(poll_interval)
+        options[:heartbeat_interval_ms] = Native.ms(heartbeat_interval)
+
+        @puller = Native.stampeded_puller_start(@client, options)
+        if @puller.null?
+          message = Native.last_error
+          close
+          raise Error, "could not start the worker: #{message}"
+        end
+        @worker_id = Native.stampeded_puller_worker_id(@puller)
+      end
+
+      def next(timeout)
+        out = FFI::MemoryPointer.new(:pointer)
+        case Native.stampeded_puller_next(@puller, Native.ms(timeout), out)
+        when OK then Lease.new(out.read_pointer)
+        when NONE then nil
+        else raise Error, Native.last_error
+        end
+      end
+
+      def stop(drain)
+        raise Error, Native.last_error if Native.stampeded_puller_stop(@puller, Native.ms(drain)) == ERROR
+      end
+
+      def close
+        Native.stampeded_puller_free(@puller) if @puller && !@puller.null?
+        Native.stampeded_client_free(@client) if @client && !@client.null?
+        @puller = @client = nil
+      end
+    end
+
+    class Lease
+      attr_reader :row
+
+      def initialize(pointer)
+        @pointer = pointer
+        @row = JSON.parse(Native.stampeded_lease_job(pointer))
+      end
+
+      def settled? = @pointer.nil?
+
+      def complete! = settle { Native.stampeded_lease_complete(it) }
+      def fail!(message, retry_in_ms: nil)
+        settle { Native.stampeded_lease_fail(it, Native.text(message), retry_in_ms || -1) }
+      end
+
+      def requeue! = settle { Native.stampeded_lease_requeue(it) }
+
+      def timed_out!(message) = settle { Native.stampeded_lease_timed_out(it, Native.text(message)) }
+
+      def discard!(message) = settle { Native.stampeded_lease_discard(it, Native.text(message)) }
+
+      def release!
+        return if settled?
+
+        pointer = @pointer
+        @pointer = nil
+        Native.stampeded_lease_free(pointer)
+      end
+
+      private
+
+      def settle
+        raise Error, "lease already settled" if settled?
+
+        pointer = @pointer
+        @pointer = nil
+        raise Error, Native.last_error if yield(pointer) == ERROR
+      end
+    end
+  end
+end