phronomy 0.27.0 → 0.29.0

data/lib/phronomy/workflow/execution/workflow_runner.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "../../engine/concurrency/worker_input_restricted"
+require_relative "../../execution/concurrency/worker_input_restricted"
 
 require "securerandom"
 
@@ -14,7 +14,7 @@ module Phronomy
   # - Runtime admission uses a separate opaque owner token.
   #
   # Workflow persistence is synchronous at the repository contract but is always
-  # invoked through Runtime's OffloadPool. Durable terminal save results return
+  # invoked through its owning execution environment. Durable terminal save results return
   # to the same FSMSession before that session becomes halted/completed.
   # @api private
   class WorkflowRunner
@@ -29,8 +29,13 @@ module Phronomy
       :recursion_limit,
       :repository,
       :persist,
-      :expected_revision
-    )
+      :expected_revision,
+      :cancellation_token
+    ) do
+      def initialize(cancellation_token: nil, **fields)
+        super(**fields, cancellation_token: cancellation_token)
+      end
+    end
 
     # API/callback -> EventLoop control messages.
     StartCommand = Data.define(
@@ -79,6 +84,7 @@ module Phronomy
       entry_point:,
       exit_actions: {},
       wait_state_names: [],
+      task_states: {},
       persistence: nil
     )
       @state_class = state_class
@@ -90,8 +96,10 @@ module Phronomy
       @external_events = external_events
       @entry_point = entry_point
       @wait_state_names = wait_state_names
+      @task_states = task_states
       @persistence = persistence
-      @phase_machine_class = Workflow::PhaseMachineBuilder.new(
+      @environment = WorkflowExecutionEnvironment.current
+      @phase_machine_class = @environment.compile_transitions(
         entry_point: @entry_point,
         declared_states: @declared_states,
         wait_state_names: @wait_state_names,
@@ -99,7 +107,7 @@ module Phronomy
         entry_actions: @entry_actions,
         auto_transitions: auto_transitions,
         exit_actions: exit_actions
-      ).build
+      )
     end
 
     def invoke(input, config: {})
@@ -125,6 +133,7 @@ module Phronomy
     def send_event(state:, event:, input: nil)
       ensure_blocking_call_allowed!(:send_event, :signal)
       current_phase = state.phase.to_sym
+      reject_task_resume!(current_phase)
       event_name = resolve_resume_event(current_phase, event)
       workflow_instance_id = state.workflow_instance_id
       unless workflow_instance_id
@@ -153,7 +162,7 @@ module Phronomy
           "Valid events: #{@external_events.keys.inspect}"
       end
 
-      registry = Phronomy::WorkflowExecutionRegistry.existing_for(Phronomy::Runtime.instance)
+      registry = @environment.existing_registry
       return false unless registry
 
       registry.post_to_workflow(
@@ -168,8 +177,7 @@ module Phronomy
     # progression therefore remain EventLoop-owned.
     # @api private
     def deliver_on_event_loop(command)
-      event_loop = Phronomy::Runtime.instance.event_loop
-      assert_event_loop!(event_loop)
+      assert_execution_owner!
 
       case command
       when StartCommand
@@ -211,7 +219,7 @@ module Phronomy
     end
 
     def ensure_blocking_call_allowed!(method_name, async_alternative)
-      return unless Phronomy::Runtime.instance.event_loop.current?
+      return unless Phronomy::WaitPolicy.blocking_forbidden?
 
       raise Phronomy::Error,
         "Cannot call Workflow##{method_name} from the EventLoop thread. " \
@@ -220,7 +228,6 @@ module Phronomy
 
     def start_new_execution(input, config, stable_observer: nil)
       reject_legacy_workflow_identity_key!(config)
-      runtime = Phronomy::Runtime.instance
       result_task = Phronomy::TaskResult.deferred(name: "workflow:preparing")
       explicit_workflow_instance_id = !config[:workflow_instance_id].nil?
       workflow_instance_id = (config[:workflow_instance_id] || SecureRandom.uuid).to_s.freeze
@@ -242,7 +249,7 @@ module Phronomy
         owner_token: Object.new.freeze,
         explicit_workflow_instance_id: explicit_workflow_instance_id
       )
