sequel-state-machine 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 75e3b94c74a1a1c835374f9e6be8d51c84b62d24cc7fd205f00ee325e1dde15a
+  data.tar.gz: 44fcd2ffd47a5ade52a4c9eda0f6bc86f8b5991f8d9e7cbf7cf9fe0194ba8aa1
+SHA512:
+  metadata.gz: 38a3c446b7b00f3a80b1257a37a0705712bc93e397963378709b0bc289aa8e85d372d869e53c94ae439a1ab83c3b507cb07af0ebe5049abd89e9c8c76088e382
+  data.tar.gz: 7a7da89ec5c83001e726c90dd83e52b973754528a71d9a360c78ea2a1bb9a09ae9dc47c965e5962d156c38fd85a052c0ac56d7f29607e8689564f8cd11b0aec0

data/lib/sequel/plugins/state_machine.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "sequel"
+require "sequel/model"
+require "state_machines/sequel"
+
+module Sequel
+  module Plugins
+    module StateMachine
+      module InstanceMethods
+        def new_audit_log
+          audit_log_assoc = self.class.association_reflections[:audit_logs]
+          model = Kernel.const_get(audit_log_assoc[:class_name])
+          return model.new
+        end
+
+        def current_audit_log
+          if @current_audit_log.nil?
+            StateMachines::Sequel.log(self, :debug, "preparing_audit_log", {})
+            @current_audit_log = self.new_audit_log
+            @current_audit_log.reason = ""
+          end
+          return @current_audit_log
+        end
+
+        def commit_audit_log(transition)
+          StateMachines::Sequel.log(self, :debug, "committing_audit_log", {transition: transition})
+          current = self.current_audit_log
+
+          last_saved = self.audit_logs.find do |a|
+            a.event == transition.event.to_s &&
+              a.from_state == transition.from &&
+              a.to_state == transition.to
+          end
+          if last_saved
+            StateMachines::Sequel.log(self, :debug, "updating_audit_log", {audit_log_id: last_saved.id})
+            last_saved.update(
+              at: Time.now,
+              actor: StateMachines::Sequel.current_actor,
+              messages: current.messages,
+              reason: current.reason,
+            )
+          else
+            StateMachines::Sequel.log(self, :debug, "creating_audit_log", {})
+            current.set(
+              at: Time.now,
+              actor: StateMachines::Sequel.current_actor,
+              event: transition.event.to_s,
+              from_state: transition.from,
+              to_state: transition.to,
+            )
+            self.add_audit_log(current)
+          end
+          @current_audit_log = nil
+        end
+
+        def audit(message, reason: nil)
+          audlog = self.current_audit_log
+          if audlog.class.state_machine_messages_supports_array
+            audlog.messages ||= []
+            audlog.messages << message
+          else
+            audlog.messages ||= ""
+            audlog.messages += (audlog.messages.empty? ? message : (message + "\n"))
+          end
+          audlog.reason = reason if reason
+        end
+
+        def audit_one_off(event, messages, reason: nil)
+          messages = [messages] unless messages.respond_to?(:to_ary)
+          audlog = self.new_audit_log
+          audlog.set(
+            at: Time.now,
+            event: event,
+            from_state: self.status,
+            to_state: self.status,
+            messages: audlog.class.state_machine_messages_supports_array ? messages : messages.join("\n"),
+            reason: reason || "",
+            actor: StateMachines::Sequel.current_actor,
+          )
+          self.add_audit_log(audlog)
+        end
+
+        # Send event with arguments inside of a transaction, save the changes to the receiver,
+        # and return the transition result.
+        # Used to ensure the event processing happens in a transaction and the receiver is saved.
+        def process(event, *args)
+          self.db.transaction do
+            self.lock!
+            result = self.send(event, *args)
+            self.save_changes
+            return result
+          end
+        end
+
+        # Same as process, but raises an error if the transition fails.
+        def must_process(event, *args)
+          success = self.process(event, *args)
+          raise StateMachines::Sequel::FailedTransition.new(self, event) unless success
+          return self
+        end
+
+        # Same as must_process, but takes a lock,
+        # and calls the given block, only doing actual processing if the block returns true.
+        # If the block returns false, it acts as a success.
+        # Used to avoid issues concurrently processing the same object through the same state.
+        def process_if(event, *args)
+          self.db.transaction do
+            self.lock!
+            return self unless yield(self)
+            return self.must_process(event, *args)
+          end
+        end
+
+        # Return true if the given event can be transitioned into by the current state.
+        def valid_state_path_through?(event)
+          current_state = self.send(self._state_value_attr).to_sym
+          event_obj = self.class.state_machine.events[event] or raise "Invalid event #{event}"
+          event_obj.branches.each do |branch|
+            branch.state_requirements.each do |state_req|
+              return true if state_req[:from]&.matches?(current_state)
+            end
+          end
+          return false
+        end
+
+        def _state_value_attr
+          return @_state_value_attr ||= self.class.state_machine.attribute
+        end
+
+        def validates_state_machine
+          states = self.class.state_machine.states.map(&:value)
+          state = self[self._state_value_attr]
+          return if states.include?(state)
+          self.errors.add(self._state_value_attr, "status '#{state}' must be one of (#{states.sort.join(', ')})")
+        end
+      end
+
+      module ClassMethods
+        def timestamp_accessors(events_and_accessors)
+          events_and_accessors.each do |(ev, acc)|
+            self.timestamp_accessor(ev, acc)
+          end
+        end
+
+        # Register the timestamp access for an event.
+        # A timestamp accessor reads when a certain transition happened
+        # by looking at the timestamp of the successful transition into that state.
+        #
+        # The event can be just the event name, or a hash of {event: <event method symbol>, from: <state name>},
+        # used when a single event can cause multiple transitions.
+        def timestamp_accessor(event, accessor)
+          define_method(accessor) do
+            event = {event: event} if event.is_a?(String)
+            audit = self.audit_logs.select(&:succeeded?).find do |a|
+              ev_match = event[:event].nil? || event[:event] == a.event
+              from_match = event[:from].nil? || event[:from] == a.from_state
+              to_match = event[:to].nil? || event[:to] == a.to_state
+              ev_match && from_match && to_match
+            end
+            return audit&.at
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sequel/plugins/state_machine_audit_log.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "sequel"
+require "sequel/model"
+
+module Sequel
+  module Plugins
+    module StateMachineAuditLog
+      DEFAULT_OPTIONS = {
+        messages_supports_array: :undefined,
+        column_mappings: {
+          at: :at,
+          event: :event,
+          to_state: :to_state,
+          from_state: :from_state,
+          reason: :reason,
+          messages: :messages,
+          actor_id: :actor_id,
+        }.freeze,
+      }.freeze
+      def self.configure(model, opts=DEFAULT_OPTIONS)
+        opts = DEFAULT_OPTIONS.merge(opts)
+        model.state_machine_column_mappings = opts[:column_mappings]
+        msgarray = opts[:messages_supports_array] || true
+        if msgarray == :undefined
+          msgcol = model.state_machine_column_mappings[:messages]
+          dbt = model.db_schema[msgcol][:db_type]
+          msgarray = dbt.include?("json") || dbt.include?("[]")
+        end
+        model.state_machine_messages_supports_array = msgarray
+      end
+
+      module ClassMethods
+        attr_accessor :state_machine_messages_supports_array, :state_machine_column_mappings
+      end
+
+      module DatasetMethods
+        def failed
+          colmap = self.state_machine_column_mappings
+          tostate_col = colmap[:to_state]
+          fromstate_col = colmap[:from_state]
+          return self.where(tostate_col => fromstate_col)
+        end
+
+        def succeeded
+          colmap = self.state_machine_column_mappings
+          tostate_col = colmap[:to_state]
+          fromstate_col = colmap[:from_state]
+          return self.exclude(tostate_col => fromstate_col)
+        end
+      end
+
+      module InstanceMethods
+        def failed?
+          colmap = self.state_machine_column_mappings
+          return colmap[:from_state] == colmap[:to_state]
+        end
+
+        def succeeded?
+          colmap = self.state_machine_column_mappings
+          return colmap[:from_state] != colmap[:to_state]
+        end
+      end
+    end
+  end
+end

