shikibu 0.1.0

data/lib/shikibu/app.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Shikibu
+  # Main application class for Shikibu
+  # Manages configuration, lifecycle, and workflow execution
+  #
+  # @example
+  #   app = Shikibu::App.new(
+  #     database_url: 'sqlite://shikibu.db',
+  #     service_name: 'my-service',
+  #     auto_migrate: true
+  #   )
+  #
+  #   app.register OrderWorkflow
+  #   app.start
+  #
+  #   instance_id = app.start_workflow(OrderWorkflow, order_id: '123', amount: 99.99)
+  #   result = app.get_result(instance_id)
+  #
+  #   app.shutdown
+  #
+  class App
+    attr_reader :storage, :worker_id, :service_name, :hooks, :message_retention_days,
+                :outbox_enabled, :broker_url, :outbox_poll_interval, :outbox_max_retries, :outbox_max_age_hours
+
+    # Create a new Shikibu application
+    # @param database_url [String] Database connection URL
+    # @param service_name [String] Service name for worker identification
+    # @param auto_migrate [Boolean] Whether to auto-apply migrations
+    # @param hooks [Object] Optional hooks for observability
+    # @param use_listen_notify [Boolean, nil] Enable PostgreSQL LISTEN/NOTIFY (nil=auto)
+    # @param message_retention_days [Integer] Days to retain channel messages (default: 7)
+    # @param outbox_enabled [Boolean] Enable outbox relayer (default: false)
+    # @param broker_url [String, nil] Message broker URL for outbox events
+    # @param outbox_poll_interval [Float] Outbox polling interval in seconds (default: 1.0)
+    # @param outbox_max_retries [Integer] Max retries for outbox events (default: 3)
+    # @param outbox_max_age_hours [Float, nil] Max age for outbox events in hours (default: nil)
+    def initialize(database_url:, service_name: 'shikibu', auto_migrate: false, hooks: nil,
+                   use_listen_notify: nil, message_retention_days: 7,
+                   outbox_enabled: false, broker_url: nil, outbox_poll_interval: 1.0,
+                   outbox_max_retries: 3, outbox_max_age_hours: nil)
+      @database_url = database_url
+      @service_name = service_name
+      @auto_migrate = auto_migrate
+      @hooks = hooks
+      @use_listen_notify = use_listen_notify
+      @message_retention_days = message_retention_days
+      @outbox_enabled = outbox_enabled
+      @broker_url = broker_url
+      @outbox_poll_interval = outbox_poll_interval
+      @outbox_max_retries = outbox_max_retries
+      @outbox_max_age_hours = outbox_max_age_hours
+      @worker_id = Locking.generate_worker_id(service_name)
+      @registered_workflows = {}
+      @running = false
+      @worker = nil
+      @notify_listener = nil
+
+      # Validate outbox configuration
+      raise ArgumentError, 'broker_url is required when outbox_enabled is true' if @outbox_enabled && @broker_url.nil?
+
+      # Initialize storage
+      @storage = Storage::SequelStorage.new(database_url, auto_migrate: auto_migrate)
+
+      # Initialize notify listener for PostgreSQL
+      setup_notify_listener if should_enable_listen_notify?
+
+      # Initialize replay engine
+      @replay_engine = ReplayEngine.new(
+        storage: @storage,
+        worker_id: @worker_id,
+        hooks: @hooks
+      )
+    end
+
+    # Check if outbox relayer is enabled
+    def outbox_enabled?
+      @outbox_enabled
+    end
+
+    # Register a workflow class
+    # @param workflow_class [Class] Workflow class to register
+    def register(workflow_class)
+      name = workflow_class.workflow_name
+      @registered_workflows[name] = workflow_class
+      Shikibu.register_workflow(workflow_class)
+    end
+
+    # Start the background worker
+    def start
+      return if @running
+
+      @running = true
+
+      # Start notify listener before worker
+      @notify_listener&.start
+
+      @worker = Worker.new(self)
+
+      # Register notification handlers
+      register_notify_handlers if @notify_listener
+
+      @worker.start
+    end
+
+    # Gracefully shutdown the application
+    def shutdown
+      return unless @running
+
+      @running = false
+      @worker&.stop
+      @notify_listener&.stop
+      @storage.close
+    end
+
+    # Access the worker
+    attr_reader :worker
+
+    # Check if app is running
+    def running?
+      @running
+    end
+
+    # Start a new workflow
+    # @param workflow_class [Class] Workflow class
+    # @param instance_id [String, nil] Optional custom instance ID
+    # @param input [Hash] Input parameters
+    # @return [String] Instance ID
+    def start_workflow(workflow_class, instance_id: nil, **input)
+      instance_id ||= SecureRandom.uuid
+
+      @replay_engine.start_workflow(workflow_class, instance_id: instance_id, **input)
+
+      instance_id
+    rescue WaitForTimerSignal, WaitForChannelSignal
+      # Workflow suspended, return instance_id
+      instance_id
+    end
+
+    # Resume a workflow
+    # @param instance_id [String] Instance ID
+    def resume_workflow(instance_id)
+      @replay_engine.resume_workflow(instance_id)
+    rescue WaitForTimerSignal, WaitForChannelSignal
+      # Workflow still suspended
+      nil
+    end
+
+    # Get workflow result
+    # @param instance_id [String] Instance ID
+    # @return [Hash] Status and output
+    def get_result(instance_id)
+      instance = @storage.get_instance(instance_id)
+      raise WorkflowNotFoundError, instance_id unless instance
+
+      {
+        status: instance[:status],
+        output: instance[:output_data],
+        error: instance[:status] == Status::FAILED ? 'Workflow failed' : nil
+      }
+    end
+
+    # Get workflow status
+    # @param instance_id [String] Instance ID
+    # @return [String] Status
+    def get_status(instance_id)
+      instance = @storage.get_instance(instance_id)
+      raise WorkflowNotFoundError, instance_id unless instance
+
+      instance[:status]
+    end
+
+    # Cancel a workflow
+    # @param instance_id [String] Instance ID
+    # @param reason [String, nil] Cancellation reason
+    def cancel_workflow(instance_id, reason: nil) # rubocop:disable Lint/UnusedMethodArgument
+      instance = @storage.get_instance(instance_id)
+      raise WorkflowNotFoundError, instance_id unless instance
+
+      # Only cancel if not already terminal
+      terminal_statuses = [Status::COMPLETED, Status::FAILED, Status::CANCELLED]
+      return false if terminal_statuses.include?(instance[:status])
+
+      @storage.update_instance_status(instance_id, Status::CANCELLED)
+      true
+    end
+
+    # List workflow instances
+    # @param limit [Integer] Maximum number of results
+    # @param offset [Integer] Offset for pagination
+    # @param status [String, nil] Filter by status
+    # @param workflow_name [String, nil] Filter by workflow name
+    # @return [Array<Hash>] List of instances
+    def list_workflows(limit: 100, offset: 0, status: nil, workflow_name: nil)
+      @storage.list_instances(
+        limit: limit,
+        offset: offset,
+        status_filter: status,
+        workflow_name: workflow_name
+      )
+    end
+
+    # Send an event to waiting workflows
+    # @param event_type [String] Event type (channel name)
+    # @param data [Object] Event data
+    # @param metadata [Hash, nil] Optional metadata
+    # @param target_instance_id [String, nil] If set, deliver only to this specific instance (Point-to-Point)
+    def send_event(event_type, data, metadata: nil, target_instance_id: nil)
+      full_metadata = (metadata || {}).merge(
+        source_service: @service_name,
+        published_at: Time.now.iso8601
+      )
+
+      # Publish message to channel for persistence
+      message_id = @storage.publish_message(
+        channel: event_type,
+        data: data,
+        metadata: full_metadata
+      )
+
+      # Deliver to subscribers
+      if target_instance_id
+        # Point-to-Point: deliver only to specific instance
+        @storage.deliver_channel_message(
+          instance_id: target_instance_id,
+          channel: event_type,
+          message_id: message_id,
+          data: data,
+          metadata: full_metadata,
+          worker_id: @worker_id
+        )
+      else
+        # Broadcast: wake all waiting subscribers (Worker will handle delivery)
+        @notify_listener&.notify(Notify::Channel::CHANNEL_MESSAGE, { channel: event_type })
+      end
+
+      # Call hook
+      hooks&.on_event_sent&.call(event_type, @service_name, data)
+    end
+
+    # Get registered workflows
+    def registered_workflows
+      @registered_workflows.dup
+    end
+
+    # Access the notify listener
+    attr_reader :notify_listener
+
+    private
+
+    def should_enable_listen_notify?
+      return @use_listen_notify unless @use_listen_notify.nil?
+
+      # Auto-detect: enable for PostgreSQL
+      @database_url.start_with?('postgres')
+    end
+
+    def setup_notify_listener
+      @notify_listener = Notify.create_listener(@database_url)
+      @storage.notify_enabled = true
+    end
+
+    def register_notify_handlers
+      # Handle workflow_resumable notifications
+      @notify_listener.subscribe(Notify::Channel::WORKFLOW_RESUMABLE) do |_payload|
+        handle_workflow_resumable_notify
+      end
+
+      # Handle channel_message notifications
+      @notify_listener.subscribe(Notify::Channel::CHANNEL_MESSAGE) do |_payload|
+        handle_channel_message_notify
+      end
+
+      # Handle outbox_pending notifications (only if outbox is enabled)
+      return unless @outbox_enabled
+
+      @notify_listener.subscribe(Notify::Channel::OUTBOX_PENDING) do |_payload|
+        handle_outbox_pending_notify
+      end
+    end
+
+    def handle_workflow_resumable_notify
+      # Wake the resumption loop
+      @worker&.resume_wake_event&.signal
+    end
+
+    def handle_channel_message_notify
+      # Wake the message delivery loop
+      @worker&.message_wake_event&.signal
+    end
+
+    def handle_outbox_pending_notify
+      # Wake the outbox relayer
+      @worker&.outbox_wake_event&.signal
+    end
+  end
+end

