signoff 0.1.0

data/app/models/signoff/event.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Signoff
+  # The immutable audit record written for every workflow transition.
+  #
+  # Columns: workflowable (polymorphic), user_id, action, from_state, to_state,
+  # comment, metadata (jsonb), ip_address, user_agent, created_at.
+  class Event < ActiveRecord::Base
+    self.table_name = Signoff.configuration.event_table_name
+
+    # Explicitly required (independent of the host's
+    # +belongs_to_required_by_default+ setting) so every audit row is anchored
+    # to its subject.
+    belongs_to :workflowable, polymorphic: true,
+                              inverse_of: :signoff_events,
+                              optional: false
+    belongs_to :user,
+               class_name: (Signoff.configuration.user_class || "User").to_s,
+               optional: true
+
+    validates :action, presence: true
+    validates :to_state, presence: true
+
+    scope :chronological, -> { order(created_at: :asc, id: :asc) }
+    scope :recent,        -> { order(created_at: :desc, id: :desc) }
+    scope :with_action,   ->(action) { where(action: action.to_s) }
+    scope :approvals,     -> { with_action("approve") }
+    scope :rejections,    -> { with_action("reject") }
+
+    # Audit rows are append-only. Once persisted they cannot be modified or
+    # destroyed through ActiveRecord unless +config.immutable_events+ is false.
+    def readonly?
+      return super unless Signoff.configuration.immutable_events
+
+      persisted? || super
+    end
+  end
+end

data/lib/generators/signoff/install/USAGE

@@ -0,0 +1,13 @@
+Description:
+    Installs Signoff. Creates the immutable audit events table
+    migration (PostgreSQL JSONB) and a configuration initializer.
+
+Example:
+    rails generate signoff:install
+
+    This will create:
+        config/initializers/signoff.rb
+        db/migrate/XXXXXXXXXXXXXX_create_signoff_events.rb
+
+    Options:
+        --table-name=signoff_events

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module Signoff
+  module Generators
+    # Generates the events table migration and the configuration initializer.
+    #
+    #   rails generate signoff:install
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates the signoff events migration and initializer."
+
+      class_option :table_name, type: :string,
+                                default: "signoff_events",
+                                desc: "Name of the events table"
+      class_option :skip_metadata_index, type: :boolean, default: false,
+                                         desc: "Skip the GIN index on the metadata column"
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/signoff.rb"
+      end
+
+      def create_migration_file
+        migration_template(
+          "migration.rb.tt",
+          File.join(db_migrate_path, "create_signoff_events.rb")
+        )
+      end
+
+      def display_post_install_message
+        say ""
+        say "signoff installed!", :green
+        say "  1. Review config/initializers/signoff.rb"
+        say "  2. Run: rails db:migrate"
+        say "  3. Add a state column to each workflow model, e.g.:"
+        say "       rails g signoff:model ExpenseReport"
+        say ""
+      end
+
+      private
+
+      def table_name
+        options[:table_name]
+      end
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/generators/signoff/install/templates/initializer.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+Signoff.configure do |config|
+  # The model that represents the acting user (referenced by Event#user).
+  config.user_class = "User"
+
+  # Persist the request IP address on each event. Populate
+  # Signoff::Current.ip_address (e.g. by including
+  # Signoff::Controller in ApplicationController) for this to take
+  # effect.
+  config.track_ip_addresses = false
+
+  # Persist the request User-Agent on each event.
+  config.store_user_agent = false
+
+  # Default column used to store the current state on workflowable models.
+  # Override per-model with `signoff(column: :workflow_state)`.
+  config.default_state_column = :approval_state
+
+  # Validate the whole record before writing the state column on a transition.
+  # Leave false so unrelated validation errors never block a transition.
+  config.validate_on_transition = false
+
+  # :dependent strategy for the events association. Audit rows are immutable by
+  # default, so use :delete_all or :nullify (not :destroy).
+  config.dependent = :delete_all
+
+  # Set to false to allow events to be updated/destroyed through ActiveRecord.
+  # config.immutable_events = true
+end

