rita 0.1.0 → 5.0.0.alpha.1

data/lib/lita/robot.rb

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+require "forwardable"
+require "i18n"
+
+require "puma"
+
+require_relative "authorization"
+require_relative "rack_app"
+require_relative "room"
+require_relative "store"
+
+module Lita
+  # The main object representing a running instance of Lita. Provides a high
+  # level API for the underlying adapter. Dispatches incoming messages to
+  # registered handlers. Can send outgoing chat messages and set the topic
+  # of chat rooms.
+  class Robot
+    extend Forwardable
+
+    # A +Rack+ application used for the built-in web server.
+    # @return [Rack::Builder] The +Rack+ app.
+    attr_reader :app
+
+    # The {Authorization} object for the currently running robot.
+    # @return [Authorization] The authorization object.
+    # @since 4.0.0
+    attr_reader :auth
+
+    # The name the robot will look for in incoming messages to determine if it's
+    # being addressed.
+    # @return [String] The mention name.
+    attr_accessor :mention_name
+
+    # An alias the robot will look for in incoming messages to determine if it's
+    # being addressed.
+    # @return [String, Nil] The alias, if one was set.
+    attr_accessor :alias
+
+    # The name of the robot as it will appear in the chat.
+    # @return [String] The robot's name.
+    attr_accessor :name
+
+    # The {Registry} for the currently running robot.
+    # @return [Registry] The registry.
+    # @since 4.0.0
+    attr_reader :registry
+
+    # The {Store} for handlers to persist data between instances.
+    # @return [Store] The store.
+    # @since 5.0.0
+    attr_reader :store
+
+    def_delegators :registry, :config, :adapters, :handlers, :hooks, :redis
+
+    # @!method chat_service
+    #   @see Adapter#chat_service
+    #   @since 4.6.0
+    # @!method mention_format(name)
+    #   @see Adapter#mention_format
+    #   @since 4.4.0
+    # @!method roster(room)
+    #   @see Adapter#roster
+    #   @since 4.4.1
+    # @!method run_concurrently
+    #   @see Adapter#run_concurrently
+    #   @since 5.0.0
+    def_delegators :adapter, :chat_service, :mention_format, :roster, :run_concurrently
+
+    # @param registry [Registry] The registry for the robot's configuration and plugins.
+    def initialize(registry = Lita)
+      @registry = registry
+      @name = config.robot.name
+      @mention_name = config.robot.mention_name || @name
+      @alias = config.robot.alias
+      @store = Store.new(Hash.new { |h, k| h[k] = Store.new })
+      @app = RackApp.build(self)
+      @auth = Authorization.new(self)
+      handlers.each do |handler|
+        handler.after_config_block&.call(config.handlers.public_send(handler.namespace))
+      end
+      trigger(:loaded, room_ids: persisted_rooms)
+    end
+
+    # The global logger. A convenience for +Lita.logger+.
+    # @return [::Logger] The logger.
+    def logger
+      Lita.logger
+    end
+
+    # The primary entry point from the adapter for an incoming message.
+    # Dispatches the message to all registered handlers.
+    # @param message [Message] The incoming message.
+    # @return [void]
+    def receive(message)
+      trigger(:message_received, message: message)
+
+      matched = handlers.map do |handler|
+        next unless handler.respond_to?(:dispatch)
+
+        handler.dispatch(self, message)
+      end.any?
+
+      trigger(:unhandled_message, message: message) unless matched
+    end
+
+    # Starts the robot, booting the web server and delegating to the adapter to
+    # connect to the chat service.
+    # @return [void]
+    def run
+      run_app
+      adapter.run
+    rescue Interrupt
+      shut_down
+    end
+
+    # Makes the robot join a room with the specified ID.
+    # @param room [Room, String] The room to join, as a {Room} object or a string identifier.
+    # @return [void]
+    # @since 3.0.0
+    def join(room)
+      room_object = find_room(room)
+
+      if room_object
+        redis.sadd("persisted_rooms", room_object.id)
+        adapter.join(room_object.id)
+      else
+        adapter.join(room)
+      end
+    end
+
+    # Makes the robot part from the room with the specified ID.
+    # @param room [Room, String] The room to leave, as a {Room} object or a string identifier.
+    # @return [void]
+    # @since 3.0.0
+    def part(room)
+      room_object = find_room(room)
+
+      if room_object
+        redis.srem("persisted_rooms", room_object.id)
+        adapter.part(room_object.id)
+      else
+        adapter.part(room)
+      end
+    end
+
+    # A list of room IDs the robot should join on boot.
+    # @return [Array<String>] An array of room IDs.
+    # @since 4.4.2
+    def persisted_rooms
+      redis.smembers("persisted_rooms").sort
+    end
+
+    # Sends one or more messages to a user or room.
+    # @param target [Source] The user or room to send to. If the Source
+    #   has a room, it will choose the room. Otherwise, it will send to the
+    #   user.
+    # @param strings [String, Array<String>] One or more strings to send.
+    # @return [void]
+    def send_messages(target, *strings)
+      adapter.send_messages(target, strings.flatten)
+    end
+    alias send_message send_messages
+
+    # Sends one or more messages to a user or room. If sending to a room,
+    # prefixes each message with the user's mention name.
+    # @param target [Source] The user or room to send to. If the Source
+    #   has a room, it will choose the room. Otherwise, it will send to the
+    #   user.
+    # @param strings [String, Array<String>] One or more strings to send.
+    # @return [void]
+    # @since 3.1.0
+    def send_messages_with_mention(target, *strings)
+      return send_messages(target, *strings) if target.private_message?
+
+      mention_name = target.user.mention_name
+      prefixed_strings = strings.map do |s|
+        "#{adapter.mention_format(mention_name).strip} #{s}"
+      end
+
+      send_messages(target, *prefixed_strings)
+    end
+    alias send_message_with_mention send_messages_with_mention
+
+    # Sets the topic for a chat room.
+    # @param target [Source] A source object specifying the room.
+    # @param topic [String] The new topic message to set.
+    # @return [void]
+    def set_topic(target, topic)
+      adapter.set_topic(target, topic)
+    end
+
+    # Gracefully shuts the robot down, stopping the web server and delegating
+    # to the adapter to perform any shut down tasks necessary for the chat
+    # service.
+    # @return [void]
+    def shut_down
+      trigger(:shut_down_started)
+      @server&.stop(true)
+      @server_thread&.join
+      adapter.shut_down
+      trigger(:shut_down_complete)
+    end
+
+    # Triggers an event, instructing all registered handlers to invoke any
+    # methods subscribed to the event, and passing them a payload hash of
+    # arbitrary data.
+    # @param event_name [String, Symbol] The name of the event to trigger.
+    # @param payload [Hash] An optional hash of arbitrary data.
+    # @return [void]
+    def trigger(event_name, payload = {})
+      handlers.each do |handler|
+        next unless handler.respond_to?(:trigger)
+
+        handler.trigger(self, event_name, payload)
+      end
+    end
+
+    private
+
+    # Loads and caches the adapter on first access.
+    def adapter
+      @adapter ||= load_adapter
+    end
+
+    # Ensure the argument is a Room.
+    def find_room(room_or_identifier)
+      case room_or_identifier
+      when Room
+        room_or_identifier
+      else
+        Room.fuzzy_find(room_or_identifier)
+      end
+    end
+
+    # Loads the selected adapter.
+    def load_adapter
+      adapter_name = config.robot.adapter
+      adapter_class = adapters[adapter_name.to_sym]
+
+      unless adapter_class
+        logger.fatal I18n.t("lita.robot.unknown_adapter", adapter: adapter_name)
+        exit(false)
+      end
+
+      adapter_class.new(self)
+    end
+
+    # Starts the web server.
+    def run_app
+      http_config = config.http
+
+      @server_thread = Thread.new do
+        @server = Puma::Server.new(app)
+        begin
+          @server.add_tcp_listener(http_config.host, http_config.port.to_i)
+        rescue Errno::EADDRINUSE, Errno::EACCES => e
+          logger.fatal I18n.t(
+            "lita.http.exception",
+            message: e.message,
+            backtrace: e.backtrace.join("\n")
+          )
+          exit(false)
+        end
+        @server.min_threads = http_config.min_threads
+        @server.max_threads = http_config.max_threads
+        @server.run
+      end
+
+      @server_thread.abort_on_exception = true
+    end
+  end
+end

