job_control 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 471ad803e3da5149baf5f1c03e526172c37b1f07574cac5063120df02c616b3f
+  data.tar.gz: c8d34d1f600761b38c9ee8397f9b64250a2a32a7c604833a5db8265f49b0f28a
+SHA512:
+  metadata.gz: 48e55f1c39310b76af6064fc4af4f21db5f333dd509ae8b0d1d7148a0f0787fc65f6579356adb5ec4648511ca80b97167cd7fe24ca7f5b5ca38382b6a2d2b793
+  data.tar.gz: 2d03b15f54f199081c4a13cc8923649f1a133eb60d0f101ba92c644fc9aff713486ce3749bd5cf60006f875c8fdc4077469d246eba7391b6262b7e84f24074ae

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## Unreleased
+
+The first public release adds cooperative cancellation, heartbeats, lifecycle notifications, Solid Queue cleanup, and Mission Control Jobs integration. It requires Rails 8.1+ and does not ship RBS declarations.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Manh Kha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,158 @@
+# JobControl
+
+[JobControl](https://github.com/kha-wogi/job_control) gives long-running Active Job jobs a small, practical control surface: a heartbeat and a safe way to ask a job to stop.
+
+Cancellation is cooperative. JobControl never kills a worker thread or interrupts a database transaction. Your job finishes the unit it is working on, notices the request at its next checkpoint, and exits cleanly. It works best when the job can divide its work into small, idempotent units.
+
+## What it supports
+
+JobControl requires Ruby 3.2+ and Rails 8.1–8.x.
+
+| Feature | Availability |
+| --- | --- |
+| Lifecycle, heartbeats, checkpoints, and cooperative cancellation | Any Active Job adapter |
+| Cleanup after a permanent discard | Solid Queue 1.4–1.7 with the optional adapter |
+| Job detail UI and cancellation button | mission_control-jobs 1.3.x with the optional integration |
+| Cleanup after Sidekiq or GoodJob discard | Not included yet |
+
+The core behavior lives at the Active Job layer, so it works with any adapter. Permanent discard is different: every queue exposes that operation differently, so it needs a queue-specific adapter.
+
+## Installation
+
+```bash
+bundle add job_control
+bin/rails generate job_control:install
+bin/rails db:migrate
+```
+
+Run the generator again when upgrading JobControl. It skips migrations that are already present and copies any new ones.
+
+## Your first controlled job
+
+Include `JobControl::Job` in jobs that need cooperative cancellation. Add checkpoints between units that are safe to finish independently.
+
+```ruby
+class ExampleJob < ApplicationJob
+  include JobControl::Job
+
+  def perform
+    100.times do
+      perform_one_unit_of_work
+      checkpoint!
+    end
+  end
+
+  private
+
+  def perform_one_unit_of_work
+  end
+end
+```
+
+```ruby
+job = ExampleJob.perform_later
+JobControl.cancel(job.job_id)
+```
+
+`checkpoint!` updates the heartbeat and raises `JobControl::Cancelled` if cancellation was requested. Put it after a blocking wait and between batches or loop iterations. It does not interrupt code already running.
+
+A checkpoint performs one database reload and one timestamp update. In practice, checkpoint once per batch or every few seconds of work—not once per record—unless near-instant cancellation matters more than the extra writes.
+
+## Lifecycle
+
+A `job_controls` row is created when a controlled job is enqueued and becomes `running` when execution begins.
+
+| What happens | What JobControl does |
+| --- | --- |
+| The job succeeds | Publishes `job_control.succeeded` and deletes the row immediately. |
+| The job sees a cancellation request at a checkpoint | Publishes `job_control.cancelled` and deletes the row immediately. |
+| The job fails without a cancellation request | Publishes `job_control.failed` and deletes the row. A retry gets a fresh active control with the same job ID. |
+| A cancellation request is followed by an error | Leaves the row as `cancel_requested`, so a retry stops before doing work. |
+| Solid Queue permanently discards the job | The Solid Queue adapter deletes any remaining row after the queue transaction commits. |
+
+There is no retention window and no cleanup cron. For an unsupported queue, a cancelled attempt that fails and is never retried cannot be detected through generic Active Job callbacks; add a queue-specific adapter before relying on permanent-discard cleanup.
+
+## Runtime API
+
+```ruby
+control = JobControl.find(job.job_id)
+
+control.status
+control.cancellable?
+control.cancel_requested?
+control.heartbeat_at
+control.last_checkpoint_at
+
+control.cancel!
+```
+
+Within a controlled job, call `checkpoint!` directly or pass `cancellation` to a service with its own loop:
+
+```ruby
+SomeService.call(cancellation: cancellation)
+```
+
+## Observability
+
+A control is stale after five minutes without a heartbeat by default:
+
+```ruby
+JobControl.configure do |config|
+  config.stale_after = 15.minutes
+end
+```
+
+JobControl publishes Active Support notifications with `control:` in the payload:
+
+- `job_control.started`
+- `job_control.checkpoint`
+- `job_control.cancel_requested`
+- `job_control.cancelled`
+- `job_control.succeeded`
+- `job_control.failed`
+
+## Solid Queue
+
+The optional adapter supports Solid Queue 1.4–1.7 and removes controls after direct and batched discard operations.
+
+```ruby
+require "job_control/adapters/solid_queue"
+
+Rails.application.config.to_prepare do
+  JobControl::Adapters::SolidQueue::Adapter.install!
+end
+```
+
+## Mission Control Jobs
+
+With mission_control-jobs 1.3.x, JobControl adds a **Job control** section to the existing job detail page. It uses Mission Control's own styles and controller authentication.
+
+```ruby
+require "job_control/integrations/mission_control_jobs"
+
+Rails.application.config.to_prepare do
+  JobControl::Integrations::MissionControlJobs.install!
+end
+```
+
+Mission Control is assumed to be mounted at `/admin/jobs`. For another location:
+
+```ruby
+JobControl::Integrations::MissionControlJobs.install!(mount_path: "/operations/jobs")
+```
+
+The endpoint, client code, controller, and translations come from JobControl. There is no application view override, custom controller, or hand-written route to maintain. Restart the web process after enabling it.
+
+## Development
+
+```bash
+bundle exec rake
+```
+
+## Out of scope
+
+JobControl does not provide hard process termination, transaction rollback, progress tracking, pause/resume, cursor recovery, throttling, batch cancellation, or an administrative adapter for every queue backend.
+
+## Contributing
+
+Issues and pull requests are welcome at [kha-wogi/job_control](https://github.com/kha-wogi/job_control).

data/app/controllers/job_control/mission_control_jobs_controller.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module JobControl
+  # Supplies control state and cancellation to the Mission Control client.
+  class MissionControlJobsController < ::MissionControl::Jobs.base_controller_class.constantize
+    def show
+      control = JobControl::Control.find_by(job_id: params[:job_id])
+      return head :not_found unless control
+
+      render json: control_payload(control)
+    end
+
+    def cancel
+      control = JobControl::Control.find_by(job_id: params[:job_id])
+
+      if control&.cancellable?
+        control.cancel!
+        flash[:notice] = t("job_control.mission_control.cancellation_requested")
+      elsif control
+        flash[:alert] = t("job_control.mission_control.not_cancellable")
+      else
+        flash[:alert] = t("job_control.mission_control.not_found")
+      end
+
+      redirect_back fallback_location: JobControl::Integrations::MissionControlJobs.mount_path
+    end
+
+    private
+
+    def control_payload(control)
+      {
+        status: control.status,
+        cancel_requested: control.cancel_requested?,
+        cancellable: control.cancellable?,
+        heartbeat_at: control.heartbeat_at&.iso8601,
+        last_checkpoint_at: control.last_checkpoint_at&.iso8601
+      }
+    end
+  end
+end

data/config/locales/job_control.en.yml

@@ -0,0 +1,6 @@
+en:
+  job_control:
+    mission_control:
+      cancellation_requested: "Cancellation requested."
+      not_cancellable: "This job can no longer be cancelled."
+      not_found: "Job control was not found."

data/db/migrate/20260924000000_create_job_controls.rb

@@ -0,0 +1,17 @@
+class CreateJobControls < ActiveRecord::Migration[8.1]
+  def change
+    create_table :job_controls do |t|
+      t.string :job_id, null: false
+      t.string :status, null: false, default: "queued"
+      t.datetime :cancel_requested_at
+      t.datetime :started_at
+      t.datetime :finished_at
+      t.datetime :last_checkpoint_at
+      t.datetime :heartbeat_at
+      t.json :metadata, null: false, default: {}
+      t.timestamps
+    end
+
+    add_index :job_controls, :job_id, unique: true
+  end
+end

data/lib/generators/job_control/install/install_generator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module JobControl
+  module Generators
+    # Installs JobControl database migrations into the host application.
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("../../../../db/migrate", __dir__)
+
+      def copy_migrations
+        migration_directory = File.join(destination_root, "db/migrate")
+
+        Dir.glob(File.join(self.class.source_root, "*.rb")).each do |path|
+          filename = File.basename(path)
+          migration_name = filename.sub(/\A\d+_/, "").delete_suffix(".rb")
+          next if self.class.migration_exists?(migration_directory, migration_name)
+
+          migration_template filename, "db/migrate/#{migration_name}.rb"
+        end
+      end
+
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+    end
+  end
+end

data/lib/job_control/adapters/solid_queue.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module JobControl
+  module Adapters
+    # Removes controls when Solid Queue permanently discards jobs.
+    module SolidQueue
+      # Internal instance hook for one discarded execution.
+      module ExecutionMethods
+        def discard
+          active_job_id = job.active_job_id
+          super.tap { Adapter.delete_control(active_job_id) }
+        end
+      end
+
+      # Internal class hooks for batch discard operations.
+      module ExecutionClassMethods
+        def discard_all_in_batches(batch_size: 500)
+          pending = count
+          discarded = 0
+
+          ::SolidQueue.instrument(:discard_all, batch_size: batch_size, status: type, batches: 0, size: 0) do |payload|
+            loop do
+              discarded, active_job_ids = discard_batch(batch_size, payload)
+              pending -= discarded
+              Adapter.delete_controls(active_job_ids)
+
+              break if pending <= 0 || discarded.zero?
+            end
+          end
+        end
+
+        def discard_all_from_jobs(jobs)
+          active_job_ids = []
+
+          ::SolidQueue.instrument(:discard_all, jobs_size: jobs.size, status: type) do |payload|
+            transaction do
+              job_ids = send(:lock_all_from_jobs, jobs)
+              active_job_ids = ::SolidQueue::Job.where(id: job_ids).pluck(:active_job_id)
+              payload[:size] = send(:discard_jobs, job_ids)
+              where(job_id: job_ids).delete_all
+            end
+          end
+          Adapter.delete_controls(active_job_ids)
+        end
+
+        private
+
+        def discard_batch(batch_size, payload)
+          active_job_ids = []
+          discarded = 0
+
+          transaction do
+            job_ids = limit(batch_size).order(:job_id).lock.pluck(:job_id)
+            active_job_ids = ::SolidQueue::Job.where(id: job_ids).pluck(:active_job_id)
+            discarded = send(:discard_jobs, job_ids)
+            where(job_id: job_ids).delete_all
+            payload[:size] += discarded
+            payload[:batches] += 1
+          end
+
+          [discarded, active_job_ids]
+        end
+      end
+
+      # Public installer and cross-database cleanup boundary.
+      module Adapter
+        SUPPORTED_VERSIONS = Gem::Requirement.new(">= 1.4", "< 1.8").freeze
+
+        module_function
+
+        def install!
+          verify_dependency!
+          ::SolidQueue::Execution.prepend(ExecutionMethods) unless ::SolidQueue::Execution < ExecutionMethods
+          singleton_class = ::SolidQueue::Execution.singleton_class
+          singleton_class.prepend(ExecutionClassMethods) unless singleton_class < ExecutionClassMethods
+        end
+
+        def delete_control(active_job_id)
+          delete_controls([active_job_id])
+        end
+
+        def delete_controls(active_job_ids)
+          ids = active_job_ids.compact
+          return if ids.empty?
+
+          JobControl::Control.where(job_id: ids).delete_all
+        end
+
+        def verify_dependency!
+          unless defined?(::SolidQueue::Execution) && defined?(::SolidQueue::Job)
+            raise LoadError, "JobControl Solid Queue adapter requires the solid_queue gem to be loaded"
+          end
+
+          version = Gem.loaded_specs.fetch("solid_queue").version
+          return if SUPPORTED_VERSIONS.satisfied_by?(version)
+
+          raise ConfigurationError, "JobControl Solid Queue adapter supports solid_queue #{SUPPORTED_VERSIONS}"
+        end
+      end
+    end
+  end
+end

data/lib/job_control/cancellation.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module JobControl
+  # A small cancellation token suitable for passing into application services.
+  class Cancellation
+    def initialize(control)
+      @control = control
+    end
+
+    def requested? = @control.reload.cancel_requested?
+    def checkpoint! = @control.checkpoint!
+  end
+end

data/lib/job_control/cancelled.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module JobControl
+  # Internal control-flow exception, deliberately not treated as job failure.
+  class Cancelled < StandardError; end
+end

data/lib/job_control/configuration.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module JobControl
+  # Process-wide settings for the control runtime.
+  class Configuration
+    attr_accessor :stale_after
+
+    def initialize
+      @stale_after = 5.minutes
+    end
+  end
+end

data/lib/job_control/control.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module JobControl
+  # Independent from a host application's base model and default scopes.
+  class Control < ActiveRecord::Base
+    self.table_name = "job_controls"
+
+    STATUSES = %w[queued running cancel_requested cancelled succeeded failed].freeze
+    COMPLETED_STATUSES = %w[cancelled succeeded].freeze
+
+    validates :job_id, presence: true
+    validates :status, inclusion: { in: STATUSES }
+
+    def controlled? = true
+    def cancellable? = status.in?(%w[queued running])
+    def cancel_requested? = cancel_requested_at.present?
+
+    def stale?
+      heartbeat_at.present? && heartbeat_at < JobControl.configuration.stale_after.ago
+    end
+
+    alias stalled? stale?
+
+    def cancel!
+      with_lock do
+        return self unless cancellable?
+
+        update!(cancel_requested_at: Time.current, status: "cancel_requested")
+      end
+      JobControl.instrument(:cancel_requested, self)
+      self
+    end
+
+    def mark_running!
+      return self if COMPLETED_STATUSES.include?(status)
+
+      update!(status: cancel_requested? ? "cancel_requested" : "running", started_at: started_at || Time.current)
+      JobControl.instrument(:started, self)
+      self
+    end
+
+    def mark_succeeded! = finish!("succeeded", :succeeded)
+    def mark_cancelled! = finish!("cancelled", :cancelled)
+    def mark_failed! = finish!("failed", :failed)
+
+    def checkpoint!
+      reload
+      now = Time.current
+      update_columns(last_checkpoint_at: now, heartbeat_at: now, updated_at: now)
+      JobControl.instrument(:checkpoint, self)
+      raise Cancelled if cancel_requested?
+
+      self
+    end
+
+    private
+
+    def finish!(next_status, event)
+      update!(status: next_status, finished_at: Time.current)
+      JobControl.instrument(event, self)
+      delete
+    end
+  end
+end

data/lib/job_control/engine.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module JobControl
+  # Registers the gem as a Rails engine; installation is performed by its generator.
+  class Engine < ::Rails::Engine
+  end
+end

data/lib/job_control/integrations/mission_control_jobs/client.js

@@ -0,0 +1,125 @@
+(() => {
+  const configuration = window.JobControlMissionControl;
+  const sectionId = "job-control-mission-control-panel";
+  const jobPath = /\/jobs\/([^/]+)\/?$/;
+
+  const statusPresentation = {
+    queued: ["Queued", "is-light"],
+    running: ["Running", "is-primary"]
+  };
+
+  const createElement = (name, { className, text } = {}) => {
+    const element = document.createElement(name);
+    if (className) element.className = className;
+    if (text) element.textContent = text;
+    return element;
+  };
+
+  const currentJobId = () => window.location.pathname.match(jobPath)?.[1];
+
+  const detailContainer = () => document.querySelector("main") || document.querySelector("[role=main]") || document.body;
+
+  const controlEndpoint = (jobId) => `${configuration.endpoint_prefix}/${encodeURIComponent(jobId)}`;
+
+  const requestControl = async (endpoint) => {
+    const response = await fetch(endpoint, {
+      headers: { Accept: "application/json" },
+      credentials: "same-origin"
+    });
+
+    return response.ok ? response.json() : null;
+  };
+
+  const statusTag = (control) => {
+    const [label, className] = control.cancel_requested ?
+      ["Cancellation requested", "is-warning"] :
+      (statusPresentation[control.status] || [control.status, "is-light"]);
+
+    return createElement("span", { className: `tag ${className}`, text: label });
+  };
+
+  const addTableRow = (body, label, value) => {
+    const row = document.createElement("tr");
+    const heading = createElement("th", { text: label });
+    const detail = document.createElement("td");
+    if (typeof value === "string") detail.textContent = value;
+    else detail.appendChild(value);
+    row.append(heading, detail);
+    body.appendChild(row);
+  };
+
+  const cancellationForm = (endpoint) => {
+    const form = document.createElement("form");
+    form.method = "post";
+    form.action = `${endpoint}/cancel`;
+
+    const csrfToken = document.querySelector("meta[name=csrf-token]")?.content;
+    if (csrfToken) {
+      const input = document.createElement("input");
+      input.type = "hidden";
+      input.name = "authenticity_token";
+      input.value = csrfToken;
+      form.appendChild(input);
+    }
+
+    const button = createElement("button", {
+      className: "button is-warning is-light",
+      text: "Request cancellation"
+    });
+    button.type = "submit";
+    button.addEventListener("click", (event) => {
+      if (!window.confirm("Request cooperative cancellation for this job?")) event.preventDefault();
+    });
+    form.appendChild(button);
+    return form;
+  };
+
+  const cancellationAction = (endpoint) => {
+    const action = createElement("div", { className: "is-flex is-align-items-center is-flex-wrap-wrap" });
+    const hint = createElement("span", {
+      className: "has-text-grey is-size-7 ml-3",
+      text: "Takes effect at the next checkpoint."
+    });
+    action.append(cancellationForm(endpoint), hint);
+    return action;
+  };
+
+  const controlSection = (control, endpoint) => {
+    const section = document.createElement("section");
+    section.id = sectionId;
+
+    const title = createElement("h2", { className: "subtitle", text: "Job control" });
+    const table = createElement("table", { className: "table" });
+    const body = document.createElement("tbody");
+
+    addTableRow(body, "Control status", statusTag(control));
+    addTableRow(body, "Heartbeat", control.heartbeat_at || "Not reported");
+    addTableRow(body, "Last checkpoint", control.last_checkpoint_at || "Not reported");
+    if (control.cancellable) addTableRow(body, "Actions", cancellationAction(endpoint));
+
+    table.appendChild(body);
+    section.append(title, table);
+    return section;
+  };
+
+  const render = async () => {
+    if (document.getElementById(sectionId)) return;
+
+    const jobId = currentJobId();
+    const container = detailContainer();
+    const generalInformation = container.querySelector("table.table");
+    if (!jobId || !generalInformation) return;
+
+    try {
+      const endpoint = controlEndpoint(jobId);
+      const control = await requestControl(endpoint);
+      if (control && !document.getElementById(sectionId)) {
+        generalInformation.insertAdjacentElement("afterend", controlSection(control, endpoint));
+      }
+    } catch (_error) {
+    }
+  };
+
+  document.addEventListener("DOMContentLoaded", render);
+  document.addEventListener("turbo:load", render);
+})();

data/lib/job_control/integrations/mission_control_jobs/client_script.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module JobControl
+  module Integrations
+    module MissionControlJobs
+      # Loads the browser client injected into Mission Control responses.
+      module ClientScript
+        module_function
+
+        def source
+          File.read(File.join(__dir__, "client.js"))
+        end
+      end
+    end
+  end
+end

data/lib/job_control/integrations/mission_control_jobs/middleware.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "client_script"
+
+module JobControl
+  module Integrations
+    module MissionControlJobs
+      # Adds the JobControl client without replacing Mission Control templates.
+      class Middleware
+        def initialize(app)
+          @app = app
+        end
+
+        def call(environment)
+          status, headers, body = @app.call(environment)
+          return [status, headers, body] unless inject?(status, headers)
+
+          response = +""
+          body.each { |chunk| response << chunk }
+          body.close if body.respond_to?(:close)
+          headers.delete("content-length")
+          [status, headers, [inject(response, environment)]]
+        end
+
+        private
+
+        def inject?(status, headers)
+          status == 200 && headers.fetch("content-type", "").start_with?("text/html")
+        end
+
+        def inject(response, environment)
+          configuration = JSON.generate(endpoint_prefix: MissionControlJobs.endpoint_prefix)
+          nonce = nonce_attribute(environment)
+          scripts = [
+            "<script#{nonce}>window.JobControlMissionControl=#{configuration};</script>",
+            "<script#{nonce}>#{ClientScript.source}</script>"
+          ].join
+          response.sub(%r{</head>}i, "#{scripts}</head>")
+        end
+
+        def nonce_attribute(environment)
+          nonce = environment["action_dispatch.content_security_policy_nonce"]
+          nonce ? " nonce=\"#{ERB::Util.html_escape(nonce)}\"" : ""
+        end
+      end
+    end
+  end
+end

data/lib/job_control/integrations/mission_control_jobs.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "mission_control_jobs/middleware"
+
+module JobControl
+  module Integrations
+    # Optional UI and cancellation endpoint for Mission Control Jobs 1.x.
+    module MissionControlJobs
+      ROUTE_NAME = :job_control_mission_control_cancel
+      SUPPORTED_VERSIONS = Gem::Requirement.new(">= 1.3", "< 2.0").freeze
+
+      class << self
+        attr_reader :mount_path
+
+        def install!(mount_path: "/admin/jobs")
+          verify_dependency!
+          requested_mount_path = normalize_mount_path(mount_path)
+
+          if @route_installed && @mount_path != requested_mount_path
+            raise ConfigurationError, "Mission Control integration is already installed at #{@mount_path}"
+          end
+
+          @mount_path = requested_mount_path
+          install_middleware!
+          install_routes!
+        end
+
+        def endpoint_prefix = "#{mount_path}/job_controls"
+
+        private
+
+        def install_middleware!
+          return if @middleware_installed
+
+          ::MissionControl::Jobs::Engine.middleware.use Middleware
+          @middleware_installed = true
+        end
+
+        def install_routes!
+          return if @route_installed
+
+          Rails.application.routes.append do
+            get "#{JobControl::Integrations::MissionControlJobs.endpoint_prefix}/:job_id",
+                to: "job_control/mission_control_jobs#show", as: :job_control_mission_control
+            post "#{JobControl::Integrations::MissionControlJobs.endpoint_prefix}/:job_id/cancel",
+                 to: "job_control/mission_control_jobs#cancel", as: ROUTE_NAME
+          end
+          @route_installed = true
+        end
+
+        def normalize_mount_path(path)
+          value = path.to_s.sub(%r{/\z}, "")
+          raise ArgumentError, "mount_path must not be empty" if value.empty?
+
+          value.start_with?("/") ? value : "/#{value}"
+        end
+
+        def verify_dependency!
+          unless defined?(::MissionControl::Jobs::Engine)
+            raise LoadError, "JobControl Mission Control integration requires the mission_control-jobs gem to be loaded"
+          end
+
+          return if SUPPORTED_VERSIONS.satisfied_by?(Gem::Version.new(::MissionControl::Jobs::VERSION))
+
+          raise ConfigurationError,
+                "JobControl Mission Control integration supports mission_control-jobs #{SUPPORTED_VERSIONS}"
+        end
+      end
+    end
+  end
+end

data/lib/job_control/job.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module JobControl
+  # Active Job lifecycle callbacks and runtime primitives.
+  module Job
+    extend ActiveSupport::Concern
+
+    included do
+      before_enqueue { |job| JobControl.register(job.job_id) }
+
+      around_perform do |job, perform|
+        control = JobControl.register(job.job_id)
+        control.mark_running!
+
+        begin
+          control.checkpoint!
+          perform.call
+          control.reload.mark_succeeded!
+        rescue Cancelled
+          control.reload.mark_cancelled!
+        rescue StandardError
+          safely_mark_failed(control)
+          raise
+        end
+      end
+    end
+
+    def control = (@control ||= JobControl.find(job_id))
+    def checkpoint! = control.checkpoint!
+    def cancellation = (@cancellation ||= Cancellation.new(control))
+
+    private
+
+    def safely_mark_failed(control)
+      control.reload
+      return if control.cancel_requested?
+
+      control.mark_failed!
+    rescue ActiveRecord::ActiveRecordError
+      # Preserve the application's exception when state persistence is unavailable.
+    end
+  end
+end

data/lib/job_control/version.rb

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

data/lib/job_control.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/notifications"
+require "active_support/core_ext/numeric/time"
+require "active_record"
+require "active_job"
+
+require_relative "job_control/version"
+require_relative "job_control/cancelled"
+require_relative "job_control/configuration"
+require_relative "job_control/cancellation"
+require_relative "job_control/control"
+require_relative "job_control/job"
+require_relative "job_control/engine" if defined?(Rails::Engine)
+
+# Runtime controls for long-running Active Job jobs.
+module JobControl
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+      configuration
+    end
+
+    def find(job_id) = Control.find_by!(job_id: job_id)
+    def cancel(job_id) = find(job_id).cancel!
+    def register(job_id) = Control.create_or_find_by!(job_id: job_id)
+
+    def instrument(event, control)
+      ActiveSupport::Notifications.instrument("job_control.#{event}", control: control)
+    end
+  end
+end

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: job_control
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Manh Kha
+bindir: exe
+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: '8.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+description: Cancellation, progress, checkpoints, heartbeats, and lifecycle tracking
+  for Active Job.
+email:
+- kha.manhthai@wogi.biz
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- app/controllers/job_control/mission_control_jobs_controller.rb
+- config/locales/job_control.en.yml
+- db/migrate/20260924000000_create_job_controls.rb
+- lib/generators/job_control/install/install_generator.rb
+- lib/job_control.rb
+- lib/job_control/adapters/solid_queue.rb
+- lib/job_control/cancellation.rb
+- lib/job_control/cancelled.rb
+- lib/job_control/configuration.rb
+- lib/job_control/control.rb
+- lib/job_control/engine.rb
+- lib/job_control/integrations/mission_control_jobs.rb
+- lib/job_control/integrations/mission_control_jobs/client.js
+- lib/job_control/integrations/mission_control_jobs/client_script.rb
+- lib/job_control/integrations/mission_control_jobs/middleware.rb
+- lib/job_control/job.rb
+- lib/job_control/version.rb
+homepage: https://github.com/kha-wogi/job_control
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/kha-wogi/job_control
+  changelog_uri: https://github.com/kha-wogi/job_control/blob/main/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.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Cooperative runtime control for long-running Active Job jobs
+test_files: []