lita 2.4.0 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 04046c9229b2303b99d39582d60790888db1e611
-  data.tar.gz: 0060005dadcb7608aa33051ed9571455463c3698
+  metadata.gz: a0f46a0926eb20ff35d1597e8d7474e64984ffd4
+  data.tar.gz: 63b751e98f2e477e41b144da5c731160963d2377
 SHA512:
-  metadata.gz: 80caca833d509b65a8015de4f3e5845fc5c0c485f4b02b4d9ce70f3beb351f8cbc05b0bdbcac474be0e3248e53915e459e6f30068becbdb701bbe73ba7df295e
-  data.tar.gz: 2c5d02ce8eed3c643dd9e0ef43b0467443ea5382686d36c785d9ebbf319ed0b4583c4d92ae1bec0036d49993c28a464aaf4aa3ae6cec1f55b6005bea1e7821b6
+  metadata.gz: 2f594e6d3301112d652d22b03c3f280c2560a7a86ab6868369d6240c3816cee6500db31c9737268850be6f04257c895baf27c4f06840a727ec95f93554d93824
+  data.tar.gz: 189688873d5ed9c3c110c0114b47ce94267ea4a7ea66f0c455652363f2433e18fed60e99ae792232e329eadb08f20ea6aeb77a2cb3eef4225f7412343582ec24

data/README.md

@@ -18,6 +18,7 @@ Automate your business and have fun with your very own robot companion.
 * Easily extendable with plugins
 * Data persistence with Redis
 * Built-in web server and routing
+* Event system for behavior triggered in response to arbitrary events
 * Support for outgoing HTTP requests
 * Group-based authorization
 * Configurable logging
@@ -183,7 +184,7 @@ For more detailed examples, check out the built in shell adapter, [lita-hipchat]
 
 ## Writing a handler
 
-A handler is packaged as a RubyGem. A handler is a class that inherits from `Lita::Handler` and is registered by calling `Lita.register_handler(TheHandlerClass)`. There are two components to a handler: route definitions, and the methods that implement those routes. There are both chat routes and HTTP routes available to handlers.
+A handler is packaged as a RubyGem. A handler is a class that inherits from `Lita::Handler` and is registered by calling `Lita.register_handler(TheHandlerClass)`. There are two components to a handler: route definitions, and the methods that implement those routes. There are chat routes, HTTP routes, and event subscriptions available to handlers.
 
 To generate a starting template for a new handler gem, run `lita handler NAME`, where NAME is the name of the new gem.
 
@@ -239,6 +240,27 @@ def baz(request, response)
 end
 ```
 
+### Event subscriptions
+
+Handlers can communicate with each other or respond to arbitrary system events with the built-in pub-sub event system. Subscribe to an event by name, and provide the name of the instance method that should be invoked when the event triggers. Event callback methods are passed a payload hash with any arbitrary data the caller chooses to provide.
+
+``` ruby
+on :connected, :greet
+
+def greet(payload)
+  target = Source.new(room: payload[:room])
+  robot.send_message(target, "Hello #{payload[:room]}!")
+end
+```
+
+Trigger an event from anywhere and pass any payload data you want the subscribed handlers to receive:
+
+``` ruby
+robot.trigger(:connected, room: "#litabot")
+```
+
+Since the `trigger` method is available on `Lita::Robot`, it can be used from anywhere in the Lita runtime (both adapters and handlers).
+
 ### Handler-specific configuration
 
 If you want your handler to expose config settings to the user, use the class-level `default_config` method. This method accepts a single config object as an argument, which will be exposed to the user as `Lita.config.handlers.your_handler_namespace`.
@@ -318,30 +340,47 @@ For more detailed examples, check out the built in authorization, help, and web
 
 ## Testing
 
-It's a core philosophy of Lita that any plugins you write for your robot should be as thoroughly tested as any other program you would write. To make this easier, Lita ships with some handy extras for [RSpec](https://github.com/rspec/rspec) that make testing a handler dead simple. They require the full RSpec suite (rspec-core, rspec-expectations, and rspec-mocks) version 2.14 or higher, as they use the newer `expect(obj).to receive(:message)` syntax.
+It's a core philosophy of Lita that any plugins you write for your robot should be as thoroughly tested as any other program you would write. To make this easier, Lita ships with some handy extras for [RSpec](https://github.com/rspec/rspec) that make testing a plugin dead simple. They require the full RSpec suite (rspec-core, rspec-expectations, and rspec-mocks) version 2.14 or higher, as they use the newer "expect" syntax.
 
-### Testing handlers
+### Testing adapters
 
-To include Lita's RSpec extras for testing a handler, require "lita/rspec", then add `lita_handler: true` to the metadata for the example group.
+To include some helpful setup for testing Lita code, require "lita/rspec", then add `lita: true` to the metadata for an example group.
 
 ``` ruby
 require "lita/rspec"
 
