rita 0.1.0 → 5.0.0.alpha.1

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "rack"
+
+module Lita
+  module RSpec
+    # A namespace to hold all of Lita's RSpec matchers.
+    module Matchers
+      # RSpec matchers for HTTP routes.
+      # @since 4.0.0
+      module HTTPRouteMatcher
+        extend ::RSpec::Matchers::DSL
+
+        matcher :route_http do |http_method, path|
+          match do
+            env = Rack::MockRequest.env_for(path, method: http_method)
+
+            matching_routes = robot.app.recognize(env)
+
+            if defined?(@method_name)
+              matching_routes.include?(@method_name)
+            else
+              !matching_routes.empty?
+            end
+          end
+
+          chain :to do |method_name|
+            @method_name = method_name
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lita/rspec.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+begin
+  require "rspec"
+  require "rspec/expectations"
+  require "rspec/mocks"
+rescue LoadError
+  abort I18n.t("lita.rspec.full_suite_required")
+end
+
+major, *_unused = RSpec::Core::Version::STRING.split(/\./)
+abort I18n.t("lita.rspec.version_3_required") if major.to_i < 3
+
+require_relative "../lita"
+require_relative "rspec/handler"
+
+module Lita
+  # Extras for +RSpec+ that facilitate the testing of Lita code.
+  module RSpec
+    class << self
+      # Causes all interaction with Redis to use a test-specific namespace.
+      # Clears Redis before each example. Stubs the logger to prevent log
+      # messages from cluttering test output. Clears Lita's global
+      # configuration.
+      # @param base [Object] The class including the module.
+      # @return [void]
+      def included(base)
+        base.class_eval do
+          let(:registry) { Registry.new }
+
+          before do
+            logger = double("Logger").as_null_object
+            allow(Lita).to receive(:logger).and_return(logger)
+            keys = Lita.redis.keys("*")
+            Lita.redis.del(keys) unless keys.empty?
+          end
+        end
+      end
+    end
+  end
+end
+
+Lita.test_mode = true
+
+RSpec.configure do |config|
+  config.include Lita::RSpec, lita: true
+  config.include Lita::RSpec::Handler, lita_handler: true
+end

data/lib/lita/source.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "i18n"
+
+require_relative "room"
+
+module Lita
+  # A wrapper object representing the source of an incoming message (either the
+  # user who sent it, the room they sent it from, or both). If a room is set,
+  # the message is from a group chat room. If no room is set, the message is
+  # assumed to be a private message, though Source objects can be explicitly
+  # marked as private messages. Source objects are also used as "target" objects
+  # when sending an outgoing message or performing another operation on a user
+  # or a room.
+  class Source
+    # A flag indicating that a message was sent to the robot privately.
+    # @return [Boolean] The boolean flag.
+    attr_reader :private_message
+    alias private_message? private_message
+
+    # The room the message came from or should be sent to, as a string.
+    # @return [String, NilClass] A string uniquely identifying the room.
+    attr_reader :room
+
+    # The room the message came from or should be sent to, as a {Room} object.
+    # @return [Room, NilClass] The room.
+    # @since 4.4.0
+    attr_reader :room_object
+
+    # The user who sent the message or should receive the outgoing message.
+    # @return [User, NilClass] The user.
+    attr_reader :user
+
+    # @param user [User] The user who sent the message or should receive
+    #   the outgoing message.
+    # @param room [Room, String] A string or {Room} uniquely identifying the room
+    #   the user sent the message from, or the room where a reply should go. The format of this
+    #   string (or the ID of the {Room} object) will differ depending on the chat service.
+    # @param private_message [Boolean] A flag indicating whether or not the
+    #   message was sent privately.
+    def initialize(user: nil, room: nil, private_message: false)
+      @user = user
+
+      case room
+      when String
+        @room = room
+        @room_object = load_with_metadata(room)
+      when Room
+        @room = room.id
+        @room_object = room
+      end
+
+      @private_message = private_message
+
+      raise ArgumentError, I18n.t("lita.source.user_or_room_required") if user.nil? && room.nil?
+
+      @private_message = true if room.nil?
+    end
+
+    # Destructively marks the source as a private message, meaning an incoming
+    # message was sent to the robot privately, or an outgoing message should be
+    # sent to a user privately.
+    # @return [void]
+    def private_message!
+      @private_message = true
+    end
+
+    private
+
+    def load_with_metadata(room_id)
+      Room.find_by_id(room_id) || Room.new(room_id)
+    end
+  end
+
+  # An alias for {Source}. Since source objects are used for both incoming and outgoing messages, it
+  # might be helpful to think of an outgoing messsage's source as a "target" rather than a source.
+  #
+  # @see Source
+  # @since 5.0.0
+  Target = Source
+end

