shikibu 0.1.0

data/lib/shikibu/locking.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'socket'
+require 'securerandom'
+
+module Shikibu
+  # Utilities for distributed locking
+  module Locking
+    class << self
+      # Generate a unique worker ID
+      # @param service_name [String] Service name prefix
+      # @return [String] Worker ID in format "service-pid-uuid"
+      def generate_worker_id(service_name = 'shikibu')
+        hostname = Socket.gethostname.gsub(/[^a-zA-Z0-9]/, '')[0, 8]
+        pid = Process.pid
+        uuid = SecureRandom.uuid[0, 8]
+        "#{service_name}-#{hostname}-#{pid}-#{uuid}"
+      end
+
+      # Acquire lock with retry and exponential backoff
+      # @param storage [Storage::SequelStorage] Storage instance
+      # @param instance_id [String] Workflow instance ID
+      # @param worker_id [String] Worker ID
+      # @param timeout [Integer] Lock timeout in seconds
+      # @param max_attempts [Integer] Maximum acquire attempts
+      # @param base_delay [Float] Initial delay between attempts
+      # @return [Boolean] Whether lock was acquired
+      def acquire_with_retry(storage, instance_id, worker_id, timeout: 300, max_attempts: 5, base_delay: 0.1)
+        attempts = 0
+
+        loop do
+          attempts += 1
+
+          return true if storage.try_acquire_lock(instance_id, worker_id, timeout: timeout)
+
+          return false if attempts >= max_attempts
+
+          # Exponential backoff with jitter
+          delay = base_delay * (2**(attempts - 1))
+          delay += rand * delay * 0.3 # Add up to 30% jitter
+          sleep(delay)
+        end
+      end
+
+      # Ensure we still hold a lock, raise if not
+      # @param storage [Storage::SequelStorage] Storage instance
+      # @param instance_id [String] Workflow instance ID
+      # @param worker_id [String] Worker ID
+      # @raise [LockNotAcquiredError] If lock is not held
+      def ensure_lock_held!(storage, instance_id, worker_id)
+        return if storage.lock_held_by?(instance_id, worker_id)
+
+        raise LockNotAcquiredError, instance_id
+      end
+
+      # Refresh a lock to extend its timeout
+      # @param storage [Storage::SequelStorage] Storage instance
+      # @param instance_id [String] Workflow instance ID
+      # @param worker_id [String] Worker ID
+      # @param timeout [Integer] New timeout in seconds
+      # @return [Boolean] Whether refresh was successful
+      def refresh_lock(storage, instance_id, worker_id, timeout: 300)
+        storage.refresh_lock(instance_id, worker_id, timeout: timeout)
+      end
+    end
+
+    # Lock guard for automatic release
+    class LockGuard
+      attr_reader :storage, :instance_id, :worker_id
+
+      def initialize(storage, instance_id, worker_id)
+        @storage = storage
+        @instance_id = instance_id
+        @worker_id = worker_id
+        @acquired = false
+      end
+
+      # Acquire the lock
+      # @param timeout [Integer] Lock timeout
+      # @return [Boolean]
+      def acquire(timeout: 300)
+        @acquired = storage.try_acquire_lock(instance_id, worker_id, timeout: timeout)
+      end
+
+      # Release the lock
+      def release
+        return unless @acquired
+
+        storage.release_lock(instance_id, worker_id)
+        @acquired = false
+      end
+
+      # Check if lock is held
+      def acquired?
+        @acquired
+      end
+
+      # Execute block with lock
+      def with_lock(timeout: 300)
+        return unless acquire(timeout: timeout)
+
+        begin
+          yield
+        ensure
+          release
+        end
+      end
+    end
+  end
+end

