shikibu 0.1.0

data/lib/shikibu/workflow.rb

@@ -0,0 +1,398 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Shikibu
+  # Base class for workflow definitions
+  # Subclass this to create durable workflows
+  #
+  # @example
+  #   # Register compensation at startup
+  #   Shikibu.register_compensation(:refund_payment) do |_ctx, order_id:|
+  #     PaymentService.refund(order_id)
+  #   end
+  #
+  #   class OrderWorkflow < Shikibu::Workflow
+  #     workflow_name 'order_processing'
+  #     event_handler true
+  #
+  #     def execute(order_id:, amount:)
+  #       result = activity :process_payment do
+  #         PaymentService.charge(order_id, amount)
+  #       end
+  #
+  #       on_failure :refund_payment, order_id: order_id
+  #
+  #       { status: 'completed', payment: result }
+  #     end
+  #   end
+  #
+  class Workflow
+    class << self
+      # Set the workflow name
+      # @param name [String, nil] The workflow name (defaults to class name)
+      def workflow_name(name = nil)
+        if name
+          @workflow_name = name.to_s
+        else
+          @workflow_name || name.to_s.gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+        end
+      end
+
+      # Set whether this workflow handles events
+      # @param value [Boolean]
+      def event_handler(value = nil)
+        if value.nil?
+          @event_handler || false
+        else
+          @event_handler = value
+        end
+      end
+
+      # Set the lock timeout for this workflow
+      # @param seconds [Integer]
+      def lock_timeout(seconds = nil)
+        if seconds
+          @lock_timeout = seconds
+        else
+          @lock_timeout || 300
+        end
+      end
+
+      # Get the source hash for this workflow
+      def source_hash
+        @source_hash ||= begin
+          source = source_code
+          Digest::SHA256.hexdigest(source)[0, 16]
+        end
+      end
+
+      # Get the source code of this workflow
+      def source_code
+        # Try to get source from file
+        file, = instance_method(:execute).source_location
+        return '' unless file && File.exist?(file)
+
+        File.read(file)
+      rescue StandardError
+        ''
+      end
+
+      # Register this workflow with Shikibu
+      def register!
+        Shikibu.register_workflow(self)
+      end
+
+      # Create and start a new workflow instance
+      # @param app [App] The Shikibu app
+      # @param input [Hash] Input parameters
+      # @param instance_id [String, nil] Optional custom instance ID
+      # @return [String] The instance ID
+      def start(app, instance_id: nil, **input)
+        app.start_workflow(self, instance_id: instance_id, **input)
+      end
+
+      # Run workflow using global Shikibu.app
+      # @example
+      #   OrderSaga.run(order_id: '123')
+      def run(**input)
+        Shikibu.run(self, **input)
+      end
+    end
+
+    attr_reader :ctx, :input
+
+    # Initialize with context (internal) or input (for Shikibu.run with instance)
+    def initialize(context_or_input = nil, **input)
+      if context_or_input.is_a?(WorkflowContext)
+        @ctx = context_or_input
+        @input = {}
+      else
+        # Called as OrderSaga.new(order_id: '123')
+        @ctx = nil
+        @input = context_or_input.is_a?(Hash) ? context_or_input : input
+      end
+      @pending_compensations = []
+    end
+
+    # Set context (called by ReplayEngine)
+    def context=(context)
+      @ctx = context
+    end
+
+    # Override this method to implement workflow logic
+    # @param input [Hash] Input parameters (keyword arguments)
+    # @return [Object] Workflow result
+    def execute(**input)
+      raise NotImplementedError, 'Subclasses must implement #execute'
+    end
+
+    # Execute an activity with automatic retry and history tracking
+    # @param name [Symbol, String] Activity name
+    # @param retry_policy [RetryPolicy] Retry policy
+    # @param block [Proc] Activity logic
+    # @return [Object] Activity result
+    def activity(name, retry_policy: nil, &)
+      activity_id = ctx.generate_activity_id(name.to_s)
+      ctx.current_activity_id = activity_id
+
+      # Check for cached result during replay
+      if ctx.replaying? && ctx.cached_result?(activity_id)
+        cached = ctx.get_cached_result(activity_id)
+        handle_cached_result(activity_id, cached)
+        ctx.record_last_activity_id(activity_id)
+        return cached[:result] if cached[:event_type] == EventType::ACTIVITY_COMPLETED
+
+        # Re-raise cached error
+        raise reconstruct_error(cached)
+      end
+
+      # Execute the activity
+      result = execute_activity(activity_id, name.to_s, retry_policy || RetryPolicy.default, &)
+      ctx.record_last_activity_id(activity_id)
+      result
+    ensure
+      ctx.current_activity_id = nil
+    end
+
+    # Register a compensation action to run on failure (Romancy/Edda compatible)
+    #
+    # @example
+    #   # First register the compensation function
+    #   Shikibu.register_compensation(:refund_payment) do |ctx, payment_id:|
+    #     PaymentService.refund(payment_id)
+    #   end
+    #
+    #   # Then use it in workflow
+    #   result = activity :charge_payment do
+    #     PaymentService.charge(order_id, amount)
+    #   end
+    #   on_failure :refund_payment, payment_id: result[:id]
+    #
+    # @param name [Symbol, String] Compensation function name (registered via Shikibu.register_compensation)
+    # @param args [Hash] Arguments to pass to the compensation function
+    def on_failure(name, **args)
+      # Use last_activity_id since current_activity_id is cleared after activity completes
+      activity_id = ctx.last_activity_id
+      compensation_name = name.to_s
+
+      # Get the compensation function from registry
+      compensation_fn = Shikibu.get_compensation(compensation_name)
+      raise ArgumentError, "Compensation '#{compensation_name}' not registered" if compensation_fn.nil?
+
+      @pending_compensations << {
+        activity_id: activity_id,
+        compensation_name: compensation_name,
+        args: args,
+        block: proc { compensation_fn.call(ctx, **args) }
+      }
+
+      ctx.register_compensation(
+        activity_id: activity_id,
+        compensation_name: compensation_name,
+        args: args
+      )
+    end
+
+    # Convenience methods delegated to context
+
+    def sleep(seconds, timer_id: nil)
+      ctx.sleep(seconds, timer_id: timer_id)
+    end
+
+    def sleep_until(until_time, timer_id: nil)
+      ctx.sleep_until(until_time, timer_id: timer_id)
+    end
+
+    def subscribe(channel, mode: ChannelMode::BROADCAST)
+      ctx.subscribe(channel, mode: mode)
+    end
+
+    def unsubscribe(channel)
+      ctx.unsubscribe(channel)
+    end
+
+    def receive(channel, timeout: nil, mode: ChannelMode::BROADCAST)
+      ctx.receive(channel, timeout: timeout, mode: mode)
+    end
+
+    def try_receive(channel, mode: ChannelMode::BROADCAST)
+      ctx.try_receive(channel, mode: mode)
+    end
+
+    def publish(channel, data, metadata: nil)
+      ctx.publish(channel, data, metadata: metadata)
+    end
+
+    def send_to(target_instance_id, channel, data)
+      ctx.send_to(target_instance_id, channel, data)
+    end
+
+    def recur(**new_input)
+      ctx.recur(**new_input)
+    end
+
+    def wait_event(event_type, timeout: nil)
+      receive(event_type, timeout: timeout, mode: ChannelMode::BROADCAST)
+    end
+
+    def instance_id
+      ctx.instance_id
+    end
+
+    # Execute registered compensations in reverse order (LIFO)
+    # Called by ReplayEngine on workflow failure
+    # Implements Romancy/Edda compatible idempotency checking
+    def run_compensations
+      # Get compensations from DB to have table IDs (for Romancy/Edda compatibility)
+      db_compensations = ctx.storage.get_compensations(ctx.instance_id)
+
+      # Get already executed compensation IDs from history (idempotency check)
+      executed_ids = executed_compensation_ids
+
+      # Build a lookup from activity_id to DB compensation record
+      db_lookup = db_compensations.each_with_object({}) do |comp, hash|
+        hash[comp[:activity_id]] = comp
+      end
+
+      # Execute compensations in reverse order (LIFO)
+      @pending_compensations.reverse.each do |comp|
+        db_comp = db_lookup[comp[:activity_id]]
+        compensation_id = db_comp&.dig(:id)
+
+        # Skip if already executed (idempotency)
+        next if compensation_id && executed_ids.include?(compensation_id)
+
+        execute_single_compensation(comp, compensation_id)
+      end
+    end
+
+    private
+
+    def executed_compensation_ids
+      history = ctx.storage.get_history(ctx.instance_id)
+      history
+        .select { |e| e[:event_type] == EventType::COMPENSATION_EXECUTED }
+        .map { |e| e[:data]&.dig(:compensation_id) }
+        .compact
+        .to_set
+    end
+
+    def execute_single_compensation(comp, compensation_id)
+      comp[:block].call
+
+      # Record successful compensation (Romancy/Edda compatible format)
+      ctx.storage.append_history(
+        instance_id: ctx.instance_id,
+        activity_id: "compensation:#{compensation_id || comp[:activity_id]}",
+        event_type: EventType::COMPENSATION_EXECUTED,
+        event_data: {
+          compensation_id: compensation_id,
+          activity_id: comp[:activity_id],
+          activity_name: comp[:compensation_name]
+        }
+      )
+    rescue StandardError => e
+      # Record failed compensation but continue with others
+      ctx.storage.append_history(
+        instance_id: ctx.instance_id,
+        activity_id: "compensation:#{compensation_id || comp[:activity_id]}",
+        event_type: EventType::COMPENSATION_FAILED,
+        event_data: {
+          compensation_id: compensation_id,
+          activity_id: comp[:activity_id],
+          activity_name: comp[:compensation_name],
+          error_type: e.class.name,
+          error_message: e.message
+        }
+      )
+    end
+
+    def execute_activity(activity_id, name, retry_policy, &block)
+      attempt = 0
+      started_at = Time.now
+      last_error = nil
+
+      loop do
+        attempt += 1
+
+        begin
+          # Call hooks
+          ctx.hooks&.on_activity_start&.call(ctx.instance_id, activity_id, name, attempt)
+
+          result = block.call
+
+          # Record successful result
+          ctx.storage.append_history(
+            instance_id: ctx.instance_id,
+            activity_id: activity_id,
+            event_type: EventType::ACTIVITY_COMPLETED,
+            event_data: { result: result }
+          )
+
+          # Cache for replay
+          ctx.cache_result(activity_id, {
+                             event_type: EventType::ACTIVITY_COMPLETED,
+                             result: result
+                           })
+
+          # Call hooks
+          ctx.hooks&.on_activity_complete&.call(ctx.instance_id, activity_id, name, result, false)
+
+          return result
+        rescue StandardError => e
+          last_error = e
+
+          # Check if retryable
+          unless retry_policy.retryable?(e) && retry_policy.should_retry?(attempt, started_at)
+            # Record failure
+            ctx.storage.append_history(
+              instance_id: ctx.instance_id,
+              activity_id: activity_id,
+              event_type: EventType::ACTIVITY_FAILED,
+              event_data: {
+                error_type: e.class.name,
+                error_message: e.message,
+                attempts: attempt
+              }
+            )
+
+            # Cache for replay
+            ctx.cache_result(activity_id, {
+                               event_type: EventType::ACTIVITY_FAILED,
+                               error_type: e.class.name,
+                               error_message: e.message
+                             })
+
+            # Call hooks
+            ctx.hooks&.on_activity_failed&.call(ctx.instance_id, activity_id, name, e, attempt)
+
+            raise
+          end
+
+          # Call retry hook
+          delay = retry_policy.delay_for(attempt)
+          ctx.hooks&.on_activity_retry&.call(ctx.instance_id, activity_id, name, e, attempt, delay)
+
+          # Wait before retry
+          Kernel.sleep(delay)
+        end
+      end
+    end
+
+    def handle_cached_result(activity_id, cached)
+      name = activity_id.split(':').first
+      ctx.hooks&.on_activity_complete&.call(ctx.instance_id, activity_id, name, cached[:result], true)
+    end
+
+    def reconstruct_error(cached)
+      error_class = begin
+        Object.const_get(cached[:error_type])
+      rescue StandardError
+        StandardError
+      end
+
+      error_class.new(cached[:error_message])
+    end
+  end
+end

