statecraft 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 207eda16ee51c42a787b0e3ba1a37c297242316edfe742c6be75b5dbca1166c0
-  data.tar.gz: efe7505f2499fdcd1175b35be3c454a9143b7afb2824dc3a6f0e2f98a8429a5f
+  metadata.gz: f809e9a1769e457d33d4b526703e4c3c7beb4ca09f8a7550cbbd31c97b07ba12
+  data.tar.gz: 8193837939f39dd0de633330b7bfc36d7adbb821221072ce1cdf30890f3488d0
 SHA512:
-  metadata.gz: 29d2cd130932273c9469dcbecf03f2a0fb20d33fc8b776efba5f850cd21bb447c5032de1dc10375e5dc9718d993001f6e0b279a5aa2e72c7be0cd1b890408710
-  data.tar.gz: c0856de0dde4ff10884ac2f567848b01b8949b514a2a171971957161d88348994d8f207e0f1e2f5d10fb1137a2b750b7f9f08e183537759dd2947be8c57911f4
+  metadata.gz: a5da582f65eb60cd2f76fef2ec213ad6c09166b288f44d80f7065a943894a66c5f36134f6c094fd873e50562976a447d0183b3e0e47b5545bce707d63f965d83
+  data.tar.gz: f1247259b3bc97de6663d9545e00015e1ea443b9e9f0ac33af6a179c09ba534140b0037863ddd2fa64e4992234a5fe14ea0d43e4a9ddc30d1018927c0d3158c5

data/README.md

@@ -113,9 +113,10 @@ do not run, and unsaved changes on other attributes are neither saved nor
 callbacks are the transition's callbacks.
 
 Bang variants return the created log record. Non-bang variants return it too,
-or `false` — and `false` means exactly "a guard said no or the edge is not
-declared" (`GuardFailed` / `InvalidTransition`). Everything else — including
-`TransitionConflict` — always raises, in both variants.
+or `false` — and `false` covers exactly three refusals: a guard said no, the
+edge is not declared, or the bypass policy refused a direct transition over
+an event-guarded edge (`GuardFailed` / `InvalidTransition`). Everything
+else — including `TransitionConflict` — always raises, in both variants.
 
 ## Guards, events and the bypass policy
 
@@ -217,7 +218,14 @@ symbol keys and values become strings, times become ISO-8601 strings — and
 then deep-frozen: **the guards see exactly what the log will store**, and a
 guard that mutates metadata dies with `FrozenError` in a transition and in a
 check alike. Unserializable values (a `Proc`, a model instance) fail
-instantly at the entrance, not inside the transaction.
+instantly at the entrance, not inside the transaction — and so do `NaN` and
+`Infinity`, which JSON cannot represent.
+
+`BigDecimal` is rejected deliberately, not by omission: jsonb would hand it
+back as a string or a float depending on the reader, silently breaking the
+"what the guards checked is what the log stored" promise. Pass money and
+other exact decimals as strings (`metadata: { price: order.total.to_s }`)
+and parse them in the guard.
 
 Facts of the transition moment (a price snapshot, a rules version) are
 collected by the caller: `order.pay!(metadata: { price: order.total })`.

data/lib/generators/statecraft/machine/USAGE

@@ -0,0 +1,26 @@
+Description:
+    Creates everything one model needs for a statecraft state machine: the
+    migration (state column with a CHECK constraint for a fresh table, the
+    state_changed_at column, and the append-only per-model log table with a
+    cascade FK), the machine class, the readonly log model, the model itself
+    when it does not exist yet (an existing model gets the state_machine
+    mounting injected instead), and — once per application — the shared
+    ApplicationMachine parent.
+
+    Namespaced models are fully supported: every file lands by the full
+    path, and a table_name_prefix module is generated the way the Rails
+    model generator does it. For a model on a non-primary database the
+    migration lands in the migrations_paths configured for that database
+    (db/migrate when none is configured).
+
+Example:
+    bin/rails generate statecraft:machine Order
+    bin/rails generate statecraft:machine Shop::Order
+
+    This will create:
+        app/state_machines/application_machine.rb  (first run only)
+        app/state_machines/shop/order_flow.rb
+        app/models/shop.rb                         (namespace prefix module)
+        app/models/shop/order_transition.rb
+        app/models/shop/order.rb                   (or mounting injection)
+        db/migrate/XXXXXXXXXXXXXX_create_shop_order_state_machine.rb

data/lib/statecraft/machine.rb

@@ -40,24 +40,28 @@ module Statecraft
       end
 
       def self.unary?(callable)
-        callable.arity == 1
+        arity = callable.respond_to?(:arity) ? callable.arity : callable.method(:call).arity
+        arity == 1
       end
     end
 
     # Class-level DSL collected declaratively and compiled by finalize!.