data/lib/generators/signoff/install/templates/migration.rb.tt

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+class CreateSignoffEvents < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :<%= table_name %> do |t|
+      t.string   :workflowable_type, null: false
+      t.bigint   :workflowable_id,   null: false
+      t.bigint   :user_id
+      t.string   :action,            null: false
+      t.string   :from_state
+      t.string   :to_state,          null: false
+      t.text     :comment
+      t.jsonb    :metadata,          null: false, default: {}
+      t.string   :ip_address
+      t.string   :user_agent
+      t.datetime :created_at,        null: false
+    end
+
+    add_index :<%= table_name %>, :workflowable_type
+    add_index :<%= table_name %>, :workflowable_id
+    add_index :<%= table_name %>, :created_at
+    add_index :<%= table_name %>, %i[workflowable_type workflowable_id created_at],
+              name: "idx_signoff_events_on_workflowable_and_created_at"
+    add_index :<%= table_name %>, %i[workflowable_type workflowable_id action created_at],
+              name: "idx_signoff_events_on_workflowable_and_action"
+    add_index :<%= table_name %>, :user_id
+<%- unless options[:skip_metadata_index] -%>
+    add_index :<%= table_name %>, :metadata, using: :gin,
+              name: "idx_signoff_events_on_metadata"
+<%- end -%>
+  end
+end

data/lib/generators/signoff/model/USAGE

@@ -0,0 +1,11 @@
+Description:
+    Adds the signoff state column (default: approval_state) to a
+    model's table, with a sensible default and an index for fast state scopes.
+
+Example:
+    rails generate signoff:model ExpenseReport
+
+    rails generate signoff:model Invoice --column=workflow_state --initial=pending
+
+    This will create:
+        db/migrate/XXXXXXXXXXXXXX_add_approval_state_to_expense_reports.rb

data/lib/generators/signoff/model/model_generator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+require "rails/generators/active_record"
+
+module Signoff
+  module Generators
+    # Adds the workflow state column to a model's table.
+    #
+    #   rails generate signoff:model ExpenseReport
+    #   rails generate signoff:model Invoice --column=workflow_state --initial=pending
+    class ModelGenerator < Rails::Generators::NamedBase
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Adds the signoff state column to a model's table."
+
+      class_option :column, type: :string, default: "approval_state",
+                            desc: "Name of the state column to add"
+      class_option :initial, type: :string, default: "draft",
+                             desc: "Default value for the state column"
+
+      def create_migration_file
+        migration_template(
+          "migration.rb.tt",
+          File.join(db_migrate_path, "add_#{column_name}_to_#{table_name}.rb")
+        )
+      end
+
+      private
+
+      def column_name
+        options[:column]
+      end
+
+      def initial_state
+        options[:initial]
+      end
+
+      def migration_class_name
+        "Add#{column_name.camelize}To#{table_name.camelize}"
+      end
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/generators/signoff/model/templates/migration.rb.tt

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class <%= migration_class_name %> < ActiveRecord::Migration<%= migration_version %>
+  def change
+    add_column :<%= table_name %>, :<%= column_name %>, :string,
+               null: false, default: <%= initial_state.inspect %>
+    add_index :<%= table_name %>, :<%= column_name %>
+  end
+end

