shikibu 0.1.0

data/lib/shikibu/constants.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Shikibu
+  # Workflow instance status values (shared with Python/Go)
+  module Status
+    RUNNING = 'running'
+    COMPLETED = 'completed'
+    FAILED = 'failed'
+    WAITING_FOR_EVENT = 'waiting_for_event'
+    WAITING_FOR_TIMER = 'waiting_for_timer'
+    WAITING_FOR_MESSAGE = 'waiting_for_message'
+    COMPENSATING = 'compensating'
+    CANCELLED = 'cancelled'
+    RECURRED = 'recurred'
+
+    ALL = [
+      RUNNING,
+      COMPLETED,
+      FAILED,
+      WAITING_FOR_EVENT,
+      WAITING_FOR_TIMER,
+      WAITING_FOR_MESSAGE,
+      COMPENSATING,
+      CANCELLED,
+      RECURRED
+    ].freeze
+  end
+
+  # History event types (shared with Python/Go)
+  module EventType
+    ACTIVITY_COMPLETED = 'ActivityCompleted'
+    ACTIVITY_FAILED = 'ActivityFailed'
+    EVENT_RECEIVED = 'EventReceived'
+    TIMER_EXPIRED = 'TimerExpired'
+    MESSAGE_TIMEOUT = 'MessageTimeout'
+    CHANNEL_MESSAGE_RECEIVED = 'ChannelMessageReceived'
+    COMPENSATION_EXECUTED = 'CompensationExecuted'
+    COMPENSATION_FAILED = 'CompensationFailed'
+    WORKFLOW_FAILED = 'WorkflowFailed'
+    WORKFLOW_CANCELLED = 'WorkflowCancelled'
+  end
+
+  # Channel subscription modes
+  module ChannelMode
+    BROADCAST = 'broadcast'
+    COMPETING = 'competing'
+    DIRECT = 'direct'
+
+    ALL = [BROADCAST, COMPETING, DIRECT].freeze
+  end
+
+  # Data type indicators for storage
+  module DataType
+    JSON = 'json'
+    BINARY = 'binary'
+  end
+
+  # Outbox event status
+  module OutboxStatus
+    PENDING = 'pending'
+    PROCESSING = 'processing'
+    PUBLISHED = 'published'
+    FAILED = 'failed'
+    INVALID = 'invalid'
+    EXPIRED = 'expired'
+  end
+
+  # Framework identifier for cross-language support
+  FRAMEWORK = 'ruby'
+end