+    # Names arrive as symbols or strings interchangeably (the ActiveRecord
+    # idiom) and are normalized to symbols at the declaration line.
     module ClassMethods
       def state(name, initial: false)
-        declared_states << { name: name, initial: initial }
+        declared_states << { name: name.to_sym, initial: initial }
       end
 
       def transition(from:, to:, guard: nil, lock: false)
         declared_edges << {
-          from: from, to: to, guards: Array(guard), lock: lock || current_event_lock,
+          from: from.to_sym, to: to.to_sym, guards: Array(guard), lock: lock || current_event_lock,
           event: current_event_name
         }
       end
 
       def event(name, from: nil, to: nil, guard: nil, lock: false, &declarations)
+        name = name.to_sym
         declared_event_names << name
         if declarations
           if from || to
@@ -89,7 +93,9 @@ module Statecraft
 
           declared_callbacks[phase] << Callback.new(
             handler: callback_handler,
-            from: from && Array(from), to: to && Array(to), event: event && Array(event)
+            from: from && Array(from).map(&:to_sym),
+            to: to && Array(to).map(&:to_sym),
+            event: event && Array(event).map(&:to_sym)
           )
         end
       end
@@ -114,8 +120,11 @@ module Statecraft
         !@statecraft_compiled_graph.nil?
       end
 
+      # Compilation memoizes the graph and freezes the declaration lists, so a
+      # reopened machine class fails loudly on any late state/transition/event
+      # instead of silently ignoring it (callbacks already freeze in compile).
       def finalize!
-        @statecraft_compiled_graph ||= Compiler.new(self).compile
+        @statecraft_compiled_graph ||= Compiler.new(self).compile.tap { freeze_declarations }
       end
 
       def declared_states
@@ -136,6 +145,12 @@ module Statecraft
 
       private
 
+      def freeze_declarations
+        declared_states.freeze
+        declared_edges.freeze
+        declared_event_names.freeze
+      end
+
       def current_event_name
         @statecraft_current_event && @statecraft_current_event[:name]
       end
@@ -268,7 +283,7 @@ module Statecraft
         from_callbacks = machine_class.declared_callbacks.each_value.flat_map do |callbacks|
           callbacks.map(&:handler)
         end
-        (from_edges + from_callbacks).select { |handler| handler.is_a?(Symbol) }
+        (from_edges + from_callbacks).grep(Symbol)
       end
 
       def deep_freeze_edges(edges)

data/lib/statecraft/mounting.rb

@@ -82,11 +82,26 @@ module Statecraft
         raise ConnectionMismatch.new(model: model, log_class: log_class)
       end
 
+      # Methods this mounting itself defines, so a verb check runs BEFORE the
+      # includes and still sees them: an event named fire or history would
+      # otherwise silently shadow the gem's own surface.
+      def mounted_surface_methods
+        Pipeline::Surface.instance_methods +
+          Introspection.instance_methods +
+          %i[history last_transition in_state?]
+      end
+
       def assert_no_verb_conflicts(graph)
         return unless @helpers
 
+        surface_methods = mounted_surface_methods
         graph.events.each_key do |event_name|
           verb_names(event_name).each do |verb|
+            if surface_methods.include?(verb.to_sym)
+              raise CompilationError,
+                    "helper #{verb} for event #{event_name.inspect} conflicts with the " \
+                    "#{verb} method statecraft itself mounts; rename the event"
+            end
             next unless model.method_defined?(verb) || model.private_method_defined?(verb)
 
             raise CompilationError,

data/lib/statecraft/pipeline/edge_resolution.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Statecraft
+  class Pipeline
+    # Resolves the requested edge from the compiled graph and raises
+    # InvalidTransition with a diagnosis that names what actually failed:
+    # an undeclared edge, a bypass-policy refusal, an unknown event, or an
+    # event with no branch from the current state.
+    module EdgeResolution
+      private
+
+      def resolve_direct_edge(current, to_state, bypass_events)
+        edge = graph.edges[[current, to_state]]
+        raise_invalid_transition(current, to_state) if edge.nil?
+        guarding_events = edge.event_names.select { |name| edge.event_guards[name].any? }
+        if guarding_events.any? && !bypass_events
+          raise InvalidTransition.new(
+            record: record, from: current, requested: to_state,
+            allowed: allowed_targets(current),
+            message: "direct transition #{current} -> #{to_state} is guarded by " \
+                     "event#{"s" if guarding_events.length > 1} #{guarding_events.join(", ")}; " \
+                     "call fire!(:#{guarding_events.first}) or pass bypass_events: true"
+          )
+        end
+        edge
+      end
+
+      def resolve_event_edge(current, event_name)
+        branches = graph.events[event_name]
+        raise_unknown_event(current, event_name) if branches.nil?
+        edge = branches[current]
+        raise_event_without_branch(current, event_name, branches) if edge.nil?
+        edge
+      end
+
+      def raise_unknown_event(current, event_name)
+        known_events = graph.events.keys
+        raise InvalidTransition.new(
+          record: record, from: current, requested: event_name,
+          allowed: allowed_targets(current),
+          message: "unknown event #{event_name.inspect} for #{configuration.machine_class.name}; " \
+                   "events: #{known_events.empty? ? "none" : known_events.map(&:inspect).join(", ")}"
+        )
+      end
+
+      def raise_event_without_branch(current, event_name, branches)
+        declared_branches = branches.map { |from, edge| "#{from} -> #{edge.to}" }.join(", ")
+        raise InvalidTransition.new(
+          record: record, from: current, requested: event_name,
+          allowed: allowed_targets(current),
+          message: "event #{event_name.inspect} has no branch from #{current} for " \
+                   "#{record.class.name}; branches: #{declared_branches}"
+        )
+      end
+
+      def raise_invalid_transition(current, requested)
+        raise InvalidTransition.new(
+          record: record, from: current, requested: requested,
+          allowed: allowed_targets(current)
+        )
+      end
+
+      def allowed_targets(current)
+        graph.edges.keys.select { |from, _to| from == current }.map(&:last)
+      end
+    end
+  end
+end

