dispatch_policy 0.1.0

data/lib/dispatch_policy/tick.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+module DispatchPolicy
+  class Tick
+    THROTTLE_ZERO_THRESHOLD = 0.001
+
+    # Single admission pass: fetch pending staged jobs per policy, evaluate
+    # gates, mark survivors as admitted, then enqueue them on the real
+    # backend outside the locking transaction.
+    def self.run(policy_name: nil)
+      return 0 unless DispatchPolicy.enabled?
+
+      pending_enqueue = []
+
+      StagedJob.transaction do
+        active_policies(policy_name).each do |pname|
+          policy = lookup_policy(pname)
+          next unless policy
+
+          batch = fetch_batch(policy)
+          next if batch.empty?
+
+          pending_enqueue.concat(run_policy(policy, batch))
+        end
+      end
+
+      admitted_count = 0
+      pending_enqueue.each do |staged, job|
+        begin
+          job.enqueue(_bypass_staging: true)
+          admitted_count += 1
+        rescue StandardError => e
+          Rails.logger&.error("[DispatchPolicy] enqueue failed staged=#{staged.id}: #{e.class}: #{e.message}")
+          revert_admission(staged)
+        end
+      end
+
+      admitted_count
+    end
+
+    def self.prune_idle_partitions
+      ttl = DispatchPolicy.config.partition_idle_ttl
+      return if ttl.nil? || ttl <= 0
+
+      cutoff = Time.current - ttl
+      PartitionInflightCount.where(in_flight: 0).where("updated_at < ?", cutoff).delete_all
+      ThrottleBucket.where("tokens <= ? AND refilled_at < ?", THROTTLE_ZERO_THRESHOLD, cutoff).delete_all
+    end
+
+    def self.prune_orphan_gate_rows
+      [ PartitionInflightCount, ThrottleBucket ].each do |model|
+        model.distinct.pluck(:policy_name, :gate_name).each do |policy_name, gate_name|
+          policy = lookup_policy(policy_name)
+          next if policy && policy.gates.any? { |g| g.name == gate_name.to_sym }
+
+          model.where(policy_name: policy_name, gate_name: gate_name).delete_all
+        end
+      end
+    end
+
+    def self.reap
+      StagedJob.expired_leases.find_each do |staged|
+        (staged.partitions || {}).each do |gate_name, partition_key|
+          policy = lookup_policy(staged.policy_name)
+          gate   = policy&.gates&.find { |g| g.name == gate_name.to_sym }
+          next unless gate&.tracks_inflight?
+
+          PartitionInflightCount.decrement(
+            policy_name:   staged.policy_name,
+            gate_name:     gate_name.to_s,
+            partition_key: partition_key.to_s
+          )
+        end
+        staged.update!(lease_expires_at: nil, completed_at: Time.current)
+      end
+    end
+
+    def self.release(policy_name:, partitions:)
+      partitions.each do |gate_name, partition_key|
+        policy = lookup_policy(policy_name)
+        gate   = policy&.gates&.find { |g| g.name == gate_name.to_sym }
+        next unless gate&.tracks_inflight?
+
+        PartitionInflightCount.decrement(
+          policy_name:   policy_name,
+          gate_name:     gate_name.to_s,
+          partition_key: partition_key.to_s
+        )
+      end
+    end
+
+    def self.active_policies(policy_name)
+      return [ policy_name ] if policy_name
+
+      StagedJob.pending
+        .where("not_before_at IS NULL OR not_before_at <= ?", Time.current)
+        .distinct
+        .pluck(:policy_name)
+    end
+
+    def self.fetch_batch(policy)
+      if policy.round_robin?
+        fetch_round_robin_batch(policy)
+      else
+        fetch_plain_batch(policy)
+      end
+    end
+
+    def self.fetch_plain_batch(policy)
+      StagedJob.pending
+        .where(policy_name: policy.name)
+        .where("not_before_at IS NULL OR not_before_at <= ?", Time.current)
+        .order(:priority, :staged_at)
+        .limit(DispatchPolicy.config.batch_size)
+        .lock("FOR UPDATE SKIP LOCKED")
+        .to_a
+    end
+
+    def self.fetch_round_robin_batch(policy)
+      quantum    = DispatchPolicy.config.round_robin_quantum
+      batch_size = DispatchPolicy.config.batch_size
+      now        = Time.current
+
+      sql = <<~SQL.squish
+        SELECT rows.*
+        FROM (
+          SELECT DISTINCT round_robin_key
+          FROM dispatch_policy_staged_jobs
+          WHERE policy_name = ?
+            AND admitted_at IS NULL
+            AND round_robin_key IS NOT NULL
+            AND (not_before_at IS NULL OR not_before_at <= ?)
+        ) AS keys
+        CROSS JOIN LATERAL (
+          SELECT *
+          FROM dispatch_policy_staged_jobs
+          WHERE policy_name = ?
+            AND admitted_at IS NULL
+            AND round_robin_key = keys.round_robin_key
+            AND (not_before_at IS NULL OR not_before_at <= ?)
+          ORDER BY priority, staged_at
+          LIMIT ?
+          FOR UPDATE SKIP LOCKED
+        ) AS rows
+        LIMIT ?
+      SQL
+
+      batch = StagedJob.find_by_sql([ sql, policy.name, now, policy.name, now, quantum, batch_size ])
+
+      remaining = batch_size - batch.size
+      return batch if remaining <= 0
+
+      top_up = StagedJob.pending
+        .where(policy_name: policy.name)
+        .where("not_before_at IS NULL OR not_before_at <= ?", now)
+        .where.not(id: batch.map(&:id))
+        .order(:priority, :staged_at)
+        .limit(remaining)
+        .lock("FOR UPDATE SKIP LOCKED")
+        .to_a
+
+      batch + top_up
+    end
+
+    def self.lookup_policy(policy_name)
+      job_class = DispatchPolicy.registry[policy_name] || autoload_job_for(policy_name)
+      return nil unless job_class
+      job_class.resolved_dispatch_policy
+    end
+
+    def self.autoload_job_for(policy_name)
+      const_name = policy_name.tr("-", "/").camelize
+      const_name.safe_constantize
+      DispatchPolicy.registry[policy_name]
+    end
+
+    def self.run_policy(policy, batch)
+      context = DispatchContext.new(policy: policy, batch: batch)
+      survivors = batch
+      policy.gates.each do |gate|
+        survivors = gate.filter(survivors, context)
+      end
+
+      survivors.map do |staged|
+        partitions = context.partitions_for(staged)
+
+        partitions.each do |gate_name, partition_key|
+          gate = policy.gates.find { |g| g.name == gate_name.to_sym }
+          next unless gate&.tracks_inflight?
+
+          PartitionInflightCount.increment(
+            policy_name:   policy.name,
+            gate_name:     gate_name.to_s,
+            partition_key: partition_key.to_s
+          )
+        end
+
+        job = staged.mark_admitted!(partitions: partitions)
+        [ staged, job ]
+      end
+    end
+
+    def self.revert_admission(staged)
+      partitions = staged.partitions || {}
+      release(policy_name: staged.policy_name, partitions: partitions)
+      staged.update_columns(
+        admitted_at:      nil,
+        lease_expires_at: nil,
+        active_job_id:    nil,
+        partitions:       {}
+      )
+    end
+  end
+end

