slack-ruby-socket-mode-bot 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3d9b476cbef5846c666a7ab994c514f998f870d2004b1d2b0f3ff6c053e4c8f0
+  data.tar.gz: 46d7af96360646c78325592dcf4e5d4ba26ec5f6f776948e387f1d907eb0b96b
+SHA512:
+  metadata.gz: c696e7a8826e208174474dbcdfa03a242e8828a9de4b50e1add4ee3604180bc5080dc0ed45058f7978a2dcf494c7ac96d031f32c65aba702c4d283c5b2aad3e4
+  data.tar.gz: a60f162cf935ede9f7f08474ec8a3401b3493843207855611acf60b46965f886ec0cb2fb169206a17daa7f6ba353af131a72a3eaf3f1353ee6bfde5bd3c5cf30

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,12 @@
+AllCops:
+  TargetRubyVersion: 3.3
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Naming/FileName:
+  Exclude:
+    - 'lib/slack-ruby-socket-mode-bot.rb'

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 guille
+
+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/README.md

@@ -0,0 +1,15 @@
+# slack-ruby-socket-mode-bot
+
+This gem allows users to create Slack bots that respond to mentions. This gem only supports events-based [socket mode](https://api.slack.com/apis/socket-mode) bots. The gem allows registering a number of callbacks that will be executed if the registered regular expression matches the mention text.
+
+See the [examples](https://github.com/guille/slack-socket-mode-bot/blob/master/examples) directory for some ideas on how to use the gem.
+
+## Limitations
+
+- The bot assumes it is only running for one workspace.
+- It only supports mention events. Other types of events such as slash commands may be implemented in the future.
+- Put this together in a few hours, very likely to go boom unexpectedly.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/bot/bot.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module SlackSocketModeBot
+  MentionHandler = Data.define(:match_regex, :callback)
+
+  class Bot
+    def initialize(bot_token:, app_token:, logger: nil)
+      @bot_token = bot_token
+      @logger = logger || Logger.new($stdout)
+
+      slack_web_client # init
+
+      @socket_mode_client = Transport::SocketModeClient.new(
+        app_token:, logger:, callback: method(:process_event)
+      )
+    end
+
+    # Registers a callback for a matching regex
+    def on(match_regex, &block)
+      (@handlers ||= []) << MentionHandler.new(match_regex, block)
+    end
+
+    def run!
+      @socket_mode_client.run!
+    end
+
+    private
+
+    def slack_web_client
+      client = Slack::Web::Client.new(
+        token: @bot_token,
+        logger: @logger
+      )
+      auth_response = client.auth_test
+
+      raise auth_response unless auth_response[:ok]
+
+      @bot_user_id = auth_response[:user_id]
+      @team_id = auth_response[:team_id]
+
+      @slack_web_client ||= client
+    end
+
+    def handle_error(err)
+      @logger.error(err.message)
+      @logger.debug(err.backtrace)
+    end
+
+    def process_event(payload)
+      return unless payload_processable?(payload)
+
+      text_without_mention = payload[:event][:text].gsub(/<@#{@bot_user_id}>\s+/, "")
+
+      @handlers.each do |handler|
+        process_handler(handler, text_without_mention, payload[:event])
+      end
+    rescue StandardError => e
+      # Don't bring down the bot from a problematic message
+      handle_error(e)
+    end
+
+    def payload_processable?(payload)
+      if payload[:team_id] != @team_id
+        raise UnrecognisedWorkspace.new, "Unrecognised team id #{payload[:team_id]} (expected #{@team_id})"
+      end
+
+      payload[:event][:type] == "app_mention"
+    end
+
+    def process_handler(handler, text, event)
+      if (match_data = handler.match_regex.match(text))
+        @logger.debug("Found matching handler for #{match_data}")
+        handler.callback.call(event, match_data, slack_web_client)
+      end
+    rescue StandardError => e
+      # Don't stop processing handlers if one of them fails
+      handle_error(e)
+    end
+  end
+end

data/lib/errors/errors.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module SlackSocketModeBot
+  module Errors
+    class UnrecognisedWorkspace < StandardError; end
+  end
+end

data/lib/slack-ruby-socket-mode-bot.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/http/endpoint"
+require "async/websocket"
+require "logger"
+require "slack-ruby-client"
+
+require_relative "bot/bot"
+require_relative "errors/errors"
+require_relative "transport/socket_mode_client"
+require_relative "transport/websocket"
+require_relative "version"

data/lib/slack_ruby_socket_mode_bot.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "slack-ruby-socket-mode-bot"

data/lib/transport/socket_mode_client.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module SlackSocketModeBot
+  module Transport
+    class SocketModeClient
+      def initialize(app_token:, callback:, logger: nil)
+        @app_token = app_token
+        @callback = callback
+        @logger = logger || Logger.new($stdout)
+
+        @socket = WebSocket.new(client: self, logger: @logger)
+      end
+
+      def run!
+        @socket.connect!
+      end
+
+      def new_socket_url
+        response = slack_web_client.apps_connections_open
+
+        raise response unless response[:ok]
+
+        response[:url]
+        # debug only:
+        "#{response[:url]}&debug_reconnects=true"
+      end
+
+      def callback(*args)
+        @callback.call(*args)
+      end
+
+      private
+
+      def slack_web_client
+        client = Slack::Web::Client.new(
+          token: @app_token,
+          logger: @logger
+        )
+        @slack_web_client ||= client
+      end
+    end
+  end
+end

data/lib/transport/websocket.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module SlackSocketModeBot
+  module Transport
+    class WebSocket
+      attr_reader :client
+
+      def initialize(client:, logger: nil)
+        @client = client
+        @logger = logger || Logger.new($stdout)
+
+        @restart = Async::Notification.new
+        @ping_id = 1
+      end
+
+      def connect!
+        Async do |task|
+          trap_sigterm(task)
+
+          loop do
+            endpoint = Async::HTTP::Endpoint.parse(client.new_socket_url)
+
+            Async::WebSocket::Client.connect(endpoint) do |connection|
+              @ping_task = task.async do |subtask|
+                subtask.annotate "socket keep-alive"
+
+                loop do
+                  subtask.sleep 50
+                  ping!(connection) if @restart
+                end
+              end
+
+              @socket_task&.stop
+              @socket_task = task.async do |subtask|
+                subtask.annotate "socket message loop"
+
+                message_loop(connection)
+              rescue StandardError => e
+                @logger.info("Message read failed: #{e.message}. Restarting the socket")
+                restart!
+              end
+
+              # Wait here letting it ping & process messages until we need to reconnect
+              @restart.wait
+            end
+          end
+        end
+      rescue Interrupt
+        puts "Interrupt detected. Exiting..."
+      ensure
+        @ping_task&.stop
+        @socket_task&.stop
+      end
+
+      private
+
+      def message_loop(connection)
+        while (message = connection.read)
+          parsed = JSON.parse(message, symbolize_names: true)
+
+          @logger.debug("Got #{parsed.dig(:payload, :event, :type) || parsed}")
+
+          # Acknowledge all events
+          ack_event(connection, parsed[:envelope_id]) if parsed[:envelope_id]
+
+          # Restart when we get the warning to minimise downtime
+          restart! if parsed[:type] == "disconnect"
+
+          client.callback(parsed[:payload]) if parsed[:payload]
+        end
+      end
+
+      def restart!
+        @ping_task&.stop
+        @ping_id = 1
+
+        @restart.signal
+      end
+
+      def ping!(connection)
+        @logger.debug("Sending ping #{@ping_id}")
+        connection.send_ping("id=#{@ping_id}")
+        connection.flush
+
+        @ping_id += 1
+      rescue StandardError => e
+        @logger.info("Ping failed: #{e.message}. Restarting the socket")
+        restart!
+      end
+
+      def ack_event(connection, envelope_id)
+        connection.write(
+          Protocol::WebSocket::TextMessage.generate({ envelope_id: envelope_id })
+        )
+        connection.flush
+      end
+
+      def trap_sigterm(task)
+        Signal.trap("SIGTERM") do
+          puts("Received SIGTERM. Exiting...") # can't log from signal handler
+          @ping_task&.stop
+          @socket_task&.stop
+          task&.stop
+        end
+      rescue StandardError => e
+        puts("Error processing SIGTERM handler: #{e.message}")
+      end
+    end
+  end
+end

data/lib/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SlackSocketModeBot
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: slack-ruby-socket-mode-bot
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- guille
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-10-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: async
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: async-websocket
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: slack-ruby-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: This gem allows users to create Slack bots that respond to mentions.
+  This gem only supports events-based socket mode bots. The gem allows registering
+  a number of callbacks that will be executed if the registered regular expression
+  matches the mention text.
+email:
+- guille@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/bot/bot.rb
+- lib/errors/errors.rb
+- lib/slack-ruby-socket-mode-bot.rb
+- lib/slack_ruby_socket_mode_bot.rb
+- lib/transport/socket_mode_client.rb
+- lib/transport/websocket.rb
+- lib/version.rb
+homepage: https://github.com/guille/slack-socket-mode-bot
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/guille/slack-socket-mode-bot
+  source_code_uri: https://github.com/guille/slack-socket-mode-bot
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: Gem for implementing simple bots for Slack using Socket Mode
+test_files: []