-      fail_task(result_task, runtime_rejected_error(:start)) unless post_control(runtime, command)
+      fail_task(result_task, runtime_rejected_error(:start)) unless post_control(command)
       result_task
     rescue => error
       fail_task(result_task, error) if defined?(result_task) && result_task
@@ -250,7 +257,6 @@ module Phronomy
     end
 
     def start_resume_execution(state, input:, event_name:, current_phase:)
-      runtime = Phronomy::Runtime.instance
       workflow_instance_id = state.workflow_instance_id.to_s.freeze
       result_task = Phronomy::TaskResult.deferred(name: "workflow-resume:#{workflow_instance_id}")
       Phronomy::Tracing::Automatic.observe_task(
@@ -271,7 +277,7 @@ module Phronomy
         workflow_instance_id: workflow_instance_id,
         owner_token: Object.new.freeze
       )
-      fail_task(result_task, runtime_rejected_error(:resume)) unless post_control(runtime, command)
+      fail_task(result_task, runtime_rejected_error(:resume)) unless post_control(command)
       result_task
     rescue => error
       fail_task(result_task, error) if defined?(result_task) && result_task
@@ -279,10 +285,8 @@ module Phronomy
     end
 
     def begin_start_on_event_loop(request)
-      runtime = Phronomy::Runtime.instance
-      event_loop = runtime.event_loop
       admitted = false