data/lib/lita/store.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Lita
+  # A simple, in-memory, thread-safe key-value store.
+  # @since 5.0.0
+  class Store
+    # @param internal_store [Hash] A hash-like object to use internally to store data.
+    def initialize(internal_store = {})
+      @store = internal_store
+      @lock = Mutex.new
+    end
+
+    # Get a key from the store.
+    def [](key)
+      @lock.synchronize { @store[key] }
+    end
+
+    # Set a key to the given value.
+    def []=(key, value)
+      @lock.synchronize { @store[key] = value }
+    end
+  end
+end

data/lib/lita/target.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "source"

data/lib/lita/template.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "erb"
+require "set"
+
+module Lita
+  # A simple wrapper around ERB to render text from files or strings.
+  # @since 4.2.0
+  class Template
+    # A clean room object to use as the binding for ERB rendering.
+    # @api private
+    class TemplateEvaluationContext
+      # Returns the evaluation context's binding.
+      # @return [Binding] The binding.
+      def __get_binding
+        binding
+      end
+    end
+
+    class << self
+      # Initializes a new Template with the contents of the file at the given path.
+      # @param path [String] The path to the file to use as the template content.
+      # @return Template
+      def from_file(path)
+        new(File.read(path).chomp)
+      end
+    end
+
+    # @param source [String] A string to use as the template's content.
+    def initialize(source)
+      @erb = ERB.new(source, trim_mode: "<>")
+      self.helpers = Set.new
+    end
+
+    # Add a module of helpers methods to be added to the template evalutation context.
+    # @param helper [Module] The module to extend onto the template evalutation context.
+    # @return [void]
+    # @since 4.5.0
+    def add_helper(helper)
+      helpers << helper
+    end
+
+    # Render the template with the provided variables.
+    # @param variables [Hash] A collection of variables for interpolation. Each key-value pair will
+    #   make the value available inside the template as an instance variable with the key as its
+    #   name.
+    def render(variables = {})
+      erb.result(context_binding(variables))
+    end
+
+    private
+
+    attr_accessor :helpers
+
+    # Create an empty object to use as the ERB context and set any provided variables in it.
+    def context_binding(variables)
+      context = TemplateEvaluationContext.new
+
+      helpers.each { |helper| context.extend(helper) }
+
+      variables.each do |k, v|
+        context.instance_variable_set("@#{k}", v)
+      end
+
+      context.__get_binding
+    end
+
+    # The underlying ERB object.
+    attr_reader :erb
+  end
+end

