bolt_rb 0.1.0

data/lib/bolt_rb/socket_mode/client.rb

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+require 'websocket-client-simple'
+require 'net/http'
+require 'uri'
+require 'json'
+
+module BoltRb
+  module SocketMode
+    # WebSocket client for Slack Socket Mode connections
+    #
+    # Handles the WebSocket lifecycle including:
+    # - Obtaining a connection URL via apps.connections.open
+    # - Establishing and maintaining the WebSocket connection
+    # - Acknowledging received events
+    # - Automatic reconnection on disconnect
+    #
+    # @example Basic usage
+    #   client = BoltRb::SocketMode::Client.new(
+    #     app_token: 'xapp-...',
+    #     logger: Logger.new(STDOUT)
+    #   )
+    #   client.on_message { |payload| handle_event(payload) }
+    #   client.start
+    class Client
+      SLACK_API_URL = 'https://slack.com/api/apps.connections.open'
+      RECONNECT_DELAY = 5
+
+      # @return [String] The Slack app-level token
+      attr_reader :app_token
+
+      # @return [Logger] The logger instance
+      attr_reader :logger
+
+      # Creates a new Socket Mode client
+      #
+      # @param app_token [String] The Slack app-level token (xapp-...)
+      # @param logger [Logger] Logger instance for output
+      def initialize(app_token:, logger: nil)
+        @app_token = app_token
+        @logger = logger || Logger.new($stdout)
+        @running = false
+        @websocket = nil
+        @message_handlers = []
+      end
+
+      # Registers a handler for incoming messages
+      #
+      # @yield [Hash] The parsed event payload
+      # @return [void]
+      def on_message(&block)
+        @message_handlers << block
+      end
+
+      # Starts the Socket Mode connection
+      #
+      # Obtains a WebSocket URL and establishes the connection.
+      # This method blocks until stop is called.
+      #
+      # @return [void]
+      def start
+        @running = true
+        connect_with_retry
+        run_loop
+      end
+
+      # Stops the Socket Mode connection
+      #
+      # @return [void]
+      def stop
+        @running = false
+        @websocket&.close
+      end
+
+      # Requests a stop - safe to call from trap context
+      #
+      # Only sets the running flag to false. Does NOT close the websocket
+      # or perform any operations that might use mutexes, as this is
+      # designed to be called from signal trap handlers.
+      #
+      # @return [void]
+      def request_stop
+        @running = false
+      end
+
+      # @return [Boolean] Whether the client is currently running
+      def running?
+        @running
+      end
+
+      # @return [Boolean] Whether the WebSocket is connected
+      def connected?
+        @websocket&.open?
+      end
+
+      private
+
+      # Main run loop that keeps the connection alive
+      #
+      # @return [void]
+      def run_loop
+        while @running
+          sleep 0.1
+          reconnect_if_needed
+        end
+      ensure
+        # Clean up websocket when loop exits
+        @websocket&.close
+      end
+
+      # Reconnects if the WebSocket is disconnected
+      #
+      # @return [void]
+      def reconnect_if_needed
+        return if !@running || connected?
+
+        logger.info '[SocketMode] Connection lost, reconnecting...'
+        sleep RECONNECT_DELAY
+        connect_with_retry
+      end
+
+      # Attempts to connect with retry logic
+      #
+      # @return [void]
+      def connect_with_retry
+        retries = 0
+        max_retries = 5
+
+        begin
+          connect
+        rescue StandardError => e
+          retries += 1
+          if retries <= max_retries
+            logger.warn "[SocketMode] Connection failed (attempt #{retries}/#{max_retries}): #{e.message}"
+            sleep RECONNECT_DELAY
+            retry
+          else
+            logger.error "[SocketMode] Max retries exceeded, giving up: #{e.message}"
+            @running = false
+          end
+        end
+      end
+
+      # Establishes the WebSocket connection
+      #
+      # @return [void]
+      def connect
+        url = obtain_websocket_url
+        logger.info '[SocketMode] Connecting to Slack...'
+
+        client = self
+        @websocket = WebSocket::Client::Simple.connect(url)
+
+        @websocket.on :open do
+          client.send(:handle_open)
+        end
+
+        @websocket.on :message do |msg|
+          client.send(:handle_message, msg)
+        end
+
+        @websocket.on :error do |e|
+          client.send(:handle_error, e)
+        end
+
+        @websocket.on :close do |e|
+          client.send(:handle_close, e)
+        end
+
+        # Wait for connection to establish
+        sleep 0.5 until @websocket.open? || !@running
+      end
+
+      # Obtains a WebSocket URL from Slack
+      #
+      # @return [String] The WebSocket URL
+      # @raise [RuntimeError] If unable to obtain URL
+      def obtain_websocket_url
+        uri = URI.parse(SLACK_API_URL)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+
+        request = Net::HTTP::Post.new(uri.path)
+        request['Authorization'] = "Bearer #{app_token}"
+        request['Content-Type'] = 'application/x-www-form-urlencoded'
+
+        response = http.request(request)
+        body = JSON.parse(response.body)
+
+        unless body['ok']
+          raise "Failed to obtain WebSocket URL: #{body['error']}"
+        end
+
+        body['url']
+      end
+
+      # Handles WebSocket open event
+      #
+      # @return [void]
+      def handle_open
+        logger.info '[SocketMode] Connected to Slack'
+      end
+
+      # Handles incoming WebSocket message
+      #
+      # @param msg [WebSocket::Client::Simple::Message] The message
+      # @return [void]
+      def handle_message(msg)
+        # Skip nil, empty, or non-JSON data (like WebSocket ping/pong frames)
+        return if msg.data.nil? || msg.data.empty? || !msg.data.start_with?('{')
+
+        data = JSON.parse(msg.data)
+
+        # Handle Slack's control messages
+        case data['type']
+        when 'hello'
+          logger.debug '[SocketMode] Received hello from Slack'
+          return
+        when 'disconnect'
+          logger.info "[SocketMode] Disconnect requested: #{data['reason']}"
+          @websocket&.close
+          return
+        when 'ping'
+          handle_ping(data)
+          return
+        end
+
+        # Acknowledge the event
+        acknowledge(data['envelope_id']) if data['envelope_id']
+
+        # Dispatch to handlers
+        dispatch_event(data)
+      rescue JSON::ParserError => e
+        logger.error "[SocketMode] Failed to parse message: #{e.message}"
+      rescue StandardError => e
+        logger.error "[SocketMode] Error handling message: #{e.message}"
+        logger.error e.backtrace.first(5).join("\n")
+      end
+
+      # Handles WebSocket error
+      #
+      # @param error [Exception] The error
+      # @return [void]
+      def handle_error(error)
+        logger.error "[SocketMode] WebSocket error: #{error.message}"
+      end
+
+      # Handles WebSocket close
+      #
+      # @param event [Object] The close event
+      # @return [void]
+      def handle_close(event)
+        logger.info "[SocketMode] WebSocket closed: #{event}"
+      end
+
+      # Handles Slack Socket Mode ping message
+      #
+      # Responds with a pong message echoing back the num field
+      # @param data [Hash] The ping message data
+      # @return [void]
+      def handle_ping(data)
+        return unless @websocket&.open?
+
+        pong = { 'type' => 'pong' }
+        pong['num'] = data['num'] if data['num']
+        @websocket.send(pong.to_json)
+        logger.debug "[SocketMode] Responded to ping#{data['num'] ? " (num: #{data['num']})" : ''}"
+      end
+
+      # Sends an acknowledgement for an event
+      #
+      # @param envelope_id [String] The envelope ID to acknowledge
+      # @return [void]
+      def acknowledge(envelope_id)
+        return unless @websocket&.open?
+
+        ack = { envelope_id: envelope_id }.to_json
+        @websocket.send(ack)
+        logger.debug "[SocketMode] Acknowledged envelope: #{envelope_id}"
+      end
+
+      # Dispatches an event to registered handlers
+      #
+      # @param data [Hash] The event data
+      # @return [void]
+      def dispatch_event(data)
+        @message_handlers.each do |handler|
+          handler.call(data)
+        rescue StandardError => e
+          logger.error "[SocketMode] Handler error: #{e.message}"
+          logger.error e.backtrace.first(5).join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/bolt_rb/testing/payload_factory.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module BoltRb
+  module Testing
+    # Factory class for creating fake Slack payloads for testing purposes.
+    #
+    # This class provides methods to generate realistic payloads for various
+    # Slack event types, making it easy to write specs for handlers without
+    # needing actual Slack events.
+    #
+    # @example Creating a message event payload
+    #   payload = BoltRb::Testing::PayloadFactory.message(text: 'hello')
+    #   # => { 'type' => 'event_callback', 'event' => { 'type' => 'message', ... } }
+    #
+    # @example Creating a slash command payload
+    #   payload = BoltRb::Testing::PayloadFactory.command(command: '/deploy', text: 'production')
+    #   # => { 'command' => '/deploy', 'text' => 'production', ... }
+    class PayloadFactory
+      class << self
+        # Creates a message event payload
+        #
+        # @param text [String] The message text
+        # @param user [String] The user ID (default: 'U123TEST')
+        # @param channel [String] The channel ID (default: 'C456TEST')
+        # @param ts [String, nil] The timestamp (auto-generated if nil)
+        # @param thread_ts [String, nil] The thread timestamp for threaded messages
+        # @return [Hash] The message event payload
+        def message(text:, user: 'U123TEST', channel: 'C456TEST', ts: nil, thread_ts: nil)
+          {
+            'type' => 'event_callback',
+            'event' => {
+              'type' => 'message',
+              'text' => text,
+              'user' => user,
+              'channel' => channel,
+              'ts' => ts || generate_ts,
+              'thread_ts' => thread_ts
+            }.compact
+          }
+        end
+
+        # Creates an app_mention event payload
+        #
+        # @param text [String] The mention text (should include the bot mention)
+        # @param user [String] The user ID (default: 'U123TEST')
+        # @param channel [String] The channel ID (default: 'C456TEST')
+        # @return [Hash] The app_mention event payload
+        def app_mention(text:, user: 'U123TEST', channel: 'C456TEST')
+          {
+            'type' => 'event_callback',
+            'event' => {
+              'type' => 'app_mention',
+              'text' => text,
+              'user' => user,
+              'channel' => channel,
+              'ts' => generate_ts
+            }
+          }
+        end
+
+        # Creates a slash command payload
+        #
+        # @param command [String] The command name (e.g., '/deploy')
+        # @param text [String] The text after the command (default: '')
+        # @param user [String] The user ID (default: 'U123TEST')
+        # @param channel [String] The channel ID (default: 'C456TEST')
+        # @return [Hash] The command payload
+        def command(command:, text: '', user: 'U123TEST', channel: 'C456TEST')
+          {
+            'command' => command,
+            'text' => text,
+            'user_id' => user,
+            'channel_id' => channel,
+            'response_url' => 'https://hooks.slack.com/commands/T123/456/xxx',
+            'trigger_id' => "trigger_#{SecureRandom.hex(8)}"
+          }
+        end
+
+        # Creates a block_actions payload for interactive components
+        #
+        # @param action_id [String] The action ID of the interactive component
+        # @param value [String, nil] The value of the action
+        # @param user [String] The user ID (default: 'U123TEST')
+        # @param block_id [String, nil] The block ID (default: 'block_1')
+        # @param channel [String] The channel ID (default: 'C456TEST')
+        # @return [Hash] The block_actions payload
+        def action(action_id:, value: nil, user: 'U123TEST', block_id: nil, channel: 'C456TEST')
+          {
+            'type' => 'block_actions',
+            'user' => { 'id' => user },
+            'channel' => { 'id' => channel },
+            'actions' => [{
+              'action_id' => action_id,
+              'block_id' => block_id || 'block_1',
+              'value' => value
+            }.compact],
+            'response_url' => 'https://hooks.slack.com/actions/T123/456/xxx',
+            'trigger_id' => "trigger_#{SecureRandom.hex(8)}"
+          }
+        end
+
+        # Creates a shortcut payload (global or message)
+        #
+        # @param callback_id [String] The callback ID of the shortcut
+        # @param user [String] The user ID (default: 'U123TEST')
+        # @param type [Symbol] The shortcut type (:global or :message)
+        # @param message_text [String, nil] The message text for message shortcuts
+        # @return [Hash] The shortcut payload
+        def shortcut(callback_id:, user: 'U123TEST', type: :global, message_text: nil)
+          payload = {
+            'type' => type == :message ? 'message_action' : 'shortcut',
+            'callback_id' => callback_id,
+            'user' => { 'id' => user },
+            'trigger_id' => "trigger_#{SecureRandom.hex(8)}"
+          }
+
+          if type == :message
+            payload['channel'] = { 'id' => 'C456TEST' }
+            payload['message'] = {
+              'type' => 'message',
+              'text' => message_text || 'Original message',
+              'user' => 'U789MSG',
+              'ts' => generate_ts
+            }
+          end
+
+          payload
+        end
+
+        private
+
+        # Generates a fake Slack timestamp
+        #
+        # @return [String] A timestamp in Slack's format (epoch.random)
+        def generate_ts
+          "#{Time.now.to_i}.#{SecureRandom.hex(3)}"
+        end
+      end
+    end
+  end
+end

data/lib/bolt_rb/testing/rspec_helpers.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module BoltRb
+  module Testing
+    # RSpec helper methods for testing Bolt handlers
+    #
+    # Include this module in your RSpec configuration to get convenient
+    # methods for building contexts and mocking Slack clients.
+    #
+    # @example Including in RSpec
+    #   RSpec.configure do |config|
+    #     config.include BoltRb::Testing::RSpecHelpers
+    #   end
+    #
+    # @example Using in specs
+    #   describe MyHandler do
+    #     it 'handles messages' do
+    #       ctx = build_context(payload.message(text: 'hello'))
+    #       MyHandler.call(ctx)
+    #       expect(ctx.acked?).to be true
+    #     end
+    #   end
+    module RSpecHelpers
+      # Builds a Context object from a payload for testing
+      #
+      # @param payload [Hash] The Slack event payload
+      # @param client [Object, nil] The Slack client (mocked if nil)
+      # @param ack [Proc, nil] The acknowledgement function (no-op if nil)
+      # @return [BoltRb::Context] The context object
+      def build_context(payload, client: nil, ack: nil)
+        BoltRb::Context.new(
+          payload: payload,
+          client: client || mock_slack_client,
+          ack: ack || ->(_) {}
+        )
+      end
+
+      # Creates a mock Slack Web API client with common methods stubbed
+      #
+      # @return [RSpec::Mocks::Double] A mock Slack client
+      def mock_slack_client
+        client = instance_double(Slack::Web::Client)
+        allow(client).to receive(:chat_postMessage).and_return({ 'ok' => true, 'ts' => '123.456' })
+        allow(client).to receive(:chat_update).and_return({ 'ok' => true })
+        allow(client).to receive(:views_open).and_return({ 'ok' => true })
+        allow(client).to receive(:views_update).and_return({ 'ok' => true })
+        client
+      end
+
+      # Convenience accessor for the PayloadFactory
+      #
+      # @return [Class] The PayloadFactory class
+      #
+      # @example
+      #   payload.message(text: 'hello')
+      #   payload.command(command: '/deploy')
+      def payload
+        BoltRb::Testing::PayloadFactory
+      end
+    end
+  end
+end

data/lib/bolt_rb/testing.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'testing/payload_factory'
+require_relative 'testing/rspec_helpers'
+
+module BoltRb
+  # Testing utilities for BoltRb applications
+  #
+  # This module provides helpers for writing tests for Slack handlers,
+  # including payload factories and RSpec integration.
+  #
+  # @example Basic setup in spec_helper.rb
+  #   require 'bolt_rb/testing'
+  #
+  #   RSpec.configure do |config|
+  #     config.include BoltRb::Testing::RSpecHelpers
+  #   end
+  module Testing
+  end
+end

data/lib/bolt_rb/version.rb

@@ -0,0 +1,4 @@
+# lib/bolt_rb/version.rb
+module BoltRb
+  VERSION = '0.1.0'
+end

data/lib/bolt_rb.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+# Define the module and core methods first so they're available during handler loading
+module BoltRb
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+
+  class << self
+    # Returns the current configuration instance
+    #
+    # @return [Configuration] The memoized configuration instance
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Yields the configuration for block-style configuration
+    #
+    # @yield [Configuration] The configuration instance
+    # @example
+    #   BoltRb.configure do |config|
+    #     config.bot_token = 'xoxb-...'
+    #   end
+    def configure
+      yield(configuration)
+    end
+
+    # Resets the configuration to a fresh instance
+    # Useful for testing or reconfiguration scenarios
+    #
+    # @return [Configuration] The new configuration instance
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # Convenience accessor for the logger
+    #
+    # @return [Logger] The configured logger instance
+    def logger
+      configuration.logger
+    end
+
+    # Returns the global router instance
+    #
+    # @return [Router] The memoized router instance
+    def router
+      @router ||= Router.new
+    end
+
+    # Resets the router to a fresh instance
+    # Useful for testing or reconfiguration scenarios
+    #
+    # @return [Router] The new router instance
+    def reset_router!
+      @router = Router.new
+    end
+  end
+end
+
+require_relative 'bolt_rb/version'
+require_relative 'bolt_rb/middleware/base'
+require_relative 'bolt_rb/middleware/chain'
+require_relative 'bolt_rb/middleware/logging'
+require_relative 'bolt_rb/configuration'
+require_relative 'bolt_rb/context'
+require_relative 'bolt_rb/router'
+require_relative 'bolt_rb/handlers/base'
+require_relative 'bolt_rb/handlers/event_handler'
+require_relative 'bolt_rb/handlers/command_handler'
+require_relative 'bolt_rb/handlers/action_handler'
+require_relative 'bolt_rb/handlers/shortcut_handler'
+require_relative 'bolt_rb/handlers/view_submission_handler'
+require_relative 'bolt_rb/socket_mode/client'
+require_relative 'bolt_rb/testing'
+require_relative 'bolt_rb/app'