statecraft 0.7.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e98ec25e4cfbb6cec172cd1f54ac9362937c967eff450ccda67d414e2dce6d3
-  data.tar.gz: e8f112727ef007ad0d6d3e91e67c122298bbf1d403f09aa9e2aeda56e43545da
+  metadata.gz: b91fc7675cab350149a2e58679893b18ccdfa779cc84e2eb5a7d28c5591c265c
+  data.tar.gz: c751611f88af3a85738877185b68de734578a353818aa130c19206d40b498b82
 SHA512:
-  metadata.gz: ed3978c9e0098cfc1ed4a19b933ce2a134e8841385e0e9542c267e43b6095f81c2b97b230a40d04605d0618717b3af289716157c3ab029f85b30886c54a11cb5
-  data.tar.gz: 626c429ccc91fc9f40401e58ab6142b81544684d57890fb0f51cec79d901e6280d06e2a14afb0400bb6d592faf33e5dbab5ef7c09045e4435b8557dd2162fb73
+  metadata.gz: 42c744386532cf91f06374dc3695c4e2ee3e64602fbb428045e3b588c27dc32843959552dea944be5d98834f28036baf1d712da2c25008dba8b16766ca23310b
+  data.tar.gz: 86822e6c1fba14b00e6a8e18efc586a7f92f35280490a168e4d96d063a6d3ecd471eac6fe877c512b9972359d1d14f4d344521dc6f0fea56235075df2bae975b

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 —
@@ -513,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`
@@ -732,7 +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] %>">
+  <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/version.rb

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

metadata

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