jidoka 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 856c4e4436542b548e463c61551160030fd4baf16c25c78a0ff1868f55b0193e
+  data.tar.gz: '0849949d4d82447b878a348d575bc36bba70c11ed64a987093a482a9627a575e'
+SHA512:
+  metadata.gz: 56f3274112e8f9e1afb3ff0c0e9e35c670a2baf4248dd46eced87429e5f3f6286d11c08ab9d79ca8f453d58a29f86763e3baa23800a11168ae94dfad068e159c
+  data.tar.gz: 17acb1f17bf45281cc1265a883bf44772270a5c0bfe24e904109dbb0af32f6ae778454652b55a9f2cb1cdb4db82a1ec5bd04360221372178d917c5d51fefe492

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+.idea

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.ruby-version

@@ -0,0 +1 @@
+3.4.2

data/.travis.yml

@@ -0,0 +1,7 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.6.3
+before_install: gem install bundler -v 1.17.2

data/Gemfile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in jidoka.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,125 @@
+PATH
+  remote: .
+  specs:
+    jidoka (0.2.0)
+      activejob (>= 6.0)
+      activerecord (>= 6.0)
+      activesupport (>= 6.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activejob (8.1.2)
+      activesupport (= 8.1.2)
+      globalid (>= 0.3.6)
+    activemodel (8.1.2)
+      activesupport (= 8.1.2)
+    activerecord (8.1.2)
+      activemodel (= 8.1.2)
+      activesupport (= 8.1.2)
+      timeout (>= 0.4.0)
+    activesupport (8.1.2)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      json
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    base64 (0.3.0)
+    bigdecimal (4.0.1)
+    coderay (1.1.3)
+    concurrent-ruby (1.3.6)
+    connection_pool (3.0.2)
+    diff-lcs (1.6.2)
+    drb (2.2.3)
+    globalid (1.3.0)
+      activesupport (>= 6.1)
+    i18n (1.14.8)
+      concurrent-ruby (~> 1.0)
+    io-console (0.8.2)
+    json (2.18.0)
+    logger (1.7.0)
+    method_source (1.1.0)
+    minitest (6.0.1)
+      prism (~> 1.5)
+    prism (1.9.0)
+    pry (0.16.0)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+      reline (>= 0.6.0)
+    rake (13.3.1)
+    reline (0.6.3)
+      io-console (~> 0.5)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.7)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    securerandom (0.4.1)
+    sqlite3 (2.9.0-arm64-darwin)
+    timeout (0.6.0)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    uri (1.1.1)
+
+PLATFORMS
+  arm64-darwin-23
+
+DEPENDENCIES
+  jidoka!
+  pry
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  sqlite3
+
+CHECKSUMS
+  activejob (8.1.2) sha256=908dab3713b101859536375819f4156b07bdf4c232cc645e7538adb9e302f825
+  activemodel (8.1.2) sha256=e21358c11ce68aed3f9838b7e464977bc007b4446c6e4059781e1d5c03bcf33e
+  activerecord (8.1.2) sha256=acfbe0cadfcc50fa208011fe6f4eb01cae682ebae0ef57145ba45380c74bcc44
+  activesupport (8.1.2) sha256=88842578ccd0d40f658289b0e8c842acfe9af751afee2e0744a7873f50b6fdae
+  base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
+  bigdecimal (4.0.1) sha256=8b07d3d065a9f921c80ceaea7c9d4ae596697295b584c296fe599dd0ad01c4a7
+  coderay (1.1.3) sha256=dc530018a4684512f8f38143cd2a096c9f02a1fc2459edcfe534787a7fc77d4b
+  concurrent-ruby (1.3.6) sha256=6b56837e1e7e5292f9864f34b69c5a2cbc75c0cf5338f1ce9903d10fa762d5ab
+  connection_pool (3.0.2) sha256=33fff5ba71a12d2aa26cb72b1db8bba2a1a01823559fb01d29eb74c286e62e0a
+  diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
+  drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
+  globalid (1.3.0) sha256=05c639ad6eb4594522a0b07983022f04aa7254626ab69445a0e493aa3786ff11
+  i18n (1.14.8) sha256=285778639134865c5e0f6269e0b818256017e8cde89993fdfcbfb64d088824a5
+  io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
+  jidoka (0.2.0)
+  json (2.18.0) sha256=b10506aee4183f5cf49e0efc48073d7b75843ce3782c68dbeb763351c08fd505
+  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  method_source (1.1.0) sha256=181301c9c45b731b4769bc81e8860e72f9161ad7d66dd99103c9ab84f560f5c5
+  minitest (6.0.1) sha256=7854c74f48e2e975969062833adc4013f249a4b212f5e7b9d5c040bf838d54bb
+  prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
+  pry (0.16.0) sha256=d76c69065698ed1f85e717bd33d7942c38a50868f6b0673c636192b3d1b6054e
+  rake (13.3.1) sha256=8c9e89d09f66a26a01264e7e3480ec0607f0c497a861ef16063604b1b08eb19c
+  reline (0.6.3) sha256=1198b04973565b36ec0f11542ab3f5cfeeec34823f4e54cebde90968092b1835
+  rspec (3.13.2) sha256=206284a08ad798e61f86d7ca3e376718d52c0bc944626b2349266f239f820587
+  rspec-core (3.13.6) sha256=a8823c6411667b60a8bca135364351dda34cd55e44ff94c4be4633b37d828b2d
+  rspec-expectations (3.13.5) sha256=33a4d3a1d95060aea4c94e9f237030a8f9eae5615e9bd85718fe3a09e4b58836
+  rspec-mocks (3.13.7) sha256=0979034e64b1d7a838aaaddf12bf065ea4dc40ef3d4c39f01f93ae2c66c62b1c
+  rspec-support (3.13.7) sha256=0640e5570872aafefd79867901deeeeb40b0c9875a36b983d85f54fb7381c47c
+  securerandom (0.4.1) sha256=cc5193d414a4341b6e225f0cb4446aceca8e50d5e1888743fac16987638ea0b1
+  sqlite3 (2.9.0-arm64-darwin) sha256=a917bd9b84285766ff3300b7d79cd583f5a067594c8c1263e6441618c04a6ed3
+  timeout (0.6.0) sha256=6d722ad619f96ee383a0c557ec6eb8c4ecb08af3af62098a0be5057bf00de1af
+  tzinfo (2.0.6) sha256=8daf828cc77bcf7d63b0e3bdb6caa47e2272dcfaf4fbfe46f8c3a9df087a829b
+  uri (1.1.1) sha256=379fa58d27ffb1387eaada68c749d1426738bd0f654d812fcc07e7568f5c57c6
+
+BUNDLED WITH
+  4.0.5

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Nate Mortensen
+
+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,58 @@
+# Jidoka
+
+Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/jidoka`. To experiment with that code, run `bin/console` for an interactive prompt.
+
+TODO: Delete this and the text above, and describe your gem
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'jidoka'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install jidoka
+
+## Usage
+
+Add an initializer to configure Jidoka:
+
+```ruby
+# config/initializers/jidoka.rb
+Jidoka.configure do |config|
+  # Inherit from your app's base job to get queues, retries, etc.
+  config.parent_job_class = "ApplicationJob" 
+  
+  # Hook into your error reporting tool
+  config.error_handler = ->(e, context) {
+    if defined?(Sentry)
+      Sentry.set_context('jidoka', context)
+      Sentry.capture_exception(e)
+      Sentry::Context.clear!
+    else
+      Rails.logger.error("Jidoka Error: #{e.message} Context: #{context}")
+    end
+  }
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/jidoka.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'jidoka'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/jidoka.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "lib/jidoka/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "jidoka"
+  spec.version       = Jidoka::VERSION
+  spec.authors       = ["Nate Mortensen"]
+  spec.summary       = "Reversible Command and Orchestrator patterns for Rails."
+  spec.description   = "Encapsulate complex business logic with automatic rollback, validation, and background processing."
+  spec.homepage      = "https://github.com/natemortensen/jidoka"
+  spec.license       = "MIT"
+
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.add_dependency "activejob", ">= 6.0"
+  spec.add_dependency "activerecord", ">= 6.0"
+  spec.add_dependency "activesupport", ">= 6.0"
+
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "sqlite3"
+end