data/lib/shikibu/context.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Shikibu
+  # Context object passed to workflow execution
+  # Provides access to workflow state, history, and operations
+  class WorkflowContext
+    attr_reader :instance_id, :workflow_name, :worker_id, :storage, :hooks, :last_activity_id
+    attr_accessor :current_activity_id
+
+    def initialize(
+      instance_id:,
+      workflow_name:,
+      worker_id:,
+      storage:,
+      hooks: nil,
+      history_cache: {},
+      replaying: false
+    )
+      @instance_id = instance_id
+      @workflow_name = workflow_name
+      @worker_id = worker_id
+      @storage = storage
+      @hooks = hooks
+      @history_cache = history_cache
+      @replaying = replaying
+      @activity_counters = Hash.new(0)
+      @compensations = []
+      @direct_subscriptions = Set.new
+      @last_activity_id = nil
+    end
+
+    # Record the last completed activity ID (for on_failure to reference)
+    def record_last_activity_id(activity_id)
+      @last_activity_id = activity_id
+    end
+
+    # Check if currently replaying from history
+    def replaying?
+      @replaying
+    end
+
+    # Generate a unique activity ID for deterministic replay
+    # @param name [String] Activity name
+    # @return [String] Activity ID in format "name:counter"
+    def generate_activity_id(name)
+      @activity_counters[name] += 1
+      "#{name}:#{@activity_counters[name]}"
+    end
+
+    # Get cached result for an activity (during replay)
+    # @param activity_id [String] Activity ID
+    # @return [Object, nil] Cached result or nil
+    def get_cached_result(activity_id)
+      return nil unless @history_cache.key?(activity_id)
+
+      @history_cache[activity_id]
+    end
+
+    # Check if activity has cached result
+    # @param activity_id [String] Activity ID
+    # @return [Boolean]
+    def cached_result?(activity_id)
+      @history_cache.key?(activity_id)
+    end
+
+    # Cache an activity result
+    # @param activity_id [String] Activity ID
+    # @param result [Object] Result to cache
+    def cache_result(activity_id, result)
+      @history_cache[activity_id] = result
+    end
+
+    # Register a compensation action (Romancy/Edda compatible)
+    # @param activity_id [String] Activity ID that this compensation is for
+    # @param compensation_name [String] Compensation function name (from registry)
+    # @param args [Hash] Arguments for compensation
+    def register_compensation(activity_id:, compensation_name:, args:)
+      @compensations << {
+        activity_id: activity_id,
+        compensation_name: compensation_name,
+        args: args
+      }
+
+      # Also persist to storage
+      @storage.push_compensation(
+        instance_id: @instance_id,
+        activity_id: activity_id,
+        activity_name: compensation_name,
+        args: args
+      )
+    end
+
+    # Get registered compensations (LIFO order)
+    def compensations
+      @compensations.reverse
+    end
+
+    # Access database session (within the same transaction)
+    def session
+      @storage.db
+    end
+
+    # Execute a block within a transaction
+    def transaction(&)
+      @storage.transaction(&)
+    end
+
+    # Check if currently in a transaction
+    def in_transaction?
+      @storage.in_transaction?
+    end
+
+    # Subscribe to a channel
+    # @param channel [String] Channel name
+    # @param mode [Symbol, String] Subscription mode (:broadcast, :competing, :direct)
+    # @return [Channels::Subscription]
+    def subscribe(channel, mode: :broadcast)
+      mode_str = mode.to_s
+      @direct_subscriptions.add(channel) if mode_str == ChannelMode::DIRECT
+
+      Channels.subscribe(self, channel, mode: mode)
+    end
+
+    # Unsubscribe from a channel
+    # @param channel [String] Channel name
+    def unsubscribe(channel)
+      @direct_subscriptions.delete(channel)
+      Channels.unsubscribe(self, channel)
+    end
+
+    # Get list of direct subscriptions
+    def direct_subscriptions
+      @direct_subscriptions.to_a
+    end
+
+    # List all active subscriptions
+    # @return [Array<Channels::Subscription>]
+    def subscriptions
+      Channels.subscriptions(self)
+    end
+
+    # Restart workflow with new input (tail recursion pattern)
+    # @param new_input [Hash] New input for the workflow
+    def recur(**new_input)
+      raise RecurSignal, new_input
+    end
+
+    # Wait for a timer to expire
+    # @param seconds [Numeric] Seconds to wait
+    # @param timer_id [String, nil] Optional timer ID
+    def sleep(seconds, timer_id: nil)
+      sleep_until(Time.now + seconds, timer_id: timer_id)
+    end
+
+    # Wait until a specific time
+    # @param until_time [Time] Time to wait until
+    # @param timer_id [String, nil] Optional timer ID
+    def sleep_until(until_time, timer_id: nil)
+      timer_id ||= generate_activity_id('timer')
+
+      # Check if already expired in history
+      return get_cached_result(timer_id) if replaying? && cached_result?(timer_id)
+
+      # Register timer and suspend
+      raise WaitForTimerSignal.new(
+        timer_id: timer_id,
+        expires_at: until_time,
+        activity_id: timer_id
+      )
+    end
+
+    # Wait for a message on a channel
+    # @param channel [String] Channel name
+    # @param timeout [Numeric, nil] Timeout in seconds
+    # @param mode [Symbol, String] Subscription mode
+    # @return [Channels::Message]
+    def receive(channel, timeout: nil, mode: :broadcast)
+      Channels.receive(self, channel, timeout: timeout, mode: mode)
+    end
+
+    # Try to receive without blocking (returns nil if no message)
+    # @param channel [String] Channel name
+    # @param mode [Symbol, String] Subscription mode
+    # @return [Channels::Message, nil]
+    def try_receive(channel, mode: :broadcast)
+      Channels.try_receive(self, channel, mode: mode)
+    end
+
+    # Publish a message to a channel
+    # @param channel [String] Channel name
+    # @param data [Object] Message data
+    # @param metadata [Hash, nil] Optional metadata
+    # @return [String] Message ID
+    def publish(channel, data, metadata: nil)
+      Channels.publish(self, channel, data, metadata: metadata)
+    end
+
+    # Send a message directly to another workflow instance
+    # @param target_instance_id [String] Target workflow instance ID
+    # @param channel [String] Channel name
+    # @param data [Object] Message data
+    # @param metadata [Hash, nil] Optional metadata
+    # @return [String] Message ID
+    def send_to(target_instance_id, channel, data, metadata: nil)
+      Channels.send_to(self, target_instance_id, channel, data, metadata: metadata)
+    end
+  end
+end