data/lib/lita/room.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "redis-namespace"
+
+require_relative "util"
+
+module Lita
+  # A room in the chat service. Persisted in Redis.
+  # @since 4.4.0
+  class Room
+    class << self
+      # Creates a new room with the given ID, or merges and saves supplied
+      # metadata to a room with the given ID.
+      # @param id [Integer, String] A unique identifier for the room.
+      # @param metadata [Hash] An optional hash of metadata about the room.
+      # @option metadata [String] name (id) The display name of the room.
+      # @return [Room] The room.
+      def create_or_update(id, metadata = {})
+        existing_room = find_by_id(id)
+        metadata = Util.stringify_keys(metadata)
+        metadata = existing_room.metadata.merge(metadata) if existing_room
+        room = new(id, metadata)
+        room.save
+        room
+      end
+
+      # Finds a room by ID.
+      # @param id [Integer, String] The room's unique ID.
+      # @return [Room, nil] The room or +nil+ if no such room is known.
+      def find_by_id(id)
+        metadata = redis.hgetall("id:#{id}")
+        new(id, metadata) if metadata.key?("name")
+      end
+
+      # Finds a room by display name.
+      # @param name [String] The room's name.
+      # @return [Room, nil] The room or +nil+ if no such room is known.
+      def find_by_name(name)
+        id = redis.get("name:#{name}")
+        find_by_id(id) if id
+      end
+
+      # Finds a room by ID or name
+      # @param identifier [Integer, String] The room's ID or name.
+      # @return [Room, nil] The room or +nil+ if no room was found.
+      def fuzzy_find(identifier)
+        find_by_id(identifier) || find_by_name(identifier)
+      end
+
+      # The +Redis::Namespace+ for room persistence.
+      # @return [Redis::Namespace] The Redis connection.
+      def redis
+        @redis ||= Redis::Namespace.new("rooms", redis: Lita.redis)
+      end
+    end
+
+    # The room's unique ID.
+    # @return [String] The room's ID.
+    attr_reader :id
+
+    # A hash of arbitrary metadata about the room.
+    # @return [Hash] The room's metadata.
+    attr_reader :metadata
+
+    # The room's name as displayed in a standard user interface.
+    # @return [String] The room's name.
+    attr_reader :name
+
+    # @param id [Integer, String] The room's unique ID.
+    # @param metadata [Hash] Arbitrary room metadata.
+    # @option metadata [String] name (id) The room's display name.
+    def initialize(id, metadata = {})
+      @id = id.to_s
+      @metadata = Util.stringify_keys(metadata)
+      @name = @metadata["name"] || @id
+    end
+
+    # Compares the room against another room object to determine equality. Rooms
+    # are considered equal if they have the same ID.
+    # @param other [Room] The room to compare against.
+    # @return [Boolean] True if rooms are equal, false otherwise.
+    def ==(other)
+      other.respond_to?(:id) && id == other.id
+    end
+    alias eql? ==
+
+    # Generates a +Fixnum+ hash value for this user object. Implemented to support equality.
+    # @return [Fixnum] The hash value.
+    # @see Object#hash
+    def hash
+      id.hash
+    end
+
+    # Saves the room record to Redis, overwriting any previous data for the current ID.
+    # @return [void]
+    def save
+      ensure_name_metadata_set
+
+      redis.pipelined do
+        redis.hmset("id:#{id}", *metadata.to_a.flatten)
+        redis.set("name:#{name}", id)
+      end
+    end
+
+    private
+
+    # Ensure the room's metadata contains its name, to ensure their Redis hash contains at least
+    # one value. It's not possible to store an empty hash key in Redis.
+    def ensure_name_metadata_set
+      room_name = metadata.delete("name")
+      metadata["name"] = room_name || id
+    end
+
+    # The Redis connection for room persistence.
+    def redis
+      self.class.redis
+    end
+  end
+end