data/lib/signoff/configuration.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Signoff
+  # Global, mutable configuration for the gem. Access via
+  # +Signoff.configuration+ or set it inside an initializer:
+  #
+  #   Signoff.configure do |config|
+  #     config.user_class          = "User"
+  #     config.track_ip_addresses  = true
+  #     config.store_user_agent    = true
+  #   end
+  class Configuration
+    # String name of the model that represents the acting user. Resolved
+    # lazily so the constant does not have to be loaded at boot.
+    attr_accessor :user_class
+
+    # When true, the +ip_address+ captured in Signoff::Current (or
+    # passed explicitly) is persisted on every event.
+    attr_accessor :track_ip_addresses
+
+    # When true, the +user_agent+ captured in Signoff::Current (or
+    # passed explicitly) is persisted on every event.
+    attr_accessor :store_user_agent
+
+    # Default column used to store the current state on workflowable models.
+    # Overridable per-model via +signoff(column: :foo)+.
+    attr_accessor :default_state_column
+
+    # Physical table name backing Signoff::Event.
+    attr_accessor :event_table_name
+
+    # When true the workflowable record is fully validated before its state
+    # column is written. When false (the default) only the state column is
+    # updated, so unrelated validation errors never block a transition.
+    attr_accessor :validate_on_transition
+
+    # +:dependent+ strategy for the events association. Because audit rows are
+    # immutable by default, use an SQL-level strategy (+:delete_all+ or
+    # +:nullify+) rather than +:destroy+, which instantiates and would be
+    # blocked by the read-only guard.
+    attr_accessor :dependent
+
+    # When true (the default) persisted events are read-only: they cannot be
+    # updated or destroyed through ActiveRecord, guaranteeing an immutable
+    # audit trail. Set to false to allow +:destroy+ as a dependent strategy.
+    attr_accessor :immutable_events
+
+    def initialize
+      @user_class            = "User"
+      @track_ip_addresses    = false
+      @store_user_agent      = false
+      @default_state_column  = :approval_state
+      @event_table_name      = "signoff_events"
+      @validate_on_transition = false
+      @dependent             = :delete_all
+      @immutable_events      = true
+    end
+
+    # Resolve the configured user class constant. Returns nil when the constant
+    # cannot be loaded (e.g. in a library context with no User model).
+    def user_model
+      return nil if user_class.nil?
+
+      user_class.to_s.constantize
+    rescue NameError
+      nil
+    end
+  end
+end

data/lib/signoff/controller.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Signoff
+  # Optional controller mix-in that populates Signoff::Current from the
+  # request so transitions are attributed automatically:
+  #
+  #   class ApplicationController < ActionController::Base
+  #     include Signoff::Controller
+  #   end
+  #
+  # It relies on a +current_user+ helper if one is available and respects the
+  # +track_ip_addresses+ / +store_user_agent+ configuration flags.
+  module Controller
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :set_signoff_context
+    end
+
+    private
+
+    def set_signoff_context
+      configuration = Signoff.configuration
+
+      Signoff::Current.user = current_user if respond_to?(:current_user, true)
+
+      return unless respond_to?(:request) && request
+
+      Signoff::Current.ip_address = request.remote_ip if configuration.track_ip_addresses
+      return unless configuration.store_user_agent
+
+      Signoff::Current.user_agent = request.user_agent
+    end
+  end
+end

data/lib/signoff/current.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "active_support/current_attributes"
+
+module Signoff
+  # Request-scoped context used to attribute transitions when the acting user,
+  # IP address or user agent are not passed explicitly to a transition method.
+  #
+  # Populate it from a controller (see Signoff::Controller) or
+  # manually:
+  #
+  #   Signoff::Current.set(user: current_user, ip_address: request.remote_ip) do
+  #     report.approve!
+  #   end
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :user, :ip_address, :user_agent
+  end
+end