data/lib/shikibu.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require_relative 'shikibu/version'
+require_relative 'shikibu/constants'
+require_relative 'shikibu/errors'
+require_relative 'shikibu/retry_policy'
+
+# CloudEvents-native Durable Execution framework for Ruby.
+module Shikibu
+  class << self
+    # Global app instance
+    attr_accessor :app
+
+    # Registry for workflow definitions
+    def workflow_registry
+      @workflow_registry ||= {}
+    end
+
+    # Register a workflow class
+    def register_workflow(workflow_class)
+      name = workflow_class.workflow_name
+      workflow_registry[name] = workflow_class
+    end
+
+    # Get a registered workflow by name
+    def get_workflow(name)
+      workflow_registry[name]
+    end
+
+    # Registry for compensation functions (Romancy/Edda compatible)
+    def compensation_registry
+      @compensation_registry ||= {}
+    end
+
+    # Register a compensation function
+    # @param name [Symbol, String] Compensation function name
+    # @param block [Proc] Compensation logic
+    # @example
+    #   Shikibu.register_compensation(:refund_payment) do |ctx, payment_id:|
+    #     PaymentService.refund(payment_id)
+    #   end
+    def register_compensation(name, &block)
+      compensation_registry[name.to_s] = block
+    end
+
+    # Get a registered compensation function by name
+    # @param name [String] Compensation function name
+    # @return [Proc, nil] Compensation function or nil if not found
+    def get_compensation(name)
+      return nil if name.nil?
+
+      compensation_registry[name.to_s]
+    end
+
+    # Clear all registered workflows and compensations (mainly for testing)
+    def clear_registry!
+      @workflow_registry = {}
+      @compensation_registry = {}
+      @app = nil
+    end
+
+    # Configure the global app
+    def configure
+      config = Configuration.new
+      yield config
+      @app = App.new(
+        database_url: config.database_url,
+        service_name: config.service_name,
+        auto_migrate: config.auto_migrate,
+        hooks: config.hooks,
+        use_listen_notify: config.use_listen_notify
+      )
+    end
+
+    # Run a workflow
+    def run(workflow, **input)
+      ensure_app!
+
+      if workflow.is_a?(Class)
+        app.register(workflow) unless workflow_registry.key?(workflow.workflow_name)
+        app.start_workflow(workflow, **input)
+      else
+        # Instance passed - extract class and input
+        workflow_class = workflow.class
+        app.register(workflow_class) unless workflow_registry.key?(workflow_class.workflow_name)
+        app.start_workflow(workflow_class, **workflow.input)
+      end
+    end
+
+    # Get workflow status
+    def status(instance_id)
+      ensure_app!
+      app.get_status(instance_id)
+    end
+
+    # Get workflow result
+    def result(instance_id)
+      ensure_app!
+      app.get_result(instance_id)
+    end
+
+    # Send event to workflows
+    def send_event(event_type, data, metadata: nil)
+      ensure_app!
+      app.send_event(event_type, data, metadata: metadata)
+    end
+
+    private
+
+    def ensure_app!
+      raise Error, 'Shikibu not configured. Call Shikibu.configure first.' unless @app
+    end
+  end
+
+  # Configuration object
+  class Configuration
+    attr_accessor :database_url, :service_name, :auto_migrate, :hooks, :use_listen_notify
+
+    def initialize
+      @database_url = 'sqlite://shikibu.db'
+      @service_name = 'shikibu'
+      @auto_migrate = false
+      @hooks = nil
+      @use_listen_notify = nil # nil = auto-detect, true/false = manual
+    end
+  end
+end
+
+# Core requires (needed before App is loaded)
+require_relative 'shikibu/notify/notify_base'
+require_relative 'shikibu/notify/wake_event'
+require_relative 'shikibu/locking'
+require_relative 'shikibu/channels'
+require_relative 'shikibu/context'
+require_relative 'shikibu/workflow'
+require_relative 'shikibu/activity'
+require_relative 'shikibu/storage/migrations'
+require_relative 'shikibu/storage/sequel_storage'
+require_relative 'shikibu/outbox/relayer'
+require_relative 'shikibu/replay'
+require_relative 'shikibu/worker'
+require_relative 'shikibu/app'
+require_relative 'shikibu/middleware/rack_app'
+
+# Optional integrations (autoload)
+module Shikibu
+  # Framework integrations (Sidekiq, ActiveJob).
+  module Integrations
+    autoload :ActiveJob, 'shikibu/integrations/active_job'
+    autoload :Sidekiq, 'shikibu/integrations/sidekiq'
+  end
+end