-      Phronomy::WorkflowExecutionRegistry.for(event_loop).admit_workflow(
+      @environment.registry.admit_workflow(
         request.workflow_instance_id,
         owner_token: request.owner_token
       )
@@ -290,7 +294,7 @@ module Phronomy
 
       recursion_limit = request.config.fetch(
         :recursion_limit,
-        Phronomy.configuration.recursion_limit
+        Phronomy::WorkflowSettings.current.recursion_limit
       )
       repository = configured_repository
       persist = request.explicit_workflow_instance_id && !repository.nil?
@@ -304,7 +308,8 @@ module Phronomy
           repository: repository,
           persist: false,
           loaded_snapshot: nil,
-          expected_revision: nil
+          expected_revision: nil,
+          cancellation_token: request.config[:cancellation_token]
         )
         register_execution(
           execution,
@@ -315,7 +320,6 @@ module Phronomy
       end
 
       submit_workflow_load(
-        runtime,
         repository,
         request.workflow_instance_id,
         StartLoadReady,
@@ -323,7 +327,7 @@ module Phronomy
       )
     rescue => error
       if admitted
-        Phronomy::WorkflowExecutionRegistry.for(event_loop).release_workflow(
+        @environment.registry.release_workflow(
           request.workflow_instance_id,
           owner_token: request.owner_token
         )
@@ -332,10 +336,8 @@ module Phronomy
     end
 
     def begin_resume_on_event_loop(request)
-      runtime = Phronomy::Runtime.instance
-      event_loop = runtime.event_loop
       admitted = false
-      Phronomy::WorkflowExecutionRegistry.for(event_loop).admit_workflow(
+      @environment.registry.admit_workflow(
         request.workflow_instance_id,
         owner_token: request.owner_token
       )
@@ -348,10 +350,11 @@ module Phronomy
           context: context,
           workflow_instance_id: request.workflow_instance_id,
           owner_token: request.owner_token,
-          recursion_limit: Phronomy.configuration.recursion_limit,
+          recursion_limit: Phronomy::WorkflowSettings.current.recursion_limit,
           repository: nil,
           persist: false,
-          expected_revision: nil
+          expected_revision: nil,
+          cancellation_token: nil
         )
         register_execution(
           execution,
@@ -363,7 +366,6 @@ module Phronomy
       end
 
       submit_workflow_load(
-        runtime,
         repository,
         request.workflow_instance_id,
         ResumeLoadReady,
@@ -371,7 +373,7 @@ module Phronomy
       )
     rescue => error
       if admitted
-        Phronomy::WorkflowExecutionRegistry.for(event_loop).release_workflow(
+        @environment.registry.release_workflow(
           request.workflow_instance_id,
           owner_token: request.owner_token
         )
@@ -379,12 +381,12 @@ module Phronomy
       fail_task(request.result_task, error)
     end
 
-    def submit_workflow_load(runtime, repository, workflow_instance_id, ready_class, request)
+    def submit_workflow_load(repository, workflow_instance_id, ready_class, request)
       operation = WorkflowLoadCommand.new(
         repository: repository,
         workflow_instance_id: workflow_instance_id.to_s.freeze
       )
-      task = runtime.offload.submit(on_full: :raise) do
+      task = @environment.submit(on_full: :raise) do
         record = operation.repository.load(operation.workflow_instance_id)
         WorkflowLoadResult.new(
           repository: operation.repository,
@@ -400,7 +402,7 @@ module Phronomy
           error: error
         )
         fail_task(request.result_task, runtime_rejected_error(:load_result)) unless
-          post_control(runtime, ready)
+          post_control(ready)
       end
       nil
     end
@@ -414,7 +416,7 @@ module Phronomy
 
       recursion_limit = request.config.fetch(
         :recursion_limit,
-        Phronomy.configuration.recursion_limit
+        Phronomy::WorkflowSettings.current.recursion_limit
       )
       execution = build_new_execution(
         request.input,
@@ -424,7 +426,8 @@ module Phronomy
         repository: ready.result.repository,
         persist: true,
         loaded_snapshot: ready.result.snapshot,
-        expected_revision: ready.result.revision
+        expected_revision: ready.result.revision,
+        cancellation_token: request.config[:cancellation_token]
       )
       register_execution(
         execution,
@@ -452,10 +455,11 @@ module Phronomy
         context: context,
         workflow_instance_id: request.workflow_instance_id,
         owner_token: request.owner_token,
-        recursion_limit: Phronomy.configuration.recursion_limit,
+        recursion_limit: Phronomy::WorkflowSettings.current.recursion_limit,
         repository: ready.result.repository,
         persist: true,
-        expected_revision: expected_revision
+        expected_revision: expected_revision,
+        cancellation_token: nil
       )
       register_execution(
         execution,
@@ -475,8 +479,11 @@ module Phronomy
       repository:,
       persist:,
       loaded_snapshot:,
-      expected_revision:
+      expected_revision:,
+      cancellation_token: nil
     )
+      stored_phase = loaded_snapshot && (loaded_snapshot[:phase] || loaded_snapshot["phase"])
+      reject_task_resume!(stored_phase&.to_sym)
       stored_fields = loaded_snapshot &&
         (loaded_snapshot[:fields] || loaded_snapshot["fields"])
       initial_fields = if stored_fields
@@ -497,7 +504,8 @@ module Phronomy
         recursion_limit: recursion_limit,
         repository: repository,
         persist: persist,
-        expected_revision: expected_revision
+        expected_revision: expected_revision,
+        cancellation_token: cancellation_token
       )
     end
 
@@ -508,7 +516,7 @@ module Phronomy
       local_snapshot = normalize_snapshot(snapshot_for(state))
       return durable_revision if normalized_durable == local_snapshot
 
-      raise Phronomy::Storage::ConflictError,
+      raise Phronomy::Persistence::StateConflictError,
         "Workflow state changed since the supplied halted context for " \
         "workflow_instance_id #{state.workflow_instance_id.inspect}; explicit reload/reconciliation is required"
     end
@@ -560,8 +568,7 @@ module Phronomy
     end
 
     def configured_repository
-      persistence = @persistence || Phronomy.configuration.persistence
-      persistence&.workflow_states
+      @persistence || Phronomy::WorkflowSettings.current.workflow_store
     end
 
     def register_execution(
@@ -571,17 +578,21 @@ module Phronomy
       resume_phase: nil,
       stable_observer: nil
     )
-      runtime = Phronomy::Runtime.instance
-      event_loop = runtime.event_loop
-      assert_event_loop!(event_loop)
+      assert_execution_owner!
+      task_execution = unless @task_states.empty?
+        WorkflowTaskExecution.new(definitions: @task_states, registry: @environment.registry,
+          environment: @environment, owner_token: execution.owner_token, result_task: result_task,
+          cancellation_token: execution.cancellation_token)
+      end
       session = build_session_for(
         execution: execution,
-        runtime: runtime,
         resume_event: resume_event,
         resume_phase: resume_phase,
-        stable_observer: stable_observer
+        stable_observer: stable_observer,
+        task_execution: task_execution
       )
-      Phronomy::WorkflowExecutionRegistry.for(event_loop).bind_workflow_session(
+      @environment.registry.bind_task_execution(task_execution) if task_execution
+      @environment.registry.bind_workflow_session(
         execution.workflow_instance_id,
         owner_token: execution.owner_token,
         fsm_session_id: session.id
@@ -593,15 +604,15 @@ module Phronomy
           execution: execution,
           result_task: result_task,
           result: result,
-          error: error
+          error: error,
+          task_execution: task_execution
         )
       end
-      event_loop.register(session, completion: source_task,
-        receiver: Phronomy::WorkflowExecutionRegistry.for(event_loop))
+      @environment.register_session(session, completion: source_task)
       result_task
     rescue => error
-      if event_loop&.current?
-        Phronomy::WorkflowExecutionRegistry.for(event_loop).release_workflow(
+      if @environment.executing?
+        @environment.registry.release_workflow(
           execution.workflow_instance_id,
           owner_token: execution.owner_token
         )
@@ -611,14 +622,17 @@ module Phronomy
 
     # Called from source_task completion on EventLoop, after the FSMSession has
     # accepted the durable terminal result (when a durable barrier is required).
-    def finalize_execution(execution:, result_task:, result:, error:)
-      event_loop = Phronomy::Runtime.instance.event_loop
-      assert_event_loop!(event_loop)
-      Phronomy::WorkflowExecutionRegistry.for(event_loop).release_workflow(
+    def finalize_execution(execution:, result_task:, result:, error:, task_execution: nil)
+      assert_execution_owner!
+      @environment.registry.release_workflow(
         execution.workflow_instance_id,
         owner_token: execution.owner_token
       )
-      error ? fail_task(result_task, error) : complete_task(result_task, result)
+      if error && task_execution&.cancelled_error&.equal?(error)
+        result_task.cancel!(error)
+      else
+        error ? fail_task(result_task, error) : complete_task(result_task, result)
+      end
     end
 
     def begin_terminal_persistence_on_event_loop(
@@ -627,10 +641,8 @@ module Phronomy
       context:,
       event_sink:
     )
-      runtime = Phronomy::Runtime.instance
-      event_loop = runtime.event_loop
-      assert_event_loop!(event_loop)
-      Phronomy::WorkflowExecutionRegistry.for(event_loop).mark_workflow_admission(
+      assert_execution_owner!
+      @environment.registry.mark_workflow_admission(
         execution.workflow_instance_id,
         owner_token: execution.owner_token,
         state: :persisting_terminal
@@ -643,7 +655,7 @@ module Phronomy
         snapshot: deep_immutable_copy(snapshot_for(context))
       )
 
-      task = runtime.offload.submit(on_full: :raise) do
+      task = @environment.submit(on_full: :raise) do
         persist_terminal_snapshot(operation)
       end
       task.on_complete do |result, operation_error|
@@ -663,10 +675,10 @@ module Phronomy
         revision: revision,
         error: nil
       )
-    rescue Phronomy::Storage::ConflictError,
-      Phronomy::Storage::NotFoundError,
-      Phronomy::Storage::SerializationError,
-      Phronomy::Storage::UnsupportedBackendError => error
+    rescue Phronomy::Persistence::ConflictError,
+      Phronomy::Persistence::NotFoundError,
+      Phronomy::Persistence::SerializationError,
+      Phronomy::Persistence::UnsupportedBackendError => error
       Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
         outcome: :known_failure,
         revision: nil,
@@ -688,7 +700,7 @@ module Phronomy
       end
       accepted = event_sink.post(:workflow_terminal_persistence_result, delivery)
       unless accepted
-        Phronomy.configuration.logger&.warn(
+        Phronomy::RuntimeSettings.current.logger&.warn(
           "[Phronomy] EventLoop rejected Workflow terminal persistence result " \
           "for #{execution.workflow_instance_id.inspect}"
         )
@@ -697,13 +709,13 @@ module Phronomy
 
     def reconcile_workflow_terminal_f1(operation, original_error)
       record = operation.repository.load(operation.workflow_instance_id)
-      case Phronomy::Recovery.compare_revisioned_snapshot(
+      case Phronomy::Persistence::SnapshotComparison.compare_revisioned_snapshot(
         record: record,
         expected_pre_revision: operation.expected_revision,
         intended_snapshot: operation.snapshot
       )
       when :post_state
-        revision = Phronomy::Recovery.fetch_value(record, :revision)
+        revision = Phronomy::Persistence::SnapshotComparison.fetch_value(record, :revision)
         Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
           outcome: :success,
           revision: revision,
@@ -719,7 +731,7 @@ module Phronomy
           error: original_error
         )
       else
-        conflict = Phronomy::Storage::ConflictError.new(
+        conflict = Phronomy::Persistence::StateConflictError.new(
           "Workflow terminal Persistence outcome conflicts with both expected " \
           "pre-state and intended post-state for #{operation.workflow_instance_id.inspect}"
         )
@@ -738,9 +750,8 @@ module Phronomy
     end
 
     def release_and_fail(request, error)
-      event_loop = Phronomy::Runtime.instance.event_loop
-      assert_event_loop!(event_loop)
-      Phronomy::WorkflowExecutionRegistry.for(event_loop).release_workflow(
+      assert_execution_owner!
+      @environment.registry.release_workflow(
         request.workflow_instance_id,
         owner_token: request.owner_token
       )
@@ -756,12 +767,12 @@ module Phronomy
 
     def build_session_for(
       execution:,
-      runtime:,
       resume_event: nil,
       resume_phase: nil,
-      stable_observer: nil
+      stable_observer: nil,
+      task_execution: nil
     )
-      Phronomy::FSMSession.new(
+      @environment.build_session(
         context: execution.context,
         context_metadata: {
           workflow_instance_id: execution.workflow_instance_id
@@ -774,27 +785,25 @@ module Phronomy
         external_events: @external_events,
         phase_machine_class: @phase_machine_class,
         recursion_limit: execution.recursion_limit,
-        event_loop: runtime.event_loop,
         resume_event: resume_event,
         resume_phase: resume_phase,
         stable_observer: stable_observer,
-        terminal_policy: build_terminal_policy(execution)
+        persist: terminal_persistence_callback(execution),
+        task_execution: task_execution
       )
     end
 
-    def build_terminal_policy(execution)
+    def terminal_persistence_callback(execution)
       return unless execution.repository && execution.persist
 
-      Phronomy::WorkflowTerminalPolicy.new(
-        persist: ->(terminal_type:, context:, event_sink:) {
-          begin_terminal_persistence_on_event_loop(
-            execution,
-            terminal_type: terminal_type,
-            context: context,
-            event_sink: event_sink
-          )
-        }
-      )
+      ->(terminal_type:, context:, event_sink:) {
+        begin_terminal_persistence_on_event_loop(
+          execution,
+          terminal_type: terminal_type,
+          context: context,
+          event_sink: event_sink
+        )
+      }
     end
 
     def resolve_resume_event(current_phase, event)
@@ -819,10 +828,14 @@ module Phronomy
         "No external event registered for state #{current_phase.inspect}"
     end
 
-    def post_control(runtime, command)
+    def reject_task_resume!(phase)
+      raise Phronomy::WorkflowTaskResumeError if phase && @task_states.key?(phase)
+    end
+
+    def post_control(command)
       admission = command.is_a?(StartCommand) || command.is_a?(ResumeCommand)
       completion = admission ? command.result_task : command.request.result_task
-      Phronomy::WorkflowExecutionRegistry.for(runtime.event_loop).post(command,
+      @environment.registry.post(command,
         admission: admission, completion: completion)
     end
 
@@ -832,8 +845,8 @@ module Phronomy
       )
     end
 
-    def assert_event_loop!(event_loop)
-      return if event_loop.current?
+    def assert_execution_owner!
+      return if @environment.executing?
 
       raise Phronomy::Error,
         "Workflow live-state progression must run on EventLoop"

data/lib/phronomy/workflow/execution/workflow_settings.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Workflow-owned progress limit and optional state repository. Composition
+  # supplies these values; existing execution boundaries decide when to read.
+  # @api private
+  class WorkflowSettings
+    class << self
+      # Bind at boot without reading settings or starting runtime resources.
+      def install_provider(&provider)
+        raise ArgumentError, "settings provider requires a block" unless provider
+        @provider = provider
+        nil
+      end
+
+      # Read only when requested; no cache or change notification is involved.
+      def current
+        @provider.call
+      end
+    end
+
+    attr_accessor :recursion_limit, :workflow_store
+
+    def initialize(recursion_limit:)
+      @recursion_limit = recursion_limit
+    end
+  end
+end