slack_socket_mode_bot 0.9.2 → 0.9.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ecdae100a7f27d51751fe1fd77c772ca8a88cfab323266c874b996ffaed909c8
-  data.tar.gz: 92b4827386e87485f3adf26e93de16e910a2c4f9d320ba4cc683768d067b130f
+  metadata.gz: a296df6a07779baa7df57823973e3d928a82859b4cc325066b7d2ece2a6a66e9
+  data.tar.gz: f6403d418f85da1a14b3f2c696d93bb8c09f67723e096038445b424e3460d249
 SHA512:
-  metadata.gz: 497006f3d3854a431e29f12f6463c57ed35290e5d722de7fe7bab24a886f667483821553da14ecc904d64b6de45c3d48ae446f90ba4424c3fbcbf7c59362ec38
-  data.tar.gz: a0e94a4812aaf022a7e62e02f0a56718ecb38cfd49002fc0dbdc7e9833fcb6520dfe799ff3d2279d9239520a615215240337261a4116c4c4ab1b7496d4239af5
+  metadata.gz: 441c1d5466ec9bdd9032e6761e49fd18cf56764e4b5409e021a1d6b174d8d2b7ea9b70e59f2d6aa659185146c2b49f8568ec09890c3d234b0d5107a107598efd
+  data.tar.gz: 0b8115dbaf7727617df6b440e824496116146850f6d554db454c23426cadec48b4efc77a0f3b72fece57fc6850f3ea7224c603b16546f17817857dcd6decea97

data/README.md

@@ -17,11 +17,11 @@ require "logger"
 
 # Slack's Bot User OAuth Token
 # You can create this token with: https://api.slack.com/apps/ - "OAuth & Permissions" - "OAuth Tokens for Your Workspace"
-SLACK_BOT_TOKEN = "xoxb-..."
+SLACK_BOT_TOKEN = ENV.fetch("SLACK_BOT_TOKEN") # "xoxb-...", or "test" for test mode
 
 # Slack's App-Level Token
 # You can create this token with: https://api.slack.com/apps/ - "Basic Information" - "App-Level Tokens"
-SLACK_APP_TOKEN = "xapp-..."
+SLACK_APP_TOKEN = ENV.fetch("SLACK_APP_TOKEN") # "xapp-..."
 
 logger = Logger.new(STDOUT, level: Logger::Severity::INFO)
 
@@ -60,11 +60,39 @@ rescue Exception
 end
 
 # Start the communication
-bot.run
+bot.run unless bot.test_mode?
+
+# Test
+if bot.test_mode?
+  # Stub chat.postMessage
+  posted = []
+  bot.test_mode.stub_web_api("chat.postMessage") {|data| posted << data }
+
+  # Simulate receiving an event from Slack
+  data = {
+    type: "events_api",
+    payload: {
+      event: {
+        type: "app_mention",
+        text: "hello",
+        channel: "C123",
+      }
+    }
+  }
+  bot.test_mode.simulate_envelope(data)
+
+  # OK if chat.postMessage was sent
+  ok = posted == [{ channel: "C123", text: "echo:hello" }]
+
+  puts "test: #{ ok ? "OK" : "NG" }"
+end
 ```
 
 ```