data/lib/shikibu/middleware/rack_app.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require 'rack'
+require 'json'
+
+module Shikibu
+  module Middleware
+    # Rack application for handling CloudEvents
+    #
+    # @example config.ru
+    #   require 'shikibu'
+    #
+    #   Shikibu.configure do |config|
+    #     config.database_url = ENV['DATABASE_URL']
+    #     config.auto_migrate = true
+    #   end
+    #
+    #   Shikibu.app.register OrderSaga
+    #   Shikibu.app.start
+    #
+    #   run Shikibu::Middleware::RackApp.new
+    #
+    # @example Rails middleware
+    #   # config/application.rb
+    #   config.middleware.use Shikibu::Middleware::RackApp
+    #
+    class RackApp
+      CONTENT_TYPE_JSON = 'application/json'
+      CONTENT_TYPE_CLOUDEVENTS = 'application/cloudevents+json'
+
+      def initialize(app = nil)
+        @app = app
+      end
+
+      def call(env)
+        request = Rack::Request.new(env)
+        path = request.path_info
+
+        case path
+        when '/shikibu/events', '/events'
+          handle_event(request)
+        when '/shikibu/health', '/health'
+          health_check
+        when '/shikibu/health/live', '/health/live'
+          liveness_check
+        when '/shikibu/health/ready', '/health/ready'
+          readiness_check
+        when %r{^/shikibu/workflows/([^/]+)/status$}
+          handle_status(::Regexp.last_match(1))
+        when %r{^/shikibu/workflows/([^/]+)/result$}
+          handle_result(::Regexp.last_match(1))
+        when %r{^/shikibu/workflows/([^/]+)/cancel$}
+          handle_cancel(request, ::Regexp.last_match(1))
+        else
+          # Pass to next middleware if available
+          @app ? @app.call(env) : not_found
+        end
+      end
+
+      private
+
+      def handle_event(request)
+        return method_not_allowed unless request.post?
+
+        body = request.body.read
+        event = parse_cloudevent(request, body)
+
+        return bad_request('Invalid CloudEvent') unless event
+
+        # Route event to workflow
+        event_type = event[:type]
+        target_instance_id = event[:shikibuinstanceid]
+
+        # Send event to waiting workflows (Point-to-Point or Broadcast)
+        Shikibu.app.send_event(
+          event_type,
+          event[:data],
+          metadata: event,
+          target_instance_id: target_instance_id
+        )
+
+        # Check if there's a workflow registered for this event type (only for broadcast)
+        unless target_instance_id
+          workflow_class = find_event_handler(event_type)
+          Shikibu.run(workflow_class, **(event[:data] || {})) if workflow_class
+        end
+
+        accepted
+      rescue JSON::ParserError
+        bad_request('Invalid JSON')
+      rescue StandardError => e
+        internal_error(e.message)
+      end
+
+      def handle_status(instance_id)
+        status = Shikibu.status(instance_id)
+        json_response(200, { instance_id: instance_id, status: status })
+      rescue WorkflowNotFoundError
+        not_found
+      end
+
+      def handle_result(instance_id)
+        result = Shikibu.result(instance_id)
+        json_response(200, { instance_id: instance_id, **result })
+      rescue WorkflowNotFoundError
+        not_found
+      end
+
+      def handle_cancel(request, instance_id)
+        return method_not_allowed unless request.post?
+
+        body = request.body.read
+        data = body.empty? ? {} : JSON.parse(body, symbolize_names: true)
+        reason = data[:reason]
+
+        success = Shikibu.app.cancel_workflow(instance_id, reason: reason)
+
+        if success
+          json_response(200, { instance_id: instance_id, status: 'cancelled' })
+        else
+          json_response(409, { error: 'Cannot cancel workflow in terminal state' })
+        end
+      rescue WorkflowNotFoundError
+        not_found
+      end
+
+      def parse_cloudevent(request, body)
+        content_type = request.content_type
+
+        if content_type&.include?(CONTENT_TYPE_CLOUDEVENTS)
+          # Structured format
+          JSON.parse(body, symbolize_names: true)
+        else
+          # Binary format - headers contain CloudEvents attributes
+          {
+            id: request.get_header('HTTP_CE_ID'),
+            source: request.get_header('HTTP_CE_SOURCE'),
+            type: request.get_header('HTTP_CE_TYPE'),
+            specversion: request.get_header('HTTP_CE_SPECVERSION') || '1.0',
+            shikibuinstanceid: request.get_header('HTTP_CE_SHIKIBUINSTANCEID'),
+            data: JSON.parse(body, symbolize_names: true)
+          }
+        end
+      end
+
+      def find_event_handler(event_type)
+        Shikibu.workflow_registry.values.find do |wf|
+          wf.event_handler && wf.workflow_name == event_type
+        end
+      end
+
+      def health_check
+        json_response(200, {
+                        status: 'ok',
+                        service: 'shikibu',
+                        running: Shikibu.app&.running? || false
+                      })
+      end
+
+      def liveness_check
+        json_response(200, { status: 'ok' })
+      end
+
+      def readiness_check
+        if Shikibu.app&.running?
+          json_response(200, { status: 'ready' })
+        else
+          json_response(503, { status: 'not_ready' })
+        end
+      end
+
+      def json_response(status, body)
+        [status, { 'Content-Type' => CONTENT_TYPE_JSON }, [JSON.generate(body)]]
+      end
+
+      def accepted
+        json_response(202, { status: 'accepted' })
+      end
+
+      def bad_request(message)
+        json_response(400, { error: message })
+      end
+
+      def not_found
+        json_response(404, { error: 'Not found' })
+      end
+
+      def method_not_allowed
+        json_response(405, { error: 'Method not allowed' })
+      end
+
+      def internal_error(message)
+        json_response(500, { error: message })
+      end
+    end
+  end
+end