data/lib/jidoka/errors.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Jidoka
+  # Raised when rollback (down) fails
+  class IrreversibleAction < StandardError; end
+
+  # Raised when enforce_arguments! validation fails
+  class ArgumentClassMismatch < StandardError
+    attr_reader :param, :expected, :actual
+
+    def initialize(argument, expected:, actual:)
+      @param = argument
+      @expected = expected
+      @actual = actual
+      super("#{param} was expected to be a(n) #{@expected} but was a(n) #{@actual || 'nil'}")
+    end
+  end
+
+  # Raised when business logic conditions are not met (Validation phase)
+  class ConditionNotMet < StandardError
+    attr_reader :code
+
+    def initialize(code:, message:)
+      @code = code
+      super(message)
+    end
+  end
+
+  # Raised when execution fails for a known reason (Execution phase)
+  class Failure < StandardError
+    attr_reader :code, :context
+
+    def initialize(code:, message:, context: {})
+      @code = code
+      @context = context
+      super(message)
+    end
+  end
+end

data/lib/jidoka/notifiable.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Jidoka
+  module Notifiable
+    extend ActiveSupport::Concern
+
+    included do
+      def send_notification
+        notify(@opts)
+
+      # These are just notifications so they can silently fail but still report error
+      rescue StandardError => e
+        capture_error(e)
+      end
+
+      def notify(**_opts); end
+    end
+  end
+end