-$ ruby examples/echo_bot.rb
+$ SLACK_BOT_TOKEN=test SLACK_APP_TOKEN=test ruby examples/echo_bot.rb
+test: OK
+
+$ SLACK_BOT_TOKEN=xoxb-... SLACK_APP_TOKEN=xapp-... ruby examples/echo_bot.rb
 I, [20XX-XX-XXTXX:XX:XX.XXXXXX #XXXXXX]  INFO -- : [ws:2560] websocket open
 I, [20XX-XX-XXTXX:XX:XX.XXXXXX #XXXXXX]  INFO -- : [ws:2600] websocket open
 I, [20XX-XX-XXTXX:XX:XX.XXXXXX #XXXXXX]  INFO -- : [ws:2640] websocket open
@@ -85,7 +113,7 @@ I, [20XX-XX-XXTXX:XX:XX.XXXXXX #XXXXXX]  INFO -- : [ws:2680] events_api app_ment
 
 Connects to Slack with Socket Mode.
 
-* `token`: Slack's Bot User OAuth token (starting with `xoxb-`)
+* `token`: Slack's Bot User OAuth token (starting with `xoxb-`), or `"test"` to build a test-mode bot (see below)
 * `app_token`: Slack's App-Level token (starting with `xapp-`)
 * `logger`: A Logger instance (optional)
 * block: Handles events received from Slack
@@ -129,3 +157,42 @@ end
 
 This method allows you to manage the main loop yourself.
 If you don't need it, you can just use `SlackSocketModeBot#run`.
+
+## Test mode
+
+Passing `token: "test"` (`SlackSocketModeBot.new(token: "test")`) puts the bot in test mode.
+In this mode, the bot never connects to Slack.
+Instead of opening a socket, you feed it events and stub the Web API yourself.
+So you can test your handler offline.
+
+See `examples/test_echo_bot.rb` for complete examples.
+
+### `SlackSocketModeBot#test_mode?`
+
+Returns whether the bot is in test mode, i.e. whether it was built with `token: "test"`.
+
+### `SlackSocketModeBot#test_mode`
+
+Returns the bot's `SlackSocketModeBot::TestMode` instance in test mode, or `nil` otherwise.
+All of the methods below are called on it (e.g. `bot.test_mode.simulate_envelope(...)`).
+
+### `SlackSocketModeBot::TestMode#stub_web_api(method, &block)`
+
+Stubs a Web API method's response.
+`bot.call(method, data)` then runs the block instead of making a real HTTP request.
+
+An unstubbed call returns `{ ok: true }`.
+When `$VERBOSE` is set, it also prints a warning.
+
+### `SlackSocketModeBot::TestMode#simulate_envelope(envelope)`
+
+Delivers an envelope to the bot as if it had arrived over the socket from Slack.
+You can use it to run and test your event handler synchronously.
+
+`envelope` is a Hash (string or symbol keys) shaped like the JSON Slack sends.
+`:envelope_id` is filled in automatically if omitted.
+
+### `SlackSocketModeBot::TestMode#reset`
+
+Clears all registered stubs and the event-deduplication state.
+Call it between test cases (for example, `setup` or `before` hooks).

data/lib/slack_socket_mode_bot/simple_web_socket.rb

@@ -1,4 +1,7 @@
 class SlackSocketModeBot::SimpleWebSocket
+  # Seconds to wait for the server's TCP close before dropping the socket ourselves.
+  CLOSE_TIMEOUT = 10
+
   def initialize(url)
     uri = URI.parse(url)
 
@@ -25,9 +28,9 @@ class SlackSocketModeBot::SimpleWebSocket
     end
 
     @version = nil
+    @close_deadline = nil # nil while open; a Time once closing
 
     @fib = Fiber.new do
-      closed = false
       begin
         handshake = WebSocket::Handshake::Client.new(url: url)
         @write_buff = handshake.to_s.dup
@@ -42,8 +45,9 @@ class SlackSocketModeBot::SimpleWebSocket
           while msg = frame.next
             case msg.type
             when :close
-              yield :close unless closed
-              closed = true
+              was_closing = closing?
+              close
+              yield :close unless was_closing
             when :ping
               send(msg.data, type: :pong)
             when :pong
@@ -57,14 +61,15 @@ class SlackSocketModeBot::SimpleWebSocket
         end
       rescue EOFError
       ensure
-        yield :close unless closed
-        @io.close
+        yield :close unless closing?
       end
     end
 
     @fib.resume
   end
 
+  def closing? = !@close_deadline.nil?
+
   def send(data, type: :text, code: nil)
     raise "not opened yet" unless @version
     frame = WebSocket::Frame::Outgoing::Client.new(version: @version, data: data, type: type, code: code)
@@ -72,22 +77,19 @@ class SlackSocketModeBot::SimpleWebSocket
   end
 
   def close(code: 1000, reason: "")
-    send(reason, type: :close, code: code) unless @io.closed?
+    return if closing? || @io.closed?
+    send(reason, type: :close, code: code)
+    @close_deadline = Time.now + CLOSE_TIMEOUT
   end
 
   def step(read_ios, write_ios)
-    wait_readable = wait_writable = false
-
-    unless @write_buff.empty?
-      len = @io.write_nonblock(@write_buff, exception: false)
-      case len
-      when :wait_readable then wait_readable = true
-      when :wait_writable then wait_writable = true
-      else
-        @write_buff.clear
-      end
+    if @close_deadline && Time.now >= @close_deadline
+      @io.close unless @io.closed?
+      return false
     end
 
+    wait_readable = wait_writable = false
+
     while true
       read_buff = @io.read_nonblock(4096, exception: false)
       case read_buff
@@ -100,6 +102,16 @@ class SlackSocketModeBot::SimpleWebSocket
       end
     end
 
+    unless @write_buff.empty?
+      len = @io.write_nonblock(@write_buff, exception: false)
+      case len
+      when :wait_readable then wait_readable = true
+      when :wait_writable then wait_writable = true
+      else
+        @write_buff.clear
+      end
+    end
+
     read_ios << @io if wait_readable
     write_ios << @io if wait_writable
     return true
@@ -109,6 +121,7 @@ class SlackSocketModeBot::SimpleWebSocket
       @fib.raise(EOFError)
     rescue FiberError
     end
-    return false
+    @io.close unless @io.closed?
+    false
   end
 end

data/lib/slack_socket_mode_bot/test_mode.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+class SlackSocketModeBot
+  # The offline test double exposed as bot.test_mode (bot built with token: "test").
+  # It drives the real dispatch without touching the network, and stubs the Web API.
+  class TestMode
+    def initialize(bot)
+      @bot = bot
+      @web_api_stubs = {}
+      @seq = 0
+    end
+
+    # Forget stubs and dedup state. Returns self.
+    def reset
+      @web_api_stubs.clear
+      @bot.instance_variable_get(:@events).clear
+      self
+    end
+
+    # Stub the Web API response for a method; the block receives the call data.
+    def stub_web_api(method, &block)
+      @web_api_stubs[method] = block
+      self
+    end
+
+    # Called in place of the real Web API request; returns the stub's value.
+    def call(method, data)
+      stub = @web_api_stubs[method]
+      return stub.call(data) if stub
+      warn "unstubbed Web API call: #{ method }" if $VERBOSE
+      { ok: true }
+    end
+
+    # Deliver an envelope as if it arrived over the socket; returns the ACK frames.
+    def simulate_envelope(envelope)
+      envelope = JSON.parse(JSON.generate(envelope), symbolize_names: true)
+      envelope[:envelope_id] ||= "test-envelope-#{ @seq += 1 }"
+      produced = []
+      @bot.send(
+        :handle_message,
+        "test",
+        JSON.generate(envelope),
+        send: ->(text) { produced << JSON.parse(text, symbolize_names: true) },
+        close: -> {},
+      )
+      produced
+    end
+  end
+end

data/lib/slack_socket_mode_bot/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class SlackSocketModeBot
-  VERSION = "0.9.2"
+  VERSION = "0.9.3"
 end

data/lib/slack_socket_mode_bot.rb

@@ -27,6 +27,9 @@ class SlackSocketModeBot
   # Max seconds to sleep on a 429 Retry-After; #call may run in the event loop.
   RETRY_AFTER_CAP = 60
 
+  # #run wakes at least this often so an empty watch set never blocks forever.
+  SELECT_TIMEOUT = 30
+
   #: (token: String, ?app_token: String, ?num_of_connections: Integer, ?debug: boolean, ?logger: Logger) { (untyped) -> untyped } -> void
   def initialize(token:, app_token: nil, num_of_connections: 4, debug: false, logger: nil, &callback)
     @token = token
@@ -36,13 +39,32 @@ class SlackSocketModeBot
     @logger = logger
     @events = {}
     @callback = callback
+    @test_mode = nil
+    if token == "test"
+      # Offline test double; #call is stubbed and dispatch is driven without connecting.
+      require_relative "slack_socket_mode_bot/test_mode"
+      @test_mode = TestMode.new(self)
+    end
+    # app_token and the handler come as a pair, else the bot hangs or crashes on the first event.
+    raise ArgumentError, "app_token is required on Socket Mode" if callback && !app_token
+    raise ArgumentError, "block is required on Socket Mode" if app_token && !callback
     # No app token: Web API calls only, no Socket Mode connections.
     @num_of_connections = app_token ? num_of_connections : 0
-    replenish_connections
+    replenish_connections unless test_mode?
+  end
+
+  # The offline test double when built with token: "test", otherwise nil.
+  attr_reader :test_mode
+
+  #: -> bool
+  def test_mode?
+    !!@test_mode
   end
 
   #: (String method, untyped data, ?token: String) -> untyped
   def call(method, data, token: @token)
+    return @test_mode.call(method, data) if @test_mode
+
     url = URI(API_BASE + method)
     body = JSON.generate(data)
     headers = {
@@ -82,10 +104,9 @@ class SlackSocketModeBot
   end
 
   private def replenish_connections
-    # Reopen from the main loop, tolerating a single failure; #step retries.
-    while @conns.size < @num_of_connections
+    while @conns.count {|ws| !ws.closing? } < @num_of_connections
       begin
-        add_connection(@callback)
+        add_connection
       rescue => e
         @logger.warn("[reconnect] failed: #{ e.message }") if @logger
         break
@@ -95,7 +116,7 @@ class SlackSocketModeBot
     raise Error, "all socket connections lost" if @num_of_connections > 0 && @conns.empty?
   end
 
-  private def add_connection(callback)
+  private def add_connection
     json = call("apps.connections.open", {}, token: @app_token)
 
     url = json[:url]
@@ -108,64 +129,69 @@ class SlackSocketModeBot
         # #step drops the dead connection; #replenish_connections reopens it.
         @logger.info("[ws:#{ ws.object_id }] websocket closed") if @logger
       when :message
-        begin
-          json = JSON.parse(data, symbolize_names: true)
-        rescue JSON::ParserError
-          # A stray non-JSON frame: skip it, don't open a spurious connection.
-          @logger.warn("[ws:#{ ws.object_id }] received a non-JSON message; ignored") if @logger
-          next
-        end
-
-        if @logger
-          @logger.debug("[ws:#{ ws.object_id }] slack message: #{ JSON.generate(json) }")
-        end
-
-        case json[:type]
-        when "hello"
-          @logger.info("[ws:#{ ws.object_id }] hello (active connections: #{ @conns.size })") if @logger
-        when "disconnect"
-          ws.close
-          @logger.info("[ws:#{ ws.object_id }] disconnect (active connections: #{ @conns.size })") if @logger
-        else
-          payload = json[:payload]
-          if @logger
-            # Log a per-type identifier; event_id/retry only apply to events_api.
-            detail =
-              case json[:type]
-              when "events_api"   then [payload.dig(:event, :type), payload[:event_id]].compact.join(" ")
-              when "slash_commands" then payload[:command]
-              else payload[:type]
-              end
-            retry_n = json[:retry_attempt].to_i
-            line = "[ws:#{ ws.object_id }] #{ json[:type] }"
-            line += " #{ detail }" if detail && !detail.empty?
-            line += " (retry ##{ retry_n })" if retry_n > 0
-            @logger.info(line)
-          end
-          # Only events_api has an event_id; dedup just those (others have none).
-          event_id = payload[:event_id]
-          expired = Time.now.to_i - 600
-          @events.reject! {|_, timestamp| timestamp < expired }
-
-          # ACK every message; only skip the handler for a duplicate, else Slack resends.
-          duplicate = event_id && @events[event_id]
-          @events[event_id] = payload[:event_time] if event_id
-
-          response = { envelope_id: json[:envelope_id] }
-          unless duplicate
-            result = callback.call(json)
-            response[:payload] = result if json[:accepts_response_payload]
-          end
-          ws.send(JSON.generate(response))
-        end
+        # `send` delivers a reply frame; `close` tears the socket down.
+        handle_message(ws.object_id, data, send: ->(text) { ws.send(text) }, close: -> { ws.close })
       end
     end
 
     @conns << ws
   end
 
+  # Dispatch one frame (log, dedup, run callback, ACK); send/close are injected so tests can drive it.
+  private def handle_message(id, data, send:, close:)
+    begin
+      json = JSON.parse(data, symbolize_names: true)
+    rescue JSON::ParserError
+      # A stray non-JSON frame: skip it, don't open a spurious connection.
+      @logger.warn("[ws:#{ id }] received a non-JSON message; ignored") if @logger
+      return
+    end
+
+    @logger.debug("[ws:#{ id }] slack message: #{ JSON.generate(json) }") if @logger
+
+    case json[:type]
+    when "hello"
+      @logger.info("[ws:#{ id }] hello (active connections: #{ @conns.size })") if @logger
+    when "disconnect"
+      close.call
+      @logger.info("[ws:#{ id }] disconnect (active connections: #{ @conns.size })") if @logger
+    else
+      payload = json[:payload]
+      if @logger
+        # Log a per-type identifier; event_id/retry only apply to events_api.
+        detail =
+          case json[:type]
+          when "events_api"   then [payload.dig(:event, :type), payload[:event_id]].compact.join(" ")
+          when "slash_commands" then payload[:command]
+          else payload[:type]
+          end
+        retry_n = json[:retry_attempt].to_i
+        line = "[ws:#{ id }] #{ json[:type] }"
+        line += " #{ detail }" if detail && !detail.empty?
+        line += " (retry ##{ retry_n })" if retry_n > 0
+        @logger.info(line)
+      end
+      # Only events_api has an event_id; dedup just those (others have none).
+      event_id = payload[:event_id]
+      expired = Time.now.to_i - 600
+      @events.reject! {|_, timestamp| timestamp < expired }
+
+      # ACK every message; only skip the handler for a duplicate, else Slack resends.
+      duplicate = event_id && @events[event_id]
+      @events[event_id] = payload[:event_time] if event_id
+
+      response = { envelope_id: json[:envelope_id] }
+      unless duplicate
+        result = @callback.call(json)
+        response[:payload] = result if json[:accepts_response_payload]
+      end
+      send.call(JSON.generate(response))
+    end
+  end
+
   #: -> [Array[IO], Array[IO]]
   def step
+    raise Error, "not supported in test mode" if @test_mode
     read_ios, write_ios = [], []
     @conns.select! {|ws| ws.step(read_ios, write_ios) }
     replenish_connections
@@ -176,7 +202,7 @@ class SlackSocketModeBot
   def run
     while true
       read_ios, write_ios = step
-      IO.select(read_ios, write_ios)
+      IO.select(read_ios, write_ios, nil, SELECT_TIMEOUT)
     end
   end
 end

data/sig/{slack_socket_mode.rbs → slack_socket_mode_bot.rbs}

@@ -11,4 +11,16 @@ class SlackSocketModeBot
   def step: () -> [ Array[IO], Array[IO] ]
 
   def run: () -> void
+
+  def test_mode?: () -> bool
+
+  def test_mode: () -> TestMode?
+
+  class TestMode
+    def stub_web_api: (String method) { (untyped) -> untyped } -> self
+
+    def simulate_envelope: (untyped envelope) -> Array[untyped]
+
+    def reset: () -> self
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: slack_socket_mode_bot
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 0.9.3
 platform: ruby
 authors:
   - Yusuke Endoh
@@ -36,8 +36,9 @@ files:
   - Rakefile
   - lib/slack_socket_mode_bot.rb
   - lib/slack_socket_mode_bot/simple_web_socket.rb
+  - lib/slack_socket_mode_bot/test_mode.rb
   - lib/slack_socket_mode_bot/version.rb
-  - sig/slack_socket_mode.rbs
+  - sig/slack_socket_mode_bot.rbs
 homepage: "https://github.com/mame/slack_socket_mode_bot"
 licenses:
   - MIT