data/lib/shikibu/notify/notify_base.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Shikibu
+  # PostgreSQL LISTEN/NOTIFY support for event-driven notifications.
+  module Notify
+    # Notification channel constants (shared with Python/Go frameworks)
+    module Channel
+      WORKFLOW_RESUMABLE = 'workflow_resumable'
+      CHANNEL_MESSAGE = 'workflow_channel_message'
+      OUTBOX_PENDING = 'workflow_outbox_pending'
+
+      ALL = [WORKFLOW_RESUMABLE, CHANNEL_MESSAGE, OUTBOX_PENDING].freeze
+    end
+
+    # Base class defining the notify listener interface
+    class NotifyListener
+      def start; end
+      def stop; end
+      def subscribe(_channel, &); end
+      def unsubscribe(_channel); end
+      def connected? = false
+    end
+
+    # No-op implementation for SQLite/MySQL
+    # All methods are no-ops - polling-based updates only
+    class NoopNotifyListener < NotifyListener
+      def initialize
+        super
+        @connected = false
+      end
+
+      def start
+        @connected = true
+      end
+
+      def stop
+        @connected = false
+      end
+
+      def subscribe(_channel, &)
+        # No-op: callbacks will never be called
+      end
+
+      def unsubscribe(_channel)
+        # No-op
+      end
+
+      def connected?
+        @connected
+      end
+    end
+
+    class << self
+      # Factory method to create appropriate listener based on database URL
+      # @param database_url [String] Database connection URL
+      # @return [NotifyListener] PostgresNotifyListener for PostgreSQL, NoopNotifyListener otherwise
+      def create_listener(database_url)
+        if database_url&.start_with?('postgres')
+          require_relative 'pg_notify'
+          PostgresNotifyListener.new(database_url)
+        else
+          NoopNotifyListener.new
+        end
+      end
+    end
+  end
+end

