RubyGems - dispatch_policy - Versions diffs - 0.1.0 → 0.3.0 - Mend

dispatch_policy 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (70) hide show

checksums.yaml +4 -4
data/MIT-LICENSE +16 -17
data/README.md +449 -288
data/app/assets/stylesheets/dispatch_policy/application.css +157 -0
data/app/controllers/dispatch_policy/application_controller.rb +45 -1
data/app/controllers/dispatch_policy/dashboard_controller.rb +91 -0
data/app/controllers/dispatch_policy/partitions_controller.rb +122 -0
data/app/controllers/dispatch_policy/policies_controller.rb +94 -241
data/app/controllers/dispatch_policy/staged_jobs_controller.rb +9 -0
data/app/models/dispatch_policy/adaptive_concurrency_stats.rb +11 -81
data/app/models/dispatch_policy/inflight_job.rb +12 -0
data/app/models/dispatch_policy/partition.rb +21 -0
data/app/models/dispatch_policy/staged_job.rb +4 -97
data/app/models/dispatch_policy/tick_sample.rb +11 -0
data/app/views/dispatch_policy/dashboard/index.html.erb +109 -0
data/app/views/dispatch_policy/partitions/index.html.erb +63 -0
data/app/views/dispatch_policy/partitions/show.html.erb +106 -0
data/app/views/dispatch_policy/policies/index.html.erb +15 -37
data/app/views/dispatch_policy/policies/show.html.erb +140 -216
data/app/views/dispatch_policy/shared/_capacity.html.erb +67 -0
data/app/views/dispatch_policy/shared/_hints.html.erb +13 -0
data/app/views/dispatch_policy/shared/_partition_row.html.erb +12 -0
data/app/views/dispatch_policy/staged_jobs/show.html.erb +31 -0
data/app/views/layouts/dispatch_policy/application.html.erb +95 -238
data/config/routes.rb +18 -2
data/db/migrate/20260501000001_create_dispatch_policy_tables.rb +103 -0
data/lib/dispatch_policy/bypass.rb +23 -0
data/lib/dispatch_policy/config.rb +85 -0
data/lib/dispatch_policy/context.rb +50 -0
data/lib/dispatch_policy/cursor_pagination.rb +121 -0
data/lib/dispatch_policy/decision.rb +22 -0
data/lib/dispatch_policy/engine.rb +4 -27
data/lib/dispatch_policy/forwarder.rb +63 -0
data/lib/dispatch_policy/gate.rb +10 -38
data/lib/dispatch_policy/gates/adaptive_concurrency.rb +99 -97
data/lib/dispatch_policy/gates/concurrency.rb +45 -26
data/lib/dispatch_policy/gates/throttle.rb +65 -37
data/lib/dispatch_policy/inflight_tracker.rb +174 -0
data/lib/dispatch_policy/job_extension.rb +155 -0
data/lib/dispatch_policy/operator_hints.rb +126 -0
data/lib/dispatch_policy/pipeline.rb +48 -0
data/lib/dispatch_policy/policy.rb +62 -47
data/lib/dispatch_policy/policy_dsl.rb +120 -0
data/lib/dispatch_policy/railtie.rb +35 -0
data/lib/dispatch_policy/registry.rb +46 -0
data/lib/dispatch_policy/repository.rb +723 -0
data/lib/dispatch_policy/serializer.rb +36 -0
data/lib/dispatch_policy/tick.rb +263 -172
data/lib/dispatch_policy/tick_loop.rb +59 -26
data/lib/dispatch_policy/version.rb +1 -1
data/lib/dispatch_policy.rb +71 -46
data/lib/generators/dispatch_policy/install/install_generator.rb +70 -0
data/lib/generators/dispatch_policy/install/templates/create_dispatch_policy_tables.rb.tt +95 -0
data/lib/generators/dispatch_policy/install/templates/dispatch_tick_loop_job.rb.tt +53 -0
data/lib/generators/dispatch_policy/install/templates/initializer.rb.tt +11 -0
metadata +101 -43
data/CHANGELOG.md +0 -12
data/app/models/dispatch_policy/partition_inflight_count.rb +0 -42
data/app/models/dispatch_policy/partition_observation.rb +0 -49
data/app/models/dispatch_policy/throttle_bucket.rb +0 -41
data/db/migrate/20260424000001_create_dispatch_policy_tables.rb +0 -80
data/db/migrate/20260424000002_create_adaptive_concurrency_stats.rb +0 -22
data/db/migrate/20260424000003_create_adaptive_concurrency_samples.rb +0 -25
data/db/migrate/20260424000004_rename_samples_to_partition_observations.rb +0 -32
data/lib/dispatch_policy/active_job_perform_all_later_patch.rb +0 -32
data/lib/dispatch_policy/dispatch_context.rb +0 -53
data/lib/dispatch_policy/dispatchable.rb +0 -120
data/lib/dispatch_policy/gates/fair_interleave.rb +0 -32
data/lib/dispatch_policy/gates/global_cap.rb +0 -26
data/lib/dispatch_policy/install_generator.rb +0 -23

