statecraft 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e98ec25e4cfbb6cec172cd1f54ac9362937c967eff450ccda67d414e2dce6d3
-  data.tar.gz: e8f112727ef007ad0d6d3e91e67c122298bbf1d403f09aa9e2aeda56e43545da
+  metadata.gz: 70f23cb88e677af1d36d2acf31fc39a1688f90a46c99d6eebef3e76c49ca4f8e
+  data.tar.gz: f38e777eed1a3fa3109da01a9f56eeb09f8c181c9d13e899ab33e3334c372d8b
 SHA512:
-  metadata.gz: ed3978c9e0098cfc1ed4a19b933ce2a134e8841385e0e9542c267e43b6095f81c2b97b230a40d04605d0618717b3af289716157c3ab029f85b30886c54a11cb5
-  data.tar.gz: 626c429ccc91fc9f40401e58ab6142b81544684d57890fb0f51cec79d901e6280d06e2a14afb0400bb6d592faf33e5dbab5ef7c09045e4435b8557dd2162fb73
+  metadata.gz: 636c11b89dabc3d977f13d503ea7cc311c59dd4c677bfea917b333de36f37c045b1b1ddfec2a1f4643131c0f160dad33651ebf4371c32a365783b8e4c7f1df5f
+  data.tar.gz: e09b76e0ca7552f014259429ee4f16ce5ee64b75f4cd829dbffa391ec0604901ba2d9b5a23dd3375bc79f95dc3abe4ca4a77c483634de0343ed2601694bde538

data/README.md

@@ -263,8 +263,12 @@ 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()`,
-and garbage raises `ArgumentError` loudly. The honest limits: staleness
+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 —
@@ -369,6 +373,20 @@ not with the block matcher.
 it names record-layer guards only. An input-reading `guard:` has no name
 there, and the failure message says so instead of guessing.
 
+Under [`versioning:`](#stale-transitions-versioning-against-aba) the block
+matcher folds the version into the same assertion — a matching transition
+must also have incremented the version column — and every failure message
+prints the record's standing with its version
+(`Order in state :pending (state_version 3)`). Staleness stays an
+exception, exactly as in production: assert the refusal of a stale token
+with `raise_error`, not with a prediction matcher —
+
+<!-- illustrative -->
+```ruby
+expect { order.cancel!(seen: stale_token) }
+  .to raise_error(Statecraft::StaleTransition)
+```
+
 ## Metadata
 
 Metadata is normalized on pipeline entry with a full JSON round-trip —
@@ -513,6 +531,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`
@@ -732,7 +755,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] %>">
+  <input type="hidden" name="seen" value="<%= @order.state_version %>">
   <fieldset>
     <legend>Metadata for the next action</legend>
     <label>

data/lib/statecraft/errors.rb

@@ -46,18 +46,25 @@ module Statecraft
     end
   end
 
-  # The refusal of a seen: token: the snapshot the caller acted on is no
-  # longer the row's version. A subclass of TransitionConflict, so existing
-  # rescues keep catching it; controllers map it to 409 specifically.
+  # 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}: " \
-                     "the caller saw version #{seen.inspect}, but the row has moved on")
+            message: "stale transition for #{record.class.name}##{record.id}: #{reason}")
     end
   end
 

data/lib/statecraft/pipeline/versioning.rb

@@ -22,6 +22,10 @@ module Statecraft
         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?
 
@@ -30,7 +34,13 @@ module Statecraft
                 "seen: requires versioning: true on the mounting of #{record.class.name}; " \
                 "add the option or drop the token"
         end
-        Integer(raw_seen)
+
+        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:

data/lib/statecraft/pipeline.rb

@@ -65,10 +65,12 @@ module Statecraft
 
       assert_single_column_primary_key
       @raw_seen = seen
-      @seen = normalize_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)

data/lib/statecraft/rspec/state_report.rb

@@ -14,7 +14,12 @@ module Statecraft
       end
 
       def standing(record)
-        "#{record.class.name} in state #{current_state(record).inspect}"
+        "#{record.class.name} in state #{current_state(record).inspect}#{version_standing(record)}"
+      end
+
+      def version_standing(record)
+        column = record.class.statecraft_mounting.version_column
+        column ? " (#{column} #{record[column]})" : ""
       end
 
       def machine(record)

data/lib/statecraft/rspec/transition.rb

@@ -7,7 +7,8 @@ module Statecraft
     #
     # The transition through the eyes of a test: the state column moved to
     # the target AND exactly one log row was appended with the matching
-    # from/to/event/metadata. A non-bang call that returned false leaves
+    # from/to/event/metadata — and under versioning: the version column
+    # incremented together with the state. A non-bang call that returned false leaves
     # both untouched — the matcher fails and explains why, from the same
     # introspection the pipeline consulted. Exceptions of the bang forms
     # fly through, like with the change matcher: refusals are asserted
@@ -45,10 +46,13 @@ module Statecraft
       def matches?(block)
         raise ArgumentError, "transition(record).to(:state) — the .to target is required" unless @to_state
 
+        @version_column = @record.class.statecraft_mounting.version_column
         @before_state = StateReport.current_state(@record)
+        @before_version = @record[@version_column] if @version_column
         appended_before = @record.history.count
         block.call
         @after_state = StateReport.current_state(@record)
+        @after_version = @record[@version_column] if @version_column
         @appended = @record.history.offset(appended_before).to_a
         collect_failures
         @failures.empty?
@@ -84,6 +88,15 @@ module Statecraft
           @failures << "the record ended in #{@after_state.inspect}, not #{@to_state.inspect}"
         end
         collect_row_mismatches(@appended.last)
+        collect_version_mismatch
+      end
+
+      def collect_version_mismatch
+        return unless @version_column
+        return if @after_version == @before_version + 1
+
+        @failures << "the #{@version_column} column went from #{@before_version} to #{@after_version}, " \
+                     "expected #{@before_version + 1}: a versioned transition increments the version with the state"
       end
 
       def collect_row_mismatches(row)

data/lib/statecraft/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: statecraft
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Igor Pugachev