data/lib/shikibu/errors.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Shikibu
+  # Base error class for all Shikibu errors
+  class Error < StandardError; end
+
+  # Raised when a workflow is cancelled
+  class WorkflowCancelledError < Error
+    attr_reader :instance_id
+
+    def initialize(instance_id, message = nil)
+      @instance_id = instance_id
+      super(message || "Workflow #{instance_id} was cancelled")
+    end
+  end
+
+  # Raised when an error should not be retried (terminal failure)
+  class TerminalError < Error
+    attr_reader :cause
+
+    def initialize(message, cause: nil)
+      @cause = cause
+      super(message)
+    end
+  end
+
+  # Raised when all retry attempts have been exhausted
+  class RetryExhaustedError < Error
+    attr_reader :attempts, :last_error
+
+    def initialize(message, attempts:, last_error: nil)
+      @attempts = attempts
+      @last_error = last_error
+      super(message)
+    end
+  end
+
+  # Raised when waiting for an event times out
+  class EventTimeoutError < Error
+    attr_reader :event_type, :timeout
+
+    def initialize(event_type, timeout)
+      @event_type = event_type
+      @timeout = timeout
+      super("Timeout waiting for event '#{event_type}' after #{timeout} seconds")
+    end
+  end
+
+  # Raised when a channel message receive times out
+  class MessageTimeoutError < Error
+    attr_reader :channel, :timeout
+
+    def initialize(channel, timeout)
+      @channel = channel
+      @timeout = timeout
+      super("Timeout waiting for message on channel '#{channel}' after #{timeout} seconds")
+    end
+  end
+
+  # Raised when subscribing with a different mode than the channel's established mode
+  class ChannelModeConflictError < Error
+    attr_reader :channel, :existing_mode, :requested_mode
+
+    def initialize(channel, existing_mode, requested_mode)
+      @channel = channel
+      @existing_mode = existing_mode
+      @requested_mode = requested_mode
+      super("Channel '#{channel}' is already configured as '#{existing_mode}' mode. " \
+            "Cannot subscribe with '#{requested_mode}' mode.")
+    end
+  end
+
+  # Raised when a lock cannot be acquired
+  class LockNotAcquiredError < Error
+    attr_reader :instance_id
+
+    def initialize(instance_id)
+      @instance_id = instance_id
+      super("Could not acquire lock for workflow #{instance_id}")
+    end
+  end
+
+  # Raised when a workflow is not found
+  class WorkflowNotFoundError < Error
+    attr_reader :instance_id
+
+    def initialize(instance_id)
+      @instance_id = instance_id
+      super("Workflow #{instance_id} not found")
+    end
+  end
+
+  # Raised when a workflow definition is not registered
+  class WorkflowNotRegisteredError < Error
+    attr_reader :workflow_name
+
+    def initialize(workflow_name)
+      @workflow_name = workflow_name
+      super("Workflow '#{workflow_name}' is not registered")
+    end
+  end
+
+  # Internal signal for workflow suspension (waiting for timer)
+  class WaitForTimerSignal < Error
+    attr_reader :timer_id, :expires_at, :activity_id
+
+    def initialize(timer_id:, expires_at:, activity_id: nil)
+      @timer_id = timer_id
+      @expires_at = expires_at
+      @activity_id = activity_id
+      super("Waiting for timer #{timer_id}")
+    end
+  end
+
+  # Internal signal for workflow suspension (waiting for channel message)
+  class WaitForChannelSignal < Error
+    attr_reader :channel, :mode, :timeout_at, :activity_id
+
+    def initialize(channel:, mode:, timeout_at: nil, activity_id: nil)
+      @channel = channel
+      @mode = mode
+      @timeout_at = timeout_at
+      @activity_id = activity_id
+      super("Waiting for message on channel #{channel}")
+    end
+  end
+
+  # Internal signal for workflow recurrence (tail recursion)
+  class RecurSignal < Error
+    attr_reader :new_input
+
+    def initialize(new_input)
+      @new_input = new_input
+      super('Workflow recurrence requested')
+    end
+  end
+end

