rita 0.1.0 → 5.0.0.alpha.1

data/lib/lita/default_configuration.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require_relative "configuration_builder"
+require_relative "middleware_registry"
+
+module Lita
+  # Builds the configuration object that is stored in each {Registry}.
+  # @since 4.0.0
+  # @api private
+  class DefaultConfiguration
+    # Valid levels for Lita's logger.
+    LOG_LEVELS = %w[debug info warn error fatal].freeze
+
+    # The default log formatter.
+    #
+    # This is specified as a constant instead of inline for +config.robot.log_formatter+ so it can
+    # be used by {Lita.logger} for early logging without accessing it via the config attribute and
+    # generating the default config too early, before plugins have been registered.
+    DEFAULT_LOG_FORMATTER = lambda { |severity, datetime, _progname, msg|
+      "[#{datetime.utc}] #{severity}: #{msg}\n"
+    }
+
+    # A {Registry} to extract configuration for plugins from.
+    # @return [Registry] The registry.
+    attr_reader :registry
+
+    # The top-level {ConfigurationBuilder} attribute.
+    # @return [Configuration] The root attribute.
+    attr_reader :root
+
+    # @param registry [Registry] The registry to build a default configuration object from.
+    def initialize(registry)
+      @registry = registry
+      @root = ConfigurationBuilder.new
+
+      adapters_config
+      handlers_config
+      http_config
+      redis_config
+      robot_config
+    end
+
+    # Processes the {ConfigurationBuilder} object to return a {Configuration}.
+    # @return [Configuration] The built configuration object.
+    def build
+      root.build
+    end
+
+    private
+
+    # Builds config.adapters
+    def adapters_config
+      adapters = registry.adapters
+
+      root.config :adapters do
+        adapters.each do |key, adapter|
+          combine(key, adapter.configuration_builder)
+        end
+      end
+    end
+
+    # Builds config.handlers
+    def handlers_config
+      handlers = registry.handlers
+
+      root.config :handlers do
+        handlers.each do |handler|
+          if handler.configuration_builder.children?
+            combine(handler.namespace, handler.configuration_builder)
+          end
+        end
+      end
+    end
+
+    # Builds config.http
+    def http_config
+      root.config :http do
+        config :host, type: String, default: "0.0.0.0"
+        config :port, type: [Integer, String], default: 8080
+        config :min_threads, type: [Integer, String], default: 0
+        config :max_threads, type: [Integer, String], default: 16
+        config :middleware, type: MiddlewareRegistry, default: MiddlewareRegistry.new
+      end
+    end
+
+    # Builds config.redis
+    def redis_config
+      root.config :redis, type: Hash, default: {}
+    end
+
+    # Builds config.robot
+    def robot_config
+      root.config :robot do
+        config :name, type: String, default: "Lita"
+        config :mention_name, type: String
+        config :alias, type: String
+        config :adapter, types: [String, Symbol], default: :shell
+        config :locale, types: [String, Symbol], default: nil
+        config :default_locale, types: [String, Symbol], default: nil
+        config :redis_namespace, type: String, default: Lita.test_mode? ? "lita.test" : "lita"
+        config :log_level, types: [String, Symbol], default: :info do
+          validate do |value|
+            unless LOG_LEVELS.include?(value.to_s.downcase.strip)
+              "must be one of: #{LOG_LEVELS.join(", ")}"
+            end
+          end
+        end
+        config :log_formatter, default: DEFAULT_LOG_FORMATTER do
+          validate do |value|
+            "must respond to #call" unless value.respond_to?(:call)
+          end
+        end
+        config :admins
+        config :error_handler, default: ->(_error, _metadata) {} do
+          validate do |value|
+            "must respond to #call" unless value.respond_to?(:call)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lita/errors.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Lita
+  # The root exception class that all Lita-specific exceptions inherit from.
+  # @since 4.0.0
+  class Error < StandardError; end
+
+  # An exception raised when a custom validation is set on a configuration attribute that is
+  # violated by the default value of the attribute.
+  # @since 4.0.0
+  class ValidationError < Error; end
+
+  # An exception raised when Lita can't connect to Redis in test mode.
+  # @since 4.0.3
+  class RedisError < Error; end
+
+  # An exception raised when attempting to resolve a template that doesn't exist.
+  # @since 4.2.0
+  class MissingTemplateError < Error; end
+
+  # An exception raised when a handler attempts to render a template without having set its
+  # template root.
+  # @since 4.2.0
+  class MissingTemplateRootError < Error; end
+end

