lita 3.3.1 → 4.0.0.rc1

data/lib/lita/handler/event_router.rb

@@ -0,0 +1,77 @@
+module Lita
+  class Handler
+    # A handler mixin that provides the methods necessary for handling events.
+    # @since 4.0.0
+    module EventRouter
+      # Includes common handler methods in any class that includes {EventRouter}.
+      def self.extended(klass)
+        klass.send(:include, Common)
+      end
+
+      # @overload on(event_name, method_name)
+      #   Registers an event subscription. When an event is triggered with
+      #   {#trigger}, a new instance of the handler will be created and the
+      #   instance method name supplied to {#on} will be invoked with a payload
+      #   (a hash of arbitrary keys and values).
+      #   @param event_name [String, Symbol] The name of the event to subscribe to.
+      #   @param method_name [String, Symbol] The name of the instance method on
+      #     the handler that should be invoked when the event is triggered.
+      #   @return [void]
+      # @overload on(event_name, callable)
+      #   Registers an event subscription. When an event is triggered with
+      #   {#trigger}, a new instance of the handler will be created and the
+      #   callable object supplied to {#on} will be evaluated within the context of the new
+      #   handler instance, and passed a payload (a hash of arbitrary keys and values).
+      #   @param event_name [String, Symbol] The name of the event to subscribe to.
+      #   @param callable [#call] A callable object to serve as the event callback.
+      #   @return [void]
+      #   @since 4.0.0
+      # @overload on(event_name)
+      #   Registers an event subscription. When an event is triggered with
+      #   {#trigger}, a new instance of the handler will be created and the
+      #   block supplied to {#on} will be evaluated within the context of the new
+      #   handler instance, and passed a payload (a hash of arbitrary keys and values).
+      #   @param event_name [String, Symbol] The name of the event to subscribe to.
+      #   @yield The body of the event callback.
+      #   @return [void]
+      #   @since 4.0.0
+      def on(event_name, method_name_or_callable = nil)
+        event_subscriptions[normalize_event(event_name)] << Callback.new(
+          method_name_or_callable || (proc if block_given?)
+        )
+      end
+
+      # Returns an array of all callbacks registered for the named event.
+      # @param event_name [String, Symbol] The name of the event to return callbacks for.
+      # @return [Array] The array of callbacks.
+      # @since 4.0.0
+      def event_subscriptions_for(event_name)
+        event_subscriptions[normalize_event(event_name)]
+      end
+
+      # Triggers an event, invoking methods previously registered with {#on} and
+      # passing them a payload hash with any arbitrary data.
+      # @param robot [Lita::Robot] The currently running robot instance.
+      # @param event_name [String, Symbol], The name of the event to trigger.
+      # @param payload [Hash] An optional hash of arbitrary data.
+      # @return [Boolean] Whether or not the event triggered any callbacks.
+      def trigger(robot, event_name, payload = {})
+        event_subscriptions_for(event_name).any? do |callback|
+          callback.call(new(robot), payload)
+        end
+      end
+
+      private
+
+      # A hash of arrays used to store event subscriptions registered with {#on}.
+      def event_subscriptions
+        @event_subscriptions ||= Hash.new { |h, k| h[k] = [] }
+      end
+
+      # Normalize the event name, ignoring casing and spaces.
+      def normalize_event(event_name)
+        event_name.to_s.downcase.strip.to_sym
+      end
+    end
+  end
+end

data/lib/lita/handler/http_router.rb

@@ -0,0 +1,26 @@
+module Lita
+  class Handler
+    # A handler mixin that provides the methods necessary for handling incoming HTTP requests.
+    # @since 4.0.0
+    module HTTPRouter
+      # Includes common handler methods in any class that includes {HTTPRouter}.
+      def self.extended(klass)
+        klass.send(:include, Common)
+      end
+
+      # Creates a new {Lita::HTTPRoute} which is used to define an HTTP route
+      # for the built-in web server.
+      # @see Lita::HTTPRoute
+      # @return [Lita::HTTPRoute] The new {Lita::HTTPRoute}.
+      def http
+        HTTPRoute.new(self)
+      end
+
+      # An array of all HTTP routes defined for the handler.
+      # @return [Array<Lita::HTTPRoute>] The array of routes.
+      def http_routes
+        @http_routes ||= []
+      end
+    end
+  end
+end

