statecraft 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9f0a6cac349045859dd7966a325ae9d0a4b27175b846e8f43bd924b298576b6
-  data.tar.gz: a148de67af8ddd2bb976ae5ed03db6a38122ebd795013f9aae6c5803e45f7120
+  metadata.gz: 207eda16ee51c42a787b0e3ba1a37c297242316edfe742c6be75b5dbca1166c0
+  data.tar.gz: efe7505f2499fdcd1175b35be3c454a9143b7afb2824dc3a6f0e2f98a8429a5f
 SHA512:
-  metadata.gz: a48dbba9f2e06f23bbcffc0fc632f17f6915954737c2f104c132fa8763823bb9f07a0e754dabf4eb95d14b21b97c912885d0d1efa252c7e3ce64cedeeb206a22
-  data.tar.gz: 8256c0463e14d6ddf19d2a757647f81bae4bfa73ecc37796f905adc82d397dbdcb730c45861d23b172711e75aff224482de7dbbdc94a07fbbc9c4cca95fd4c37
+  metadata.gz: 29d2cd130932273c9469dcbecf03f2a0fb20d33fc8b776efba5f850cd21bb447c5032de1dc10375e5dc9718d993001f6e0b279a5aa2e72c7be0cd1b890408710
+  data.tar.gz: c0856de0dde4ff10884ac2f567848b01b8949b514a2a171971957161d88348994d8f207e0f1e2f5d10fb1137a2b750b7f9f08e183537759dd2947be8c57911f4

data/README.md

@@ -1,7 +1,11 @@
 # statecraft
 