data/lib/jidoka/supervisor/step.rb

@@ -0,0 +1,31 @@
+module Jidoka
+  class Supervisor < Commander
+    class Step
+      attr_reader :result
+
+      def initialize(caller)
+        @caller = caller
+      end
+
+      def up(&block)
+        @result = @caller.instance_eval(&block)
+      end
+
+      def _down
+        @caller.instance_exec(@result, &@down) if @down.present?
+      end
+
+      def down(&block)
+        @down = block
+      end
+
+      def _notify
+        @caller.instance_exec(@result, &@notify) if @notify.present?
+      end
+
+      def notify(&block)
+        @notify = block
+      end
+    end
+  end
+end

data/lib/jidoka/supervisor.rb

@@ -0,0 +1,94 @@
+require_relative "supervisor/step"
+
+module Jidoka
+  class Supervisor < Commander
+    def initialize(*args)
+      super(*args)
+      @steps = []
+    end
+
+    def run!
+      orchestrate(**@opts)
+    rescue StandardError => e
+      rollback
+      # notice_failure! is called in run! wrapper of super, but we need to ensure
+      # we notice it here if we want to log it before re-raising
+      send(:notice_failure!, e)
+      raise(e)
+    end
+
+    def rollback
+      @steps.reverse_each do |step|
+        begin
+          step._down
+        rescue StandardError => e
+          report_error(e)
+        end
+      end
+    end
+
+    # Alias for compatibility
+    def down
+      rollback
+    end
+
+    def notify!
+      @steps.each(&:_notify)
+      _notify(**@opts)
+    rescue StandardError => e
+      report_error(e)
+      raise(e) if defined?(Rails) && Rails.env.test?
+    end
+
+    protected
+
+    def step!(&block)
+      step = Step.new(self)
+      begin
+        step.instance_eval(&block)
+      rescue StandardError => e
+        @message = e.message
+        raise(e)
+      end
+
+      @steps << step
+      step.result
+    end
+
+    def worker_step!(klass, opts = {})
+      step! do
+        up { klass.run!(**opts.merge(notify: false)) }
+        down(&:down) # Calls down on the worker instance returned by up
+        notify(&:notify!) unless opts[:notify] == false
+      end
+    end
+
+    def update_record_step!(record, updates)
+      previous_state = updates.to_h do |k, v|
+        [
+          k,
+          k.to_s =~ /_attributes/ ? v.class.new : record.send(k)
+        ]
+      end
+
+      step! do
+        up { record.tap { record.update!(updates) } }
+        down { record.tap { record.update!(previous_state) } }
+      end
+    end
+
+    def create_record_step!(&block)
+      step! do
+        up(&block)
+        down do |record|
+          record.reload.destroy!
+        end
+      end
+    end
+
+    # Abstract method to be implemented by subclass
+    def orchestrate(**_opts)
+      raise NotImplementedError
+    end
+  end
+end