data/lib/lita/handler/chat_router.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "i18n"
+
+require_relative "../callback"
+require_relative "../response"
+require_relative "../route_validator"
+require_relative "common"
+
+module Lita
+  class Handler
+    # A handler mixin that provides the methods necessary for responding to chat messages.
+    # @since 4.0.0
+    module ChatRouter
+      # Includes common handler methods in any class that includes {ChatRouter}.
+      def self.extended(klass)
+        klass.include(Common)
+      end
+
+      # A Struct representing a chat route defined by a handler.
+      Route = Struct.new(
+        :pattern,
+        :callback,
+        :command,
+        :required_groups,
+        :help,
+        :extensions
+      )
+
+      class Route
+        alias command? command
+      end
+
+      # @overload route(pattern, method_name, **options)
+      #   Creates a chat route.
+      #   @param pattern [Regexp] A regular expression to match incoming messages against.
+      #   @param method_name [Symbol, String] The name of the instance method to trigger.
+      #   @param command [Boolean] Whether or not the message must be directed at the robot.
+      #   @param restrict_to [Array<Symbol, String>, nil] An optional list of authorization
+      #     groups the user must be in to trigger the route.
+      #   @param help [Hash] An optional map of example invocations to descriptions.
+      #   @param options [Hash] Aribtrary additional data that can be used by Lita extensions.
+      #   @return [void]
+      # @overload route(pattern, **options)
+      #   Creates a chat route.
+      #   @param pattern [Regexp] A regular expression to match incoming messages against.
+      #   @param command [Boolean] Whether or not the message must be directed at the robot.
+      #   @param restrict_to [Array<Symbol, String>, nil] An optional list of authorization
+      #     groups the user must be in to trigger the route.
+      #   @param help [Hash] An optional map of example invocations to descriptions.
+      #   @param options [Hash] Aribtrary additional data that can be used by Lita extensions.
+      #   @yield The body of the route's callback.
+      #   @return [void]
+      #   @since 4.0.0
+      def route(pattern, method_name = nil, **options, &block)
+        options = default_route_options.merge(options)
+        options[:restrict_to] = options[:restrict_to].nil? ? nil : Array(options[:restrict_to])
+        routes << Route.new(
+          pattern,
+          Callback.new(method_name || block),
+          options.delete(:command),
+          options.delete(:restrict_to),
+          options.delete(:help),
+          options
+        )
+      end
+
+      # A list of chat routes defined by the handler.
+      # @return [Array<Handler::Route>]
+      def routes
+        @routes ||= []
+      end
+
+      # The main entry point for the handler at runtime. Checks if the message
+      # matches any of the routes and invokes the route's method if it does.
+      # Called by {Robot#receive}.
+      # @param robot [Robot] The currently running robot.
+      # @param message [Message] The incoming message.
+      # @return [Boolean] Whether or not the message matched any routes.
+      def dispatch(robot, message)
+        routes.map do |route|
+          next unless route_applies?(route, message, robot)
+
+          log_dispatch(robot, route)
+
+          robot.run_concurrently { dispatch_to_route(route, robot, message) }
+
+          true
+        end.any?
+      end
+
+      # Dispatch directly to a {Route}, ignoring route conditions.
+      # @param route [Route] The route to invoke.
+      # @param robot [Robot] The currently running robot.
+      # @param message [Message] The incoming message.
+      # @return [void]
+      # @since 3.3.0
+      def dispatch_to_route(route, robot, message)
+        response = Response.new(message, route.pattern)
+        robot.hooks[:trigger_route].each { |hook| hook.call(response: response, route: route) }
+        handler = new(robot)
+        route.callback.call(handler, response)
+        robot.hooks[:post_route].each { |hook| hook.call(response: response, route: route) }
+        robot.trigger(
+          :message_dispatched,
+          handler: self,
+          route: route,
+          message: message,
+          robot: robot
+        )
+      rescue StandardError => e
+        log_error(robot, e, message: message)
+      end
+
+      private
+
+      # The default options for every chat route.
+      def default_route_options
+        {
+          command: false,
+          restrict_to: nil,
+          help: {}
+        }
+      end
+
+      # Determines whether or not an incoming messages should trigger a route.
+      def route_applies?(route, message, robot)
+        RouteValidator.new(self, route, message, robot).call
+      end
+
+      # Logs the dispatch of message.
+      def log_dispatch(robot, route)
+        robot.logger.debug I18n.t(
+          "lita.handler.dispatch",
+          handler: name,
+          method: route.callback.method_name || "(block)"
+        )
+      end
+    end
+  end
+end