data/lib/dispatch_policy/tick_loop.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module DispatchPolicy
+  # Shared driver for DispatchTickLoopJob and any foreground tick (e.g. a
+  # rake task). Loops Tick.reap + Tick.run with an interruptible sleep and
+  # bails when stop_when returns true.
+  class TickLoop
+    def self.run(policy_name: nil, sleep_for: nil, sleep_for_busy: nil, stop_when: -> { false })
+      idle_sleep = (sleep_for      || DispatchPolicy.config.tick_sleep).to_f
+      busy_sleep = (sleep_for_busy || DispatchPolicy.config.tick_sleep_busy).to_f
+
+      loop do
+        break if stop_when.call
+
+        admitted = 0
+        begin
+          ActiveRecord::Base.uncached do
+            Tick.reap
+            admitted = Tick.run(policy_name: policy_name).to_i
+          end
+        rescue StandardError => e
+          Rails.logger&.error("[DispatchPolicy] tick error: #{e.class}: #{e.message}")
+          Rails.error.report(e, handled: true) if defined?(Rails) && Rails.respond_to?(:error)
+        end
+
+        break if stop_when.call
+
+        interruptible_sleep(admitted.positive? ? busy_sleep : idle_sleep, stop_when)
+      end
+    end
+
+    def self.interruptible_sleep(total, stop_when)
+      return unless total.positive?
+
+      remaining = total
+      step = 0.1
+      while remaining.positive?
+        break if stop_when.call
+        chunk = [ remaining, step ].min
+        sleep(chunk)
+        remaining -= chunk
+      end
+    end
+  end
+end

data/lib/dispatch_policy/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DispatchPolicy
+  VERSION = "0.1.0"
+end