data/lib/signoff/definition.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Signoff
+  # Immutable-once-validated description of a model's workflow: its states, the
+  # allowed forward transitions, the reject state, authorization guards and
+  # lifecycle callbacks. Built by Signoff::DSL and stored on the model
+  # class as +signoff_definition+.
+  class Definition
+    attr_reader :states, :transitions, :authorizations,
+                :before_callbacks, :after_callbacks, :state_column
+    attr_writer :initial_state
+
+    def initialize(state_column: :approval_state)
+      @states           = []
+      @transitions      = {} # from(Symbol) => [to(Symbol), ...]
+      @authorizations   = {} # from(Symbol) => callable guard
+      @before_callbacks = []
+      @after_callbacks  = []
+      @initial_state    = nil
+      @reject_state     = nil
+      @state_column     = state_column.to_sym
+    end
+
+    # --- builders (called by the DSL) ------------------------------------
+
+    def add_state(name)
+      name = name.to_sym
+      raise DefinitionError, "duplicate state #{name.inspect}" if @states.include?(name)
+
+      @states << name
+    end
+
+    def add_transition(from, to)
+      from = from.to_sym
+      Array(to).each do |target|
+        target = target.to_sym
+        @transitions[from] ||= []
+        @transitions[from] << target unless @transitions[from].include?(target)
+      end
+    end
+
+    def add_authorization(from, guard)
+      @authorizations[from.to_sym] = guard
+    end
+
+    def reject_state=(name)
+      @reject_state = name&.to_sym
+    end
+
+    attr_reader :reject_state
+
+    # --- queries ---------------------------------------------------------
+
+    def initial_state
+      @initial_state || @states.first
+    end
+
+    # Targets reachable from +state+ via a declared forward transition.
+    def forward_targets(state)
+      @transitions[state.to_sym] || []
+    end
+
+    # States with no outgoing forward transition.
+    def terminal_states
+      @states.reject { |s| forward_targets(s).any? }
+    end
+
+    # Terminal states that represent successful completion (everything that is
+    # terminal except the reject state).
+    def approval_terminal_states
+      terminal_states - [reject_state].compact
+    end
+
+    def guard_for(state)
+      @authorizations[state.to_sym]
+    end
+
+    # Resolve the next state when advancing forward from +from+. +to+ may be
+    # supplied to disambiguate when several forward transitions exist.
+    def next_state(from, to: nil)
+      from = from.to_sym
+      targets = forward_targets(from)
+
+      if to
+        to = to.to_sym
+        return to if targets.include?(to)
+
+        raise InvalidTransitionError,
+              "no transition declared from #{from.inspect} to #{to.inspect}"
+      end
+
+      case targets.size
+      when 0
+        raise InvalidTransitionError,
+              "no forward transition declared from #{from.inspect}"
+      when 1
+        targets.first
+      else
+        raise InvalidTransitionError,
+              "ambiguous transition from #{from.inspect}; pass to: " \
+              "(one of #{targets.inspect})"
+      end
+    end
+
+    # --- validation ------------------------------------------------------
+
+    def validate!
+      raise DefinitionError, "no states have been defined" if @states.empty?
+
+      validate_initial_state!
+      validate_transitions!
+      validate_reject_state!
+      validate_authorizations!
+      self
+    end
+
+    private
+
+    def validate_initial_state!
+      raise DefinitionError, "an initial state is required" if initial_state.nil?
+      return if @states.include?(initial_state)
+
+      raise DefinitionError,
+            "initial state #{initial_state.inspect} is not a declared state"
+    end
+
+    def validate_transitions!
+      @transitions.each do |from, targets|
+        unless @states.include?(from)
+          raise DefinitionError,
+                "transition from undeclared state #{from.inspect}"
+        end
+
+        targets.each do |target|
+          next if @states.include?(target)
+
+          raise DefinitionError,
+                "transition to undeclared state #{target.inspect}"
+        end
+      end
+    end
+
+    def validate_reject_state!
+      return if reject_state.nil? || @states.include?(reject_state)
+
+      raise DefinitionError,
+            "reject state #{reject_state.inspect} is not a declared state"
+    end
+
+    def validate_authorizations!
+      @authorizations.each_key do |state|
+        next if @states.include?(state)
+
+        raise DefinitionError,
+              "allow_transition references undeclared state #{state.inspect}"
+      end
+    end
+  end
+end