data/lib/shikibu/integrations/active_job.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'active_job' if defined?(ActiveJob)
+
+module Shikibu
+  module Integrations
+    # ActiveJob integration for Rails
+    #
+    # @example config/initializers/shikibu.rb
+    #   Shikibu.configure do |config|
+    #     config.database_url = ENV['DATABASE_URL']
+    #     config.auto_migrate = Rails.env.development?
+    #   end
+    #
+    # @example Using the workflow job
+    #   class ProcessOrderJob < Shikibu::Integrations::WorkflowJob
+    #     self.workflow_class = OrderSaga
+    #   end
+    #
+    #   ProcessOrderJob.perform_later(order_id: '123', amount: 99.99)
+    #
+    # @example Or inline
+    #   Shikibu::Integrations::WorkflowJob.perform_later(
+    #     workflow_class: 'OrderSaga',
+    #     order_id: '123'
+    #   )
+    #
+    module ActiveJob
+      # Base job for running workflows
+      class WorkflowJob < ::ActiveJob::Base
+        queue_as :shikibu
+
+        class << self
+          attr_accessor :workflow_class
+        end
+
+        # Run a workflow
+        # @param workflow_class [String, nil] Workflow class name (if not set on class)
+        # @param input [Hash] Input parameters
+        def perform(workflow_class: nil, **input)
+          klass = resolve_workflow_class(workflow_class)
+          Shikibu.run(klass, **input)
+        end
+
+        private
+
+        def resolve_workflow_class(name)
+          return self.class.workflow_class if self.class.workflow_class
+
+          raise ArgumentError, 'workflow_class not specified' unless name
+
+          Object.const_get(name)
+        end
+      end
+
+      # Job for resuming workflows
+      class ResumeJob < ::ActiveJob::Base
+        queue_as :shikibu
+
+        def perform(instance_id)
+          Shikibu.app.resume_workflow(instance_id)
+        rescue LockNotAcquiredError
+          # Another worker got it, retry later
+          self.class.set(wait: 1.second).perform_later(instance_id)
+        end
+      end
+
+      # Job for processing expired timers
+      class TimerJob < ::ActiveJob::Base
+        queue_as :shikibu
+
+        def perform(instance_id, timer_id)
+          storage = Shikibu.app.storage
+
+          # Record timer expiration
+          storage.append_history(
+            instance_id: instance_id,
+            activity_id: timer_id,
+            event_type: EventType::TIMER_EXPIRED,
+            event_data: { timer_id: timer_id, expired_at: Time.now.iso8601 }
+          )
+
+          # Remove timer subscription
+          storage.remove_timer(instance_id: instance_id, timer_id: timer_id)
+
+          # Resume workflow
+          Shikibu.app.resume_workflow(instance_id)
+        end
+      end
+    end
+
+    # Convenience alias
+    WorkflowJob = ActiveJob::WorkflowJob
+  end
+end

data/lib/shikibu/integrations/sidekiq.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+begin
+  require 'sidekiq'
+rescue LoadError
+  # Sidekiq not available
+end
+
+module Shikibu
+  module Integrations
+    # Sidekiq integration for background workflow processing
+    #
+    # @example config/initializers/shikibu.rb
+    #   Shikibu.configure do |config|
+    #     config.database_url = ENV['DATABASE_URL']
+    #   end
+    #
+    # @example Running a workflow
+    #   Shikibu::Integrations::Sidekiq::WorkflowWorker.perform_async(
+    #     'OrderSaga',
+    #     { 'order_id' => '123', 'amount' => 99.99 }
+    #   )
+    #
+    # @example Custom worker class
+    #   class ProcessOrderWorker
+    #     include Sidekiq::Job
+    #     sidekiq_options queue: 'workflows'
+    #
+    #     def perform(order_id, amount)
+    #       Shikibu.run(OrderSaga, order_id: order_id, amount: amount)
+    #     end
+    #   end
+    #
+    module Sidekiq
+      if defined?(::Sidekiq)
+        # Worker for running workflows
+        class WorkflowWorker
+          include ::Sidekiq::Job
+
+          sidekiq_options queue: 'shikibu', retry: 3
+
+          def perform(workflow_class_name, input = {})
+            klass = Object.const_get(workflow_class_name)
+            symbolized_input = input.transform_keys(&:to_sym)
+            Shikibu.run(klass, **symbolized_input)
+          end
+        end
+
+        # Worker for resuming workflows
+        class ResumeWorker
+          include ::Sidekiq::Job
+
+          sidekiq_options queue: 'shikibu', retry: 5
+
+          def perform(instance_id)
+            Shikibu.app.resume_workflow(instance_id)
+          rescue LockNotAcquiredError
+            # Retry with backoff
+            self.class.perform_in(1 + rand, instance_id)
+          end
+        end
+
+        # Worker for processing expired timers
+        class TimerWorker
+          include ::Sidekiq::Job
+
+          sidekiq_options queue: 'shikibu', retry: 3
+
+          def perform(instance_id, timer_id)
+            storage = Shikibu.app.storage
+
+            storage.append_history(
+              instance_id: instance_id,
+              activity_id: timer_id,
+              event_type: EventType::TIMER_EXPIRED,
+              event_data: { timer_id: timer_id, expired_at: Time.now.iso8601 }
+            )
+
+            storage.remove_timer(instance_id: instance_id, timer_id: timer_id)
+            storage.update_instance_status(instance_id, Status::RUNNING)
+
+            ResumeWorker.perform_async(instance_id)
+          end
+        end
+
+        # Scheduler for checking timers (run with sidekiq-scheduler or similar)
+        class TimerScheduler
+          include ::Sidekiq::Job
+
+          sidekiq_options queue: 'shikibu_scheduler', retry: false
+
+          def perform
+            storage = Shikibu.app.storage
+            expired = storage.find_expired_timers(limit: 100)
+
+            expired.each do |timer|
+              TimerWorker.perform_async(timer[:instance_id], timer[:timer_id])
+            end
+          end
+        end
+      end
+    end
+  end
+end