data/lib/dispatch_policy.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "active_job"
+require "active_record"
+
+require "dispatch_policy/version"
+require "dispatch_policy/engine" if defined?(Rails)
+
+module DispatchPolicy
+  Config = Struct.new(
+    :enabled,
+    :lease_duration,
+    :batch_size,
+    :round_robin_quantum,
+    :tick_max_duration,
+    :tick_sleep,
+    :tick_sleep_busy,
+    :partition_idle_ttl,
+    keyword_init: true
+  )
+
+  def self.config
+    @config ||= Config.new(
+      enabled:             true,
+      lease_duration:      15 * 60,          # 15.minutes
+      batch_size:          500,
+      round_robin_quantum: 50,
+      tick_max_duration:   60,               # 1.minute
+      tick_sleep:          1,                # idle sleep
+      tick_sleep_busy:     0.05,             # busy sleep
+      partition_idle_ttl:  30 * 60           # 30.minutes
+    )
+  end
+
+  def self.configure
+    yield config
+  end
+
+  def self.enabled?
+    config.enabled != false
+  end
+
+  # Registry: policy_name => job_class. Populated by Policy#initialize.
+  def self.registry
+    @registry ||= {}
+  end
+
+  def self.reset_registry!
+    @registry = {}
+  end
+end
+
+require "dispatch_policy/policy"
+require "dispatch_policy/gate"
+require "dispatch_policy/gates/concurrency"
+require "dispatch_policy/gates/throttle"
+require "dispatch_policy/gates/global_cap"
+require "dispatch_policy/gates/fair_interleave"
+require "dispatch_policy/gates/adaptive_concurrency"
+require "dispatch_policy/dispatch_context"
+require "dispatch_policy/dispatchable"
+require "dispatch_policy/tick"
+require "dispatch_policy/tick_loop"
+require "dispatch_policy/active_job_perform_all_later_patch"

metadata

@@ -0,0 +1,182 @@
+--- !ruby/object:Gem::Specification
+name: dispatch_policy
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- José Galisteo
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sprockets-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: DispatchPolicy stages ActiveJob enqueues into a policy table and admits
+  them through declared gates. Supports per-partition throttle/concurrency, dedupe,
+  round-robin fairness, and ships a minimal Rails engine to inspect pending/admitted
+  state.
+email:
+- ceritium@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- app/controllers/dispatch_policy/application_controller.rb
+- app/controllers/dispatch_policy/policies_controller.rb
+- app/models/dispatch_policy/adaptive_concurrency_stats.rb
+- app/models/dispatch_policy/application_record.rb
+- app/models/dispatch_policy/partition_inflight_count.rb
+- app/models/dispatch_policy/partition_observation.rb
+- app/models/dispatch_policy/staged_job.rb
+- app/models/dispatch_policy/throttle_bucket.rb
+- app/views/dispatch_policy/policies/index.html.erb
+- app/views/dispatch_policy/policies/show.html.erb
+- app/views/layouts/dispatch_policy/application.html.erb
+- config/routes.rb
+- db/migrate/20260424000001_create_dispatch_policy_tables.rb
+- db/migrate/20260424000002_create_adaptive_concurrency_stats.rb
+- db/migrate/20260424000003_create_adaptive_concurrency_samples.rb
+- db/migrate/20260424000004_rename_samples_to_partition_observations.rb
+- lib/dispatch_policy.rb
+- lib/dispatch_policy/active_job_perform_all_later_patch.rb
+- lib/dispatch_policy/dispatch_context.rb
+- lib/dispatch_policy/dispatchable.rb
+- lib/dispatch_policy/engine.rb
+- lib/dispatch_policy/gate.rb
+- lib/dispatch_policy/gates/adaptive_concurrency.rb
+- lib/dispatch_policy/gates/concurrency.rb
+- lib/dispatch_policy/gates/fair_interleave.rb
+- lib/dispatch_policy/gates/global_cap.rb
+- lib/dispatch_policy/gates/throttle.rb
+- lib/dispatch_policy/install_generator.rb
+- lib/dispatch_policy/policy.rb
+- lib/dispatch_policy/tick.rb
+- lib/dispatch_policy/tick_loop.rb
+- lib/dispatch_policy/version.rb
+homepage: https://github.com/ceritium/dispatch_policy
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ceritium/dispatch_policy
+  source_code_uri: https://github.com/ceritium/dispatch_policy
+  bug_tracker_uri: https://github.com/ceritium/dispatch_policy/issues
+  changelog_uri: https://github.com/ceritium/dispatch_policy/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Per-partition admission control (throttle, concurrency, dedupe, fairness)
+  for ActiveJob.
+test_files: []