data/lib/state_machines/sequel/spec_helpers.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "rspec"
+
+RSpec::Matchers.define :transition_on do |event|
+  match do |receiver|
+    raise 'must provide a "to" state' if (@to || "").to_s.empty?
+    receiver.send(event, *@args)
+    @to == receiver.status
+  end
+
+  chain :to do |to_state|
+    @to = to_state
+  end
+
+  chain :with do |*args|
+    @args = args
+  end
+
+  chain :audit do
+    @audit = true
+  end
+
+  failure_message do |receiver|
+    msg =
+      if @to == receiver.status
+        "expected that event #{event} would transition, but did not"
+      else
+        "expected that event #{event} would transition to #{@to} but is #{receiver.status}"
+      end
+    (msg += "\n#{receiver.audit_logs.map(&:inspect).join("\n")}") if @audit
+    msg
+  end
+end
+
+RSpec::Matchers.define :not_transition_on do |event|
+  match do |receiver|
+    !receiver.send(event, *@args)
+  end
+
+  chain :with do |*args|
+    @args = args
+  end
+
+  failure_message do |receiver|
+    "expected that event #{event} would not transition, but did and is now #{receiver.status}"
+  end
+end
+
+RSpec.shared_examples "a state machine with audit logging" do |event, to_state|
+  it "logs transitions" do
+    expect(machine).to transition_on(event).to(to_state)
+    expect(machine.audit_logs).to contain_exactly(
+      have_attributes(to_state: to_state, event: event.to_s),
+    )
+  end
+end