data/lib/jidoka/validatable.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Jidoka
+  module Validatable
+    extend ActiveSupport::Concern
+
+    included do
+      attr_reader :message, :error
+
+      ##
+      # This is a Hash of required argument keys and their expected class
+      class_attribute :argument_types, :errors
+
+      def validate!
+        validate_arguments!(@opts)
+        prepare(@opts)
+        audit(@opts)
+      rescue ConditionNotMet, ArgumentClassMismatch, Failure => e
+        notice_failure(e)
+        raise(e)
+      end
+
+      def validate
+        validate!
+      rescue StandardError => e
+        notice_failure(e)
+      end
+
+      def notice_failure(e)
+        @failure = true
+        @error = e
+        @message = e.message
+
+        capture_error(error)
+      end
+
+      def capture_error(error); end
+
+      def failure?
+        !@failure.nil?
+      end
+
+      def failed
+        yield(self) if failure?
+      end
+
+      def success?
+        !failure?
+      end
+
+      def succeeded
+        yield(self) if success?
+      end
+
+      def audit(**_opts); end
+
+      ##
+      # Raises `ConditionNotMet` with specified error message if block does not return a truthy value.
+      # Intended for use with `audit`
+      def valid_if(error_key, message: nil)
+        raise_condition!(error_key, message: message) unless yield
+      end
+
+      ##
+      # Raises `ConditionNotMet` with specified error message if block does not return a falsey value.
+      # Intended for use with `audit`
+      def valid_unless(error_key, message: nil)
+        raise_condition!(error_key, message: message) if yield
+      end
+
+      def raise_condition!(key, message: nil)
+        raise ConditionNotMet.new(
+          message: message || self.class.possible_errors[key],
+          code: key
+        )
+      end
+
+      def fail!(key, message: nil)
+        raise Failure.new(
+          message: message || self.class.possible_errors[key],
+          code: key
+        )
+      end
+
+      # Iterate through `argument_types` checking for a class match
+      def validate_arguments!(**args)
+        return if self.class.argument_types.nil?
+
+        self.class.argument_types.each do |key, klass|
+          case args[key]
+          when *Array(klass).map(&:constantize) then nil # Object is okay
+          else raise ArgumentClassMismatch.new(key, expected: klass, actual: args[key]&.class&.to_s)
+          end
+        end
+      end
+    end
+
+    class_methods do
+      def enforce_arguments!(obj)
+        self.argument_types = obj.freeze
+      end
+
+      def set_errors(obj)
+        self.errors = (errors || {}).merge(obj)
+      end
+
+      def possible_errors(with_prefix = false)
+        @possible_errors ||= errors || {}
+        with_prefix ? @possible_errors.transform_keys { |k| [to_s.underscore, k].join('-') } : @possible_errors
+      end
+    end
+  end
+end

data/lib/jidoka/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Jidoka
+  VERSION = '0.2.0'
+end

data/lib/jidoka/worker.rb