-describe Lita::Handlers::MyHandler, lita_handler: true do
+describe Lita::Adapters::MyAdapter, lita: true do
   # ...
 end
 ```
 
-This provides the following:
+This will have the following effects:
 
 * All Redis interaction will be namespaced to a test environment and automatically cleared out before each example.
 * Lita's logger is stubbed to prevent log messages from cluttering up your test output.
 * Lita's configuration is cleared out before each example, so that the first call to `Lita.config` will start from the default configuration.
+
+### Testing handlers
+
+To include Lita's RSpec extras for testing a handler, require "lita/rspec", then add `lita_handler: true` to the metadata for the example group.
+
+``` ruby
+require "lita/rspec"
+
+describe Lita::Handlers::MyHandler, lita_handler: true do
+  # ...
+end
+```
+
+This will have the following effects, in addition to the effects of the `lita: true` metadata hook:
+
 * `Lita.handlers` will return an array with only the class you're testing (`described_class`).
 * Strings sent with `Lita::Robot#send_messages` will be pushed to an array accessible as `replies` so you can make expectations about output from the robot.
 * You have access to the following cached objects set with `let`: `robot`, `source`, and `user`. Note that these objects are instances of the real classes and not test doubles.
 
-The custom helper methods are where `Lita::RSpec` really shines. You can test routes (both chat and HTTP routes) very easily using this syntax:
+The custom helper methods are where `Lita::RSpec` really shines. You can test routes (both chat and HTTP routes) and event subscriptions very easily using this syntax:
+
+#### Testing routes
 
 ``` ruby
 it { routes("some message").to(:some_method) }
@@ -349,6 +388,8 @@ it { routes_command("directed message").to(:some_command_method) }
 it { doesnt_route("message").to(:some_command_method) }
 it { routes_http(:get, "/foo/bar").to(:baz) }
 it { doesnt_route_http(:post, "/foo/bar").to(:baz) }
+it { routes_event(:connected).to(:greet) }
+it { doesnt_route_event(:some_other_event).to(:greet) }
 ```
 
 * `routes` - Sets an expectation that the given string will trigger the given method when overheard by the robot.
@@ -357,9 +398,15 @@ it { doesnt_route_http(:post, "/foo/bar").to(:baz) }
 * `doesnt_route_command` - Sets an expectation that is the inverse of the one set by `routes_command`. Also aliased to `does_not_route_command`.
 * `routes_http` - Sets an expectation that an HTTP request with the given HTTP method and path will route to the given handler method.
 * `doesnt_route_http` - Sets an expectation that is the inverse of `routes_http`. Also aliased to `does_not_route_http`.
+* `routes_event` - Sets an expectation that the given event will trigger the given subscribed method.
+* `doesnt_route_event` - Sets an expectation that is the inverse of `routes_event`. Also aliased to `does_not_route_event`.
 
 **Note: These routing helpers bypass authorization for routes restricted to authorization groups.**
 