data/lib/lita/route_validator.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Lita
+  # Determines if an incoming message should trigger a route.
+  # @api private
+  class RouteValidator
+    # The handler class the route belongs to.
+    attr_reader :handler
+
+    # The incoming message.
+    attr_reader :message
+
+    # The currently running robot.
+    attr_reader :robot
+
+    # The route being checked.
+    attr_reader :route
+
+    # @param handler [Handler] The handler the route belongs to.
+    # @param route [Handler::ChatRouter::Route] The route being validated.
+    # @param message [Message] The incoming message.
+    # @param robot [Robot] The currently running robot.
+    def initialize(handler, route, message, robot)
+      @handler = handler
+      @route = route
+      @message = message
+      @robot = robot
+    end
+
+    # Returns a boolean indicating whether or not the route should be triggered.
+    # @return [Boolean] Whether or not the route should be triggered.
+    def call
+      return unless command_satisfied?(route, message)
+      return if from_self?(message, robot)
+      return unless matches_pattern?(route, message)
+
+      unless authorized?(robot, message.user, route.required_groups)
+        robot.trigger(
+          :route_authorization_failed,
+          message: message,
+          robot: robot,
+          route: route,
+        )
+        return
+      end
+      return unless passes_route_hooks?(route, message, robot)
+
+      true
+    end
+
+    private
+
+    # Message must be a command if the route requires a command
+    def command_satisfied?(route, message)
+      !route.command? || message.command?
+    end
+
+    # Messages from self should be ignored to prevent infinite loops
+    def from_self?(message, robot)
+      message.user.name == robot.name
+    end
+
+    # Message must match the pattern
+    def matches_pattern?(route, message)
+      route.pattern.match?(message.body)
+    end
+
+    # Allow custom route hooks to reject the route
+    def passes_route_hooks?(route, message, robot)
+      robot.hooks[:validate_route].all? do |hook|
+        hook.call(handler: handler, route: route, message: message, robot: robot)
+      end
+    end
+
+    # User must be in auth group if route is restricted.
+    def authorized?(robot, user, required_groups)
+      required_groups.nil? || required_groups.any? do |group|
+        robot.auth.user_in_group?(user, group)
+      end
+    end
+  end
+end