@@ -0,0 +1,239 @@
+module Jidoka
+  class Commander < Jidoka.configuration.parent_job_class.constantize
+    include ActiveSupport::Rescuable
+
+    # @return [String] Error message to display to end users
+    attr_reader :message, :error
+
+    class_attribute :argument_types
+
+    # Shared error messages available to all Commanders
+    BASE_ERRORS = {
+      invalid_state_transition: 'You cannot transition to this state',
+      action_already_performed: 'This action has already been performed'
+    }.freeze
+
+    # Default ERRORS hash to be overridden by subclasses
+    ERRORS = {}.freeze
+
+    # -- Class Methods --
+
+    def self.enforce_arguments!(obj)
+      self.argument_types = obj.freeze
+    end
+
+    def self.possible_errors(with_prefix = false)
+      @possible_errors ||= self::ERRORS
+      with_prefix ? @possible_errors.transform_keys { |k| [to_s.underscore, k].join('-') } : @possible_errors
+    end
+
+    def self.run!(opts = {})
+      initialize_and_call!(opts, :validate!, :run!, *include_notify?(opts))
+    end
+
+    def self.run(opts = {})
+      initialize_and_call!(opts, :validate, :run, *include_notify?(opts)).tap do |result|
+        yield(result) if block_given?
+      end
+    end
+
+    def self.dry_run!(opts = {})
+      initialize_and_call!(opts, :validate!)
+    end
+
+    def self.dry_run(opts = {})
+      initialize_and_call!(opts, :validate)
+    end
+
+    def self.undo!(opts = {})
+      initialize_and_call!(opts, :undo!)
+    end
+
+    def self.undo(opts = {})
+      initialize_and_call!(opts, :undo).tap do |result|
+        yield(result) if block_given?
+      end
+    end
+
+    def self.include_notify?(opts)
+      [nil, true].include?(opts.delete(:notify)) ? %i[notify!] : []
+    end
+
+    def self.initialize_and_call!(opts, *methods_to_call)
+      instance = new(opts.transform_keys(&:to_sym))
+      methods_to_call.each do |m|
+        instance.send(m)
+        break if instance.failure?
+      end
+      instance
+    end
+
+    # -- Instance Methods --
+
+    def initialize(args = nil)
+      super
+      # Handle ActiveJob vs direct instantiation args
+      @opts = args || (arguments ? arguments[0] : {})
+      @opts = @opts.transform_keys(&:to_sym) if @opts
+    end
+
+    def perform(opts = {})
+      @opts = opts.transform_keys(&:to_sym)
+      validate!
+      run!
+      notify!
+    end
+
+    def prepare(opts); end
+
+    def validate!
+      validate_arguments!(**@opts)
+      prepare(**@opts)
+      validate_conditions!(**@opts)
+    rescue Jidoka::ConditionNotMet, Jidoka::ArgumentClassMismatch, Jidoka::Failure => e
+      notice_failure!(e)
+      raise(e)
+    end
+
+    def validate
+      validate!
+    rescue StandardError => e
+      notice_failure!(e)
+    end
+
+    def run!
+      ActiveRecord::Base.transaction { up(**@opts) }
+    rescue Jidoka::ConditionNotMet, Jidoka::Failure => e
+      notice_failure!(e)
+      raise(e)
+    end
+
+    def run
+      run!
+    rescue StandardError => e
+      notice_failure!(e)
+    end
+
+    def undo!
+      prepare_inverse(**@opts) if respond_to?(:prepare_inverse)
+      ActiveRecord::Base.transaction { down }
+    rescue Jidoka::ConditionNotMet, Jidoka::Failure => e
+      notice_failure!(e)
+      raise(e)
+    end
+
+    def undo
+      undo!
+    rescue StandardError => e
+      notice_failure!(e)
+    end
+
+    def up(_opts = nil)
+      raise NotImplementedError
+    end
+
+    def down; end
+
+    def notify!
+      _notify(**@opts)
+    rescue StandardError => e
+      report_error(e)
+      # We do not re-raise notification errors by default unless in test
+      raise(e) if defined?(Rails) && Rails.env.test?
+    end
+
+    def _notify(**_opts); end
+
+    # -- State Helpers --
+
+    def failure?
+      @failure.present?
+    end
+
+    def success?
+      !failure?
+    end
+
+    def failed
+      yield(self) if failure?
+    end
+
+    def success
+      yield(self) if success?
+    end
+
+    protected
+
+    def validate_conditions!(**opts); end
+
+    def condition!(key, message: nil)
+      raise_condition!(key, message: message) unless yield
+    end
+
+    def raise_condition!(key, message: nil)
+      raise Jidoka::ConditionNotMet.new(
+        message: message || self.class.possible_errors[key],
+        code: [self.class.to_s.underscore, key].join('-')
+      )
+    end
+
+    def fail!(key, message: nil, **context)
+      raise Jidoka::Failure.new(
+        message: message || self.class.possible_errors[key],
+        code: [self.class.to_s.underscore, key].join('-'),
+        context: context
+      )
+    end
+
+    def validate_arguments!(**args)
+      return if self.class.argument_types.nil?
+
+      self.class.argument_types.each do |key, klass_name|
+        val = args[key]
+        expected_classes = Array(klass_name).map(&:constantize)
+
+        # Check if value matches any of the expected classes
+        unless expected_classes.any? { |k| val.is_a?(k) }
+          raise Jidoka::ArgumentClassMismatch.new(key, expected: klass_name, actual: val.class.to_s)
+        end
+      end
+    end
+
+    # Validates usage of AASM state machines if AASM is present
+    def aasm_event_condition!(object, event)
+      return unless defined?(AASM)
+
+      matched = object.class.aasm.events.detect { |e| e.name.to_s == event.to_s }
+      return if matched.may_fire?(object)
+
+      if matched.transitions[0].to == object.aasm.current_state
+        raise_condition!(
+          :action_already_performed,
+          message: "This #{object.class.to_s.humanize} is already #{object.try(:status)&.humanize || 'in that state'}"
+        )
+      else
+        raise_condition!(
+          :invalid_state_transition,
+          message: "Could not #{event} because current status is #{object.try(:status)&.humanize || 'invalid'}"
+        )
+      end
+    end
+
+    def valid_for?(record, context)
+      record.valid?(context) || raise(ActiveRecord::RecordInvalid, record)
+    end
+
+    private
+
+    def notice_failure!(e)
+      @failure = true
+      @error = e
+      @message = e.message
+      report_error(e)
+    end
+
+    def report_error(e)
+      Jidoka.configuration.error_handler.call(e, { worker: self.class.name, args: @opts })
+    end
+  end
+end

