signoff 0.1.0

data/lib/signoff/model.rb

@@ -0,0 +1,424 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Signoff
+  # The behaviour mixed into ActiveRecord models via +include Signoff+.
+  # It provides the +signoff+ class macro, the transition methods
+  # (+submit!+, +approve!+, +reject!+), state predicates, query scopes and the
+  # audit-trail helpers.
+  module Model
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :signoff_definition,
+                      instance_accessor: false,
+                      default: nil
+
+      after_initialize :_set_initial_approval_state, if: :new_record?
+    end
+
+    class_methods do
+      # Declare the workflow for this model.
+      #
+      #   signoff do
+      #     state :draft
+      #     state :approved
+      #     transition :draft, to: :approved
+      #   end
+      #
+      # +column+ overrides the state column for this model (defaults to
+      # +Signoff.configuration.default_state_column+).
+      def signoff(column: nil, &block)
+        raise DefinitionError, "signoff requires a block" unless block
+
+        definition = Signoff::Definition.new(
+          state_column: column || Signoff.configuration.default_state_column
+        )
+        Signoff::DSL.new(definition).instance_eval(&block)
+        definition.validate!
+        self.signoff_definition = definition
+
+        has_many :signoff_events,
+                 -> { order(created_at: :asc, id: :asc) },
+                 as: :workflowable,
+                 class_name: "Signoff::Event",
+                 inverse_of: :workflowable,
+                 dependent: Signoff.configuration.dependent
+
+        _define_signoff_predicates(definition)
+        definition
+      end
+
+      # The definition, raising a friendly error if the macro was never called.
+      def signoff_definition!
+        signoff_definition ||
+          raise(NotConfiguredError,
+                "#{name} includes Signoff but never declared an " \
+                "`signoff do ... end` block")
+      end
+
+      def signoff_column
+        signoff_definition!.state_column
+      end
+
+      def signoff_states
+        signoff_definition!.states
+      end
+
+      # --- query scopes --------------------------------------------------
+
+      # Records currently in any of the given states.
+      def in_state(*names)
+        where(signoff_column => names.flatten.map(&:to_s))
+      end
+
+      # Records that reached a successful terminal state.
+      def approved
+        in_state(*signoff_definition!.approval_terminal_states)
+      end
+
+      # Records in the reject state.
+      def rejected
+        reject_state = signoff_definition!.reject_state
+        reject_state ? in_state(reject_state) : none
+      end
+
+      # Records that are neither approved nor rejected (still in flight).
+      def pending
+        definition = signoff_definition!
+        finalized = (definition.approval_terminal_states +
+                     [definition.reject_state].compact).map(&:to_s)
+        finalized.empty? ? all : where.not(signoff_column => finalized)
+      end
+
+      def _define_signoff_predicates(definition)
+        reserved = %i[approved rejected pending]
+        definition.states.each do |state|
+          next if reserved.include?(state)
+
+          predicate = "#{state}?"
+          next if method_defined?(predicate) || private_method_defined?(predicate)
+
+          define_method(predicate) { current_state == state }
+        end
+      end
+    end
+
+    # --- state -----------------------------------------------------------
+
+    # The current workflow state as a Symbol.
+    def current_state
+      definition = self.class.signoff_definition!
+      _ensure_state_column!(definition)
+      value = self[definition.state_column]
+      (value.presence || definition.initial_state).to_sym
+    end
+
+    def approved?
+      self.class.signoff_definition!
+          .approval_terminal_states.include?(current_state)
+    end
+
+    def rejected?
+      current_state == self.class.signoff_definition!.reject_state
+    end
+
+    def pending?
+      !approved? && !rejected?
+    end
+
+    # --- transitions -----------------------------------------------------
+
+    # Advance the record forward and record a "submit" event. Conventionally
+    # used for the initial submission out of the draft state.
+    def submit!(user: nil, comment: nil, metadata: {}, to: nil,
+                ip_address: nil, user_agent: nil)
+      _advance!(action: "submit", to: to, user: user, comment: comment,
+                metadata: metadata, ip_address: ip_address, user_agent: user_agent)
+    end
+
+    # Advance the record forward and record an "approve" event.
+    def approve!(user: nil, comment: nil, metadata: {}, to: nil,
+                 ip_address: nil, user_agent: nil)
+      _advance!(action: "approve", to: to, user: user, comment: comment,
+                metadata: metadata, ip_address: ip_address, user_agent: user_agent)
+    end
+
+    # Move the record to the configured reject state and record a "reject"
+    # event.
+    def reject!(user: nil, comment: nil, metadata: {},
+                ip_address: nil, user_agent: nil)
+      definition = self.class.signoff_definition!
+      unless definition.reject_state
+        raise InvalidTransitionError,
+              "no reject state configured for #{self.class.name}"
+      end
+
+      from = current_state
+      raise InvalidTransitionError, "record is already rejected" if from == definition.reject_state
+      if definition.approval_terminal_states.include?(from)
+        raise InvalidTransitionError,
+              "cannot reject a finalized record (state: #{from})"
+      end
+
+      _perform_transition!(action: "reject", from: from,
+                           to: definition.reject_state, user: user,
+                           comment: comment, metadata: metadata,
+                           ip_address: ip_address, user_agent: user_agent)
+    end
+
+    # --- authorization predicates ---------------------------------------
+
+    def can_approve?(user = nil)
+      definition = self.class.signoff_definition!
+      from = current_state
+      # A no-argument approve! only proceeds when exactly one forward
+      # transition exists (zero => terminal, many => ambiguous).
+      return false unless definition.forward_targets(from).size == 1
+
+      _guard_satisfied?(from, user || Signoff::Current.user)
+    end
+
+    def can_reject?(user = nil)
+      definition = self.class.signoff_definition!
+      return false unless definition.reject_state
+
+      from = current_state
+      return false if from == definition.reject_state ||
+                      definition.approval_terminal_states.include?(from)
+
+      _guard_satisfied?(from, user || Signoff::Current.user)
+    end
+
+    # --- audit helpers ---------------------------------------------------
+
+    # The full, chronologically ordered event history (preloadable via
+    # +includes(:signoff_events)+ to avoid N+1 queries).
+    def workflow_history
+      signoff_events
+    end
+
+    def last_approval
+      _latest_event(conditions: { action: "approve" }) { |e| e.action == "approve" }
+    end
+
+    def last_rejection
+      _latest_event(conditions: { action: "reject" }) { |e| e.action == "reject" }
+    end
+
+    # The user that moved the record into a successful terminal state.
+    def approved_by
+      states = self.class.signoff_definition!
+                   .approval_terminal_states.map(&:to_s)
+      return nil if states.empty?
+
+      _latest_event(conditions: { to_state: states }) do |e|
+        states.include?(e.to_state)
+      end&.user
+    end
+
+    private
+
+    def _set_initial_approval_state
+      definition = self.class.signoff_definition
+      return unless definition
+
+      column = definition.state_column
+      return unless self.class.table_exists?
+      return unless self.class.column_names.include?(column.to_s)
+      return if self[column].present?
+
+      self[column] = definition.initial_state.to_s
+    end
+
+    def _advance!(action:, to:, user:, comment:, metadata:, ip_address:, user_agent:)
+      definition = self.class.signoff_definition!
+      from = current_state
+      target = definition.next_state(from, to: to)
+      _perform_transition!(action: action, from: from, to: target, user: user,
+                           comment: comment, metadata: metadata,
+                           ip_address: ip_address, user_agent: user_agent)
+    end
+
+    def _perform_transition!(action:, from:, to:, user:, comment:, metadata:,
+                             ip_address:, user_agent:)
+      if new_record?
+        raise InvalidTransitionError,
+              "persist #{self.class.name} before transitioning it"
+      end
+
+      definition = self.class.signoff_definition!
+      column = definition.state_column
+      user ||= Signoff::Current.user
+      _authorize_transition!(from: from, user: user)
+
+      event = nil
+      wrote = false
+      begin
+        self.class.transaction do
+          # Serialize concurrent transitions on this row with SELECT ... FOR
+          # UPDATE on just the state column, then re-assert the precondition
+          # against the locked value (the column is the single source of truth)
+          # so two racing approvals cannot both win. This locks without reloading
+          # the record, preserving in-memory/association state.
+          locked = self.class.where(self.class.primary_key => id).lock(true).pick(column)
+          actual = locked.presence&.to_s || definition.initial_state.to_s
+          unless actual == from.to_s
+            raise InvalidTransitionError,
+                  "#{self.class.name} state changed concurrently " \
+                  "(expected #{from}, was #{actual})"
+          end
+
+          _run_before_callbacks(definition, from, to)
+          _write_state!(definition, to)
+          wrote = true
+          event = _build_event(action: action, from: from, to: to, user: user,
+                               comment: comment, metadata: metadata,
+                               ip_address: ip_address, user_agent: user_agent)
+          event.save!
+        end
+      rescue StandardError
+        # Undo the optimistic in-memory state write if the transaction rolled
+        # back after we had already changed it.
+        self[column] = from.to_s if wrote
+        raise
+      end
+
+      _track_persisted_event(event)
+      _run_after_callbacks(definition, event)
+      event
+    end
+
+    def _write_state!(definition, to)
+      column = definition.state_column
+      if Signoff.configuration.validate_on_transition
+        self[column] = to.to_s
+        save!
+      else
+        updates = { column => to.to_s }
+        updates[:updated_at] = Time.current if self.class.column_names.include?("updated_at")
+        update_columns(updates)
+      end
+    end
+
+    def _authorize_transition!(from:, user:)
+      guard = self.class.signoff_definition!.guard_for(from)
+      return true unless guard
+
+      if user.nil?
+        raise UnauthorizedError,
+              "a user is required to perform a transition from #{from}"
+      end
+
+      unless _call_guard(guard, user)
+        raise UnauthorizedError,
+              "user is not authorized to transition from #{from}"
+      end
+
+      true
+    end
+
+    def _guard_satisfied?(from, user)
+      guard = self.class.signoff_definition!.guard_for(from)
+      return true unless guard
+      return false if user.nil?
+
+      !!_call_guard(guard, user)
+    rescue StandardError
+      false
+    end
+
+    def _call_guard(guard, user)
+      arity = guard.arity
+      if arity == 2 || arity <= -2
+        guard.call(user, self)
+      else
+        guard.call(user)
+      end
+    end
+
+    def _build_event(action:, from:, to:, user:, comment:, metadata:,
+                     ip_address:, user_agent:)
+      configuration = Signoff.configuration
+      attributes = {
+        action: action.to_s,
+        from_state: from&.to_s,
+        to_state: to.to_s,
+        comment: comment,
+        metadata: metadata || {}
+      }
+      attributes[:user_id] = _user_identifier(user) unless user.nil?
+
+      if configuration.track_ip_addresses
+        ip = ip_address || Signoff::Current.ip_address
+        attributes[:ip_address] = ip unless ip.nil?
+      end
+
+      if configuration.store_user_agent
+        agent = user_agent || Signoff::Current.user_agent
+        attributes[:user_agent] = agent unless agent.nil?
+      end
+
+      # Built standalone (not via the association) so a rolled-back transaction
+      # never leaves a phantom event in a loaded association cache.
+      Signoff::Event.new(attributes.merge(workflowable: self))
+    end
+
+    def _user_identifier(user)
+      user.respond_to?(:id) ? user.id : user
+    end
+
+    # Keep a loaded association cache consistent after a successful commit so
+    # read-after-write on a preloaded record stays correct.
+    def _track_persisted_event(event)
+      association = self.association(:signoff_events)
+      association.add_to_target(event) if association.loaded?
+    end
+
+    # Return the most recent matching event. Uses the in-memory collection when
+    # the association is already loaded (so +includes(:signoff_events)+
+    # eliminates N+1 queries), otherwise issues a targeted query.
+    def _latest_event(conditions:, &predicate)
+      association = self.association(:signoff_events)
+      if association.loaded?
+        association.target.select(&predicate).max_by { |e| [e.created_at, e.id] }
+      else
+        signoff_events
+          .where(conditions)
+          .reorder(created_at: :desc, id: :desc)
+          .first
+      end
+    end
+
+    def _run_before_callbacks(definition, from, to)
+      definition.before_callbacks.each do |callback|
+        _invoke_callback(callback, [self, from, to])
+      end
+    end
+
+    def _run_after_callbacks(definition, event)
+      definition.after_callbacks.each do |callback|
+        _invoke_callback(callback, [self, event])
+      end
+    end
+
+    def _invoke_callback(callback, args)
+      if callback.arity.negative?
+        callback.call(*args)
+      else
+        callback.call(*args.first(callback.arity))
+      end
+    end
+
+    def _ensure_state_column!(definition)
+      column = definition.state_column.to_s
+      return if self.class.column_names.include?(column)
+
+      raise MissingColumnError,
+            "#{self.class.name} is missing the #{column.inspect} state column. " \
+            "Run `rails g signoff:model #{self.class.name}` or add a " \
+            "string column named #{column.inspect}."
+    end
+  end
+end

