rita 0.1.0 → 5.0.0.alpha.2

data/lib/lita/handlers/authorization.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Lita
+  # A namespace to hold all subclasses of {Handler}.
+  module Handlers
+    # Provides a chat interface for administering authorization groups.
+    class Authorization
+      extend Handler::ChatRouter
+
+      route(
+        /^auth\s+add/,
+        :add,
+        command: true,
+        restrict_to: :admins,
+        help: { t("help.add_key") => t("help.add_value") }
+      )
+      route(
+        /^auth\s+remove/,
+        :remove,
+        command: true,
+        restrict_to: :admins,
+        help: { t("help.remove_key") => t("help.remove_value") }
+      )
+      route(/^auth\s+list/, :list, command: true, restrict_to: :admins, help: {
+        t("help.list_key") => t("help.list_value")
+      })
+
+      # Adds a user to an authorization group.
+      # @param response [Response] The response object.
+      # @return [void]
+      def add(response)
+        toggle_membership(response, :add_user_to_group, "user_added", "user_already_in")
+      end
+
+      # Removes a user from an authorization group.
+      # @param response [Response] The response object.
+      # @return [void]
+      def remove(response)
+        toggle_membership(response, :remove_user_from_group, "user_removed", "user_not_in")
+      end
+
+      # Lists all authorization groups (or only the specified group) and the
+      # names of their members.
+      # @param response [Response] The response object.
+      # @return [void]
+      def list(response)
+        requested_group = response.args[1]
+        output = get_groups_list(response.args[1])
+        if output.empty?
+          response.reply(empty_state_for_list(requested_group))
+        else
+          response.reply(output.join("\n"))
+        end
+      end
+
+      private
+
+      def empty_state_for_list(requested_group)
+        if requested_group
+          t("empty_state_group", group: requested_group)
+        else
+          t("empty_state")
+        end
+      end
+
+      def get_groups_list(requested_group)
+        groups_with_users = robot.auth.groups_with_users
+        if requested_group
+          requested_group = requested_group.downcase.strip.to_sym
+          groups_with_users.select! { |group, _| group == requested_group }
+        end
+        groups_with_users.map do |group, users|
+          user_names = users.map(&:name).join(", ")
+          "#{group}: #{user_names}"
+        end
+      end
+
+      def toggle_membership(response, method_name, success_key, failure_key)
+        return unless valid_message?(response)
+
+        if robot.auth.public_send(method_name, response.user, @user, @group)
+          response.reply t(success_key, user: @user.name, group: @group)
+        else
+          response.reply t(failure_key, user: @user.name, group: @group)
+        end
+      end
+
+      def valid_group?(response, identifier)
+        unless identifier && @group
+          response.reply "#{t("format")}: #{robot.name} auth add USER GROUP"
+          return false
+        end
+
+        if @group.downcase.strip == "admins"
+          response.reply t("admin_management")
+          return false
+        end
+
+        true
+      end
+
+      # Validates that incoming messages have the right format and a valid user.
+      # Also assigns the user and group to instance variables for the main
+      # methods to use later.
+      def valid_message?(response)
+        _command, identifier, @group = response.args
+
+        return unless valid_group?(response, identifier)
+
+        return unless valid_user?(response, identifier)
+
+        true
+      end
+
+      def valid_user?(response, identifier)
+        @user = User.fuzzy_find(identifier)
+
+        if @user
+          true
+        else
+          response.reply t("no_user_found", identifier: identifier)
+          false
+        end
+      end
+    end
+
+    Lita.register_handler(Authorization)
+  end
+end