data/lib/jidoka.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_job"
+require "active_record"
+require "jidoka/version"
+require "jidoka/errors"
+
+module Jidoka
+  class Error < StandardError; end
+
+  class Configuration
+    # The parent class for Workers (defaults to ActiveJob::Base)
+    attr_accessor :parent_job_class
+    # Block to execute when an error occurs (for Sentry/Honeybadger)
+    attr_accessor :error_handler
+
+    def initialize
+      @parent_job_class = "ActiveJob::Base"
+      @error_handler = ->(error, context = {}) {
+        # Default: just log it
+        if defined?(Rails)
+          Rails.logger.error("[Jidoka] #{error.message}")
+          Rails.logger.error(error.backtrace.join("\n"))
+        end
+      }
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+  end
+end
+
+require "jidoka/worker"
+require "jidoka/supervisor"

metadata

@@ -0,0 +1,158 @@
+--- !ruby/object:Gem::Specification
+name: jidoka
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Nate Mortensen
+bindir: exe
+cert_chain: []
+date: 2026-02-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  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: sqlite3
+  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: Encapsulate complex business logic with automatic rollback, validation,
+  and background processing.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".ruby-version"
+- ".travis.yml"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- jidoka.gemspec
+- lib/jidoka.rb
+- lib/jidoka/errors.rb
+- lib/jidoka/notifiable.rb
+- lib/jidoka/supervisor.rb
+- lib/jidoka/supervisor/step.rb
+- lib/jidoka/validatable.rb
+- lib/jidoka/version.rb
+- lib/jidoka/worker.rb
+homepage: https://github.com/natemortensen/jidoka
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Reversible Command and Orchestrator patterns for Rails.
+test_files: []