data/lib/lita/handlers/authorization.rb

@@ -25,29 +25,14 @@ module Lita
       # @param response [Lita::Response] The response object.
       # @return [void]
       def add(response)
-        return unless valid_message?(response)
-
-        if Lita::Authorization.add_user_to_group(response.user, @user, @group)
-          response.reply t("user_added", user: @user.name, group: @group)
-        else
-          response.reply t("user_already_in", user: @user.name, group: @group)
-        end
+        toggle_membership(response, :add_user_to_group, "user_added", "user_already_in")
       end
 
       # Removes a user from an authorization group.
       # @param response [Lita::Response] The response object.
       # @return [void]
       def remove(response)
-        return unless valid_message?(response)
-
-        if Lita::Authorization.remove_user_from_group(response.user, @user, @group)
-          response.reply t("user_removed",
-            user: @user.name,
-            group: @group
-          )
-        else
-          response.reply t("user_not_in", user: @user.name, group: @group)
-        end
+        toggle_membership(response, :remove_user_from_group, "user_removed", "user_not_in")
       end
 
       # Lists all authorization groups (or only the specified group) and the
@@ -75,7 +60,7 @@ module Lita
       end
 
       def get_groups_list(requested_group)
-        groups_with_users = Lita::Authorization.groups_with_users
+        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 }
@@ -86,6 +71,16 @@ module Lita
         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"

data/lib/lita/handlers/deprecation_check.rb

@@ -0,0 +1,24 @@
+module Lita
+  module Handlers
+    # Warns about any handlers using deprecated features.
+    # @since 4.0.0
+    class DeprecationCheck
+      extend Lita::Handler::EventRouter
+
+      on :loaded, :check_handlers_for_default_config
+
+      # Warns about handlers using the old +default_config+ method.
+      def check_handlers_for_default_config(_payload)
+        robot.registry.handlers.each do |handler|
+          if handler.respond_to?(:default_config)
+            Lita.logger.warn(
+              I18n.t("lita.config.handler_default_config_deprecated", name: handler.namespace)
+            )
+          end
+        end
+      end
+    end
+
+    Lita.register_handler(DeprecationCheck)
+  end
+end

data/lib/lita/handlers/help.rb

@@ -22,13 +22,15 @@ module Lita
       # 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|
-          Lita::Authorization.user_in_group?(user, group)
+          robot.auth.user_in_group?(user, group)
         end
       end
 
       # Creates an array of help info for all registered routes.
       def build_help(response)
-        Lita.handlers.map do |handler|
+        robot.handlers.map do |handler|
+          next unless handler.respond_to?(:routes)
+
           handler.routes.map do |route|
             route.help.map do |command, description|
               if authorized?(response.user, route.required_groups)
@@ -58,7 +60,7 @@ module Lita
 
       # The way the bot should be addressed in order to trigger a command.
       def name
-        Lita.config.robot.mention_name || Lita.config.robot.name
+        robot.config.robot.mention_name || robot.config.robot.name
       end
     end
 

data/lib/lita/handlers/info.rb

@@ -22,13 +22,13 @@ module Lita
       end
 
       # Returns JSON with basic information about the robot.
-      # @param request [Rack::Request] The HTTP request.
+      # @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 = MultiJson.dump(
-          adapter: Lita.config.robot.adapter,
+          adapter: robot.config.robot.adapter,
           lita_version: Lita::VERSION,
           redis_memory_usage: redis_memory_usage,
           redis_version: redis_version,

data/lib/lita/http_callback.rb

