geneva_drive 0.5.0 → 0.7.0

data/lib/generators/geneva_drive/install/templates/add_metadata_to_workflows.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class AddMetadataToGenevaDriveWorkflows < ActiveRecord::Migration[7.2]
+  def change
+    return if column_exists?(:geneva_drive_workflows, :metadata)
+
+    adapter = connection.adapter_name.downcase
+
+    if adapter.include?("postgresql")
+      add_column :geneva_drive_workflows, :metadata, :jsonb
+    elsif adapter.include?("mysql")
+      add_column :geneva_drive_workflows, :metadata, :text, limit: 4_294_967_295
+    else
+      add_column :geneva_drive_workflows, :metadata, :text
+    end
+  end
+end

data/lib/generators/geneva_drive/install/templates/add_resumable_step_support.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class AddResumableStepSupportToGenevaDriveStepExecutions < ActiveRecord::Migration[7.2]
+  include GenevaDrive::MigrationHelpers
+
+  def change
+    unless column_exists?(:geneva_drive_step_executions, :cursor)
+      # Cursor for resumable steps. Use database-native JSON type:
+      # - PostgreSQL: jsonb (indexed, efficient, supports containment queries)
+      # - MySQL 5.7+: json (native validation and storage)
+      # - SQLite: json (Rails handles as TEXT with serialization)
+      if connection.adapter_name.downcase.include?("postgresql")
+        add_column :geneva_drive_step_executions, :cursor, :jsonb
+      else
+        add_column :geneva_drive_step_executions, :cursor, :json
+      end
+    end
+
+    unless column_exists?(:geneva_drive_step_executions, :continues_from_id)
+      # Link successor executions to their predecessor, chaining the execution
+      # records of a resumable step. Match the primary key type (bigint or uuid)
+      # of the step_executions table.
+      # No foreign key constraint - SQLite rewrites the table on add_foreign_key,
+      # which can destroy data.
+      add_column :geneva_drive_step_executions, :continues_from_id, geneva_drive_key_type
+      add_index :geneva_drive_step_executions, :continues_from_id
+    end
+  end
+end