data/lib/signoff/version.rb

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

data/lib/signoff.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/concern"
+require "active_record"
+
+require_relative "signoff/version"
+require_relative "signoff/errors"
+require_relative "signoff/configuration"
+require_relative "signoff/definition"
+require_relative "signoff/dsl"
+require_relative "signoff/current"
+require_relative "signoff/model"
+require_relative "signoff/controller"
+require_relative "signoff/engine" if defined?(::Rails::Engine)
+
+# Signoff adds concurrency-safe approval workflows with an immutable audit
+# trail to ActiveRecord models.
+#
+#   class ExpenseReport < ApplicationRecord
+#     include Signoff
+#
+#     signoff do
+#       state :draft
+#       state :manager_review
+#       state :approved
+#       state :rejected
+#
+#       transition :draft,          to: :manager_review
+#       transition :manager_review, to: :approved
+#
+#       reject_to :rejected
+#     end
+#   end
+#
+# Including the module mixes in Signoff::Model (the +signoff+
+# macro, transition methods, scopes and audit helpers). The same namespace also
+# holds the configuration, the audit Event model and the supporting classes.
+module Signoff
+  extend ActiveSupport::Concern
+  include Signoff::Model
+
+  class << self
+    # The current global configuration.
+    def configuration
+      @configuration ||= Configuration.new
+    end
+    alias_method :config, :configuration
+
+    # Configure the gem, typically from an initializer:
+    #
+    #   Signoff.configure do |config|
+    #     config.user_class         = "User"
+    #     config.track_ip_addresses = true
+    #   end
+    def configure
+      yield(configuration)
+    end
+
+    # Reset configuration to defaults (primarily useful in tests).
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