data/lib/shikibu/channels.rb

@@ -0,0 +1,360 @@
+# frozen_string_literal: true
+
+module Shikibu
+  # Channel-based messaging for workflow communication
+  # Supports three modes:
+  #   - broadcast: All subscribers receive all messages
+  #   - competing: Each message goes to exactly one subscriber
+  #   - direct: Point-to-point messaging to specific instance
+  #
+  # @example Broadcast (pub/sub)
+  #   # Workflow A
+  #   subscribe 'notifications', mode: :broadcast
+  #   message = receive 'notifications', timeout: 60
+  #
+  #   # Workflow B
+  #   publish 'notifications', { type: 'alert', text: 'Hello!' }
+  #
+  # @example Competing consumers (work queue)
+  #   # Worker workflows (multiple instances)
+  #   subscribe 'tasks', mode: :competing
+  #   task = receive 'tasks'
+  #   process(task)
+  #
+  #   # Producer
+  #   publish 'tasks', { job_id: 123, action: 'process' }
+  #
+  # @example Direct messaging (point-to-point)
+  #   # Parent workflow
+  #   child_id = start_workflow(ChildWorkflow, parent_id: instance_id)
+  #   subscribe 'results', mode: :direct
+  #   result = receive 'results', timeout: 300
+  #
+  #   # Child workflow
+  #   send_to parent_id, 'results', { status: 'done', data: result }
+  #
+  module Channels
+    # Message wrapper with metadata
+    class Message
+      attr_reader :id, :channel, :data, :metadata, :published_at
+
+      def initialize(id:, channel:, data:, metadata: nil, published_at: nil)
+        @id = id
+        @channel = channel
+        @data = data
+        @metadata = metadata || {}
+        @published_at = published_at
+      end
+
+      def [](key)
+        @data[key]
+      end
+
+      def to_h
+        {
+          id: @id,
+          channel: @channel,
+          data: @data,
+          metadata: @metadata,
+          published_at: @published_at
+        }
+      end
+    end
+
+    # Subscription info
+    class Subscription
+      attr_reader :channel, :mode, :subscribed_at
+
+      def initialize(channel:, mode:, subscribed_at: nil)
+        @channel = channel
+        @mode = mode.to_s
+        @subscribed_at = subscribed_at || Time.now
+      end
+
+      def broadcast?
+        @mode == ChannelMode::BROADCAST
+      end
+
+      def competing?
+        @mode == ChannelMode::COMPETING
+      end
+
+      def direct?
+        @mode == ChannelMode::DIRECT
+      end
+    end
+
+    module_function
+
+    # Subscribe to a channel
+    # @param ctx [WorkflowContext] Workflow context
+    # @param channel [String] Channel name
+    # @param mode [Symbol, String] Subscription mode (:broadcast, :competing, :direct)
+    # @raise [ChannelModeConflictError] If channel is already configured with a different mode
+    def subscribe(ctx, channel, mode: :broadcast)
+      mode_str = mode.to_s
+      validate_mode!(mode_str)
+
+      # For direct mode, use instance-specific channel
+      actual_channel = if mode_str == ChannelMode::DIRECT
+                         "#{channel}:#{ctx.instance_id}"
+                       else
+                         channel
+                       end
+
+      # Determine actual mode (direct maps to competing)
+      actual_mode = mode_str == ChannelMode::DIRECT ? ChannelMode::COMPETING : mode_str
+
+      # Check for mode conflict
+      existing_mode = ctx.storage.get_channel_mode(actual_channel)
+      if existing_mode && existing_mode != actual_mode
+        raise ChannelModeConflictError.new(channel, existing_mode, mode_str)
+      end
+
+      ctx.storage.subscribe_to_channel(
+        instance_id: ctx.instance_id,
+        channel: actual_channel,
+        mode: actual_mode
+      )
+
+      Subscription.new(channel: actual_channel, mode: mode_str)
+    end
+
+    # Unsubscribe from a channel
+    # @param ctx [WorkflowContext] Workflow context
+    # @param channel [String] Channel name
+    def unsubscribe(ctx, channel)
+      ctx.storage.unsubscribe_from_channel(
+        instance_id: ctx.instance_id,
+        channel: channel
+      )
+    end
+
+    # Receive a message from a channel (blocks workflow until message arrives)
+    # @param ctx [WorkflowContext] Workflow context
+    # @param channel [String] Channel name
+    # @param timeout [Numeric, nil] Timeout in seconds (nil = no timeout)
+    # @param mode [Symbol, String] Subscription mode
+    # @return [Message] Received message
+    # @raise [MessageTimeoutError] If timeout expires
+    def receive(ctx, channel, timeout: nil, mode: :broadcast)
+      mode_str = mode.to_s
+      activity_id = ctx.generate_activity_id("receive:#{channel}")
+
+      # For direct mode, use instance-specific channel
+      actual_channel = if mode_str == ChannelMode::DIRECT
+                         "#{channel}:#{ctx.instance_id}"
+                       else
+                         channel
+                       end
+
+      # Check cache during replay
+      if ctx.replaying? && ctx.cached_result?(activity_id)
+        cached = ctx.get_cached_result(activity_id)
+        return build_message_from_cached(cached) if cached[:event_type] == EventType::CHANNEL_MESSAGE_RECEIVED
+
+        # Timeout was recorded
+        raise MessageTimeoutError.new(channel, timeout)
+      end
+
+      # Try to get pending message immediately
+      message = try_receive_immediate(ctx, actual_channel, mode_str)
+      if message
+        # Call hook
+        ctx.hooks&.on_event_received&.call(ctx.instance_id, actual_channel, message.data)
+
+        record_message_received(ctx, activity_id, actual_channel, message)
+        return message
+      end
+
+      # No message available, suspend workflow
+      timeout_at = timeout ? Time.now + timeout : nil
+
+      raise WaitForChannelSignal.new(
+        channel: actual_channel,
+        mode: mode_str == ChannelMode::DIRECT ? ChannelMode::COMPETING : mode_str,
+        timeout_at: timeout_at,
+        activity_id: activity_id
+      )
+    end
+
+    # Publish a message to a channel
+    # @param ctx [WorkflowContext] Workflow context
+    # @param channel [String] Channel name
+    # @param data [Object] Message data
+    # @param metadata [Hash, nil] Optional metadata
+    # @return [String] Message ID
+    def publish(ctx, channel, data, metadata: nil)
+      full_metadata = (metadata || {}).merge(
+        source_instance_id: ctx.instance_id,
+        source_workflow: ctx.workflow_name,
+        published_at: Time.now.iso8601
+      )
+
+      result = ctx.storage.publish_message(
+        channel: channel,
+        data: data,
+        metadata: full_metadata
+      )
+
+      # Call hook
+      ctx.hooks&.on_event_sent&.call(channel, ctx.workflow_name, data)
+
+      result
+    end
+
+    # Send a message directly to a specific workflow instance
+    # @param ctx [WorkflowContext] Workflow context
+    # @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(ctx, target_instance_id, channel, data, metadata: nil)
+      direct_channel = "#{channel}:#{target_instance_id}"
+
+      full_metadata = (metadata || {}).merge(
+        source_instance_id: ctx.instance_id,
+        source_workflow: ctx.workflow_name,
+        target_instance_id: target_instance_id,
+        published_at: Time.now.iso8601
+      )
+
+      ctx.storage.publish_message(
+        channel: direct_channel,
+        data: data,
+        metadata: full_metadata
+      )
+    end
+
+    # Receive without blocking (returns nil if no message)
+    # @param ctx [WorkflowContext] Workflow context
+    # @param channel [String] Channel name
+    # @param mode [Symbol, String] Subscription mode
+    # @return [Message, nil] Message or nil
+    def try_receive(ctx, channel, mode: :broadcast)
+      mode_str = mode.to_s
+      actual_channel = if mode_str == ChannelMode::DIRECT
+                         "#{channel}:#{ctx.instance_id}"
+                       else
+                         channel
+                       end
+
+      try_receive_immediate(ctx, actual_channel, mode_str)
+    end
+
+    # List active subscriptions for an instance
+    # @param ctx [WorkflowContext] Workflow context
+    # @return [Array<Subscription>]
+    def subscriptions(ctx)
+      subs = ctx.storage.db[:channel_subscriptions]
+                .where(instance_id: ctx.instance_id)
+                .all
+
+      subs.map do |row|
+        Subscription.new(
+          channel: row[:channel],
+          mode: row[:mode],
+          subscribed_at: row[:subscribed_at]
+        )
+      end
+    end
+
+    class << self
+      private
+
+      def validate_mode!(mode)
+        return if ChannelMode::ALL.include?(mode)
+
+        raise ArgumentError, "Invalid channel mode: #{mode}. Must be one of: #{ChannelMode::ALL.join(', ')}"
+      end
+
+      def try_receive_immediate(ctx, channel, mode)
+        sub = ctx.storage.get_subscription(instance_id: ctx.instance_id, channel: channel)
+
+        # Get cursor for broadcast mode
+        cursor_id = sub&.dig(:cursor_message_id)
+
+        row = ctx.storage.get_next_message(
+          channel: channel,
+          mode: mode == ChannelMode::DIRECT ? ChannelMode::COMPETING : mode,
+          instance_id: ctx.instance_id,
+          cursor_id: cursor_id
+        )
+
+        return nil unless row
+
+        # For competing mode, try to claim
+        if mode == ChannelMode::COMPETING
+          claimed = ctx.storage.claim_message(
+            message_id: row[:message_id],
+            instance_id: ctx.instance_id
+          )
+          return nil unless claimed
+        end
+
+        # Update cursor for broadcast mode
+        update_broadcast_cursor(ctx, channel, row[:id]) if mode == ChannelMode::BROADCAST
+
+        build_message(row)
+      end
+
+      def update_broadcast_cursor(ctx, channel, message_id)
+        ctx.storage.db[:channel_subscriptions]
+           .where(instance_id: ctx.instance_id, channel: channel)
+           .update(cursor_message_id: message_id)
+      end
+
+      def build_message(row)
+        data = if row[:data_type] == DataType::BINARY
+                 row[:data_binary]
+               else
+                 raw_data = row[:data]
+                 raw_data.is_a?(String) ? JSON.parse(raw_data, symbolize_names: true) : raw_data
+               end
+
+        metadata = row[:metadata]
+        metadata = JSON.parse(metadata, symbolize_names: true) if metadata.is_a?(String)
+
+        Message.new(
+          id: row[:message_id],
+          channel: row[:channel],
+          data: data,
+          metadata: metadata,
+          published_at: row[:published_at]
+        )
+      end
+
+      def build_message_from_cached(cached)
+        # The cached structure is { event_type: ..., data: { message_id:, channel:, data:, metadata: } }
+        msg_data = cached[:data] || {}
+        Message.new(
+          id: msg_data[:message_id] || SecureRandom.uuid,
+          channel: msg_data[:channel] || 'unknown',
+          data: msg_data[:data],
+          metadata: msg_data[:metadata] || {},
+          published_at: msg_data[:published_at]
+        )
+      end
+
+      def record_message_received(ctx, activity_id, channel, message)
+        ctx.storage.append_history(
+          instance_id: ctx.instance_id,
+          activity_id: activity_id,
+          event_type: EventType::CHANNEL_MESSAGE_RECEIVED,
+          event_data: {
+            channel: channel,
+            message_id: message.id,
+            data: message.data,
+            metadata: message.metadata
+          }
+        )
+
+        ctx.cache_result(activity_id, {
+                           event_type: EventType::CHANNEL_MESSAGE_RECEIVED,
+                           data: message.to_h
+                         })
+      end
+    end
+  end
+end