data/lib/signoff/dsl.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Signoff
+  # The receiver for the +signoff do ... end+ block. Every method
+  # here mutates the Signoff::Definition it was built with.
+  #
+  #   signoff do
+  #     state :draft
+  #     state :manager_review
+  #     state :approved
+  #     state :rejected
+  #
+  #     initial_state :draft
+  #
+  #     transition :draft,           to: :manager_review
+  #     transition :manager_review,  to: :approved
+  #
+  #     reject_to :rejected
+  #
+  #     allow_transition :manager_review do |user|
+  #       user.manager?
+  #     end
+  #
+  #     after_transition do |record, event|
+  #       WorkflowNotificationJob.perform_later(record.id, event.id)
+  #     end
+  #   end
+  class DSL
+    def initialize(definition)
+      @definition = definition
+    end
+
+    # Declare a state. Pass +initial: true+ to mark it as the starting state
+    # (equivalent to a separate +initial_state+ call).
+    def state(name, initial: false)
+      @definition.add_state(name)
+      @definition.initial_state = name if initial
+    end
+
+    # Declare several states at once: +states :draft, :review, :approved+.
+    def states(*names)
+      names.flatten.each { |name| state(name) }
+    end
+
+    # Explicitly set the starting state. Defaults to the first declared state.
+    def initial_state(name)
+      @definition.initial_state = name
+    end
+
+    # Declare a forward transition. +to+ accepts a single state or an array.
+    def transition(from, to:)
+      @definition.add_transition(from, to)
+    end
+
+    # The state a record moves to when +reject!+ is called.
+    def reject_to(state)
+      @definition.reject_state = state
+    end
+
+    # Authorize transitions out of +from_state+. The block receives the acting
+    # user (and optionally the record) and must return a truthy value to allow
+    # the transition.
+    #
+    #   allow_transition :finance_review do |user, record|
+    #     user.finance_team? && record.amount <= user.approval_limit
+    #   end
+    def allow_transition(from_state, &block)
+      raise DefinitionError, "allow_transition requires a block" unless block
+
+      @definition.add_authorization(from_state, block)
+    end
+
+    # Run +block+ inside the transition's transaction, before the state column
+    # is written. Receives +(record, from_state, to_state)+.
+    def before_transition(&block)
+      raise DefinitionError, "before_transition requires a block" unless block
+
+      @definition.before_callbacks << block
+    end
+
+    # Run +block+ after the transition's transaction commits. Receives
+    # +(record, event)+. The created event is already persisted, so this is the
+    # right place to enqueue jobs or send mail.
+    def after_transition(&block)
+      raise DefinitionError, "after_transition requires a block" unless block
+
+      @definition.after_callbacks << block
+    end
+  end
+end

data/lib/signoff/engine.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module Signoff
+  # Minimal Rails engine. Its sole job is to expose +app/models+ (so
+  # +Signoff::Event+ autoloads in the host application) and the
+  # generators under +lib/generators+.
+  class Engine < ::Rails::Engine
+    # Register the Engine itself (a Rails::Engine responds to +eager_load!+);
+    # pushing the bare Signoff module here would crash host boot under
+    # eager loading (the production default) with NoMethodError: eager_load!.
+    config.eager_load_namespaces << Signoff::Engine
+
+    config.app_generators do |generator|
+      generator.orm :active_record
+    end
+  end
+end

data/lib/signoff/errors.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Signoff
+  # Base class for every error raised by the gem. Rescue this to catch any
+  # approval-workflow specific failure.
+  class Error < StandardError; end
+
+  # Raised while building a workflow definition with the DSL when the
+  # definition is invalid (duplicate states, unknown transition targets,
+  # missing initial state, ...).
+  class DefinitionError < Error; end
+
+  # Raised at runtime when a transition is not permitted by the workflow
+  # definition (no edge from the current state, ambiguous target, rejecting a
+  # finalized record, ...).
+  class InvalidTransitionError < Error; end
+
+  # Raised when an authorization guard declared via +allow_transition+ rejects
+  # the acting user (or when a user is required but none was supplied).
+  class UnauthorizedError < Error; end
+
+  # Raised when a model has +include Signoff+ but never declared an
+  # +signoff do ... end+ block.
+  class NotConfiguredError < Error; end
+
+  # Raised when the workflowable table is missing the state column the workflow
+  # expects (run +rails g signoff:model NAME+ or add it yourself).
+  class MissingColumnError < Error; end
+end