statecraft 0.6.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4689cea0dee40236473975f52ea5ccd2ecd303783edebd7626ab1518a1f8c8bd
-  data.tar.gz: b3713ea5d55ea4881b55b10ceccb38847f2f85aa971d29326fd26e97412d0620
+  metadata.gz: b91fc7675cab350149a2e58679893b18ccdfa779cc84e2eb5a7d28c5591c265c
+  data.tar.gz: c751611f88af3a85738877185b68de734578a353818aa130c19206d40b498b82
 SHA512:
-  metadata.gz: 9690fff2fb62feaaea147a53c63113a77dc93103432ad3f5aa63b5593173d513d2abf83d5d53decf0d6eed7347d94509197f5bb0d03077cdbd5a98f1f20cefd4
-  data.tar.gz: cbd7e8d84af570a4c2cb1e51582262860b2d6d0cd7d87ed0304528413ca1d34720dbe6c9b4186fab5a68639c6814243ed2fed32f9774d4985a5f4f5408b45ede
+  metadata.gz: 42c744386532cf91f06374dc3695c4e2ee3e64602fbb428045e3b588c27dc32843959552dea944be5d98834f28036baf1d712da2c25008dba8b16766ca23310b
+  data.tar.gz: 86822e6c1fba14b00e6a8e18efc586a7f92f35280490a168e4d96d063a6d3ecd471eac6fe877c512b9972359d1d14f4d344521dc6f0fea56235075df2bae975b

data/README.md

@@ -210,6 +210,74 @@ through untouched: those errors mean "restart the whole transaction", a
 different protocol than the conflict's "continue from clean state", and the
 retry policy belongs to whoever chose the isolation level.
 
+## Stale transitions: versioning against ABA
+
+The CAS above compares the state's *value* — so a state that went away and
+came back (`pending → paid → … → pending`) passes for the state an open
+page rendered minutes ago. That is the ABA problem, and `versioning: true`
+closes it:
+
+<!-- illustrative -->
+```ruby
+class Order < ApplicationRecord
+  state_machine OrderFlow, versioning: true  # the state_version column
+end
+```
+
+With the option every transition compares-and-swaps on the *pair* of state
+and version and increments the version in the same UPDATE — a returned
+state no longer matches, even without any token. `true` names the column
+`<column>_version`; a symbol overrides the name. The column is a plain
+`bigint NOT NULL DEFAULT 0`: `rails g statecraft:machine Order --versioning`
+generates it, and for an existing table one step is enough — on
+PostgreSQL 11+ an `add_column` with a constant default is metadata-only,
+no table rewrite:
+
+<!-- illustrative -->
+```ruby
+add_column :orders, :state_version, :bigint, null: false, default: 0
+```
+
+The user-facing half is the `seen:` token: render the version into the
+form, send it back, and the pipeline refuses the action when the row has
+moved on — `Statecraft::StaleTransition`, a `TransitionConflict` subclass
+carrying `expected_version` and `seen`, published as reason `:stale`:
+
+<!-- illustrative -->
+```erb
+<input type="hidden" name="seen" value="<%= order.state_version %>">
+```
+
+<!-- illustrative -->
+```ruby
+def cancel
+  order = Order.find(params[:id])
+  order.cancel!(metadata: cancel_metadata, seen: params[:seen])
+  redirect_to order_path(order), notice: "Cancelled."
+rescue Statecraft::StaleTransition
+  head :conflict  # the API mapping: 409
+  # a form flow redirects instead:
+  # redirect_to order_path(order),
+  #             alert: "This order changed while the page was open."
+end
+```
+
+`seen:` rides all four surface forms and the helper verbs. A string token
+straight from params is fine — the pipeline normalizes it with `Integer()`.
+The field comes back from the browser, so it is hostile input: a token that
+cannot be read at all — a tampered `seen=abc`, an array from `seen[]=1` —
+is refused as `StaleTransition` too, with `expected_version: nil` because
+nothing was compared. A broken or forged form never turns into a 500.
+The honest limits: staleness
+exists only where a token was given — without `seen:` a version mismatch
+is the ordinary `TransitionConflict`; the early deterministic check runs
+only under `lock: true`, where the reload holds the row's real version —
+without the lock the CAS itself is the check, since a fresh token can
+outrun a stale in-memory record; and `seen:` on a mounting without
+`versioning:` raises a `CompilationError` naming the fix instead of
+silently skipping the protection. Reads stay join-free: the version lives
+on the parent row, right next to the state.
+
 ## Introspection
 
 <!-- illustrative -->
