lita 1.1.2 → 2.0.0

data/lib/lita/handlers/help.rb

@@ -1,37 +1,40 @@
 module Lita
   module Handlers
+    # Provides online help about Lita commands for users.
     class Help < Handler
-      route(/^help\s*(.+)?/, to: :help, command: true)
+      route(/^help\s*(.+)?/, :help, command: true, help: {
+        "help" => "Lists help information for terms and command the robot will respond to.",
+        "help COMMAND" => "Lists help information for terms or commands that begin with COMMAND."
+      })
 
-      def self.help
-        robot_name = Lita.config.robot.name
-
-        {
-          "#{robot_name}: help" => "Lists help information for terms and commands #{robot_name} will respond to.",
-          "#{robot_name}: help COMMAND" => "Lists help information for terms and commands starting with COMMAND."
-        }
-      end
-
-      def help(matches)
-        commands = {}
+      # Outputs help information about Lita commands.
+      # @param response [Lita::Response] The response object.
+      # @return [void]
+      def help(response)
+        output = []
 
         Lita.handlers.each do |handler|
-          commands.merge!(handler.help) if handler.respond_to?(:help)
+          handler.routes.each do |route|
+            route.help.each do |command, description|
+              command = "#{name}: #{command}" if route.command?
+              output << "#{command} - #{description}"
+            end
+          end
         end
 
-        filter = matches[0][0]
+        filter = response.matches[0][0]
         if filter