data/lib/lita/handlers/help.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Lita
+  # A namespace to hold all subclasses of {Handler}.
+  module Handlers
+    # Provides online help about Lita commands for users.
+    class Help
+      extend Handler::ChatRouter
+
+      route(/^help\s*(?<query>.+)?/i, :help, command: true, help: {
+        "help"                   => t("help.help_value"),
+        t("help.help_query_key") => t("help.help_query_value")
+      })
+
+      # Outputs help information about Lita commands.
+      # @param response [Response] The response object.
+      # @return [void]
+      def help(response)
+        query = response.match_data["query"]
+
+        if query.nil?
+          return response.reply_privately(
+            "#{t("info", address: address)}\n\n#{list_handlers.join("\n")}"
+          )
+        end
+
+        handlers = matching_handlers(query)
+        handlers_to_messages = map_handlers_to_messages(response, handlers)
+        messages = matching_messages(response, query, handlers_to_messages)
+        response.reply_privately(format_reply(handlers_to_messages, messages, query))
+      end
+
+      private
+
+      # Checks if the user is authorized to at least one of the given groups.
+      def authorized?(user, required_groups)
+        required_groups.nil? || required_groups.any? do |group|
+          robot.auth.user_in_group?(user, group)
+        end
+      end
+
+      # Creates an alphabetically-sorted array containing the names of all
+      # installed handlers.
+      def list_handlers
+        robot.handlers.flat_map do |handler|
+          handler.namespace if handler.respond_to?(:routes)
+        end.compact.uniq.sort
+      end
+
+      # Creates an array of handlers matching the given query.
+      def matching_handlers(query)
+        name = query.downcase.strip
+
+        return [] unless list_handlers.include?(name)
+
+        robot.handlers.select { |handler| handler.namespace == name }
+      end
+
+      # Creates a hash of handler namespaces and their associated help messages.
+      def map_handlers_to_messages(response, handlers)
+        handlers_to_messages = {}
+        handlers.each do |handler|
+          messages = if handler.respond_to?(:routes)
+            handler.routes.map do |route|
+              route.help.map do |command, description|
+                help_command(response, route, command, description)
+              end
+            end.flatten
+          else
+            []
+          end
+
+          (handlers_to_messages[handler.namespace] ||= []).push(*messages)
+        end
+
+        handlers_to_messages
+      end
+
+      # Creates an array of help messages for all registered routes.
+      def all_help_messages(response)
+        robot.handlers.map do |handler|
+          next unless handler.respond_to?(:routes)
+
+          handler.routes.map do |route|
+            route.help.map do |command, description|
+              help_command(response, route, command, description)
+            end
+          end
+        end.flatten.compact
+      end
+
+      # Creates an array consisting of all help messages that match the given
+      # query.
+      def all_matching_messages(response, query)
+        filter_messages(all_help_messages(response), query)
+      end
+
+      # Removes matching help messages that are already present in the
+      # comprehensive array of help messages defined by the requested
+      # handler(s).
+      def dedup_messages(handlers_to_messages, messages)
+        all_handler_messages = handlers_to_messages.values.flatten
+        messages.reject { |m| all_handler_messages.include?(m) }
+      end
+
+      # Creates an array of help messages matching the given query, minus
+      # duplicates.
+      def matching_messages(response, query, handlers_to_messages)
+        dedup_messages(handlers_to_messages, all_matching_messages(response, query))
+      end
+
+      # Filters help messages matching a query.
+      def filter_messages(messages, query)
+        messages.select do |line|
+          /(?:@?#{Regexp.escape(address)})?#{Regexp.escape(query)}/i.match?(line)
+        end
+      end
+
+      # Formats a block of text associating a handler namespace with the help
+      # messages it defines.
+      def format_handler_messages(handler, messages)
+        unless messages.empty?
+          "#{t("handler_contains", handler: handler)}:\n\n" + messages.join("\n")
+        end
+      end
+
+      # Formats a block of text for message patterns or descriptions that directly match the user's
+      # query.
+      def format_messages(messages, query)
+        if messages.empty?
+          messages
+        else
+          ["#{t("pattern_or_description_contains", query: query)}:\n"] + messages
+        end
+      end
+
+      # Formats the message to be sent in response to a help command.
+      def format_reply(handlers_to_messages, messages, query)
+        return t("no_help_found") if handlers_to_messages.empty? && messages.empty?
+
+        handler_messages = handlers_to_messages.keys.map do |handler|
+          format_handler_messages(handler, handlers_to_messages[handler])
+        end.compact
+        separator = handler_messages.empty? || messages.empty? ? "" : "\n\n"
+        [handler_messages, format_messages(messages, query)].map do |m|
+          m.join("\n")
+        end.join(separator)
+      end
+
+      # Formats an individual command's help message.
+      def help_command(response, route, command, description)
+        command = "#{address}#{command}" if route.command?
+        message = "#{command} - #{description}"
+        message << t("unauthorized") unless authorized?(response.user, route.required_groups)
+        message
+      end
+
+      # The way the bot should be addressed in order to trigger a command.
+      def address
+        robot.config.robot.alias || "#{name}: "
+      end
+
+      # Fallback in case no alias is defined.
+      def name
+        robot.config.robot.mention_name || robot.config.robot.name
+      end
+    end
+
+    Lita.register_handler(Help)
+  end
+end

data/lib/lita/handlers/info.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Lita
+  # A namespace to hold all subclasses of {Handler}.
+  module Handlers
+    # Provides information about the currently running robot.
+    class Info
+      extend Handler::ChatRouter
+      extend Handler::HTTPRouter
+
+      route(/^info$/i, :chat, command: true, help: {
+        "info" => t("help.info_value")
+      })
+
+      http.get "/lita/info", :web
+
+      # Replies with the current version of Lita, the current version of Redis,
+      # and Redis memory usage.
+      # @param response [Response] The response object.
+      # @return [void]
+      # @since 3.0.0
+      def chat(response)
+        response.reply(
+          %(Lita #{Lita::VERSION} - https://www.lita.io/),
+          %(Redis #{redis_version} - Memory used: #{redis_memory_usage})
+        )
+      end
+
+      # Returns JSON with basic information about the robot.
+      # @param _request [Rack::Request] The HTTP request.
+      # @param response [Rack::Response] The HTTP response.
+      # @return [void]
+      def web(_request, response)
+        response.headers["Content-Type"] = "application/json"
+        json = JSON.dump(
+          adapter: robot.config.robot.adapter,
+          lita_version: Lita::VERSION,
+          redis_memory_usage: redis_memory_usage,
+          redis_version: redis_version,
+          robot_mention_name: robot.mention_name,
+          robot_name: robot.name
+        )
+        response.write(json)
+      end
+
+      # A hash of information about Redis.
+      def redis_info
+        @redis_info ||= Lita.redis.redis.info
+      end
+
+      # The current version of Redis.
+      def redis_version
+        redis_info["redis_version"]
+      end
+
+      # The amount of memory Redis is using.
+      def redis_memory_usage
+        redis_info["used_memory_human"]
+      end
+    end
+
+    Lita.register_handler(Info)
+  end
+end

data/lib/lita/handlers/room.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Lita
+  # A namespace to hold all subclasses of {Handler}.
+  module Handlers
+    # Allows administrators to make Lita join and part from rooms.
+    # @since 3.0.0
+    class Room
+      extend Handler::ChatRouter
+
+      route(/^join\s+(.+)$/i, :join, command: true, restrict_to: :admins, help: {
+        t("help.join_key") => t("help.join_value")
+      })
+
+      route(/^part\s+(.+)$/i, :part, command: true, restrict_to: :admins, help: {
+        t("help.part_key") => t("help.part_value")
+      })
+
+      # Joins the room with the specified ID.
+      # @param response [Response] The response object.
+      # @return [void]
+      def join(response)
+        robot.join(response.args[0])
+      end
+
+      # Parts from the room with the specified ID.
+      # @param response [Response] The response object.
+      # @return [void]
+      def part(response)
+        robot.part(response.args[0])
+      end
+    end
+
+    Lita.register_handler(Room)
+  end
+end

data/lib/lita/handlers/users.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Lita
+  module Handlers
+    # Provides information on Lita users.
+    # @since 4.1.0
+    class Users
+      extend Handler::ChatRouter
+
+      route(/^users\s+find\s+(.+)/i, :find, command: true, help: {
+        t("help.find_key") => t("help.find_value")
+      })
+
+      # Outputs the name, ID, and mention name of a user matching the search query.
+      # @param response [Response] The response object.
+      # @return [void]
+      def find(response)
+        user = User.fuzzy_find(response.args[1])
+
+        if user
+          response.reply(formatted_user(user))
+        else
+          response.reply(t("find_empty_state"))
+        end
+      end
+
+      private
+
+      # Extract and label the relevant user information.
+      def formatted_user(user)
+        "#{user.name} (ID: #{user.id}, Mention name: #{user.mention_name})"
+      end
+    end
+
+    Lita.register_handler(Users)
+  end
+end

data/lib/lita/http_callback.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "rack"
+
+module Lita
+  # A wrapper around a handler's HTTP route callbacks that sets up the request and response.
+  # @api private
+  # @since 4.0.0
+  class HTTPCallback
+    # @param handler_class [Handler] The handler defining the callback.
+    # @param callback [Proc] The callback.
+    def initialize(handler_class, callback)
+      @handler_class = handler_class
+      @callback = callback
+    end
+
+    # Call the Rack endpoint with a standard environment hash.
+    def call(env)
+      request = Rack::Request.new(env)
+      response = Rack::Response.new
+
+      if request.head?
+        response.status = 204
+      else
+        begin
+          handler = @handler_class.new(env["lita.robot"])
+
+          @callback.call(handler, request, response)
+        rescue StandardError => e
+          robot = env["lita.robot"]
+          error_handler = robot.config.robot.error_handler
+
+          if error_handler.arity == 2
+            error_handler.call(e, rack_env: env, robot: robot)
+          else
+            error_handler.call(e)
+          end
+
+          raise
+        end
+      end
+
+      response.finish
+    end
+  end
+end

data/lib/lita/http_route.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "http_router"
+
+require_relative "callback"
+require_relative "http_callback"
+
+module Lita
+  # Handlers use this class to define HTTP routes for the built-in web
+  # server.
+  class HTTPRoute
+    # An +HttpRouter::Route+ class used for dispatch.
+    # @since 3.0.0
+    ExtendedRoute = Class.new(HttpRouter::Route) do
+      include HttpRouter::RouteHelper
+      include HttpRouter::GenerationHelper
+    end
+
+    # The handler registering the route.
+    # @return [Handler] The handler.
+    attr_reader :handler_class
+
+    # @param handler_class [Handler] The handler registering the route.
+    def initialize(handler_class)
+      @handler_class = handler_class
+    end
+
+    class << self
+      private
+
+      # @!macro define_http_method
+      #   @overload $1(path, method_name, options = {})
+      #     Defines a new route with the "$1" HTTP method.
+      #     @param path [String] The URL path component that will trigger the route.
+      #     @param method_name [Symbol, String] The name of the instance method in
+      #       the handler to call for the route.
+      #     @param options [Hash] Various options for controlling the behavior of the route.
+      #     @return [void]
+      #   @overload $1(path, options = {})
+      #     Defines a new route with the "$1" HTTP method.
+      #     @param path [String] The URL path component that will trigger the route.
+      #     @param options [Hash] Various options for controlling the behavior of the route.
+      #     @yield The body of the route's callback.
+      #     @return [void]
+      #     @since 4.0.0
+      def define_http_method(http_method)
+        define_method(http_method) do |path, method_name = nil, options = {}, &block|
+          register_route(http_method.to_s.upcase, path, Callback.new(method_name || block), options)
+        end
+      end
+    end
+
+    define_http_method :head
+    define_http_method :get
+    define_http_method :post
+    define_http_method :put
+    define_http_method :patch
+    define_http_method :delete
+    define_http_method :options
+    define_http_method :link
+    define_http_method :unlink
+
+    private
+
+    # Adds a new HTTP route for the handler.
+    def register_route(http_method, path, callback, options)
+      route = new_route(http_method, path, callback, options)
+      route.to(HTTPCallback.new(handler_class, callback))
+      handler_class.http_routes << route
+    end
+
+    # Creates and configures a new HTTP route.
+    def new_route(http_method, path, callback, options)
+      route = ExtendedRoute.new
+      route.path = path
+      route.name = callback.method_name
+      route.add_match_with(options)
+      route.add_request_method(http_method)
+      route.add_request_method("HEAD") if http_method == "GET"
+      route
+    end
+  end
+end

data/lib/lita/logger.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "logger"
+
+require_relative "default_configuration"
+
+module Lita
+  # Creates a Logger with the proper configuration.
+  # @api private
+  module Logger
+    class << self
+      # Creates a new {::Logger} outputting to standard error with the given
+      # severity level and a custom format.
+      # @param level [Symbol, String] The name of the log level to use.
+      # @param formatter [Proc] A proc to produce a custom log message format.
+      # @param io [String, IO] Where to write the logs. When this value is a +String+, logs will be
+      #   written to the named file. When this value is an +IO+, logs will be written to the +IO+.
+      # @return [::Logger] The {::Logger} object.
+      def get_logger(level, formatter: DefaultConfiguration::DEFAULT_LOG_FORMATTER, io: $stderr)
+        logger = ::Logger.new(io)
+        logger.progname = "lita"
+        logger.level = get_level_constant(level)
+        logger.formatter = formatter if formatter
+        logger
+      end
+
+      private
+
+      # Gets the Logger constant for the given severity level.
+      def get_level_constant(level)
+        if level
+          begin
+            ::Logger.const_get(level.to_s.upcase)
+          rescue NameError
+            ::Logger::INFO
+          end
+        else
+          ::Logger::INFO
+        end
+      end
+    end
+  end
+end