data/lib/statecraft/pipeline.rb

@@ -28,6 +28,8 @@ module Statecraft
     STACK_KEY = :statecraft_transition_stack
     MAX_CHAIN_DEPTH = 16
 
+    include EdgeResolution
+
     def self.transition_stack
       ActiveSupport::IsolatedExecutionState[STACK_KEY] ||= []
     end
@@ -70,7 +72,7 @@ module Statecraft
         begin
           log_record = execute_transaction(edge, event, bypass, metadata, frame)
         ensure
-          Pipeline.transition_stack.delete(frame)
+          Pipeline.transition_stack.delete_if { |open| open.equal?(frame) }
         end
       rescue GuardFailed, InvalidTransition, TransitionConflict => transition_error
         publish_failure(started_at, transition_error)
@@ -149,41 +151,6 @@ module Statecraft
       record[configuration.column].to_s.to_sym
     end
 
-    def resolve_direct_edge(current, to_state, bypass_events)
-      edge = graph.edges[[current, to_state]]
-      raise_invalid_transition(current, to_state) if edge.nil?
-      guarding_events = edge.event_names.select { |name| edge.event_guards[name].any? }
-      if guarding_events.any? && !bypass_events
-        raise InvalidTransition.new(
-          record: record, from: current, requested: to_state,
-          allowed: allowed_targets(current),
-          message: "direct transition #{current} -> #{to_state} is guarded by " \
-                   "event#{"s" if guarding_events.length > 1} #{guarding_events.join(", ")}; " \
-                   "call fire!(:#{guarding_events.first}) or pass bypass_events: true"
-        )
-      end
-      edge
-    end
-
-    def resolve_event_edge(current, event_name)
-      branches = graph.events[event_name]
-      raise_invalid_transition(current, event_name) if branches.nil?
-      edge = branches[current]
-      raise_invalid_transition(current, event_name) if edge.nil?
-      edge
-    end
-
-    def raise_invalid_transition(current, requested)
-      raise InvalidTransition.new(
-        record: record, from: current, requested: requested,
-        allowed: allowed_targets(current)
-      )
-    end
-
-    def allowed_targets(current)
-      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.
@@ -311,7 +278,7 @@ module Statecraft
     end
 
     def warn_when_row_locking_unavailable
-      return unless base_class.connection.adapter_name.match?(/sqlite/i)
+      return unless base_class.connection_db_config.adapter.match?(/sqlite/i)
 
       Statecraft.warn(
         [configuration.machine_class.name, :sqlite_row_lock],

data/lib/statecraft/version.rb

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

data/lib/statecraft.rb

@@ -9,6 +9,7 @@ require_relative "statecraft/warnings"
 require_relative "statecraft/instrumentation"
 require_relative "statecraft/machine"
 require_relative "statecraft/metadata"
+require_relative "statecraft/pipeline/edge_resolution"
 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.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Igor Pugachev
@@ -60,6 +60,7 @@ extra_rdoc_files: []
 files:
 - LICENSE.txt
 - README.md
+- lib/generators/statecraft/machine/USAGE
 - lib/generators/statecraft/machine/machine_generator.rb
 - lib/generators/statecraft/machine/templates/add_migration.rb.tt
 - lib/generators/statecraft/machine/templates/application_machine.rb.tt
@@ -76,6 +77,7 @@ files:
 - lib/statecraft/metadata.rb
 - lib/statecraft/mounting.rb
 - lib/statecraft/pipeline.rb
+- lib/statecraft/pipeline/edge_resolution.rb
 - lib/statecraft/pipeline/surface.rb
 - lib/statecraft/version.rb
 - lib/statecraft/warnings.rb