data/lib/lita/template_resolver.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "i18n"
+
+require_relative "errors"
+
+module Lita
+  # Finds the file path of the most appropriate template for the given adapter.
+  # @api private
+  # @since 4.2.0
+  class TemplateResolver
+    # @param template_root [String] The directory to search for templates.
+    # @param template_name [String] The name of the template to search for.
+    # @param adapter_name [String, Symbol] The name of the current adapter.
+    def initialize(template_root, template_name, adapter_name)
+      @template_root = template_root
+      @template_name = template_name
+      @adapter_name = adapter_name
+    end
+
+    # Returns the adapter-specific template, falling back to a generic template.
+    # @return [String] The path of the template to use.
+    # @raise [MissingTemplateError] If no templates with the given name exist.
+    def resolve
+      return adapter_template if File.exist?(adapter_template)
+      return generic_template if File.exist?(generic_template)
+
+      raise MissingTemplateError, I18n.t("lita.template.missing_template", path: generic_template)
+    end
+
+    private
+
+    # The directory to search for templates.
+    attr_reader :template_root
+
+    # The name of the template to search for.
+    attr_reader :template_name
+
+    # The name of the current adapter.
+    attr_reader :adapter_name
+
+    # Path to the adapter-specific template.
+    def adapter_template
+      @adapter_template ||= File.join(template_root, "#{template_name}.#{adapter_name}.erb")
+    end
+
+    # Path to the generic template.
+    def generic_template
+      @generic_template ||= File.join(template_root, "#{template_name}.erb")
+    end
+  end
+end

data/lib/lita/timer.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Lita
+  # A timer that executes a block after a certain number of seconds, either once or repeatedly.
+  # @since 3.0.0
+  class Timer
+    # @param interval [Integer] The number of seconds to wait before calling the block.
+    # @param recurring [Boolean] If true, the timer will fire repeatedly until stopped.
+    # @yieldparam timer [Timer] The current {Timer} instance.
+    def initialize(interval: 0, recurring: false, &block)
+      @interval = interval
+      @recurring = recurring
+      @running = false
+      @block = block
+    end
+
+    # Starts running the timer.
+    def start
+      @running = true
+      run
+    end
+
+    # Stops the timer, preventing any further invocations of the block until started again.
+    def stop
+      @running = false
+    end
+
+    private
+
+    # Is this a recurring timer?
+    def recurring?
+      @recurring
+    end
+
+    # Sleep for the given interval, call the block, then run again if it's a recurring timer.
+    def run
+      loop do
+        sleep @interval
+        @block.call(self) if running? && @block
+        break unless running? && recurring?
+      end
+    end
+
+    # Is the timer currently running?
+    def running?
+      @running
+    end
+  end
+end