metadata

@@ -0,0 +1,143 @@
+--- !ruby/object:Gem::Specification
+name: signoff
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jijo Bose
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.1'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.1'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.1'
+description: |
+  Signoff adds convention-over-configuration approval workflows to
+  ActiveRecord models. Declare states and transitions with a simple DSL, get
+  submit!/approve!/reject! methods, authorization hooks, query scopes and an
+  immutable PostgreSQL JSONB audit trail - no external services required.
+email:
+- bosejijo@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- app/models/signoff/event.rb
+- lib/generators/signoff/install/USAGE
+- lib/generators/signoff/install/install_generator.rb
+- lib/generators/signoff/install/templates/initializer.rb
+- lib/generators/signoff/install/templates/migration.rb.tt
+- lib/generators/signoff/model/USAGE
+- lib/generators/signoff/model/model_generator.rb
+- lib/generators/signoff/model/templates/migration.rb.tt
+- lib/signoff.rb
+- lib/signoff/configuration.rb
+- lib/signoff/controller.rb
+- lib/signoff/current.rb
+- lib/signoff/definition.rb
+- lib/signoff/dsl.rb
+- lib/signoff/engine.rb
+- lib/signoff/errors.rb
+- lib/signoff/model.rb
+- lib/signoff/version.rb
+homepage: https://github.com/JijoBose/Signoff
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/JijoBose/Signoff
+  changelog_uri: https://github.com/JijoBose/Signoff/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/JijoBose/Signoff/issues
+  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.13
+specification_version: 4
+summary: Concurrency-safe approval workflows for ActiveRecord; immutable audit trail.
+test_files: []