@@ -0,0 +1,29 @@
+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 [Lita::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
+        handler = @handler_class.new(env["lita.robot"])
+
+        @callback.call(handler, request, response)
+      end
+
+      response.finish
+    end
+  end
+end

data/lib/lita/http_route.rb

@@ -1,3 +1,17 @@
+# Primary class from the +http_router+ gem.
+# @todo Remove this monkey patch as soon as a gem is released with this pull request merged:
+#   https://github.com/joshbuddy/http_router/pull/40
+class HttpRouter
+  # An individual HTTP route.
+  class Route
+    # Sets a name for the route. Monkey patched due to a bug.
+    def name=(name)
+      @name = name
+      router.named_routes[name] << self if router
+    end
+  end
+end
+
 module Lita
   # Handlers use this class to define HTTP routes for the built-in web
   # server.
@@ -22,16 +36,23 @@ module Lita
       private
 
       # @!macro define_http_method
-      #   @method $1(path, method_name)
-      #   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.
-      #   @return [void]
+      #   @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, options = {}|
-          create_route(http_method.to_s.upcase, path, method_name, options)
+        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
@@ -48,28 +69,22 @@ module Lita
 
     private
 
-    # Creates a new HTTP route.
-    def create_route(http_method, path, method_name, options)
+    # 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.to do |env|
-        request = Rack::Request.new(env)
-        response = Rack::Response.new
-
-        if request.head?
-          response.status = 204
-        else
-          handler_class.new(env["lita.robot"]).public_send(method_name, request, response)
-        end
-
-        response.finish
-      end
-
-      handler_class.http_routes << route
+      route
     end
   end
 end

data/lib/lita/namespace.rb

@@ -0,0 +1,23 @@
+module Lita
+  # A mixin for setting and getting a plugin's namespace.
+  # @since 4.0.0
+  module Namespace
+    # Gets (and optionally sets) the namespace for a plugin. The namespace is generated from the
+    # class's name by default.
+    # @param value [String] If provided, sets the namespace of the plugin to the value.
+    # @return [String] The namespace.
+    # @raise [RuntimeError] If the plugin is an anonymous class, does not define +self.name+, and
+    #   has not set a namespace manually.
+    def namespace(value = nil)
+      @namespace = value.to_s if value
+
+      string_name = defined?(@namespace) ? @namespace : name
+
+      if string_name
+        Util.underscore(string_name.split("::").last)
+      else
+        raise I18n.t("lita.plugin.name_required")
+      end
+    end
+  end
+end

data/lib/lita/rack_app.rb

@@ -1,5 +1,5 @@
 module Lita
-  # A +Rack+ application to serve routes registered by handlers.
+  # A +Rack+ application to serve HTTP routes registered by handlers.
   class RackApp
     # The currently running robot.
     # @return [Lita::Robot] The robot.
@@ -9,6 +9,16 @@ module Lita
     # @return [HttpRouter] The router.
     attr_reader :router
 
+    # Constructs a {RackApp} inside a +Rack::Builder+, including any configured middleware.
+    # @param robot [Lita::Robot] The currently running robot.
+    # @return [Lita::RackApp, Class] The Rack application.
+    def self.build(robot)
+      builder = Rack::Builder.new
+      builder.run(new(robot))
+      robot.config.http.middleware.each { |middleware| builder.use(middleware) }
+      builder.to_app
+    end
+
     # @param robot [Lita::Robot] The currently running robot.
     def initialize(robot)
       @robot = robot
@@ -24,13 +34,30 @@ module Lita
       router.call(env)
     end
 
+    # Finds the first route that matches the request environment, if any. Does not trigger the
+    # route.
+    # @param env [Hash] A Rack environment.
+    # @return [Array] An array of the name of the first matching route.
+    # @since 4.0.0
+    def recognize(env)
+      env["lita.robot"] = robot
+      recognized_routes_for(env).map { |match| match.route.name }
+    end
+
     private
 
     # Registers routes in the router for each handler's defined routes.
     def compile
-      Lita.handlers.each do |handler|
+      robot.handlers.each do |handler|
+        next unless handler.respond_to?(:http_routes)
+
         handler.http_routes.each { |route| router.add_route(route) }
       end
     end
+
+    # Returns an array containing the first recongnized route, if any.
+    def recognized_routes_for(env)
+      Array(router.recognize(env).first)
+    end
   end
 end

data/lib/lita/registry.rb

@@ -0,0 +1,133 @@
+module Lita
+  # An object to hold various types of data including configuration and plugins.
+  # @since 4.0.0
+  class Registry
+    # Allows a registry to be added to another object.
+    module Mixins
+      # The primary configuration object. Provides user settings for the robot.
+      # @return [Object] The configuration object.
+      def config
+        @config ||= DefaultConfiguration.new(self).finalize
+      end
+
+      # Yields the configuration object. Called by the user in a +lita_config.rb+ file.
+      # @yieldparam [Object] config The configuration object.
+      # @return [void]
+      def configure
+        yield config
+      end
+
+      # A registry of adapters.
+      # @return [Hash] A map of adapter keys to adapter classes.
+      def adapters
+        @adapters ||= {}
+      end
+
+      # A registry of handlers.
+      # @return [Set] The set of handlers.
+      def handlers
+        @handlers ||= Set.new
+      end
+
+      # A registry of hook handler objects.
+      # @return [Hash] A hash mapping hook names to sets of objects that handle them.
+      # @since 3.2.0
+      def hooks
+        @hooks ||= Hash.new { |h, k| h[k] = Set.new }
+      end
+
+      # @overload register_adapter(key, adapter)
+      #   Adds an adapter to the registry under the provided key.
+      #   @param key [String, Symbol] The key that identifies the adapter.
+      #   @param adapter [Class] The adapter class.
+      #   @return [void]
+      # @overload register_adapter(key)
+      #   Adds an adapter to the registry under the provided key.
+      #   @param key [String, Symbol] The key that identifies the adapter.
+      #   @yield The body of the adapter class.
+      #   @return [void]
+      #   @since 4.0.0
+      def register_adapter(key, adapter = nil)
+        adapter = Builder.new(key, &proc).build_adapter if block_given?
+
+        unless adapter.is_a?(Class)
+          raise ArgumentError, I18n.t("lita.core.register_adapter.block_or_class_required")
+        end
+
+        adapters[key.to_sym] = adapter
+      end
+
+      # @overload register_handler(handler)
+      #   Adds a handler to the registry.
+      #   @param handler [Lita::Handler] The handler class.
+      #   @return [void]
+      # @overload register_handler(key)
+      #   Adds a handler to the registry.
+      #   @param key [String] The namespace of the handler.
+      #   @yield The body of the handler class.
+      #   @return [void]
+      #   @since 4.0.0
+      def register_handler(handler_or_key)
+        if block_given?
+          handler = Builder.new(handler_or_key, &proc).build_handler
+        else
+          handler = handler_or_key
+
+          unless handler.is_a?(Class)
+            raise ArgumentError, I18n.t("lita.core.register_handler.block_or_class_required")
+          end
+        end
+
+        handlers << handler
+      end
+
+      # Adds a hook handler object to the registry for the given hook.
+      # @return [void]
+      # @since 3.2.0
+      def register_hook(name, hook)
+        hooks[name.to_s.downcase.strip.to_sym] << hook
+      end
+
+      # Clears the configuration object and the adapter, handler, and hook registries.
+      # @return [void]
+      # @since 3.2.0
+      def reset
+        reset_adapters
+        reset_config
+        reset_handlers
+        reset_hooks
+      end
+
+      # Resets the adapter registry, removing all registered adapters.
+      # @return [void]
+      # @since 3.2.0
+      def reset_adapters
+        @adapters = nil
+      end
+
+      # Resets the configuration object. The next call to {#config}
+      # will create a fresh config object.
+      # @return [void]
+      def reset_config
+        @config = nil
+      end
+      alias_method :clear_config, :reset_config
+
+      # Resets the handler registry, removing all registered handlers.
+      # @return [void]
+      # @since 3.2.0
+      def reset_handlers
+        @handlers = nil
+      end
+
+      # Resets the hooks registry, removing all registered hook handlers.
+      # @return [void]
+      # @since 3.2.0
+      def reset_hooks
+        @hooks = nil
+      end
+    end
+
+    include Mixins
+  end
+end