data/lib/shikibu/notify/pg_notify.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require 'pg'
+require 'json'
+require 'concurrent'
+require_relative 'notify_base'
+
+module Shikibu
+  module Notify
+    # PostgreSQL LISTEN/NOTIFY listener using pg gem
+    # Uses a dedicated connection separate from the Sequel connection pool
+    #
+    # @example
+    #   listener = PostgresNotifyListener.new('postgres://localhost/mydb')
+    #   listener.subscribe('workflow_resumable') { |payload| puts payload }
+    #   listener.start
+    #   # ... later
+    #   listener.stop
+    class PostgresNotifyListener < NotifyListener
+      DEFAULT_RECONNECT_INTERVAL = 5
+      MAX_RECONNECT_INTERVAL = 60
+
+      # @param database_url [String] PostgreSQL connection URL
+      # @param reconnect_interval [Numeric] Seconds between reconnection attempts
+      def initialize(database_url, reconnect_interval: DEFAULT_RECONNECT_INTERVAL)
+        super()
+        @database_url = database_url
+        @reconnect_interval = reconnect_interval
+        @connection = nil
+        @callbacks = {} # channel => [callbacks]
+        @running = false
+        @listen_thread = nil
+        @mutex = Mutex.new
+        @reconnect_count = 0
+        @executor = Concurrent::ThreadPoolExecutor.new(
+          min_threads: 1,
+          max_threads: 4,
+          max_queue: 100,
+          fallback_policy: :discard
+        )
+      end
+
+      # Start the notification listener
+      # Establishes connection and begins listening for notifications
+      def start
+        return if @running
+
+        @running = true
+        establish_connection
+        start_listen_thread
+        log_info('PostgresNotifyListener started')
+      end
+
+      # Stop the notification listener
+      # Closes connection and stops the listener thread
+      def stop
+        @running = false
+        @executor.shutdown
+        @executor.wait_for_termination(5)
+        @listen_thread&.join(5)
+        @listen_thread = nil
+        close_connection
+        @callbacks.clear
+        log_info('PostgresNotifyListener stopped')
+      end
+
+      # Subscribe to notifications on a channel
+      # @param channel [String] PostgreSQL channel name
+      # @yield [payload] Block called when notification received
+      # @yieldparam payload [String] Notification payload (JSON string)
+      def subscribe(channel, &callback)
+        @mutex.synchronize do
+          @callbacks[channel] ||= []
+          @callbacks[channel] << callback
+
+          listen_to_channel(channel) if connected?
+        end
+      end
+
+      # Unsubscribe from notifications on a channel
+      # @param channel [String] PostgreSQL channel name
+      def unsubscribe(channel)
+        @mutex.synchronize do
+          @callbacks.delete(channel)
+          unlisten_from_channel(channel) if connected?
+        end
+      end
+
+      # Check if listener is connected to PostgreSQL
+      # @return [Boolean]
+      def connected?
+        !@connection.nil? && !@connection.finished?
+      end
+
+      private
+
+      def establish_connection
+        @connection = PG.connect(@database_url)
+        @connection.setnonblocking(true)
+
+        # Subscribe to all registered channels
+        @callbacks.each_key { |channel| listen_to_channel(channel) }
+
+        @reconnect_count = 0
+        log_info('Connected to PostgreSQL')
+      rescue PG::Error => e
+        log_error("Failed to connect: #{e.message}")
+        @connection = nil
+        raise
+      end
+
+      def close_connection
+        return unless @connection
+
+        begin
+          @connection.close
+        rescue StandardError
+          nil
+        end
+        @connection = nil
+      end
+
+      def listen_to_channel(channel)
+        return unless connected?
+
+        # Use identifier quoting for safety
+        escaped_channel = @connection.escape_identifier(channel)
+        @connection.exec("LISTEN #{escaped_channel}")
+        log_debug("Listening on channel: #{channel}")
+      rescue PG::Error => e
+        log_error("Failed to LISTEN on #{channel}: #{e.message}")
+      end
+
+      def unlisten_from_channel(channel)
+        return unless connected?
+
+        escaped_channel = @connection.escape_identifier(channel)
+        @connection.exec("UNLISTEN #{escaped_channel}")
+        log_debug("Unlistened from channel: #{channel}")
+      rescue PG::Error => e
+        log_error("Failed to UNLISTEN from #{channel}: #{e.message}")
+      end
+
+      def start_listen_thread
+        @listen_thread = Thread.new do
+          Thread.current.name = 'shikibu-pg-notify'
+          reconnect_loop
+        end
+      end
+
+      def reconnect_loop
+        while @running
+          begin
+            establish_connection unless connected?
+            listen_for_notifications
+          rescue PG::Error => e
+            handle_connection_error(e)
+          rescue StandardError => e
+            log_error("Unexpected error: #{e.message}")
+            sleep(@reconnect_interval) if @running
+          end
+        end
+      end
+
+      def listen_for_notifications
+        while @running && connected?
+          # Wait for notifications with 1 second timeout
+          # This allows checking @running flag periodically
+          @connection.wait_for_notify(1) do |channel, _pid, payload|
+            dispatch_notification(channel, payload)
+          end
+        end
+      end
+
+      def dispatch_notification(channel, payload)
+        callbacks = @mutex.synchronize { @callbacks[channel]&.dup }
+        return unless callbacks
+
+        callbacks.each do |callback|
+          @executor.post do
+            callback.call(payload)
+          rescue StandardError => e
+            log_error("Error in notification callback for #{channel}: #{e.message}")
+          end
+        end
+      end
+
+      def handle_connection_error(error)
+        log_error("Connection error: #{error.message}, reconnecting...")
+        close_connection
+
+        @reconnect_count += 1
+        delay = calculate_reconnect_delay
+
+        sleep(delay) if @running
+      end
+
+      def calculate_reconnect_delay
+        # Exponential backoff: 5, 10, 20, 40, 60, 60, ...
+        exp = [@reconnect_count - 1, 5].min
+        [@reconnect_interval * (2**exp), MAX_RECONNECT_INTERVAL].min
+      end
+
+      def log_info(message)
+        warn "[Shikibu::PostgresNotifyListener] #{message}"
+      end
+
+      def log_debug(message)
+        # No-op in production
+      end
+
+      def log_error(message)
+        warn "[Shikibu::PostgresNotifyListener] ERROR: #{message}"
+      end
+    end
+  end
+end

data/lib/shikibu/notify/wake_event.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Shikibu
+  module Notify
+    # Thread-safe wake event for interrupting sleep with NOTIFY signals
+    # Uses ConditionVariable for efficient signaling between threads
+    class WakeEvent
+      def initialize
+        @mutex = Mutex.new
+        @condition = ConditionVariable.new
+        @signaled = false
+      end
+
+      # Signal the wake event (non-blocking)
+      # Wakes up any thread waiting on this event
+      def signal
+        @mutex.synchronize do
+          @signaled = true
+          @condition.signal
+        end
+      end
+
+      # Wait for signal with timeout
+      # @param timeout_seconds [Numeric] Maximum time to wait in seconds
+      # @return [Boolean] true if signaled, false if timeout
+      def wait(timeout_seconds)
+        @mutex.synchronize do
+          if @signaled
+            @signaled = false
+            return true
+          end
+
+          @condition.wait(@mutex, timeout_seconds)
+
+          if @signaled
+            @signaled = false
+            true
+          else
+            false
+          end
+        end
+      end
+
+      # Clear any pending signal without waiting
+      def clear
+        @mutex.synchronize { @signaled = false }
+      end
+
+      # Check if there is a pending signal
+      # @return [Boolean] true if signaled
+      def signaled?
+        @mutex.synchronize { @signaled }
+      end
+    end
+  end
+end