-          robot_name = Lita.config.robot.name
-          commands.select! do |key, value|
-            /^#{filter}/i === key.sub(/^\s*@?#{robot_name}[:,]?\s*/, "")
-          end
+          output.select! { |line| /(?:@?#{name}[:,]?)?#{filter}/i === line }
         end
 
-        message = commands.map do |command, description|
-          "#{command} - #{description}"
-        end.join("\n")
+        response.reply output.join("\n")
+      end
+
+      private
 
-        reply message
+      # The way the bot should be addressed in order to trigger a command.
+      def name
+        Lita.config.robot.mention_name || Lita.config.robot.name
       end
     end
 

data/lib/lita/handlers/web.rb

@@ -0,0 +1,25 @@
+module Lita
+  module Handlers
+    # Provides an HTTP route with basic information about the running robot.
+    class Web < Handler
+      http.get "/lita/info", :info
+
+      # 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 info(request, response)
+        response.headers["Content-Type"] = "application/json"
+        json = MultiJson.dump(
+          lita_version: Lita::VERSION,
+          adapter: Lita.config.robot.adapter,
+          robot_name: robot.name,
+          robot_mention_name: robot.mention_name
+        )
+        response.write(json)
+      end
+    end
+
+    Lita.register_handler(Web)
+  end
+end

data/lib/lita/http_route.rb

@@ -0,0 +1,64 @@
+module Lita
+  # Handlers use this class to define HTTP routes for the built-in web
+  # server.
+  class HTTPRoute
+    # The handler registering the route.
+    # @return [Lita::Handler] The handler.
+    attr_reader :handler_class
+
+    # The HTTP method for the route (GET, POST, etc.).
+    # @return [String] The HTTP method.
+    attr_reader :http_method
+
+    # The name of the instance method in the handler to call for the route.
+    # @return [Symbol, String] The method name.
+    attr_reader :method_name
+
+    # The URL path component that will trigger the route.
+    # @return [String] The path.
+    attr_reader :path
+
+    # @param handler_class [Lita::Handler] The handler registering the route.
+    def initialize(handler_class)
+      @handler_class = handler_class
+    end
+
+    class << self
+      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]
+      def define_http_method(http_method)
+        define_method(http_method) do |path, method_name|
+          route(http_method.to_s.upcase, path, method_name)
+        end
+      end
+    end
+
+    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
+
+    # Creates a new HTTP route.
+    def route(http_method, path, method_name)
+      @http_method = http_method
+      @path = path
+      @method_name = method_name
+
+      handler_class.http_routes << self
+    end
+  end
+end

data/lib/lita/logger.rb

@@ -0,0 +1,34 @@
+module Lita
+  # Creates a Logger with the proper configuration.
+  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.
+      # @return [::Logger] The {::Logger} object.
+      def get_logger(level)
+        logger = ::Logger.new(STDERR)
+        logger.level = get_level_constant(level)
+        logger.formatter = proc do |severity, datetime, progname, msg|
+          "[#{datetime.utc}] #{severity}: #{msg}\n"
+        end
+        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
+            return ::Logger::INFO
+          end
+        else
+          ::Logger::INFO
+        end
+      end
+    end
+  end
+end

data/lib/lita/message.rb

@@ -1,38 +1,72 @@
 module Lita
+  # Represents an incoming chat message.
   class Message
     extend Forwardable
 
-    attr_reader :body, :source
-    alias_method :message, :body
+    # The body of the message.
+    # @return [String] The message body.
+    attr_reader :body
 
-    def_delegators :@body, :scan
-    def_delegators :@source, :user
+    # The source of the message, which is a user and optional room.
+    # @return [Lita::Source] The message source.
+    attr_reader :source
 
+    # @!method user
+    # The user who sent the message.
+    # @return [Lita::User] The user.
+    # @see Lita::Source#user
+    def_delegators :source, :user
+
+    # @param robot [Lita::Robot] The currently running robot.
+    # @param body [String] The body of the message.
+    # @param source [Lita::Source] The source of the message.
     def initialize(robot, body, source)
       @robot = robot
       @body = body
       @source = source
 
-      @command = !!@body.sub!(/^\s*@?#{@robot.mention_name}[:,]?\s*/, "")
+      @command = !!@body.sub!(/^\s*@?#{@robot.mention_name}[:,]?\s*/i, "")
     end
 
+    # An array of arguments created by shellsplitting the message body, as if
+    # it were a shell command.
+    # @return [Array<String>] The array of arguments.
     def args
       begin
-        command, *args = message.shellsplit
+        command, *args = body.shellsplit
       rescue ArgumentError
         command, *args =
-          message.split(/\s+/).map(&:shellescape).join(" ").shellsplit
+          body.split(/\s+/).map(&:shellescape).join(" ").shellsplit
       end
 
       args
     end
 
+    # Marks the message as a command, meaning it was directed at the robot
+    # specifically.
+    # @return [void]
     def command!
       @command = true
     end
 
+    # A boolean representing whether or not the message was a command.
+    # @return [Boolean] +true+ if the message was a command, +false+ if not.
     def command?
       @command
     end
+
+    # An array of matches against the message body for the given {::Regexp}.
+    # @param pattern [Regexp] A pattern to match.
+    # @return [Array<String>, Array<Array<String>>] An array of matches.
+    def match(pattern)
+      body.scan(pattern)
+    end
+
+    # Replies by sending the given strings back to the source of the message.
+    # @param strings [String, Array<String>] The strings to send back.
+    # @return [void]
+    def reply(*strings)
+      @robot.send_messages(source, *strings)
+    end
   end
 end

data/lib/lita/rack_app_builder.rb

@@ -0,0 +1,110 @@
+module Lita
+  # Creates a +Rack+ application from all the routes registered by handlers.
+  class RackAppBuilder
+    # The character that separates the pieces of a URL's path component.
+    PATH_SEPARATOR = "/"
+
+    # A +Struct+ representing a route's destination handler and method name.
+    RouteMapping = Struct.new(:handler, :method_name)
+
+    # All registered paths. Used to respond to HEAD requests.
+    # @return [Array<String>] The array of paths.
+    attr_reader :all_paths
+
+    # The currently running robot.
+    # @return [Lita::Robot] The robot.
+    attr_reader :robot
+
+    # A hash mapping HTTP request methods and paths to handlers and methods.
+    # @return [Hash] The mapping.
+    attr_reader :routes
+
+    # @param robot [Lita::Robot] The currently running robot.
+    def initialize(robot)
+      @robot = robot
+      @routes = Hash.new { |h, k| h[k] = {} }
+      compile
+    end
+
+    # Creates a +Rack+ application from the compiled routes.
+    # @return [Rack::Builder] The +Rack+ application.
+    def to_app
+      app = Rack::Builder.new
+      app.run(app_proc)
+      app
+    end
+
+    private
+
+    # The proc that serves as the +Rack+ application.
+    def app_proc
+      -> (env) do
+        request = Rack::Request.new(env)
+
+        mapping = routes[request.request_method][request.path]
+
+        if mapping
+          Lita.logger.info <<-LOG.chomp
+Routing HTTP #{request.request_method} #{request.path} to \
+#{mapping.handler}##{mapping.method_name}.
+LOG
+          response = Rack::Response.new
+          instance = mapping.handler.new(robot)
+          instance.public_send(mapping.method_name, request, response)
+          response.finish
+        elsif request.head? && all_paths.include?(request.path)
+          Lita.logger.info "HTTP HEAD #{request.path} was a 204."
+          [204, {}, []]
+        else
+          Lita.logger.info <<-LOG.chomp
+HTTP #{request.request_method} #{request.path} was a 404.
+LOG
+          [404, {}, ["Route not found."]]
+        end
+      end
+    end
+
+    # Collect all registered paths. Used for responding to HEAD requests.
+    def collect_paths
+      @all_paths = routes.values.map { |hash| hash.keys.first }.uniq
+    end
+
+    # Registers routes in the route mapping for each handler's defined routes.
+    def compile
+      Lita.handlers.each do |handler|
+        handler.http_routes.each { |route| register_route(handler, route) }
+      end
+      collect_paths
+    end
+
+    # Registers a route.
+    def register_route(handler, route)
+      cleaned_path = clean_path(route.path)
+
+      if @routes[route.http_method][cleaned_path]
+        Lita.logger.fatal <<-ERR.chomp
+#{handler.name} attempted to register an HTTP route that was already \
+registered: #{route.http_method} "#{cleaned_path}"
+ERR
+        abort
+      end
+
+      Lita.logger.debug <<-LOG.chomp
+Registering HTTP route: #{route.http_method} #{cleaned_path} to \
+#{handler}##{route.method_name}.
+LOG
+      @routes[route.http_method][cleaned_path] = RouteMapping.new(
+        handler,
+        route.method_name
+      )
+    end
+
+    # Ensures that paths begin with one slash and do not end with one.
+    def clean_path(path)
+      path.strip!
+      path.chop! while path.end_with?(PATH_SEPARATOR)
+      path = path[1..-1] while path.start_with?(PATH_SEPARATOR)
+      "/#{path}"
+    end
+  end
+end

data/lib/lita/response.rb

@@ -0,0 +1,30 @@
+module Lita
+  # A wrapper object that provides the primary interface for handlers to
+  # respond to incoming chat messages.
+  class Response
+    extend Forwardable
+
+    # The incoming message.
+    # @return [Lita::Message] The message.
+    attr_accessor :message
+
+    # An array of matches from running the message against the route pattern.
+    # @return [Array<String>, Array<Array<String>>] The array of matches.
+    attr_accessor :matches
+
+    # @!method args
+    #   @see Lita::Message#args
+    # @!method reply
+    #   @see Lita::Message#reply
+    # @!method user
+    #   @see Lita::Message#user
+    def_delegators :message, :args, :reply, :user
+
+    # @param message [Lita::Message] The incoming message.
+    # @param matches [Array<String>, Array<Array<String>>] The Regexp matches.
+    def initialize(message, matches: nil)
+      self.message = message
+      self.matches = matches
+    end
+  end
+end

data/lib/lita/robot.rb

@@ -1,39 +1,79 @@
 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
-    attr_reader :name
+    # A +Rack+ application used for the built-in web server.
+    # @return [Rack::Builder] The +Rack+ app.
+    attr_reader :app
+
+    # 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
 
+    # The name of the robot as it will appear in the chat.
+    # @return [String] The robot's name.
+    attr_reader :name
+
     def initialize
       @name = Lita.config.robot.name
       @mention_name = Lita.config.robot.mention_name || @name
+      @app = RackAppBuilder.new(self).to_app
       load_adapter
     end
 
+    # The primary entry point from the adapter for an incoming message.
+    # Dispatches the message to all registered handlers.
+    # @param message [Lita::Message] The incoming message.
+    # @return [void]
     def receive(message)
       Lita.handlers.each { |handler| handler.dispatch(self, message) }
     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
 
+    # Sends one or more messages to a user or room.
+    # @param target [Lita::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_method :send_message, :send_messages
 
+    # Sets the topic for a chat room.
+    # @param target [Lita::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
+      @server.stop if @server
+      @server_thread.join if @server_thread
       @adapter.shut_down
     end
 
     private
 
+    # Loads the selected adapter.
     def load_adapter
       adapter_name = Lita.config.robot.adapter
       adapter_class = Lita.adapters[adapter_name.to_sym]
@@ -45,5 +85,20 @@ module Lita
 
       @adapter = adapter_class.new(self)
     end
+
+    # Starts the web server.
+    def run_app
+      @server_thread = Thread.new do
+        @server = Thin::Server.new(
+          app,
+          Lita.config.http.port.to_i,
+          signals: false
+        )
+        @server.silent = true unless Lita.config.http.debug
+        @server.start
+      end
+
+      @server_thread.abort_on_exception = true
+    end
   end
 end