data/app/views/layouts/dispatch_policy/application.html.erb CHANGED Viewed

@@ -1,266 +1,123 @@
 <!DOCTYPE html>
-<html>
+<html lang="en">
   <head>
-    <title>DispatchPolicy</title>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <title>dispatch_policy</title>
     <%= csrf_meta_tags %>
+    <%# Same-URL Turbo.visit (used by the auto-refresh) is treated as a "page %>
+    <%# refresh"; with these two meta tags Turbo morphs the body in place and %>
+    <%# preserves scroll position. %>
     <meta name="turbo-refresh-method" content="morph">
     <meta name="turbo-refresh-scroll" content="preserve">
-    <script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.0/dist/chart.umd.min.js"></script>
-    <script src="https://cdn.jsdelivr.net/npm/@hotwired/turbo@8.0.12/dist/turbo.es2017-umd.min.js"></script>
-    <style>
-      body { font-family: -apple-system, system-ui, sans-serif; max-width: 1200px; margin: 2em auto; padding: 0 1em; color: #222; }
-      h1 { font-size: 1.6em; margin-bottom: 0.25em; }
-      h2 { font-size: 1.2em; margin-top: 2em; border-bottom: 1px solid #ddd; padding-bottom: 0.25em; }
-      table { border-collapse: collapse; width: 100%; margin: 0.5em 0 1em; }
-      th, td { text-align: left; padding: 0.4em 0.6em; border-bottom: 1px solid #eee; }
-      th { font-size: 0.85em; text-transform: uppercase; color: #666; letter-spacing: 0.02em; }
-      code { background: #f4f4f4; padding: 0.1em 0.3em; border-radius: 3px; font-size: 0.9em; }
-      .muted { color: #888; }
-      .summary { display: flex; gap: 2em; margin: 1em 0; flex-wrap: wrap; }
-      .summary-item { min-width: 120px; }
-      .summary-item .value { font-size: 1.5em; font-weight: 600; }
-      .summary-item .label { font-size: 0.8em; color: #666; text-transform: uppercase; }
-      .summary-item .sub { font-size: 0.75em; color: #888; margin-top: 0.25em; }
-      .back { font-size: 0.9em; }
-      .stale { color: #c92a2a; }
-      .badge { display: inline-block; padding: 0.1em 0.5em; background: #eee; border-radius: 3px; font-size: 0.8em; margin-right: 0.25em; }
-      .text-end { text-align: right; }
-      .refresh-bar { display: flex; gap: 0.5em; align-items: center; justify-content: flex-end; font-size: 0.85em; margin-bottom: 0.5em; }
-      .refresh-bar button { font: inherit; background: transparent; text-decoration: none; padding: 0.15em 0.5em; border: 1px solid #ddd; border-radius: 3px; color: #555; cursor: pointer; }
-      .refresh-bar button.on { background: #e3f0d6; border-color: #b7d59c; color: #2b5a18; }
-      .refresh-bar button:hover { background: #f4f4f4; }
-      .refresh-bar button.on:hover { background: #d7e7c5; }
-      .chart-global { height: 220px; position: relative; margin: 0.5em 0 1em; }
-      .sparkline-cell { padding: 0.2em 0.6em 0.4em !important; border-bottom: 1px solid #eee !important; background: #fafafa; }
-      .sparkline-wrap { height: 70px; position: relative; }
-      .sparkline-empty { display: flex; align-items: center; justify-content: center; font-size: 0.85em; }
-      .chip { font: inherit; padding: 0.1em 0.5em; min-width: 1.6em; border: 1px solid #ccc; background: #fff; border-radius: 3px; cursor: pointer; font-size: 0.85em; color: #555; }
-      .chip:hover { background: #f4f4f4; }
-      .chip.on { background: #e3f0d6; border-color: #b7d59c; color: #2b5a18; cursor: default; }
-      .partition-search { margin: 0.75em 0; display: flex; gap: 0.5em; align-items: center; }
-      .partition-search input[type="text"] { font: inherit; padding: 0.25em 0.5em; border: 1px solid #ccc; border-radius: 3px; }
-      .partition-search input[type="submit"] { font: inherit; padding: 0.25em 0.75em; border: 1px solid #bbb; background: #f4f4f4; border-radius: 3px; cursor: pointer; }
-      .pagination { display: flex; gap: 1em; align-items: center; margin-top: 0.5em; font-size: 0.9em; }
-      th a { color: inherit; text-decoration: none; }
-      th a:hover { color: #0057b7; }
-      th a.sorted { color: #0057b7; }
-    </style>
-  </head>
-  <body>
-    <div class="refresh-bar">
-      <span class="muted">Auto-refresh:</span>
-      <% [ [ "off", 0 ], [ "2s", 2 ], [ "5s", 5 ], [ "15s", 15 ] ].each do |label, seconds| %>
-        <button type="button" data-refresh="<%= seconds %>"><%= label %></button>
-      <% end %>
-    </div>
-    <%= yield %>
+    <style><%= DispatchPolicy::Engine.root.join("app/assets/stylesheets/dispatch_policy/application.css").read.html_safe %></style>
+    <script src="https://cdn.jsdelivr.net/npm/@hotwired/turbo@8.0.4/dist/turbo.es2017-umd.min.js"></script>
     <script>
       (function () {
-        const KEY = "dispatch_policy_refresh_seconds";
-        let refreshTimer = null;
+        var KEY = "dispatch_policy:refresh-interval";
+        var timer = null;
+        // True between turbo:visit and turbo:load|turbo:render. While true,
+        // setTimeout reprograms instead of firing — otherwise a slow page
+        // (DB churn under load, /partitions with many rows) lets the
+        // setTimeout fire while the previous Turbo visit is still in
+        // flight, stacking requests on top of each other.
+        var visiting = false;
-        function scheduleRefresh() {
-          clearTimeout(refreshTimer);
-          const seconds = parseInt(localStorage.getItem(KEY) || "0", 10);
-          if (seconds <= 0) return;
-          refreshTimer = setTimeout(() => {
-            // Turbo.visit fetches + morphs thanks to the turbo-refresh-method
-            // meta tag, so the page updates in place without a full reload —
-            // scroll position, chart tooltips, form focus stay put.
-            if (window.Turbo) {
-              Turbo.visit(location.href, { action: "replace" });
-            } else {
-              location.reload();
-            }
-          }, seconds * 1000);
+        function getInterval() {
+          return parseInt(sessionStorage.getItem(KEY) || "0", 10);
         }
-        function wireRefreshButtons() {
-          const current = parseInt(localStorage.getItem(KEY) || "0", 10);
-          document.querySelectorAll(".refresh-bar button[data-refresh]").forEach(btn => {
-            btn.classList.toggle("on", parseInt(btn.dataset.refresh, 10) === current);
-            if (btn.dataset.wired) return;
-            btn.dataset.wired = "true";
-            btn.addEventListener("click", () => {
-              const v = parseInt(btn.dataset.refresh, 10);
-              if (v === 0) localStorage.removeItem(KEY);
-              else         localStorage.setItem(KEY, String(v));
-              wireRefreshButtons();
-              scheduleRefresh();
-            });
-          });
+        function setInterval(value) {
+          sessionStorage.setItem(KEY, String(value));
+          syncControls();
+          restart();
         }
-        // Charts get destroyed + rebuilt on each render because Chart.js
-        // keeps a registry keyed by canvas element; the morphed canvases
-        // are fresh DOM, so previous Chart instances would leak listeners.
-        function destroyExistingCharts() {
-          if (!window.Chart) return;
-          Chart.instances && Object.values(Chart.instances).forEach(c => c.destroy && c.destroy());
+        function restart() {
+          if (timer) { clearTimeout(timer); timer = null; }
+          var seconds = getInterval();
+          if (seconds > 0) {
+            timer = setTimeout(function () {
+              if (visiting) { restart(); return; }
+              if (typeof Turbo !== "undefined") {
+                Turbo.visit(window.location.href, { action: "replace" });
+              } else {
+                window.location.assign(window.location.href);
+              }
+            }, seconds * 1000);
+          }
         }
-        // Chart.js initialization for canvases with data-chart.
-        const BLUE        = "#0057b7";
-        const BAR_FILL    = "rgba(0, 87, 183, 0.18)";
-        const TOOLTIP_FMT = {
-          titleFont: { size: 11 },
-          bodyFont:  { size: 11 },
-          padding:   6,
-          displayColors: false,
-          boxPadding: 3
-        };
-        function parseJSON(s, fallback) {
-          try { return JSON.parse(s); } catch (e) { return fallback; }
+        function syncControls() {
+          var current = getInterval();
+          document.querySelectorAll("[data-dp-refresh]").forEach(function (btn) {
+            var v = parseInt(btn.getAttribute("data-dp-refresh"), 10);
+            if (v === current) btn.classList.add("dp-refresh-active");
+            else btn.classList.remove("dp-refresh-active");
+          });
         }
-        function renderCharts() {
-          if (!window.Chart) return;
-        document.querySelectorAll("canvas[data-chart]").forEach(canvas => {
-          const kind   = canvas.dataset.chart;
-          const values = parseJSON(canvas.dataset.values, []);
-          const labels = parseJSON(canvas.dataset.labels, []);
-          const counts = parseJSON(canvas.dataset.counts, []);
-          const label  = canvas.dataset.label || "";
-          const datasets = [];
-          if (counts.length) {
-            datasets.push({
-              type: "bar",
-              label: "completions/min",
-              data: counts,
-              backgroundColor: BAR_FILL,
-              borderWidth: 0,
-              yAxisID: "y1",
-              order: 2
+        function bindControls() {
+          document.querySelectorAll("[data-dp-refresh]").forEach(function (btn) {
+            if (btn.dataset.bound) return;
+            btn.dataset.bound = "1";
+            btn.addEventListener("click", function (e) {
+              e.preventDefault();
+              setInterval(parseInt(btn.getAttribute("data-dp-refresh"), 10));
             });
-          }
-          datasets.push({
-            type: "line",
-            label: label || "ewma ms",
-            data: values,
-            borderColor: BLUE,
-            backgroundColor: "rgba(0, 87, 183, 0.1)",
-            tension: 0.25,
-            fill: kind === "line",
-            pointRadius: 0,
-            pointHoverRadius: 4,
-            pointHitRadius: 10,
-            borderWidth: kind === "sparkline" ? 1.5 : 2,
-            spanGaps: false,
-            yAxisID: "y",
-            order: 1
           });
-          const isSpark = kind === "sparkline";
-          const config = {
-            data: { labels: labels.length ? labels : values.map((_, i) => i), datasets },
-            options: {
-              responsive: true, maintainAspectRatio: false,
-              interaction: { mode: "index", intersect: false },
-              plugins: {
-                legend: { display: false },
-                tooltip: Object.assign({}, TOOLTIP_FMT, {
-                  enabled: true,
-                  callbacks: {
-                    title: items => items[0].label,
-                    label: ctx => {
-                      if (ctx.dataset.yAxisID === "y1") {
-                        return `${ctx.parsed.y} completions`;
-                      }
-                      return ctx.parsed.y != null ? `${ctx.parsed.y} ms` : "no data";
-                    }
-                  }
-                })
-              },
-              scales: {
-                x: isSpark
-                  ? { display: false, min: 0, max: values.length - 1 }
-                  : { ticks: { maxTicksLimit: 12, autoSkip: true } },
-                y: isSpark
-                  ? { display: false, beginAtZero: true }
-                  : { beginAtZero: true, ticks: { callback: v => v + "ms" } },
-                y1: {
-                  position: "right",
-                  display: !isSpark,
-                  beginAtZero: true,
-                  grid: { drawOnChartArea: false },
-                  ticks: { callback: v => v + "/m" }
-                }
-              },
-              animation: false
-            }
-          };
-          new Chart(canvas, config);
-        });
+          syncControls();
         }
-        // Watched-partitions manager. Scopes the localStorage list to the
-        // current policy (via [data-policy-name]); watch/unwatch clicks
-        // rewrite the URL's `watch` param and Turbo.visit into it.
-        function policyKey() {
-          const el = document.querySelector("[data-policy-name]");
-          return el ? `dp_watched:${el.dataset.policyName}` : null;
-        }
-        function getWatched() {
-          const key = policyKey(); if (!key) return [];
-          try { return JSON.parse(localStorage.getItem(key) || "[]"); } catch (_) { return []; }
-        }
-        function setWatched(arr) {
-          const key = policyKey(); if (!key) return;
-          localStorage.setItem(key, JSON.stringify(arr));
-          const url = new URL(location.href);
-          if (arr.length) url.searchParams.set("watch", arr.join(","));
-          else            url.searchParams.delete("watch");
-          if (window.Turbo) Turbo.visit(url.toString(), { action: "replace" });
-          else              location.href = url.toString();
+        function init() {
+          bindControls();
+          restart();
         }
-        function wireWatch() {
-          document.addEventListener("click", (e) => {
-            const add = e.target.closest("[data-watch]");
-            const rm  = e.target.closest("[data-unwatch]");
-            if (!add && !rm) return;
-            e.preventDefault();
-            const arr = getWatched();
-            if (add) {
-              if (!arr.includes(add.dataset.watch)) arr.push(add.dataset.watch);
-            } else {
-              const idx = arr.indexOf(rm.dataset.unwatch);
-              if (idx >= 0) arr.splice(idx, 1);
-            }
-            setWatched(arr);
-          }, { once: true });
-        }
+        document.addEventListener("DOMContentLoaded", init);
+        document.addEventListener("turbo:load",       init);
-        // On first load, if localStorage has a watched list but the URL
-        // doesn't, inject it so the page renders the right partitions.
-        function syncWatchedIntoUrl() {
-          const arr = getWatched();
-          if (!arr.length) return;
-          const url = new URL(location.href);
-          if (url.searchParams.get("watch") === arr.join(",")) return;
-          url.searchParams.set("watch", arr.join(","));
-          if (window.Turbo) Turbo.visit(url.toString(), { action: "replace" });
-          else              location.replace(url.toString());
-        }
+        document.addEventListener("turbo:visit",  function () { visiting = true;  });
+        document.addEventListener("turbo:load",   function () { visiting = false; });
+        document.addEventListener("turbo:render", function () { visiting = false; });
-        function boot() {
-          destroyExistingCharts();
-          wireRefreshButtons();
-          wireWatch();
-          renderCharts();
-          scheduleRefresh();
-          syncWatchedIntoUrl();
-        }
-        // Run on the initial load + whenever Turbo renders (morph or full).
-        document.addEventListener("DOMContentLoaded", boot);
-        document.addEventListener("turbo:render", boot);
-        document.addEventListener("turbo:load",   boot);
+        // Pause refresh when the tab is hidden (saves DB load); resume when visible.
+        document.addEventListener("visibilitychange", function () {
+          if (document.hidden) {
+            if (timer) { clearTimeout(timer); timer = null; }
+          } else {
+            restart();
+          }
+        });
       })();
     </script>
+  </head>
+  <body>
+    <header class="dp-header">
+      <div class="dp-brand">
+        <%= link_to "dispatch_policy", root_path, class: "dp-logo" %>
+      </div>
+      <nav class="dp-nav">
+        <%= link_to "Dashboard",  root_path %>
+        <%= link_to "Policies",   policies_path %>
+        <%= link_to "Partitions", partitions_path %>
+      </nav>
+      <div class="dp-refresh">
+        <span class="dp-refresh-label">Auto-refresh</span>
+        <button type="button" class="dp-refresh-btn" data-dp-refresh="0">off</button>
+        <button type="button" class="dp-refresh-btn" data-dp-refresh="2">2s</button>
+        <button type="button" class="dp-refresh-btn" data-dp-refresh="5">5s</button>
+        <button type="button" class="dp-refresh-btn" data-dp-refresh="10">10s</button>
+      </div>
+    </header>
+    <% if flash[:notice] %><div class="dp-flash dp-flash-ok"><%= flash[:notice] %></div><% end %>
+    <% if flash[:alert]  %><div class="dp-flash dp-flash-err"><%= flash[:alert]  %></div><% end %>
+    <main class="dp-main">
+      <%= yield %>
+    </main>
+    <footer class="dp-footer">
+      <span>dispatch_policy v<%= DispatchPolicy::VERSION %></span>
+      <span>now: <%= Time.current.utc.strftime("%Y-%m-%d %H:%M:%S UTC") %></span>
+    </footer>
   </body>
 </html>

data/config/routes.rb CHANGED Viewed

@@ -1,6 +1,22 @@
 # frozen_string_literal: true
 DispatchPolicy::Engine.routes.draw do
-  root to: "policies#index"
-  resources :policies, only: %i[index show], param: :policy_name, constraints: { policy_name: %r{[^/]+} }
+  root to: "dashboard#index"
+  resources :policies, only: %i[index show], param: :name, constraints: { name: %r{[^/]+} } do
+    member do
+      post :pause
+      post :resume
+      post :drain
+    end
+  end
+  resources :partitions, only: %i[index show] do
+    member do
+      post :drain
+      post :admit
+    end
+  end
+  resources :staged_jobs, only: %i[show]
 end

data/db/migrate/20260501000001_create_dispatch_policy_tables.rb ADDED Viewed

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+class CreateDispatchPolicyTables < ActiveRecord::Migration[7.1]
+  def change
+    create_table :dispatch_policy_staged_jobs do |t|
+      t.string  :policy_name,   null: false
+      t.string  :partition_key, null: false
+      t.string  :queue_name
+      t.string  :job_class,     null: false
+      t.jsonb   :job_data,      null: false
+      t.datetime :scheduled_at
+      t.integer :priority,      default: 0, null: false
+      t.datetime :enqueued_at,  null: false, default: -> { "now()" }
+      t.jsonb   :context,       null: false, default: {}
+    end
+    add_index :dispatch_policy_staged_jobs,
+              [:policy_name, :partition_key, :scheduled_at, :id],
+              name: "idx_dp_staged_admission",
+              order: { scheduled_at: "ASC NULLS FIRST", id: :asc }
+    add_index :dispatch_policy_staged_jobs, :enqueued_at,
+              name: "idx_dp_staged_enqueued_at"
+    create_table :dispatch_policy_partitions do |t|
+      t.string   :policy_name,        null: false
+      t.string   :partition_key,      null: false
+      t.string   :queue_name
+      t.string   :shard,              null: false, default: "default"
+      t.string   :status,             null: false, default: "active"
+      t.integer  :pending_count,      null: false, default: 0
+      t.bigint   :total_admitted,     null: false, default: 0
+      t.jsonb    :context,            null: false, default: {}
+      t.datetime :context_updated_at
+      t.datetime :last_enqueued_at
+      t.datetime :last_checked_at
+      t.datetime :last_admit_at
+      t.datetime :next_eligible_at
+      t.jsonb    :gate_state,         null: false, default: {}
+      t.float    :decayed_admits,     null: false, default: 0.0
+      t.datetime :decayed_admits_at
+      t.timestamps
+    end
+    add_index :dispatch_policy_partitions,
+              [:policy_name, :partition_key],
+              unique: true,
+              name:   "idx_dp_partitions_lookup"
+    add_index :dispatch_policy_partitions,
+              [:policy_name, :shard, :status, :next_eligible_at, :last_checked_at],
+              name:  "idx_dp_partitions_tick_order",
+              order: { next_eligible_at: "ASC NULLS FIRST", last_checked_at: "ASC NULLS FIRST" }
+    create_table :dispatch_policy_inflight_jobs do |t|
+      t.string   :policy_name,    null: false
+      t.string   :partition_key,  null: false
+      t.string   :active_job_id,  null: false
+      t.datetime :admitted_at,    null: false, default: -> { "now()" }
+      t.datetime :heartbeat_at,   null: false, default: -> { "now()" }
+    end
+    add_index :dispatch_policy_inflight_jobs, :active_job_id, unique: true,
+              name: "idx_dp_inflight_active_job_id"
+    add_index :dispatch_policy_inflight_jobs, [:policy_name, :partition_key],
+              name: "idx_dp_inflight_partition"
+    add_index :dispatch_policy_inflight_jobs, :heartbeat_at,
+              name: "idx_dp_inflight_heartbeat"
+    create_table :dispatch_policy_tick_samples do |t|
+      t.string   :policy_name,        null: false
+      t.datetime :sampled_at,         null: false, default: -> { "now()" }
+      t.integer  :duration_ms,        null: false, default: 0
+      t.integer  :partitions_seen,    null: false, default: 0
+      t.integer  :partitions_admitted, null: false, default: 0
+      t.integer  :partitions_denied,  null: false, default: 0
+      t.integer  :jobs_admitted,      null: false, default: 0
+      t.integer  :forward_failures,   null: false, default: 0
+      t.integer  :pending_total,      null: false, default: 0
+      t.integer  :inflight_total,     null: false, default: 0
+      t.jsonb    :denied_reasons,     null: false, default: {}
+    end
+    add_index :dispatch_policy_tick_samples, [:policy_name, :sampled_at],
+              name: "idx_dp_tick_samples_lookup",
+              order: { sampled_at: :desc }
+    add_index :dispatch_policy_tick_samples, :sampled_at,
+              name: "idx_dp_tick_samples_sweep"
+    # adaptive_concurrency stats: one row per (policy_name, partition_key)
+    # for partitions whose policy declares an :adaptive_concurrency gate.
+    # Holds the AIMD-tuned current_max plus the EWMA queue-lag signal it
+    # adapts on. Populated by Repository.adaptive_seed! on first admission
+    # and updated by Repository.adaptive_record! after each perform.
+    create_table :dispatch_policy_adaptive_concurrency_stats do |t|
+      t.string   :policy_name,      null: false
+      t.string   :partition_key,    null: false
+      t.integer  :current_max,      null: false
+      t.float    :ewma_latency_ms,  null: false, default: 0.0
+      t.integer  :sample_count,     null: false, default: 0
+      t.datetime :last_observed_at
+      t.timestamps
+    end
+    add_index :dispatch_policy_adaptive_concurrency_stats,
+              [:policy_name, :partition_key],
+              unique: true,
+              name:   "idx_dp_adaptive_concurrency_lookup"
+  end
+end

data/lib/dispatch_policy/bypass.rb ADDED Viewed

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+module DispatchPolicy
+  # Thread-local guard. When active, ActiveJob#enqueue calls within the block
+  # bypass the dispatch_policy around_enqueue and reach the real adapter.
+  module Bypass
+    KEY = :__dispatch_policy_bypass__
+    module_function
+    def with
+      previous = Thread.current[KEY]
+      Thread.current[KEY] = true
+      yield
+    ensure
+      Thread.current[KEY] = previous
+    end
+    def active?
+      Thread.current[KEY] == true
+    end
+  end
+end

data/lib/dispatch_policy/config.rb ADDED Viewed

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+module DispatchPolicy
+  class Config
+    attr_accessor :enabled,
+                  :tick_max_duration,
+                  :partition_batch_size,
+                  :admission_batch_size,
+                  :idle_pause,
+                  :busy_pause,
+                  :partition_inactive_after,
+                  :inflight_stale_after,
+                  :inflight_heartbeat_interval,
+                  :real_adapter,
+                  :logger,
+                  :clock,
+                  :sweep_every_ticks,
+                  :metrics_retention,
+                  :database_role,
+                  :fairness_half_life_seconds,
+                  :tick_admission_budget,
+                  :adapter_throughput_target
+    def initialize
+      # Master switch. When false, the around_enqueue and the BulkEnqueue
+      # patch pass through to the real adapter without staging — all of
+      # the gem's machinery becomes a no-op for new perform_later calls.
+      # The TickLoop also exits early. Used during cutovers to drain
+      # the staging table without taking traffic offline.
+      @enabled                   = true
+      @tick_max_duration         = 25
+      @partition_batch_size      = 50
+      @admission_batch_size      = 100
+      @idle_pause                = 0.5
+      # Sleep between iterations when the previous tick admitted > 0
+      # jobs. 0 (default) preserves the original "busy = no pause"
+      # behavior. Set to a small value (e.g. 0.02) to back off the DB
+      # when several TickLoops compete for connections; the per-loop
+      # throughput ceiling becomes admission_batch_size / busy_pause.
+      @busy_pause                = 0.0
+      @partition_inactive_after  = 24 * 60 * 60
+      @inflight_stale_after      = 5 * 60
+      @inflight_heartbeat_interval = 30
+      @real_adapter              = nil
+      @logger                    = nil
+      @clock                     = -> { Time.now.utc }
+      @sweep_every_ticks         = 50
+      @metrics_retention         = 24 * 60 * 60
+      # AR role for the admission TX. nil = default connection. Set to
+      # e.g. :queue when the host runs solid_queue on a separate DB.
+      @database_role             = nil
+      # Fairness: the half-life of decayed_admits (per-partition EWMA).
+      # 60s means a partition's "recent activity" weight halves every
+      # 60s of idleness. Tick reorders claimed partitions by lowest
+      # decayed_admits first; under-admitted ones get first crack.
+      @fairness_half_life_seconds = 60
+      # Optional global cap on admissions per tick. nil = no cap; each
+      # partition uses admission_batch_size as its ceiling. When set,
+      # fair_share = ceil(cap / partitions_seen) is the per-partition
+      # ceiling, with redistribution of leftover budget after pass-1.
+      @tick_admission_budget     = nil
+      # Operator-supplied "ceiling" of the underlying adapter, in jobs
+      # per second. The dashboard renders the live admit rate as a
+      # percentage of this and fires a hint when we're closing on it.
+      # nil = no ceiling reference (just shows the absolute rate).
+      # Measured locally against good_job: ~3500 jobs/sec per worker.
+      @adapter_throughput_target = nil
+    end
+    def now
+      @clock.call
+    end
+    def logger
+      @logger || (defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger) || default_logger
+    end
+    private
+    def default_logger
+      require "logger"
+      @default_logger ||= Logger.new($stdout, level: Logger::INFO)
+    end
+  end
+end

data/lib/dispatch_policy/context.rb ADDED Viewed

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+module DispatchPolicy
+  class Context
+    def self.wrap(value)
+      case value
+      when Context then value
+      when Hash    then new(value)
+      when nil     then new({})
+      else
+        raise InvalidPolicy, "context must be a Hash, got #{value.class}"
+      end
+    end
+    attr_reader :data
+    def initialize(hash)
+      @data = deep_stringify(hash).freeze
+    end
+    def [](key)
+      @data[key.to_s]
+    end
+    def to_h
+      @data
+    end
+    def to_jsonb
+      @data
+    end
+    def fetch(key, *args, &block)
+      @data.fetch(key.to_s, *args, &block)
+    end
+    private
+    def deep_stringify(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(k, v), m| m[k.to_s] = deep_stringify(v) }
+      when Array
+        value.map { |v| deep_stringify(v) }
+      else
+        value
+      end
+    end
+  end
+end