data/lib/lita/handler/common.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "i18n"
+require "redis-namespace"
+
+require_relative "../configurable"
+require_relative "../configuration_builder"
+require_relative "../errors"
+require_relative "../namespace"
+require_relative "../template"
+require_relative "../template_resolver"
+require_relative "../timer"
+require_relative "../version"
+
+module Lita
+  class Handler
+    # Methods included in any class that includes at least one type of router.
+    # @since 4.0.0
+    module Common
+      # Adds common functionality to the class and initializes the handler's configuration builder.
+      def self.included(klass)
+        klass.extend(ClassMethods)
+        klass.extend(Configurable)
+        klass.extend(Namespace)
+        klass.configuration_builder = ConfigurationBuilder.new
+      end
+
+      # Common class-level methods for all handlers.
+      module ClassMethods
+        # Gets (and optionally sets) the directory where the handler's templates are stored.
+        # @param path [String] If provided, sets the template root to this value.
+        # @return [String] The template root path.
+        # @raise [MissingTemplateRootError] If accessed without setting a value first.
+        def template_root(path = nil)
+          @template_root = path if path
+
+          if defined?(@template_root)
+            @template_root
+          else
+            raise MissingTemplateRootError
+          end
+        end
+
+        # Returns the translation for a key, automatically namespaced to the handler.
+        # @param key [String] The key of the translation.
+        # @param hash [Hash] An optional hash of values to be interpolated in the string.
+        # @return [String] The translated string.
+        # @since 3.0.0
+        def translate(key, hash = {})
+          I18n.translate("lita.handlers.#{namespace}.#{key}", **hash)
+        end
+
+        alias t translate
+
+        # Logs an error raised by a plugin.
+        def log_error(robot, error, metadata = {})
+          error_handler = robot.config.robot.error_handler
+
+          if error_handler.arity == 2
+            error_handler.call(error, metadata.merge(robot: robot))
+          else
+            error_handler.call(error)
+          end
+
+          robot.logger.error I18n.t(
+            "lita.handler.exception",
+            handler: name,
+            message: error.message,
+            backtrace: error.backtrace.join("\n")
+          )
+
+          raise error if Lita.test_mode?
+        end
+      end
+
+      # A Redis::Namespace scoped to the handler.
+      # @return [Redis::Namespace]
+      attr_reader :redis
+
+      # The running {Robot} instance.
+      # @return [Robot]
+      attr_reader :robot
+
+      # @param robot [Robot] The currently running robot.
+      def initialize(robot)
+        @robot = robot
+        @redis = Redis::Namespace.new(redis_namespace, redis: robot.redis)
+      end
+
+      # Invokes the given block after the given number of seconds.
+      # @param interval [Integer] The number of seconds to wait before invoking the block.
+      # @yieldparam timer [Timer] The current {Timer} instance.
+      # @return [void]
+      # @since 3.0.0
+      def after(interval, &block)
+        robot.run_concurrently { Timer.new(interval: interval, &block).start }
+      end
+
+      # The handler's configuration object.
+      # @return [Configuration, Config] The handler's configuration object.
+      # @since 3.2.0
+      def config
+        if robot.config.handlers.respond_to?(self.class.namespace)
+          robot.config.handlers.public_send(self.class.namespace)
+        end
+      end
+
+      # Invokes the given block repeatedly, waiting the given number of seconds between each
+      # invocation.
+      # @param interval [Integer] The number of seconds to wait before each invocation of the block.
+      # @yieldparam timer [Timer] The current {Timer} instance.
+      # @return [void]
+      # @note The block should call {Timer#stop} at a terminating condition to avoid infinite
+      #   recursion.
+      # @since 3.0.0
+      def every(interval, &block)
+        robot.run_concurrently { Timer.new(interval: interval, recurring: true, &block).start }
+      end
+
+      # Creates a new +Faraday::Connection+ for making HTTP requests.
+      # @param options [Hash] A set of options passed on to Faraday.
+      # @yield [builder] A Faraday builder object for adding middleware.
+      # @return [Faraday::Connection] The new connection object.
+      def http(options = {}, &block)
+        options = default_faraday_options.merge(options)
+
+        if block
+          Faraday::Connection.new(nil, options, &block)
+        else
+          Faraday::Connection.new(nil, options)
+        end
+      end
+
+      # The +Logger+ for the currently running robot.
+      # @return [Logger] The Lita logger.
+      # @since 3.2.0
+      def log
+        robot.logger
+      end
+
+      # Render an ERB template to a string, with any provided variables made available to the
+      # template.
+      # @param template_name [String] The name of the ERB template file.
+      # @param variables [Hash] An optional hash of variables to make available within the
+      #   template. Hash keys become instance variable names with the hash values as the instance
+      #   variables' values.
+      # @return [String] The rendered template.
+      # @since 4.2.0
+      def render_template(template_name, variables = {})
+        Template.from_file(file_for_template(template_name)).render(variables)
+      end
+
+      # Renders an ERB template to a string, like {#render_template}, but also takes an array of
+      # modules with helper methods to be made available to the template.
+      # @param template_name [String] The name of the ERB template file.
+      # @param helpers [Array<Module>] An array of modules whose methods should be added to the
+      #   template evaluation context.
+      # @param variables [Hash] An optional hash of variables to make available within the
+      #   template. Hash keys become instance variable names with the hash values as the instance
+      #   variables' values.
+      # @return [String] The rendered template.
+      # @since 4.5.0
+      def render_template_with_helpers(template_name, helpers, variables = {})
+        template = Template.from_file(file_for_template(template_name))
+        helpers.each { |helper| template.add_helper(helper) }
+        template.render(variables)
+      end
+
+      # A hash-like object that can be used to persist data between instances of the current
+      # handler. Useful for storing objects that are expensive to create and that can be safely
+      # reused between instances.
+      # @return [Store] The handler's shared store.
+      # @since 5.0.0
+      def store
+        robot.store[self.class.namespace]
+      end
+
+      # @see .translate
+      def translate(*args)
+        self.class.translate(*args)
+      end
+
+      alias t translate
+
+      private
+
+      # Default options for new Faraday connections. Sets the user agent to the
+      # current version of Lita.
+      def default_faraday_options
+        { headers: { "User-Agent" => "Lita v#{VERSION}" } }
+      end
+
+      def file_for_template(template_name)
+        TemplateResolver.new(
+          self.class.template_root,
+          template_name,
+          robot.config.robot.adapter
+        ).resolve
+      end
+
+      # The handler's namespace for Redis.
+      def redis_namespace
+        "handlers:#{self.class.namespace}"
+      end
+    end
+  end
+end