data/lib/state_machines/sequel/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module StateMachines
+  module Sequel
+    VERSION = "1.0.0"
+  end
+end

data/lib/state_machines/sequel.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module StateMachines
+  module Sequel
+    class CurrentActorAlreadySet < StateMachines::Error; end
+
+    class FailedTransition < StateMachines::Error
+      attr_reader :event, :object, :audit_log
+
+      def initialize(obj, event)
+        @event = event
+        @object = obj
+        msg = "#{obj.class}[#{obj.id}] failed to transition on #{event}"
+        if obj.respond_to?(:audit_logs) && obj.audit_logs.present?
+          @audit_log = obj.audit_logs.max_by(&:id)
+          msg += ": #{@audit_log.messages.last}"
+        end
+        super(msg)
+      end
+    end
+
+    class << self
+      attr_accessor :structured_logging
+
+      # Proc called with [instance, level, message, params].
+      # By default, logs to `instance.logger` if it instance responds to :logger.
+      # If structured_logging is true, the message will be an 'event' without any dynamic info,
+      # if false, the params will be rendered into the message so are suitable for unstructured logging.
+      attr_accessor :log_callback
+
+      def reset_logging
+        self.log_callback = lambda { |instance, level, msg, _params|
+          instance.respond_to?(:logger) ? instance.logger.send(level, msg) : nil
+        }
+        self.structured_logging = false
+      end
+
+      def log(instance, level, message, params)
+        if self.structured_logging
+          paramstr = params.map { |k, v| "#{k}=#{v}" }.join(" ")
+          message = "#{message} #{paramstr}"
+        end
+        self.log_callback[instance, level, message, params]
+      end
+
+      def current_actor
+        return Thread.current[:sequel_state_machines_current_actor]
+      end
+
+      def set_current_actor(admin, &block)
+        raise CurrentActorAlreadySet, "already set to: #{self.current_actor}" if !admin.nil? && !self.current_actor.nil?
+        Thread.current[:sequel_state_machines_current_actor] = admin
+        return if block.nil?
+        begin
+          yield
+        ensure
+          Thread.current[:sequel_state_machines_current_actor] = nil
+        end
+      end
+    end
+  end
+end
+
+StateMachines::Sequel.reset_logging

data/lib/state_machines.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "state_machines"
+require "state_machines/sequel"

metadata

@@ -0,0 +1,164 @@
+--- !ruby/object:Gem::Specification
+name: sequel-state-machine
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Lithic Tech
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2022-03-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.10'
+- !ruby/object:Gem::Dependency
+  name: rspec-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.10'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rubocop-sequel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: sequel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: state_machines
+  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: |
+  sequel-state-machine hooks together the excellent Ruby Sequel ORM to
+  the state-machines library, with auditing and other tools.
+email: hello@lithic.tech
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/sequel/plugins/state_machine.rb
+- lib/sequel/plugins/state_machine_audit_log.rb
+- lib/state_machines.rb
+- lib/state_machines/sequel.rb
+- lib/state_machines/sequel/spec_helpers.rb
+- lib/state_machines/sequel/version.rb
+homepage: https://github.com/lithictech/sequel-state-machine
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key: 
+specification_version: 4
+summary: Hook together the excellent Ruby Sequel ORM to the state-machines library,
+  with auditing and other tools.
+test_files: []