data/lib/generators/geneva_drive/install/templates/add_signals_support.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+# Signals: external events delivered to a workflow, and the two columns on
+# step executions that let one park until a matching event arrives. Both halves
+# ship together - a signals table nobody can wait on is useless, and a waiting
+# step with nowhere to read its event from is worse - so they are one migration.
+class AddSignalsSupportToGenevaDrive < ActiveRecord::Migration[7.2]
+  include GenevaDrive::MigrationHelpers
+
+  def change
+    key_type = geneva_drive_key_type
+    adapter = connection.adapter_name.downcase
+
+    # Build reference options - we add the foreign key separately to avoid
+    # MySQL type mismatch (see below).
+    reference_options = {
+      null: false,
+      index: true
+    }
+    reference_options[:type] = key_type if key_type == :uuid
+
+    create_table :geneva_drive_signals, **geneva_drive_table_options do |t|
+      # Link to workflow (cascade delete when the workflow is deleted)
+      t.references :workflow, **reference_options
+
+      # The event name, as passed to Workflow#signal!
+      t.string :name, null: false
+
+      # Optional caller-supplied deduplication key. NULLs are distinct in
+      # unique indexes on PostgreSQL, MySQL and SQLite alike, so signals
+      # without an idempotency key always insert.
+      t.string :idempotency_key
+
+      # Lifecycle: pending -> claimed -> consumed
+      t.string :state, null: false, default: "pending"
+
+      # Serialized payload. Use the database-native JSON type, same flavor
+      # logic as the resumable step cursor:
+      # - PostgreSQL: jsonb
+      # - MySQL 5.7+: json
+      # - SQLite: json (Rails handles as TEXT with serialization)
+      if adapter.include?("postgresql")
+        t.jsonb :payload
+      else
+        t.json :payload
+      end
+
+      t.datetime :claimed_at
+      t.datetime :consumed_at
+
+      # How many executions have attached to this signal, and how many of
+      # those attached chains have resolved cleanly. For a linear workflow
+      # both end at 1 (more claims if the step was retried); when one signal
+      # is dispatched onto several concurrent executions the pair is the
+      # progress readout of that fan-out. Counters, not the lifecycle state -
+      # the `state` column above is what says claimed or consumed.
+      t.bigint :claimed, null: false, default: 0
+      t.bigint :consumed, null: false, default: 0
+
+      t.timestamps
+    end
+
+    # Deduplication: one signal per (workflow, name, idempotency_key)
+    add_index :geneva_drive_signals, [:workflow_id, :name, :idempotency_key],
+      unique: true, name: "index_geneva_drive_signals_dedup"
+
+    # Scanning a workflow's unconsumed signals
+    add_index :geneva_drive_signals, [:workflow_id, :state]
+
+    # Add foreign key separately to avoid MySQL type mismatch (UNSIGNED vs SIGNED bigint)
+    # MySQL creates primary keys as UNSIGNED but references as SIGNED, causing FK constraint failure
+    unless adapter.include?("mysql")
+      add_foreign_key :geneva_drive_signals, :geneva_drive_workflows,
+        column: :workflow_id, on_delete: :cascade
+    end
+
+    unless column_exists?(:geneva_drive_step_executions, :signal_id)
+      # The attachment pin: which signal this execution is processing. One
+      # signal may be pinned by many executions, so this lives on the
+      # execution side. Match the primary key type (bigint or uuid) of the
+      # signals table.
+      # No foreign key constraint - SQLite rewrites the table on
+      # add_foreign_key, which can destroy data.
+      add_column :geneva_drive_step_executions, :signal_id, key_type
+      add_index :geneva_drive_step_executions, :signal_id
+    end
+
+    unless column_exists?(:geneva_drive_step_executions, :waiting_since)
+      # When the execution parked waiting for a signal, so "waiting for N
+      # days" is queryable without abusing updated_at.
+      add_column :geneva_drive_step_executions, :waiting_since, :datetime
+    end
+  end
+end

data/lib/generators/geneva_drive/install/templates/add_started_at_index_to_step_executions.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+class AddStartedAtIndexToGenevaDriveStepExecutions < ActiveRecord::Migration[7.2]
+  # Partial index scoped to state = 'in_progress'. HousekeepingJob's
+  # recover_stuck_in_progress! filters `state = 'in_progress' AND
+  # started_at < cutoff LIMIT N`; without this the planner walks the whole
+  # in-progress set looking for old rows and trips the caller's
+  # statement_timeout on large / mostly-fresh workloads.
+  INDEX_NAME = :index_geneva_drive_step_executions_in_progress_started_at
+
+  disable_ddl_transaction!
+
+  def up
+    return if index_name_exists?(:geneva_drive_step_executions, INDEX_NAME)
+
+    adapter = connection.adapter_name.downcase
+
+    if adapter.include?("postgresql")
+      add_index :geneva_drive_step_executions, :started_at,
+        name: INDEX_NAME,
+        where: "state = 'in_progress'",
+        algorithm: :concurrently
+    elsif adapter.include?("sqlite")
+      # SQLite supports partial indexes but has no CONCURRENTLY.
+      add_index :geneva_drive_step_executions, :started_at,
+        name: INDEX_NAME,
+        where: "state = 'in_progress'"
+    else
+      # MySQL does not support partial indexes; fall back to a plain index.
+      # Composite (state, started_at) so the planner can seek by state first.
+      add_index :geneva_drive_step_executions, [:state, :started_at],
+        name: INDEX_NAME
+    end
+  end
+
+  def down
+    return unless index_name_exists?(:geneva_drive_step_executions, INDEX_NAME)
+
+    adapter = connection.adapter_name.downcase
+    if adapter.include?("postgresql")
+      remove_index :geneva_drive_step_executions,
+        name: INDEX_NAME,
+        algorithm: :concurrently
+    else
+      remove_index :geneva_drive_step_executions, name: INDEX_NAME
+    end
+  end
+end