data/lib/lita/user.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "redis-namespace"
+
+require_relative "util"
+
+module Lita
+  # A user in the chat service. Persisted in Redis.
+  class User
+    class << self
+      # The +Redis::Namespace+ for user persistence.
+      # @return [Redis::Namespace] The Redis connection.
+      def redis
+        @redis ||= Redis::Namespace.new("users", redis: Lita.redis)
+      end
+
+      # Creates a new user with the given ID, or merges and saves supplied
+      # metadata to an existing user with the given ID.
+      # @param id [Integer, String] A unique identifier for the user.
+      # @param metadata [Hash] An optional hash of metadata about the user.
+      # @option metadata [String] name (id) The display name of the user.
+      # @return [User] The user.
+      def create(id, metadata = {})
+        existing_user = find_by_id(id)
+        metadata = Util.stringify_keys(metadata)
+        metadata = existing_user.metadata.merge(metadata) if existing_user
+        user = new(id, metadata)
+        user.save
+        user
+      end
+
+      # Finds a user by ID.
+      # @param id [Integer, String] The user's unique ID.
+      # @return [User, nil] The user or +nil+ if no such user is known.
+      def find_by_id(id)
+        metadata = redis.hgetall("id:#{id}")
+        new(id, metadata) if metadata.key?("name")
+      end
+
+      # Finds a user by mention name.
+      # @param mention_name [String] The user's mention name.
+      # @return [User, nil] The user or +nil+ if no such user is known.
+      # @since 3.0.0
+      def find_by_mention_name(mention_name)
+        id = redis.get("mention_name:#{mention_name}")
+        find_by_id(id) if id
+      end
+
+      # Finds a user by display name.
+      # @param name [String] The user's name.
+      # @return [User, nil] The user or +nil+ if no such user is known.
+      def find_by_name(name)
+        id = redis.get("name:#{name}")
+        find_by_id(id) if id
+      end
+
+      # Attempts to find a user with a name starting with the provided string.
+      # @param name [String] The first characters in the user's name.
+      # @return [User, nil] The user, or +nil+ if zero or greater than 1 matches were found.
+      # @since 3.0.0
+      def find_by_partial_name(name)
+        keys = redis.keys("name:#{name}*")
+
+        if keys.length == 1
+          id = redis.get(keys.first)
+          find_by_id(id)
+        end
+      end
+
+      # Finds a user by ID, mention name, name, or partial name.
+      # @param identifier [String] The user's ID, name, partial name, or mention name.
+      # @return [User, nil] The user or +nil+ if no users were found.
+      # @since 3.0.0
+      def fuzzy_find(identifier)
+        find_by_id(identifier) || find_by_mention_name(identifier) ||
+          find_by_name(identifier) || find_by_partial_name(identifier)
+      end
+    end
+
+    # The user's unique ID.
+    # @return [String] The user's ID.
+    attr_reader :id
+
+    # A hash of arbitrary metadata about the user.
+    # @return [Hash] The user's metadata.
+    attr_reader :metadata
+
+    # The user's name as displayed in the chat.
+    # @return [String] The user's name.
+    attr_reader :name
+
+    # @param id [Integer, String] The user's unique ID.
+    # @param metadata [Hash] Arbitrary user metadata.
+    # @option metadata [String] name (id) The user's display name.
+    def initialize(id, metadata = {})
+      @id = id.to_s
+      @metadata = Util.stringify_keys(metadata)
+      @name = @metadata["name"] || @id
+      ensure_name_metadata_set
+    end
+
+    # The name used to "mention" the user in a group chat.
+    # @return [String] The user's mention name.
+    # @since 3.1.0
+    def mention_name
+      metadata["mention_name"] || name
+    end
+
+    # Saves the user record to Redis, overwriting any previous data for the
+    # current ID and user name.
+    # @return [void]
+    def save
+      mention_name = metadata[:mention_name] || metadata["mention_name"]
+
+      current_keys = metadata.keys
+      redis_keys = redis.hkeys("id:#{id}")
+      delete_keys = (redis_keys - current_keys)
+
+      redis.pipelined do
+        redis.hdel("id:#{id}", *delete_keys) if delete_keys.any?
+        redis.hmset("id:#{id}", *metadata.to_a.flatten)
+        redis.set("name:#{name}", id)
+        redis.set("mention_name:#{mention_name}", id) if mention_name
+      end
+    end
+
+    # Compares the user against another user object to determine equality. Users
+    # are considered equal if they have the same ID and name.
+    # @param other (User) The user to compare against.
+    # @return [Boolean] True if users are equal, false otherwise.
+    def ==(other)
+      other.respond_to?(:id) && id == other.id && other.respond_to?(:name) && name == other.name
+    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 ^ name.hash
+    end
+
+    private
+
+    # Ensure the user's metadata contains their 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
+      username = metadata.delete("name")
+      metadata["name"] = username || id
+    end
+
+    # The Redis connection for user persistence.
+    def redis
+      self.class.redis
+    end
+  end
+end

data/lib/lita/util.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Lita
+  # Handy utilities used by other Lita classes.
+  # @api private
+  module Util
+    class << self
+      # Returns a hash with any symbol keys converted to strings.
+      # @param hash [Hash] The hash to convert.
+      # @return [Hash] The converted hash.
+      def stringify_keys(hash)
+        result = {}
+        hash.each_key { |key| result[key.to_s] = hash[key] }
+        result
+      end
+
+      # Transforms a camel-cased string into a snaked-cased string. Taken from +ActiveSupport.+
+      # @param camel_cased_word [String] The word to transform.
+      # @return [String] The transformed word.
+      def underscore(camel_cased_word)
+        word = camel_cased_word.to_s.dup
+        word.gsub!("::", "/")
+        word.gsub!(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+        word.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
+        word.tr!("-", "_")
+        word.downcase!
+        word
+      end
+    end
+  end
+end

data/lib/lita/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Lita
+  # The current version of Lita.
+  VERSION = "5.0.0.alpha.1"
+end