data/lib/lita/rspec/handler.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "set"
+
+require "i18n"
+require "faraday"
+
+require_relative "../adapters/test"
+require_relative "../message"
+require_relative "../rspec"
+require_relative "../robot"
+require_relative "../source"
+require_relative "../user"
+require_relative "matchers/chat_route_matcher"
+require_relative "matchers/http_route_matcher"
+require_relative "matchers/event_route_matcher"
+
+module Lita
+  module RSpec
+    # Extras for +RSpec+ to facilitate testing Lita handlers.
+    module Handler
+      include Matchers::ChatRouteMatcher
+      include Matchers::HTTPRouteMatcher
+      include Matchers::EventRouteMatcher
+
+      class << self
+        # Sets up the RSpec environment to easily test Lita handlers.
+        def included(base)
+          base.include(Lita::RSpec)
+
+          prepare_handlers(base)
+          prepare_adapter(base)
+          prepare_let_blocks(base)
+          prepare_subject(base)
+        end
+
+        private
+
+        # Register the test adapter.
+        def prepare_adapter(base)
+          base.class_eval do
+            before do
+              registry.register_adapter(:test, Lita::Adapters::Test)
+              registry.config.robot.adapter = :test
+            end
+          end
+        end
+
+        # Register the handler(s) under test.
+        def prepare_handlers(base)
+          base.class_eval do
+            before do
+              handlers = Set.new(
+                [described_class] + Array(base.metadata[:additional_lita_handlers])
+              )
+
+              handlers.each do |handler|
+                registry.register_handler(handler)
+              end
+            end
+          end
+        end
+
+        # Create common test objects.
+        def prepare_let_blocks(base)
+          base.class_eval do
+            let(:robot) { Robot.new(registry) }
+            let(:source) { Source.new(user: user) }
+            let(:user) { User.create("1", name: "Test User") }
+          end
+        end
+
+        # Set up a working test subject.
+        def prepare_subject(base)
+          base.class_eval do
+            subject { described_class.new(robot) }
+          end
+        end
+      end
+
+      # An array of strings that have been sent by the robot during the course of a test.
+      # @return [Array<String>] The replies.
+      def replies
+        robot.chat_service.sent_messages
+      end
+
+      # Sends a message to the robot.
+      # @param body [String] The message to send.
+      # @param as [User] The user sending the message.
+      # @param from [Room] The room where the message is received from.
+      # @return [void]
+      def send_message(body, as: user, from: nil, privately: false)
+        message = Message.new(
+          robot,
+          body,
+          Source.new(user: as, room: from, private_message: privately)
+        )
+
+        robot.receive(message)
+      end
+
+      # Sends a "command" message to the robot.
+      # @param body [String] The message to send.
+      # @param as [User] The user sending the message.
+      # @param from [Room] The room where the message is received from.
+      # @return [void]
+      def send_command(body, as: user, from: nil, privately: false)
+        send_message("#{robot.mention_name}: #{body}", as: as, from: from, privately: privately)
+      end
+
+      # Returns a Faraday connection hooked up to the currently running robot's Rack app.
+      # @return [Faraday::Connection] The connection.
+      # @since 4.0.0
+      def http
+        unless Rack.const_defined?(:Test)
+          begin
+            require "rack/test"
+          rescue LoadError
+            raise LoadError, I18n.t("lita.rspec.rack_test_required")
+          end
+        end
+
+        Faraday::Connection.new { |c| c.adapter(:rack, robot.app) }
+      end
+    end
+  end
+end