data/lib/lita/handler/event_router.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative "../callback"
+require_relative "common"
+
+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.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, &block)
+        event_subscriptions[normalize_event(event_name)] << Callback.new(
+          method_name_or_callable || block
+        )
+      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 [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).map do |callback|
+          callback.call(new(robot), payload)
+        rescue StandardError => e
+          log_error(robot, e, payload: payload)
+        end.any?
+      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,31 @@
+# frozen_string_literal: true
+
+require_relative "../http_route"
+require_relative "common"
+
+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.include(Common)
+      end
+
+      # Creates a new {HTTPRoute} which is used to define an HTTP route
+      # for the built-in web server.
+      # @see HTTPRoute
+      # @return [HTTPRoute] The new {HTTPRoute}.
+      def http
+        HTTPRoute.new(self)
+      end
+
+      # An array of all HTTP routes defined for the handler.
+      # @return [Array<HTTPRoute>] The array of routes.
+      def http_routes
+        @http_routes ||= []
+      end
+    end
+  end
+end

data/lib/lita/handler.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "handler/chat_router"
+require_relative "handler/http_router"
+require_relative "handler/event_router"
+
+module Lita
+  # Base class for objects that add new behavior to Lita. {Handler} is simply a class with all
+  # types of routers mixed in.
+  class Handler
+    extend ChatRouter
+    extend HTTPRouter
+    extend EventRouter
+  end
+end