data/lib/generators/geneva_drive/install/templates/create_workflows_migration.rb

@@ -4,6 +4,8 @@ class CreateGenevaDriveWorkflows < ActiveRecord::Migration[7.2]
   include GenevaDrive::MigrationHelpers
 
   def change
+    adapter = connection.adapter_name.downcase
+
     create_table :geneva_drive_workflows, **geneva_drive_table_options do |t|
       # Core identification (STI)
       t.string :type, null: false, index: true
@@ -22,6 +24,15 @@ class CreateGenevaDriveWorkflows < ActiveRecord::Migration[7.2]
       # Multiple workflows of same type for same hero
       t.boolean :allow_multiple, default: false, null: false
 
+      # Freeform JSON metadata
+      if adapter.include?("postgresql")
+        t.jsonb :metadata
+      elsif adapter.include?("mysql")
+        t.text :metadata, limit: 4_294_967_295
+      else
+        t.text :metadata
+      end
+
       # Timestamps
       t.datetime :started_at
       t.datetime :transitioned_at

data/lib/generators/geneva_drive/install/templates/initializer.rb.tt

@@ -31,6 +31,14 @@
 #
 # GenevaDrive.housekeeping_batch_size = 1000
 
+# Maximum size in bytes of a resumable step cursor once serialized to JSON.
+# The cursor is a position marker (an id, page number, or pagination token),
+# not a place to store the data being processed - it is rewritten on every
+# checkpoint and copied to every successor execution. Exceeding the limit
+# raises GenevaDrive::CursorTooLargeError. Set to nil to disable the check.
+#
+# GenevaDrive.max_cursor_size = 128.kilobytes
+
 # Whether to defer job enqueueing until after the database transaction commits.
 # In production this ensures step execution records are visible to job workers
 # before the job runs. In test environments (the default when Rails.env.test?)

data/lib/geneva_drive/combined_exception_policy.rb

@@ -88,7 +88,7 @@ class GenevaDrive::CombinedExceptionPolicy
     cap = max_reattempts
     if cap && result[:action] == :reattempt && reattempt_count >= cap
       terminal = child.terminal_action.to_s.chomp("!").to_sym
-      return {action: terminal, error: error}
+      return {action: terminal, error: error, report: result[:report], terminal: true}
     end
 
     result

data/lib/geneva_drive/exception_policy.rb

@@ -85,6 +85,9 @@ class GenevaDrive::ExceptionPolicy
   #   Each entry can be an Exception subclass or any object responding to #===.
   attr_reader :exception_matchers
 
+  # @return [Symbol] when to report the exception via Rails.error.report (:always, :never, or :terminal_only)
+  attr_reader :report
+
   # @return [Proc, nil] the handler block (imperative mode)
   attr_reader :handler
 
@@ -93,7 +96,10 @@ class GenevaDrive::ExceptionPolicy
   # Valid terminal_action values
   VALID_TERMINAL_ACTIONS = %i[pause! cancel! skip!].freeze
 
-  # @overload initialize(action, matching: nil, wait: nil, max_reattempts: nil, terminal_action: :pause!)
+  # Valid report values
+  VALID_REPORT_OPTIONS = %i[always never terminal_only].freeze
+
+  # @overload initialize(action, matching: nil, wait: nil, max_reattempts: nil, terminal_action: :pause!, report: :always)
   #   Declarative mode — specify action and options.
   #   @param action [Symbol] the flow control action (:pause!, :cancel!, :reattempt!, :skip!)
   #   @param matching [Class, String, #===, Array<Class, String, #===>, nil] exception classes
@@ -104,12 +110,19 @@ class GenevaDrive::ExceptionPolicy
   #   @param wait [ActiveSupport::Duration, nil] wait time before reattempt
   #   @param max_reattempts [Integer, nil] max consecutive reattempts (nil = unlimited)
   #   @param terminal_action [Symbol] what to do when max_reattempts is exceeded (:pause!, :cancel!, or :skip!)