+#### Testing handler methods
+
+Since the behavior in handlers are regular instance methods, you can unit test them just as you would any other methods in a Ruby class. However, if you prefer a more integration test approach, there are some helper methods available to help with this.
+
 To send a message to the robot, use `send_message` and `send_command`. Then set expectations about the contents of the `replies` array.
 
 ``` ruby
@@ -387,14 +434,6 @@ end
 * `send_message(string, as: user)` - Sends the given string to the robot.
 * `send_command(string, as: user)` - Sends the given string to the robot, prefixing it with the robot's mention name.
 
-### Testing adapters or other code
-
-If you use `lita: true` instead of `lita_handler: true` in the metadata for your example group, only a small subset of Lita's RSpec extras will be enabled:
-
-* All Redis interaction will be namespaced to a test environment and automatically cleared out before each example.
-* Lita's logger is stubbed to prevent log messages from cluttering up your test output.
-* Lita's configuration is cleared out before each example, so that the first call to `Lita.config` will start from the default configuration.
-
 ## Running as a daemon
 
 Lita has built-in support for daemonization on Unix systems. When run as a daemon, Lita will redirect standard output and standard error to a log file, and write the process ID to a PID file. To start Lita as a daemon, run `lita -d`. There are additional command line flags for specifying the path of the log and PID files, which override the defaults. If an existing Lita process is running when `lita -d` is invoked, Lita will abort and leave the original process running, unless the `-k` flag is specified, in which case it will kill the existing process. Run `lita help` for information about all the possible command line flags.

data/lib/lita/adapters/shell.rb

@@ -7,8 +7,9 @@ module Lita
       # @return [void]
       def run
         user = User.create(1, name: "Shell User")
-        source = Source.new(user)
+        source = Source.new(user: user)
         puts 'Type "exit" or "quit" to end the session.'
+        robot.trigger(:connected)
 
         loop do
           print "#{robot.name} > "

data/lib/lita/handler.rb

@@ -95,8 +95,38 @@ module Lita
         end
       end
 
+      # 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]
+      def on(event_name, method_name)
+        event_subscriptions[normalize_event(event_name)] << method_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 [void]
+      def trigger(robot, event_name, payload = {})
+        event_subscriptions[normalize_event(event_name)].each do |method_name|
+          new(robot).public_send(method_name, 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
+
       # Determines whether or not an incoming messages should trigger a route.
       def route_applies?(route, message, robot)
         # Message must be a command if the route requires a command
@@ -141,6 +171,10 @@ LOG
 #{e.backtrace.join("\n")}
 ERROR
       end
+
+      def normalize_event(event_name)
+        event_name.to_s.downcase.strip.to_sym
+      end
     end
 
     # @param robot [Lita::Robot] The currently running robot.

data/lib/lita/message.rb

@@ -74,7 +74,9 @@ module Lita
     # @param strings [String, Array<String>] The strings to send back.
     # @return [void]
     def reply_privately(*strings)
-      @robot.send_messages(Source.new(source.user), *strings)
+      private_source = source.clone
+      private_source.private_message!
+      @robot.send_messages(private_source, *strings)
     end
   end
 end

data/lib/lita/robot.rb

@@ -71,6 +71,18 @@ module Lita
       @adapter.shut_down
     end
 
+    # Triggers an event, instructing all registered handlers to invoke any
+    # methods subscribed to the event, and passing them a payload hash of
+    # arbitrary data.
+    # @param event_name [String, Symbol] The name of the event to trigger.
+    # @param payload [Hash] An optional hash of arbitrary data.
+    # @return [void]
+    def trigger(event_name, payload = {})
+      Lita.handlers.each do |handler|
+        handler.trigger(self, event_name, payload)
+      end
+    end
+
     private
 
     # Loads the selected adapter.

data/lib/lita/rspec/handler.rb

@@ -34,7 +34,7 @@ module Lita
         def set_up_let_blocks(base)
           base.class_eval do
             let(:robot) { Robot.new }
-            let(:source) { Source.new(user) }
+            let(:source) { Source.new(user: user) }
             let(:user) { User.create("1", name: "Test User") }
             let(:replies) { [] }
           end
@@ -56,7 +56,7 @@ module Lita
         message = if as == user
           Message.new(robot, body, source)
         else
-          Message.new(robot, body, Source.new(as))
+          Message.new(robot, body, Source.new(user: as))
         end
 
         robot.receive(message)
@@ -136,6 +136,27 @@ module Lita
         HTTPRouteMatcher.new(self, http_method, path, invert: true)
       end
       alias_method :doesnt_route_http, :does_not_route_http
+
+      # Starts an event subscription test chain, asserting that an event should
+      # trigger the target method.
+      # @param event_name [String, Symbol] The name of the event that should
+      #   be triggered.
+      # @return [EventSubscriptionMatcher] An {EventSubscriptionMatcher} that
+      #   should have +to+ called on it to complete the test.
+      def routes_event(event_name)
+        EventSubscriptionMatcher.new(self, event_name)
+      end
+
+      # Starts an event subscription test chain, asserting that an event should
+      # not trigger the target method.
+      # @param event_name [String, Symbol] The name of the event that should
+      #   not be triggered.
+      # @return [EventSubscriptionMatcher] An {EventSubscriptionMatcher} that
+      #   should have +to+ called on it to complete the test.
+      def does_not_route_event(event_name)
+        EventSubscriptionMatcher.new(self, event_name, invert: true)
+      end
+      alias_method :doesnt_route_event, :does_not_route_event
     end
 
     # Used to complete a chat routing test chain.
@@ -190,5 +211,32 @@ module Lita
         end
       end
     end
+
+    # Used to complete an event subscription test chain.
+    class EventSubscriptionMatcher
+      def initialize(context, event_name, invert: false)
+        @context = context
+        @event_name = event_name
+        @method = invert ? :not_to : :to
+      end
+
+      # Sets an expectation that a handler method will or will not be called in
+      # response to a triggered event, then triggers the event.
+      # @param target_method_name [String, Symbol] The name of the method that
+      #   should or should not be triggered.
+      # @return [void]
+      def to(target_method_name)
+        e = @event_name
+        m = @method
+
+        @context.instance_eval do
+          expect_any_instance_of(described_class).public_send(
+            m,
+            receive(target_method_name)
+          )
+          robot.trigger(e)
+        end
+      end
+    end
   end
 end

data/lib/lita/source.rb

@@ -1,11 +1,16 @@
 module Lita
-  # A wrapper object representing the source of an incoming message (the user
-  # who sent it, and optionally the room they sent it from). If a room is set,
+  # 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. Source objects are also used as "target"
-  # objects when sending an outgoing message or performing another operation
-  # on a user or a room.
+  # 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_method :private_message?, :private_message
 
     # The room the message came from or should be sent to.
     # @return [String] A string uniquely identifying the room.
@@ -20,9 +25,37 @@ module Lita
     # @param room [String] A string uniquely identifying the room the user sent
     #   the message from, or the room where a reply should go. The format of
     #   this string will differ depending on the chat service.
-    def initialize(user, room = nil)
-      @user = user
-      @room = room
+    # @param private_message [Boolean] A flag indicating whether or not the
+    #   message was sent privately.
+    def initialize(*args)
+      options = args.last.is_a?(Hash) ? args.pop : {}
+
+      @user = options[:user]
+      @room = options[:room]
+      @private_message = options[:private_message]
+
+      if args.size > 0
+        Lita.logger.warn <<-WARNING.chomp
+Passing positional arguments to Source is deprecated. \
+Use Source.new(user: user, room: room, private_message: pm) instead.
+WARNING
+        @user = args[0] if args[0]
+        @room = args[1] if args[1]
+      end
+
+      if user.nil? && room.nil?
+        raise ArgumentError.new("Either a user or a room is required.")
+      end
+
+      @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
   end
 end

data/lib/lita/version.rb

@@ -1,4 +1,4 @@
 module Lita
   # The current version of Lita.
-  VERSION = "2.4.0"
+  VERSION = "2.5.0"
 end

data/spec/lita/adapters/shell_spec.rb

@@ -8,6 +8,7 @@ describe Lita::Adapters::Shell do
       allow(subject).to receive(:puts)
       allow(subject).to receive(:print)
       allow($stdin).to receive(:gets).and_return("foo", "exit")
+      allow(robot).to receive(:trigger)
       allow(robot).to receive(:receive)
     end
 
@@ -22,6 +23,11 @@ describe Lita::Adapters::Shell do
       expect_any_instance_of(Lita::Message).to receive(:command!)
       subject.run
     end
+
+    it "triggers a connected event" do
+      expect(robot).to receive(:trigger).with(:connected)
+      subject.run
+    end
   end
 
   describe "#send_message" do

data/spec/lita/handler_spec.rb

@@ -19,6 +19,9 @@ describe Lita::Handler, lita: true do
 
       http.get "web", :web
 
+      on :connected, :greet
+      on :some_hook, :test_payload
+
       def foo(response)
       end
 
@@ -35,6 +38,10 @@ describe Lita::Handler, lita: true do
         raise "The developer of this handler's got a bug in their code!"
       end
 
+      def greet(payload)
+        robot.send_message("Hi, #{payload[:name]}! Lita has started!")
+      end
+
       def self.name
         "Lita::Handlers::Test"
       end
@@ -130,6 +137,21 @@ describe Lita::Handler, lita: true do
     end
   end
 
+  describe ".trigger" do
+    it "invokes methods registered with .on and passes an arbitrary payload" do
+      expect(robot).to receive(:send_message).with(
+        "Hi, Carl! Lita has started!"
+      )
+      handler_class.trigger(robot, :connected, name: "Carl")
+    end
+
+    it "normalizes the event name" do
+      expect(robot).to receive(:send_message).twice
+      handler_class.trigger(robot, "connected")
+      handler_class.trigger(robot, " ConNected  ")
+    end
+  end
+
   describe "#http" do
     it "returns a Faraday connection" do
       expect(subject.http).to be_a(Faraday::Connection)

data/spec/lita/message_spec.rb

@@ -77,10 +77,10 @@ describe Lita::Message do
       subject = described_class.new(
         robot,
         "Hello",
-        Lita::Source.new("Carl", "#room")
+        Lita::Source.new(user: "Carl", room: "#room")
       )
       expect(robot).to receive(:send_messages) do |source, *strings|
-        expect(source.room).to be_nil
+        expect(source).to be_a_private_message
         expect(strings).to eq(["foo", "bar"])
       end
       subject.reply_privately("foo", "bar")

data/spec/lita/robot_spec.rb

@@ -9,15 +9,28 @@ describe Lita::Robot do
     expect { subject }.to raise_error(SystemExit)
   end
 
-  describe "#receive" do
+  context "with registered handlers" do
     let(:handler1) { double("Handler 1").as_null_object }
     let(:handler2) { double("Handler 2").as_null_object }
 
-    it "dispatches messages to every registered handler" do
+    before do
       allow(Lita).to receive(:handlers).and_return([handler1, handler2])
-      expect(handler1).to receive(:dispatch).with(subject, "foo")
-      expect(handler2).to receive(:dispatch).with(subject, "foo")
-      subject.receive("foo")
+    end
+
+    describe "#receive" do
+      it "dispatches messages to every registered handler" do
+        expect(handler1).to receive(:dispatch).with(subject, "foo")
+        expect(handler2).to receive(:dispatch).with(subject, "foo")
+        subject.receive("foo")
+      end
+    end
+
+    describe "#trigger" do
+      it "triggers the supplied event on all registered handlers" do
+        expect(handler1).to receive(:trigger).with(subject, :foo, bar: "baz")
+        expect(handler2).to receive(:trigger).with(subject, :foo, bar: "baz")
+        subject.trigger(:foo, bar: "baz")
+      end
     end
   end
 

data/spec/lita/rspec_spec.rb

@@ -7,6 +7,8 @@ handler_class = Class.new(Lita::Handler) do
 
   http.get "web", :web
 
+  on :connected, :greet
+
   def foo(response)
     response.reply "baz"
   end
@@ -21,6 +23,9 @@ handler_class = Class.new(Lita::Handler) do
   def web(request, response)
   end
 
+  def greet(payload)
+  end
+
   def self.name
     "Lita::Handlers::Test"
   end
@@ -36,6 +41,9 @@ describe handler_class, lita_handler: true do
   it { routes("restricted").to(:restricted) }
   it { routes_http(:get, "web").to(:web) }
   it { doesnt_route_http(:post, "web").to(:web) }
+  it { routes_event(:connected).to(:greet) }
+  it { doesnt_route_event(:connected).to(:web) }
+  it { does_not_route_event(:connected).to(:web) }
 
   describe "#foo" do
     it "replies with baz" do

data/spec/lita/source_spec.rb

@@ -2,12 +2,43 @@ require "spec_helper"
 
 describe Lita::Source do
   it "has a user" do
-    subject = described_class.new("Carl")
+    subject = described_class.new(user: "Carl")
     expect(subject.user).to eq("Carl")
   end
 
   it "has a room" do
-    subject = described_class.new("Carl", "#litabot")
+    subject = described_class.new(room: "#litabot")
     expect(subject.room).to eq("#litabot")
   end
+
+  it "has a private message flag" do
+    subject = described_class.new(user: "Carl", private_message: true)
+    expect(subject).to be_a_private_message
+  end
+
+  it "can be manually marked as private" do
+    subject = described_class.new(user: "Carl", room: "#litabot")
+    subject.private_message!
+    expect(subject).to be_a_private_message
+  end
+
+  it "requires either a user or a room" do
+    expect { described_class.new }.to raise_error(ArgumentError)
+  end
+
+  describe "the deprecated Source.new(user, room) API" do
+    it "can have a user and is marked as private if there is no room" do
+      expect(Lita.logger).to receive(:warn)
+      subject = described_class.new("Carl")
+      expect(subject.user).to eq("Carl")
+      expect(subject).to be_a_private_message
+    end
+
+    it "can have a room and is not marked as private if it does" do
+      expect(Lita.logger).to receive(:warn)
+      subject = described_class.new("Carl", "#litabot")
+      expect(subject.room).to eq("#litabot")
+      expect(subject).not_to be_a_private_message
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lita
 version: !ruby/object:Gem::Version
-  version: 2.4.0
+  version: 2.5.0
 platform: ruby
 authors:
 - Jimmy Cuadra
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-09-10 00:00:00.000000000 Z
+date: 2013-10-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -283,7 +283,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.3
+rubygems_version: 2.1.3
 signing_key: 
 specification_version: 4
 summary: A multi-service chat bot with extendable behavior.