data/lib/lita/rspec/matchers/chat_route_matcher.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "../../message"
+require_relative "../../route_validator"
+
+module Lita
+  module RSpec
+    module Matchers
+      # RSpec matchers for chat routes.
+      # @since 4.0.0
+      module ChatRouteMatcher
+        extend ::RSpec::Matchers::DSL
+
+        matcher :route do |message_body|
+          match do
+            message = Message.new(robot, message_body, source)
+
+            if defined?(@group) && @group.to_s.casecmp("admins").zero?
+              robot.config.robot.admins = Array(robot.config.robot.admins) + [source.user.id]
+            elsif defined?(@group)
+              robot.auth.add_user_to_group!(source.user, @group)
+            end
+
+            matching_routes = described_class.routes.select do |route|
+              RouteValidator.new(described_class, route, message, robot).call
+            end
+
+            if defined?(@method_name)
+              matching_routes.any? { |route| route.callback.method_name == @method_name }
+            else
+              !matching_routes.empty?
+            end
+          end
+
+          chain :with_authorization_for do |group|
+            @group = group
+          end
+
+          chain :to do |method_name|
+            @method_name = method_name
+          end
+        end
+
+        # Sets an expectation that the provided message routes to a command.
+        # @param message_body [String] The body of the message.
+        # @return [void]
+        def route_command(message_body)
+          route("#{robot.mention_name} #{message_body}")
+        end
+      end
+    end
+  end
+end

data/lib/lita/rspec/matchers/event_route_matcher.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Lita
+  module RSpec
+    module Matchers
+      # RSpec matchers for event routes.
+      # @since 4.0.0
+      module EventRouteMatcher
+        extend ::RSpec::Matchers::DSL
+
+        matcher :route_event do |event_name|
+          match do
+            callbacks = described_class.event_subscriptions_for(event_name)
+
+            if defined?(@method_name)
+              callbacks.any? { |callback| callback.method_name.equal?(@method_name) }
+            else
+              !callbacks.empty?
+            end
+          end
+
+          chain :to do |method_name|
+            @method_name = method_name
+          end
+        end
+      end
+    end
+  end
+end