data/schema/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yasushi Itoh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/schema/README.md

@@ -0,0 +1,57 @@
+# Durax Schema
+
+Shared database schema for [Durax](https://github.com/durax-io) - a multi-language durable execution framework.
+
+- [edda](https://github.com/i2y/edda) (Python)
+- [romancy](https://github.com/i2y/romancy) (Go)
+
+## Quick Start
+
+### 1. Install dbmate
+
+```bash
+# macOS
+brew install dbmate
+
+# Linux
+curl -fsSL https://github.com/amacneil/dbmate/releases/latest/download/dbmate-linux-amd64 -o dbmate
+chmod +x dbmate && sudo mv dbmate /usr/local/bin/
+```
+
+### 2. Run Migration
+
+```bash
+# PostgreSQL
+DATABASE_URL="postgresql://user:pass@localhost:5432/dbname?sslmode=disable" \
+  dbmate -d ./db/migrations/postgresql up
+
+# MySQL
+DATABASE_URL="mysql://user:pass@localhost:3306/dbname" \
+  dbmate -d ./db/migrations/mysql up
+
+# SQLite
+DATABASE_URL="sqlite:./mydb.sqlite" \
+  dbmate -d ./db/migrations/sqlite up
+```
+
+## Integration as Submodule
+
+```bash
+git submodule add https://github.com/durax-io/schema.git schema
+git submodule update --init
+```
+
+## Other Commands
+
+```bash
+dbmate status   # Check migration status
+dbmate down     # Rollback latest migration
+```
+
+## Documentation
+
+- [Column Values Reference](docs/column-values.md) - Standard values for database columns across all implementations
+
+## License
+
+MIT