+[![Gem Version](https://img.shields.io/gem/v/statecraft.svg)](https://rubygems.org/gems/statecraft)
+[![CI](https://github.com/supostat/statecraft/actions/workflows/ci.yml/badge.svg)](https://github.com/supostat/statecraft/actions/workflows/ci.yml)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
 
+**[Website →](https://supostat.github.io/statecraft/)** · [RubyGems](https://rubygems.org/gems/statecraft) · [Issues](https://github.com/supostat/statecraft/issues)
+
 A state machine for ActiveRecord where the current state lives in a column as
 the single source of truth, history is an append-only per-model log with
 write-once metadata, and every transition is guarded by a compare-and-swap
@@ -96,7 +100,8 @@ generator turns them on for new code).
    reload.
 5. `transaction(requires_new: true)` — a savepoint inside your transaction,
    a real transaction otherwise: optional `SELECT ... FOR UPDATE` + reload
-   (with edge re-resolution from the fresh state), guards, `before_transition`
+   (a state that changed under the lock raises
+   `Statecraft::TransitionConflict`), guards, `before_transition`
    callbacks, the CAS update (touching `updated_at` and the `changed_at`
    column in the same statement), the log INSERT, `after_transition`.
 6. `after_commit` callbacks are registered on the outermost real
@@ -309,7 +314,8 @@ The log lives next to its model, always — a cascade FK cannot cross
 databases, so this is a definition, not a restriction. The generated log
 class inherits the model's connection-owning ancestor (base, roles and
 horizontal shards follow automatically), and the generator drops the
-migration into that connection's migration path. Mounting verifies connection
+migration into the migration path configured for that connection's database
+(`db/migrate` when none is configured). Mounting verifies connection
 identity — same pool, same per-thread connection, one real transaction — and
 raises `Statecraft::ConnectionMismatch` with a fix hint otherwise. Two
 `connects_to` blocks pointing at one physical database are still two pools:
@@ -369,6 +375,12 @@ docker compose run --rm test-postgres                       # PostgreSQL 16
 AR_VERSION=7.2 RUBY_VERSION=3.3 docker compose run --rm test-postgres
 ```
 
+## Links
+
+- Landing page: <https://supostat.github.io/statecraft/>
+- RubyGems: <https://rubygems.org/gems/statecraft>
+- Issues: <https://github.com/supostat/statecraft/issues>
+
 ## License
 
 MIT. See [LICENSE.txt](LICENSE.txt).

data/lib/generators/statecraft/machine/machine_generator.rb

@@ -10,16 +10,16 @@ module Statecraft
     # the per-model log table with a cascade FK and a CHECK constraint for a
     # freshly created table), the machine class, the readonly log model, the
     # model mounting with helpers and scopes on, and lazily the shared
-    # ApplicationMachine parent. The migration lands in the migration path of
-    # the model's connection owner, so multi-database apps get it next to
-    # their model.
+    # ApplicationMachine parent. The migration lands in the migration path
+    # configured for the model's database, so multi-database apps get it next
+    # to their model.
     class MachineGenerator < Rails::Generators::NamedBase
       include ActiveRecord::Generators::Migration
 
       source_root File.expand_path("templates", __dir__)
 
       def detect_model_presence
-        @existing_model = File.exist?(File.join(destination_root, "app/models/#{file_name}.rb"))
+        @existing_model = File.exist?(File.join(destination_root, model_file))
       end
 
       def create_application_machine
@@ -29,26 +29,35 @@ module Statecraft
         template "application_machine.rb.tt", application_machine_path
       end
 
+      def create_namespace_module
+        return if class_path.empty? || existing_model?
+
+        module_file = "app/models/#{class_path.join("/")}.rb"
+        return if File.exist?(File.join(destination_root, module_file))
+
+        template "namespace_module.rb.tt", module_file
+      end
+
       def create_machine_class
-        template "machine.rb.tt", "app/state_machines/#{file_name}_flow.rb"
+        template "machine.rb.tt", "app/state_machines/#{file_path}_flow.rb"
       end
 
       def create_log_model
-        template "log_model.rb.tt", "app/models/#{file_name}_transition.rb"
+        template "log_model.rb.tt", "app/models/#{file_path}_transition.rb"
       end
 
       def create_or_mount_model
         if existing_model?
-          inject_into_class "app/models/#{file_name}.rb", class_name, mounting_line
+          inject_into_class model_file, mounting_target_class, mounting_line
         else
-          template "model.rb.tt", "app/models/#{file_name}.rb"
+          template "model.rb.tt", model_file
         end
       end
 
       def create_migration_file
         migration_source = existing_model? ? "add_migration.rb.tt" : "create_migration.rb.tt"
         migration_template migration_source,
-                           "#{migration_directory}/create_#{file_name}_state_machine.rb"
+                           "#{migration_directory}/create_#{migration_slug}_state_machine.rb"
       end
 
       private
@@ -57,22 +66,43 @@ module Statecraft
         @existing_model
       end
 
+      def model_file
+        "app/models/#{file_path}.rb"
+      end
+
       def mounting_line
         "  state_machine #{class_name}Flow, changed_at: true, helpers: true, scopes: true\n"
       end
 
+      # inject_into_class matches the literal `class <name>` line, so the name
+      # must follow the style the model file actually uses: the full constant
+      # for the compact `class Shop::Order` style, the demodulized one for
+      # `module Shop / class Order` nesting.
+      def mounting_target_class
+        return class_name if class_path.empty?
+
+        model_source = File.read(File.join(destination_root, model_file))
+        model_source.match?(/class #{class_name}\b/) ? class_name : class_name.demodulize
+      end
+
+      # Without a configured migrations_paths, `rails db:migrate` reads
+      # db/migrate for every database — so that is the honest fallback.
       def migration_directory
-        specification_name = model_connection_specification_name
-        return "db/migrate" if specification_name.nil? || specification_name == "ActiveRecord::Base"
+        db_config = model_class&.connection_db_config
+        configured = db_config && Array(db_config.migrations_paths).first
+        configured || "db/migrate"
+      end
 
-        "db/#{specification_name.underscore.tr("/", "_")}_migrate"
+      def model_class
+        class_name.safe_constantize
       end
 
-      def model_connection_specification_name
-        model_class = class_name.safe_constantize
-        model_class&.connection_specification_name
-      rescue StandardError
-        nil
+      # The generated model's table follows the loaded model when one exists;
+      # otherwise the Rails naming convention for the argument, namespace
+      # included (`Shop::Order` -> shop_orders, matching the generated
+      # namespace module's table_name_prefix).
+      def table_name
+        @table_name ||= model_class ? model_class.table_name : super
       end
 
       def log_table_name
@@ -80,7 +110,7 @@ module Statecraft
       end
 
       def parent_class_name
-        specification_name = model_connection_specification_name
+        specification_name = model_class&.connection_specification_name
         return "ApplicationRecord" if specification_name.nil? || specification_name == "ActiveRecord::Base"
 
         specification_name
@@ -90,8 +120,12 @@ module Statecraft
         "#{file_name}_id"
       end
 
+      def migration_slug
+        file_path.tr("/", "_")
+      end
+
       def migration_class_name
-        "Create#{class_name}StateMachine"
+        "Create#{migration_slug.camelize}StateMachine"
       end
     end
   end

data/lib/generators/statecraft/machine/templates/namespace_module.rb.tt

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+<% class_path.each_with_index do |part, depth| -%>
+<%= "  " * depth %>module <%= part.camelize %>
+<% end -%>
+<%= "  " * class_path.length %>def self.table_name_prefix
+<%= "  " * class_path.length %>  "<%= class_path.join("_") %>_"
+<%= "  " * class_path.length %>end
+<% (class_path.length - 1).downto(0) do |depth| -%>
+<%= "  " * depth %>end
+<% end -%>

data/lib/statecraft/metadata.rb

@@ -19,7 +19,8 @@ module Statecraft
         value.map { |element| round_trip(element) }
       when String then value.dup
       when Symbol then value.to_s
-      when Integer, Float, true, false, nil then value
+      when Integer, true, false, nil then value
+      when Float then round_trip_float(value)
       when Time, Date, DateTime then value.iso8601
       else
         raise ArgumentError,
@@ -28,6 +29,14 @@ module Statecraft
       end
     end
 
+    def self.round_trip_float(value)
+      return value if value.finite?
+
+      raise ArgumentError,
+            "metadata value #{value.inspect} is not JSON-serializable; " \
+            "jsonb has no NaN or Infinity"
+    end
+
     def self.round_trip_key(key)
       case key
       when String then key.dup

data/lib/statecraft/mounting.rb

@@ -40,7 +40,6 @@ module Statecraft
 
       def mount
         assert_not_mounted
-        assert_single_column_primary_key
         log_class = resolve_log_class
         assert_shared_connection_class(log_class)
         graph = machine_class.finalize!
@@ -64,10 +63,6 @@ module Statecraft
         raise AlreadyMounted.new(model: model) if model.respond_to?(:statecraft_mounting)
       end
 
-      def assert_single_column_primary_key
-        raise CompositePrimaryKeyUnsupported.new(model: model) if model.primary_key.is_a?(Array)
-      end
-
       def resolve_log_class
         return @log_option if @log_option
 

data/lib/statecraft/pipeline/surface.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Statecraft
+  class Pipeline
+    # The record-facing API mixed into the model at mounting time. Bang
+    # variants return the created log record; non-bang variants return it too,
+    # or false on GuardFailed / InvalidTransition. Programmer errors and
+    # TransitionConflict always raise.
+    module Surface
+      def transition_to!(to_state, metadata: {}, bypass_events: false)
+        Pipeline.new(self).direct(to_state, metadata: metadata, bypass_events: bypass_events)
+      end
+
+      def transition_to(to_state, metadata: {}, bypass_events: false)
+        transition_to!(to_state, metadata: metadata, bypass_events: bypass_events)
+      rescue GuardFailed, InvalidTransition
+        false
+      end
+
+      def fire!(event_name, metadata: {})
+        Pipeline.new(self).fire(event_name, metadata: metadata)
+      end
+
+      def fire(event_name, metadata: {})
+        fire!(event_name, metadata: metadata)
+      rescue GuardFailed, InvalidTransition
+        false
+      end
+    end
+  end
+end

data/lib/statecraft/pipeline.rb

@@ -5,7 +5,7 @@ module Statecraft
   #
   #   persisted? -> metadata normalize+freeze -> edge resolution ->
   #   dirty check (lock only) -> transaction(requires_new: true) [
-  #     lock+reload -> re-resolve edge from fresh state -> guards ->
+  #     lock+reload -> conflict check against the resolved edge -> guards ->
   #     before_transition -> CAS UPDATE -> log INSERT (insert path) ->
   #     after_transition
   #   ] -> after_commit registration on the outermost real commit
@@ -32,32 +32,6 @@ module Statecraft
       ActiveSupport::IsolatedExecutionState[STACK_KEY] ||= []
     end
 
-    # The record-facing API mixed into the model at mounting time. Bang
-    # variants return the created log record; non-bang variants return it too,
-    # or false on GuardFailed / InvalidTransition. Programmer errors and
-    # TransitionConflict always raise.
-    module Surface
-      def transition_to!(to_state, metadata: {}, bypass_events: false)
-        Pipeline.new(self).direct(to_state, metadata: metadata, bypass_events: bypass_events)
-      end
-
-      def transition_to(to_state, metadata: {}, bypass_events: false)
-        transition_to!(to_state, metadata: metadata, bypass_events: bypass_events)
-      rescue GuardFailed, InvalidTransition
-        false
-      end
-
-      def fire!(event_name, metadata: {})
-        Pipeline.new(self).fire(event_name, metadata: metadata)
-      end
-
-      def fire(event_name, metadata: {})
-        fire!(event_name, metadata: metadata)
-      rescue GuardFailed, InvalidTransition
-        false
-      end
-    end
-
     def initialize(record)
       @record = record
       @configuration = record.class.statecraft_mounting
@@ -86,6 +60,7 @@ module Statecraft
     def run(raw_metadata, &edge_resolver)
       raise UnsavedRecordError.new(record: record) unless record.persisted?
 
+      assert_single_column_primary_key
       metadata = Metadata.normalize(raw_metadata)
       started_at = Time.current
       begin
@@ -93,18 +68,12 @@ module Statecraft
         assert_clean_when_locked(edge)
         frame = open_frame(edge, event)
         begin
-          log_record = execute_transaction(edge, event, bypass, metadata, edge_resolver, frame)
+          log_record = execute_transaction(edge, event, bypass, metadata, frame)
         ensure
           Pipeline.transition_stack.delete(frame)
         end
-      rescue GuardFailed => guard_error
-        publish_failure(started_at, :guard_failed, guard: guard_error.guard)
-        raise
-      rescue InvalidTransition => invalid_error
-        publish_failure(started_at, :invalid_transition, requested: invalid_error.requested)
-        raise
-      rescue TransitionConflict => conflict_error
-        publish_failure(started_at, :conflict, expected_from: conflict_error.expected_from)
+      rescue GuardFailed, InvalidTransition, TransitionConflict => transition_error
+        publish_failure(started_at, transition_error)
         raise
       end
       Instrumentation.publish_transition(
@@ -115,19 +84,25 @@ module Statecraft
       log_record
     end
 
-    def publish_failure(started_at, reason, details)
+    def publish_failure(started_at, error)
+      reason, details =
+        case error
+        when GuardFailed then [:guard_failed, { guard: error.guard }]
+        when InvalidTransition then [:invalid_transition, { requested: error.requested }]
+        when TransitionConflict then [:conflict, { expected_from: error.expected_from }]
+        end
       Instrumentation.publish_failure(
         started_at: started_at, record: record,
         machine_class: configuration.machine_class, reason: reason, details: details
       )
     end
 
-    def execute_transaction(edge, event, bypass, metadata, edge_resolver, frame)
+    def execute_transaction(edge, event, bypass, metadata, frame)
       base_class.transaction(requires_new: true) do
         if edge.lock
           warn_when_row_locking_unavailable
           record.reload(lock: true)
-          edge, event, bypass = edge_resolver.call(current_state)
+          assert_lock_saw_expected_state(edge)
         end
         transition_time = Time.current
         run_guards(edge, event, bypass, metadata)
@@ -138,8 +113,13 @@ module Statecraft
         cas_update!(edge, transition_time)
         frame.cas_done = true
         context.log_record = insert_log_row(edge, event, metadata, transition_time)
-        sync_record(edge, transition_time)
-        run_callbacks(:after_transition, context)
+        synced_snapshot = sync_record(edge, transition_time)
+        begin
+          run_callbacks(:after_transition, context)
+        rescue Exception # rubocop:disable Lint/RescueException -- the savepoint rolls the database back on ANY exception, so the in-memory sync must roll back with it
+          restore_synced_attributes(synced_snapshot)
+          raise
+        end
         context.log_record
       end
     end
@@ -204,12 +184,31 @@ module Statecraft
       graph.edges.keys.select { |from, _to| from == current }.map(&:last)
     end
 
+    # Checked at the first transition, not at mounting time: resolving an
+    # implicit primary key goes through the schema cache, and mounting must
+    # stay safe without a database connection.
+    def assert_single_column_primary_key
+      return unless base_class.primary_key.is_a?(Array)
+
+      raise CompositePrimaryKeyUnsupported.new(model: base_class)
+    end
+
     def assert_clean_when_locked(edge)
       return unless edge.lock && record.changed?
 
       raise DirtyRecordError.new(record: record, changed_attributes: record.changed)
     end
 
+    # The lock reload can reveal a state that no longer matches the edge the
+    # caller validated. That is a concurrent write observed early: the same
+    # conflict CAS would report, so it raises the same error instead of
+    # silently resolving a different edge from the fresh state.
+    def assert_lock_saw_expected_state(edge)
+      return if current_state == edge.from
+
+      raise TransitionConflict.new(record: record, expected_from: edge.from)
+    end
+
     def run_guards(edge, event, bypass, metadata)
       guards = edge.edge_guards.dup
       guards.concat(edge.event_guards.fetch(event, [])) if event && !bypass
@@ -267,18 +266,20 @@ module Statecraft
       log_class.find(log_id)
     end
 
+    # Mirrors exactly what the CAS statement wrote into the row, without a
+    # dirty mark, and returns the prior values so a failing after_transition
+    # can roll the memory back alongside the savepoint.
     def sync_record(edge, transition_time)
-      synced_columns = [configuration.column]
-      record[configuration.column] = edge.to.to_s
-      if touch_updated_at?
-        record[:updated_at] = transition_time
-        synced_columns << :updated_at
-      end
-      if changed_at_column
-        record[changed_at_column] = transition_time
-        synced_columns << changed_at_column
-      end
-      record.clear_attribute_changes(synced_columns)
+      updates = cas_updates(edge, transition_time)
+      snapshot = updates.to_h { |column, _value| [column, record[column]] }
+      updates.each { |column, value| record[column] = value }
+      record.clear_attribute_changes(updates.keys)
+      snapshot
+    end
+
+    def restore_synced_attributes(snapshot)
+      snapshot.each { |column, value| record[column] = value }
+      record.clear_attribute_changes(snapshot.keys)
     end
 
     def register_after_commit_callbacks(log_record, metadata)

data/lib/statecraft/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Statecraft
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/lib/statecraft.rb

@@ -10,6 +10,7 @@ require_relative "statecraft/instrumentation"
 require_relative "statecraft/machine"
 require_relative "statecraft/metadata"
 require_relative "statecraft/pipeline"
+require_relative "statecraft/pipeline/surface"
 require_relative "statecraft/introspection"
 require_relative "statecraft/mounting"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: statecraft
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Igor Pugachev
@@ -67,6 +67,7 @@ files:
 - lib/generators/statecraft/machine/templates/log_model.rb.tt
 - lib/generators/statecraft/machine/templates/machine.rb.tt
 - lib/generators/statecraft/machine/templates/model.rb.tt
+- lib/generators/statecraft/machine/templates/namespace_module.rb.tt
 - lib/statecraft.rb
 - lib/statecraft/errors.rb
 - lib/statecraft/instrumentation.rb
@@ -75,6 +76,7 @@ files:
 - lib/statecraft/metadata.rb
 - lib/statecraft/mounting.rb
 - lib/statecraft/pipeline.rb
+- lib/statecraft/pipeline/surface.rb
 - lib/statecraft/version.rb
 - lib/statecraft/warnings.rb
 homepage: https://supostat.github.io/statecraft/