@@ -449,6 +517,11 @@ statecraft's CAS on the state column.
 Outside Rails, the same five steps work by hand — pair the runbook above
 with the reference schema in [Outside Rails](#outside-rails).
 
+Once the conversion has settled, one more `add_column` buys protection
+statesman never had: see [Stale transitions](#stale-transitions-versioning-against-aba)
+— the version column is a constant default, so adding it costs a
+metadata-only migration on PostgreSQL 11+.
+
 ## PII and erasure
 
 Metadata is the only place personal data can live — `from_state`, `to_state`
@@ -644,7 +717,7 @@ actions over services, guard refusals local to their form:
       @order = Order.find(params[:id])
       authorize! event_name, @order
       @metadata = submitted_metadata
-      @order.fire!(event_name, metadata: @metadata)
+      @order.fire!(event_name, metadata: @metadata, seen: params[:seen].presence)
       redirect_to admin_order_path(@order),
                   notice: "#{event_name} fired: the order is now #{@order[:state]}."
     rescue Statecraft::GuardFailed => error
@@ -668,6 +741,7 @@ possibility-times-permission intersection:
 <!-- readme: preview-pattern -->
 ```erb
 <%= form_with url: preview_admin_order_path(@order), method: :post, local: true do %>
+  <input type="hidden" name="seen" value="<%= @order.state_version %>">
   <fieldset>
     <legend>Metadata for the next action</legend>
     <label>
@@ -705,13 +779,12 @@ ActiveSupport::Notifications.subscribe("transition.statecraft") do |_name, _star
   )
 end
 
+# The failure payload names the record, the machine and the reason — it
+# carries no from/to/event keys: the transition never happened.
 ActiveSupport::Notifications.subscribe("transition_failed.statecraft") do |_name, _started, _finished, _id, payload|
   OperationEntry.create!(
     record_class: payload[:record_class],
     record_id: payload[:record_id].to_s,
-    from_state: payload[:from],
-    to_state: payload[:to],
-    event_name: payload[:event],
     outcome: "refused",
     reason: payload[:reason].to_s
   )

data/lib/generators/statecraft/machine/USAGE

@@ -13,8 +13,13 @@ Description:
     migration lands in the migrations_paths configured for that database
     (db/migrate when none is configured).
 
+    With --versioning the migration also adds a state_version column and
+    the mounting carries versioning: true — a tagged CAS that refuses
+    stale seen: tokens with Statecraft::StaleTransition.
+
 Example:
     bin/rails generate statecraft:machine Order
+    bin/rails generate statecraft:machine Order --versioning
     bin/rails generate statecraft:machine Shop::Order
 
     This will create:

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

@@ -18,6 +18,10 @@ module Statecraft
 
       source_root File.expand_path("templates", __dir__)
 
+      class_option :versioning, type: :boolean, default: false,
+                                desc: "Add a state_version column and mount with versioning: " \
+                                      "true — a tagged CAS that refuses stale seen: tokens"
+
       def detect_model_presence
         @existing_model = File.exist?(File.join(destination_root, model_file))
       end
@@ -71,7 +75,17 @@ module Statecraft
       end
 
       def mounting_line
-        "  state_machine #{class_name}Flow, changed_at: true, helpers: true, scopes: true\n"
+        "  state_machine #{class_name}Flow, #{mounting_options}\n"
+      end
+
+      def mounting_options
+        options_list = ["changed_at: true"]
+        options_list << "versioning: true" if options[:versioning]
+        (options_list + ["helpers: true", "scopes: true"]).join(", ")
+      end
+
+      def versioning?
+        options[:versioning]
       end
 
       # inject_into_class matches the literal `class <name>` line, so the name

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

@@ -5,6 +5,9 @@ class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Mi
     add_column :<%= table_name %>, :state, :string, null: false, default: "pending"
     add_index :<%= table_name %>, :state
     add_column :<%= table_name %>, :state_changed_at, :datetime
+<% if versioning? -%>
+    add_column :<%= table_name %>, :state_version, :bigint, null: false, default: 0
+<% end -%>
 
     # The existing table may carry legacy values, so no CHECK constraint is
     # generated here. To add one later without blocking writes:

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

@@ -5,6 +5,9 @@ class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Mi
     create_table :<%= table_name %> do |t|
       t.string :state, null: false, default: "pending", index: true
       t.datetime :state_changed_at
+<% if versioning? -%>
+      t.bigint :state_version, null: false, default: 0
+<% end -%>
       t.timestamps null: false
     end
 

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

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class <%= class_name %> < ApplicationRecord
-  state_machine <%= class_name %>Flow, changed_at: true, helpers: true, scopes: true
+  state_machine <%= class_name %>Flow, <%= mounting_options %>
 end

data/lib/statecraft/errors.rb

@@ -38,11 +38,33 @@ module Statecraft
   class TransitionConflict < Error
     attr_reader :record, :expected_from
 
-    def initialize(record:, expected_from:)
+    def initialize(record:, expected_from:, message: nil)
       @record = record
       @expected_from = expected_from
-      super("concurrent update detected for #{record.class.name}##{record.id}: " \
-            "expected state #{expected_from.inspect}, another writer got there first")
+      super(message || "concurrent update detected for #{record.class.name}##{record.id}: " \
+                       "expected state #{expected_from.inspect}, another writer got there first")
+    end
+  end
+
+  # The refusal of a seen: token: the snapshot the caller acted on is not
+  # the row's version — or could not be read at all, which is the same
+  # answer with nothing to compare (expected_version stays nil). A subclass
+  # of TransitionConflict, so existing rescues keep catching it;
+  # controllers map it to 409 specifically.
+  class StaleTransition < TransitionConflict
+    attr_reader :expected_version, :seen
+
+    def initialize(record:, expected_from:, expected_version:, seen:)
+      @expected_version = expected_version
+      @seen = seen
+      reason =
+        if expected_version.nil?
+          "the token #{seen.inspect} is not a readable version"
+        else
+          "the caller saw version #{seen.inspect}, but the row has moved on"
+        end
+      super(record: record, expected_from: expected_from,
+            message: "stale transition for #{record.class.name}##{record.id}: #{reason}")
     end
   end
 

data/lib/statecraft/mounting.rb

@@ -10,16 +10,17 @@ module Statecraft
   # in_state?). Everything internal goes through base_class.
   module Mounting
     Configuration = Struct.new(
-      :machine_class, :log_class, :column, :changed_at_column, :touch, :helpers, :scopes,
-      :log_foreign_key,
+      :machine_class, :log_class, :column, :changed_at_column, :version_column, :touch,
+      :helpers, :scopes, :log_foreign_key,
       keyword_init: true
     )
 
-    def state_machine(machine_class, log: nil, column: :state, changed_at: false, touch: true,
-                      helpers: false, scopes: false)
+    def state_machine(machine_class, log: nil, column: :state, changed_at: false,
+                      versioning: false, touch: true, helpers: false, scopes: false)
       Builder.new(
         model: self, machine_class: machine_class, log: log, column: column,
-        changed_at: changed_at, touch: touch, helpers: helpers, scopes: scopes
+        changed_at: changed_at, versioning: versioning, touch: touch,
+        helpers: helpers, scopes: scopes
       ).mount
     end
 
@@ -27,16 +28,20 @@ module Statecraft
     # class hierarchies only — never on the schema and never on a live
     # connection, so mounting is safe at load time.
     class Builder
-      def initialize(model:, machine_class:, log:, column:, changed_at:, touch:, helpers:, scopes:)
+      # rubocop:disable Metrics/ParameterLists -- mirrors state_machine's kwargs one-to-one
+      def initialize(model:, machine_class:, log:, column:, changed_at:, versioning:, touch:,
+                     helpers:, scopes:)
         @model = model
         @machine_class = machine_class
         @log_option = log
         @column = column
         @changed_at = changed_at
+        @versioning = versioning
         @touch = touch
         @helpers = helpers
         @scopes = scopes
       end
+      # rubocop:enable Metrics/ParameterLists
 
       def mount
         assert_not_mounted
@@ -132,6 +137,7 @@ module Statecraft
           log_class: log_class,
           column: @column.to_sym,
           changed_at_column: resolve_changed_at_column,
+          version_column: resolve_version_column,
           touch: @touch,
           helpers: @helpers,
           scopes: @scopes,
@@ -147,6 +153,14 @@ module Statecraft
         end
       end
 
+      def resolve_version_column
+        case @versioning
+        when false then nil
+        when true then :"#{@column}_version"
+        else @versioning.to_sym
+        end
+      end
+
       def store_configuration(configuration)
         model.define_singleton_method(:statecraft_mounting) { configuration }
       end
@@ -163,8 +177,12 @@ module Statecraft
       def define_verbs(graph)
         verbs = Module.new do
           graph.events.each_key do |event_name|
-            define_method("#{event_name}!") { |metadata: {}| fire!(event_name, metadata: metadata) }
-            define_method(event_name) { |metadata: {}| fire(event_name, metadata: metadata) }
+            define_method("#{event_name}!") do |metadata: {}, seen: nil|
+              fire!(event_name, metadata: metadata, seen: seen)
+            end
+            define_method(event_name) do |metadata: {}, seen: nil|
+              fire(event_name, metadata: metadata, seen: seen)
+            end
             define_method("may_#{event_name}?") { |metadata: {}| can_fire?(event_name, metadata: metadata) }
           end
         end

data/lib/statecraft/pipeline/surface.rb

@@ -5,24 +5,24 @@ module Statecraft
     # 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.
+    # TransitionConflict — StaleTransition included — 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)
+      def transition_to!(to_state, metadata: {}, bypass_events: false, seen: nil)
+        Pipeline.new(self).direct(to_state, metadata: metadata, bypass_events: bypass_events, seen: seen)
       end
 
-      def transition_to(to_state, metadata: {}, bypass_events: false)
-        transition_to!(to_state, metadata: metadata, bypass_events: bypass_events)
+      def transition_to(to_state, metadata: {}, bypass_events: false, seen: nil)
+        transition_to!(to_state, metadata: metadata, bypass_events: bypass_events, seen: seen)
       rescue GuardFailed, InvalidTransition
         false
       end
 
-      def fire!(event_name, metadata: {})
-        Pipeline.new(self).fire(event_name, metadata: metadata)
+      def fire!(event_name, metadata: {}, seen: nil)
+        Pipeline.new(self).fire(event_name, metadata: metadata, seen: seen)
       end
 
-      def fire(event_name, metadata: {})
-        fire!(event_name, metadata: metadata)
+      def fire(event_name, metadata: {}, seen: nil)
+        fire!(event_name, metadata: metadata, seen: seen)
       rescue GuardFailed, InvalidTransition
         false
       end

data/lib/statecraft/pipeline/versioning.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Statecraft
+  class Pipeline
+    # The tagged half of the CAS: when the mounting carries versioning, every
+    # transition compares-and-swaps on (state, version) and increments the
+    # version in the same UPDATE. A seen: token substitutes the compared
+    # value with what the caller's form actually rendered, and its refusal is
+    # StaleTransition — the 409 of the pipeline.
+    module Versioning
+      private
+
+      def version_column
+        column = configuration.version_column
+        return nil unless column
+
+        unless record.class.column_names.include?(column.to_s)
+          raise CompilationError,
+                "versioning column #{column} does not exist on #{record.class.table_name}; " \
+                "add the column or drop the versioning option"
+        end
+        column
+      end
+
+      # The token arrives from a form field, so it is hostile input: a
+      # tampered or broken form must not escape the gem's own hierarchy.
+      # An unreadable token IS an invalid snapshot — the same refusal a
+      # stale one gets, with no version to compare against.
+      def normalize_seen(raw_seen)
+        return nil if raw_seen.nil?
+
+        unless configuration.version_column
+          raise CompilationError,
+                "seen: requires versioning: true on the mounting of #{record.class.name}; " \
+                "add the option or drop the token"
+        end
+
+        begin
+          Integer(raw_seen)
+        rescue ArgumentError, TypeError
+          raise StaleTransition.new(record: record, expected_from: current_state,
+                                    expected_version: nil, seen: raw_seen)
+        end
+      end
+
+      # What the CAS requires the row's version to be: the caller's seen:
+      # token when given, the in-memory value otherwise — fresh after a lock
+      # reload, synced by the previous link inside a chain.
+      def expected_version
+        @seen || record[version_column]
+      end
+
+      # With a seen: token any versioned refusal is staleness — the caller
+      # acted on a snapshot; without one it is the ordinary conflict of two
+      # writers.
+      def cas_refusal(edge)
+        if @seen
+          StaleTransition.new(record: record, expected_from: edge.from,
+                              expected_version: expected_version, seen: @raw_seen)
+        else
+          TransitionConflict.new(record: record, expected_from: edge.from)
+        end
+      end
+
+      # The same early observation as assert_lock_saw_expected_state, for the
+      # seen: token: the reload holds the row's real version under the lock,
+      # so a mismatched token is a stale snapshot detected deterministically,
+      # before any write.
+      def assert_lock_saw_expected_version(edge)
+        return unless @seen && version_column
+        return if record[version_column] == @seen
+
+        raise StaleTransition.new(record: record, expected_from: edge.from,
+                                  expected_version: @seen, seen: @raw_seen)
+      end
+    end
+  end
+end

data/lib/statecraft/pipeline.rb

@@ -29,6 +29,7 @@ module Statecraft
     MAX_CHAIN_DEPTH = 16
 
     include EdgeResolution
+    include Versioning
 
     def self.transition_stack
       ActiveSupport::IsolatedExecutionState[STACK_KEY] ||= []
@@ -41,15 +42,15 @@ module Statecraft
       @machine_instance = @configuration.machine_class.new
     end
 
-    def direct(to_state, metadata:, bypass_events:)
-      run(metadata) do |current_state|
+    def direct(to_state, metadata:, bypass_events:, seen: nil)
+      run(metadata, seen: seen) do |current_state|
         edge = resolve_direct_edge(current_state, to_state.to_sym, bypass_events)
         [edge, nil, bypass_events]
       end
     end
 
-    def fire(event_name, metadata:)
-      run(metadata) do |current_state|
+    def fire(event_name, metadata:, seen: nil)
+      run(metadata, seen: seen) do |current_state|
         edge = resolve_event_edge(current_state, event_name.to_sym)
         [edge, event_name.to_sym, false]
       end
@@ -59,13 +60,17 @@ module Statecraft
 
     attr_reader :record, :configuration, :graph, :machine_instance
 
-    def run(raw_metadata, &edge_resolver)
+    def run(raw_metadata, seen: nil, &edge_resolver)
       raise UnsavedRecordError.new(record: record) unless record.persisted?
 
       assert_single_column_primary_key
+      @raw_seen = seen
       metadata = Metadata.normalize(raw_metadata)
       started_at = Time.current
       begin
+        # Inside the rescue: an unreadable token is a refusal like any
+        # other and belongs in the failure telemetry.
+        @seen = normalize_seen(seen)
         edge, event, bypass = edge_resolver.call(current_state)
         assert_clean_when_locked(edge)
         frame = open_frame(edge, event)
@@ -91,6 +96,7 @@ module Statecraft
         case error
         when GuardFailed then [:guard_failed, { guard: error.guard }]
         when InvalidTransition then [:invalid_transition, { requested: error.requested }]
+        when StaleTransition then [:stale, { expected_version: error.expected_version, seen: error.seen }]
         when TransitionConflict then [:conflict, { expected_from: error.expected_from }]
         end
       Instrumentation.publish_failure(
@@ -105,6 +111,7 @@ module Statecraft
           warn_when_row_locking_unavailable
           record.reload(lock: true)
           assert_lock_saw_expected_state(edge)
+          assert_lock_saw_expected_version(edge)
         end
         transition_time = Time.current
         run_guards(edge, event, bypass, metadata)
@@ -204,17 +211,21 @@ module Statecraft
     end
 
     def cas_update!(edge, transition_time)
-      affected_rows = base_class.unscoped
-                                .where(base_class.primary_key => record.id,
-                                       configuration.column => edge.from.to_s)
-                                .update_all(cas_updates(edge, transition_time))
-      raise TransitionConflict.new(record: record, expected_from: edge.from) if affected_rows.zero?
+      scope = base_class.unscoped
+                        .where(base_class.primary_key => record.id,
+                               configuration.column => edge.from.to_s)
+      scope = scope.where(version_column => expected_version) if version_column
+      affected_rows = scope.update_all(cas_updates(edge, transition_time))
+      raise cas_refusal(edge) if affected_rows.zero?
     end
 
     def cas_updates(edge, transition_time)
       updates = { configuration.column => edge.to.to_s }
       updates[:updated_at] = transition_time if touch_updated_at?
       updates[changed_at_column] = transition_time if changed_at_column
+      # The literal is correct by construction: the CAS WHERE guarantees the
+      # row held exactly expected_version, so the memory mirror stays exact.
+      updates[version_column] = expected_version + 1 if version_column
       updates
     end
 

data/lib/statecraft/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Statecraft
-  VERSION = "0.6.0"
+  VERSION = "0.7.1"
 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/edge_resolution"
+require_relative "statecraft/pipeline/versioning"
 require_relative "statecraft/pipeline"
 require_relative "statecraft/pipeline/surface"
 require_relative "statecraft/introspection"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: statecraft
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.1
 platform: ruby
 authors:
 - Igor Pugachev
@@ -87,6 +87,7 @@ files:
 - lib/statecraft/pipeline.rb
 - lib/statecraft/pipeline/edge_resolution.rb
 - lib/statecraft/pipeline/surface.rb
+- lib/statecraft/pipeline/versioning.rb
 - lib/statecraft/rspec.rb
 - lib/statecraft/rspec/allow_event.rb
 - lib/statecraft/rspec/allow_transition_to.rb