+  #   @param report [Symbol] when to report the exception to +Rails.error.report+.
+  #     - +:always+ (default) — report every exception regardless of what action is taken
+  #     - +:never+ — never report; the exception is expected and handled by the policy
+  #     - +:terminal_only+ — suppress reports while the step is being reattempted, but
+  #       report when reattempts are exhausted and the +terminal_action+ fires
   #
-  # @overload initialize(matching: nil, &block)
+  # @overload initialize(matching: nil, report: :always, &block)
   #   Imperative mode — block receives exception, runs in workflow context.
   #   Must call a flow control method (reattempt!, cancel!, pause!, skip!).
-  #   Can be combined with +matching:+ to target specific exception classes.
+  #   Can be combined with +matching:+ and +report:+ to target specific exception classes
+  #   and control error reporting.
   #   @param matching [Class, String, #===, Array<Class, String, #===>, nil] exception classes
+  #   @param report [Symbol] when to report the exception (+:always+, +:never+, or +:terminal_only+)
   #   @yield [error] the exception that was raised
   #
   # @example Blanket reattempt policy
@@ -126,7 +139,18 @@ class GenevaDrive::ExceptionPolicy
   #
   # @example Imperative policy with exception matching
   #   ExceptionPolicy.new(matching: Timeout::Error) { |error| reattempt!(wait: error.retry_after) }
-  def initialize(action = nil, wait: nil, max_reattempts: nil, terminal_action: :pause!, matching: nil, &block)
+  #
+  # @example Suppress error reporting for expected exceptions
+  #   ExceptionPolicy.new(:reattempt!, matching: RateLimitError, report: :never)
+  #
+  # @example Only report when reattempts are exhausted
+  #   ExceptionPolicy.new(:reattempt!, matching: Net::OpenTimeout, max_reattempts: 5, report: :terminal_only)
+  def initialize(action = nil, wait: nil, max_reattempts: nil, terminal_action: :pause!, matching: nil, report: :always, &block)
+    @report = report
+    unless VALID_REPORT_OPTIONS.include?(@report)
+      raise ArgumentError,
+        "report: must be one of #{VALID_REPORT_OPTIONS.join(", ")}, got #{@report.inspect}"
+    end
     if block
       if action || wait || max_reattempts || terminal_action != :pause!
         raise ArgumentError,
@@ -191,8 +215,10 @@ class GenevaDrive::ExceptionPolicy
   # in the workflow context and translates the resulting flow control signal
   # into a result.
   #
-  # The returned Hash always contains +:action+ (Symbol without +!+) and
-  # +:error+ (the original exception). Reattempt results also include +:wait+.
+  # The returned Hash always contains +:action+ (Symbol without +!+),
+  # +:error+ (the original exception), and +:report+ (the reporting mode).
+  # Reattempt results also include +:wait+. When the terminal action fires
+  # (reattempt limit exceeded), +:terminal+ is set to +true+.
   #
   # @param error [Exception] the exception that was raised
   # @param reattempt_count [Integer] consecutive reattempts so far for this step
@@ -241,9 +267,9 @@ class GenevaDrive::ExceptionPolicy
     end
 
     if signal.is_a?(GenevaDrive::FlowControlSignal)
-      {action: signal.action, wait: signal.options[:wait], error: error}
+      {action: signal.action, wait: signal.options[:wait], error: error, report: @report}
     else
-      {action: :pause, error: error}
+      {action: :pause, error: error, report: @report}
     end
   end
 
@@ -256,9 +282,9 @@ class GenevaDrive::ExceptionPolicy
   def apply_declarative(error, reattempt_count)
     if action == :reattempt! && max_reattempts && reattempt_count >= max_reattempts
       terminal = terminal_action.to_s.chomp("!").to_sym
-      {action: terminal, error: error}
+      {action: terminal, error: error, report: @report, terminal: true}
     else
-      {action: action.to_s.chomp("!").to_sym, wait: wait, error: error}
+      {action: action.to_s.chomp("!").to_sym, wait: wait, error: error, report: @report}
     end
   end