mockingbird 0.1.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Hayes Davis
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,102 @@
+Mockingbird
+===========
+Mockingbird emulates the Twitter Streaming API using a simple script-like 
+configuration that makes it easy to test code that connects to the Streaming 
+API. Mockingbird can be used to simulate bad data, unexpected status codes, 
+hard disconnects, etc.
+
+Mockingbird uses eventmachine to run as an actual streaming http server so
+it's a drop-in replacement for code that reads from the streaming api. 
+Simply change the host and port your code is connecting to from Twitter to 
+a mockingbird instance.
+
+Since mockingbird is designed for testing, it includes a simple 
+Mockingbird#setup and Mockingbird#teardown interface that makes it easy to 
+configure and spawn a server for testing purposes during unit tests.
+
+Configuration Quickstart
+------------------------
+Mockingbird uses a simple script-like configuration API for telling a 
+mockingbird server what you want it to do. Here's a simple example:
+
+    Mockingbird.setup(:port=>8080) do
+      send '{"foo":"bar"}'
+      wait 1
+      5.times do
+        send '{"foo2":"bar2"}'
+      end
+      pipe "some/file.txt", :wait=>1
+      close
+    end
+    
+Here's what this does in plain english:
+
+* Tells the server to listen on port 8080 and do the stuff in the block on 
+  each connection.
+* On a connection, send '{"foo":"bar"}' down to the client
+* Wait 1 second
+* Then send '{"foo2":"bar2"}' down to the client 5 times
+* Then send each line from some/file.txt to the clien, waiting 1 second in 
+  between sends
+* Close the connection
+  
+Mockingbird assigns each conection an incrementing id. This means you can 
+specify behavior over multiple connections with different connections doing 
+different things. This is handy for testing reconnection code:
+
+    Mockingbird.setup(:port=>8080) do
+      on_connection(1) do
+        disconnect!
+      end
+      
+      on_connection(2..5) do
+        wait(0.5)
+        close
+      end
+      
+      on_connection('*') do
+        100.times do
+          send '{"foo":"bar"}'
+        end
+        close
+      end
+    end
+    
+Again, in plain english:
+
+* On the first connection, we do a hard disconnect (just drop the connection)
+* On connections 2-5, wait a half second, then close the connection nicely
+* On all subsequent connections ("*"), send down 100 foo bars and close
+
+See the docs on Mockingbird::Script for all the available configuration options.
+Also, see the examples directory for more usage.
+
+Using in Tests
+--------------
+The basic pattern for using Mockingbird in your unit tests is to simply call 
+Mockingbird#setup and Mockingbird#teardown at appropriate times. This will 
+setup a mockingbird server in a separate process and then kill it when you're 
+done. Make sure to *always* call Mockingbird#teardown. This is easy in test/unit 
+if you're actually calling these methods in setup and teardown. If you need to 
+setup and teardown a server in a test method, do the following:
+
+    def test_something
+      Mockingbird.setup(:port=>NNNN) do
+         # config here
+      end
+      # do tests
+    ensure
+      Mockingbird.teardown
+    end  
+
+Limitations
+-----------
+* SSL is not supported.
+* Since connection ids are incrementing with each connection you won't be able 
+  able to easily target specific connections if you have multiple clients 
+  connecting at once to the mockingbird server. It's generally recommended that 
+  you have a single client connecting to mockingbird serially during a single 
+  test run. Doing otherwise would probably be confusing anyway.
+* The server does not even pay attention to your actual request, it will just 
+  always respond with the defined configuration script regardless of what you 
+  send on connection.

data/examples/examples.md

@@ -0,0 +1,35 @@
+How to run examples
+===================
+It's easiest to do this if you have curl. From the root directory of this 
+project run the following
+
+    $ ruby examples/EXAMPLE_FILE.rb
+    Waiting for Mockingbird to start...
+    Mockingbird is mocking you on 0.0.0.0:8080 (pid=50990)    
+    $ curl -v http://localhost:8080 
+   
+Depending on the example file and your version of curl, you'll see something 
+similar to this:
+    * About to connect() to 0.0.0.0 port 8080 (#0)
+    *   Trying 0.0.0.0... connected
+    * Connected to 0.0.0.0 (0.0.0.0) port 8080 (#0)
+    > GET / HTTP/1.1
+    > User-Agent: curl/7.19.6 (i386-apple-darwin9.7.0) libcurl/7.19.6 zlib/1.2.3
+    > Host: 0.0.0.0:8080
+    > Accept: */*
+    > 
+    < HTTP/1.1 200 OK
+    < Transfer-Encoding: chunked
+    < Content-Type: application/json
+    < Server: Mockingbird
+    < 
+    * Connection #0 to host 0.0.0.0 left intact
+    * Closing connection #0
+
+When you're done you need to kill the mockingbird server which is running in 
+its own process. You can grep it like below or use the pid printed when you 
+ran the example file.
+
+    $ ps | grep mockingbird
+    50990 ttys006    0:00.33 mockingbird:0.0.0.0:8080
+    $ kill -9 50990

data/examples/overview.rb

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift File.expand_path(File.dirname(__FILE__) + '/../lib')
+require 'mockingbird'
+
+Mockingbird.setup(:port=>8080) do
+  send '{"foo":"bar"}'
+  wait 0.5
+  5.times do |n|
+    send %Q({"foo":"bar#{n}"})
+  end
+  pipe "#{File.dirname(__FILE__)}/overview_output.txt", :wait=>1
+  close
+end

data/examples/overview_output.txt

@@ -0,0 +1,5 @@
+{"line":1}
+{"line":2}
+{"line":3}
+{"line":4}
+{"line":5}

data/examples/reconnects.rb

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift File.expand_path(File.dirname(__FILE__) + '/../lib')
+require 'mockingbird'
+
+# Note: you'll need to run curl several times to see the full effect of this one
+
+Mockingbird.setup(:port=>8080) do
+  on_connection(1) do
+    disconnect!
+  end
+  
+  on_connection(2..5) do
+    wait(0.5)
+    close
+  end
+  
+  on_connection('*') do
+    100.times do
+      send '{"foo":"bar"}'
+    end
+    close
+  end
+end

data/examples/status_and_headers.rb

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift File.expand_path(File.dirname(__FILE__) + '/../lib')
+require 'mockingbird'
+
+Mockingbird.setup(:port=>8080) do
+  status 404, "Not Found"
+  headers "X-Hi-There"=>"Howdy"
+  close
+end

data/lib/mockingbird.rb

@@ -0,0 +1,61 @@
+# External dependencies
+require 'rubygems'
+require 'eventmachine'
+
+# Mockingbird code
+require 'mockingbird/version'
+require 'mockingbird/commands'
+require 'mockingbird/connection_script'
+require 'mockingbird/script'
+require 'mockingbird/script_runner'
+require 'mockingbird/server'
+
+module Mockingbird
+  
+  class << self
+    
+    # Convenience method for starting a mockingbird server during a test. 
+    # This will be most users' primary interface to mockingbird. The mockingbird 
+    # server will be forked as a separate process. Ensure that your test code 
+    # always calls teardown at some point after setup, or the separate process 
+    # will not be terminated.
+    # 
+    # Options are
+    #   :host - The host to listen on. 0.0.0.0 by default
+    #   :port - The port to listen on. 4879 by default
+    #
+    # The block is a Mockingbird configuration (see README).
+    def setup(opts={},&block)
+      Server.configure(&block)
+      @pid = fork do
+        opts = {:host=>'0.0.0.0',:port=>4879}.merge(opts)
+        $0 = "mockingbird:#{opts[:host]}:#{opts[:port]}"
+        Server.start!(opts)
+      end
+      Process.detach(@pid)
+      puts "Waiting for Mockingbird to start..."
+      sleep(1) # Necessary to make sure the forked proc is up and running
+      @pid
+    end
+    
+    # Terminates the mockingbird server created by a call to setup. Make sure 
+    # to always pair this call with setup to ensure that mockingbird server 
+    # processes don't linger. If you're using test/unit, the recommended 
+    # pattern is to actually call setup and teardown here during the setup and 
+    # teardown phase of your unit tests. Otherwise, use the following pattern:
+    # 
+    #   def test_something
+    #     Mockingbird.setup(:port=>NNNN) do
+    #       # config here
+    #     end
+    #     # do tests
+    #   ensure
+    #     Mockingbird.teardown
+    #   end
+    def teardown
+      Process.kill('KILL',@pid)
+    end    
+    
+  end
+  
+end

data/lib/mockingbird/commands.rb

@@ -0,0 +1,135 @@
+module Mockingbird
+  module Commands
+    class Command
+      
+      attr_accessor :next_command, :callback
+      
+      def initialize(&block)
+        self.callback = block      
+      end
+      
+      def run(conn)
+        callback.call(conn) if callback
+        advance(conn)
+      end
+      
+      def advance(conn)
+        next_command.run(conn) if next_command
+      end
+    
+    end
+  
+    class Send < Command
+      
+      def initialize(data=nil,&block)
+        @data = data || block
+      end
+      
+      def run(conn)
+        to_send = data
+        conn.send_chunk(to_send)
+        advance(conn)
+      end
+      
+      private
+        def data
+          if @data.respond_to?(:call)
+            @data.call
+          else
+            @data
+          end
+        end
+      
+    end
+    
+    class Disconnect < Command
+      
+      def run(conn)
+        conn.close_connection
+        advance(conn)
+      end
+      
+    end
+    
+    class Wait < Command
+      
+      def initialize(time=nil,&block)
+        @time = time || block
+      end
+      
+      def run(conn)
+        EM.add_timer(wait_time) do
+          advance(conn)
+        end
+      end
+      
+      private
+        def wait_time
+          if @time.respond_to?(:call)
+            @time.call
+          else
+            @time
+          end
+        end
+      
+    end
+    
+    class Close < Command
+      
+      def run(conn)
+        conn.send_terminal_chunk
+        EM.add_timer(0.1) do
+          conn.close_connection
+        end
+        advance(conn)
+      end
+      
+    end
+    
+    class Quit < Command
+      def run(conn)
+        EM.add_timer(0.5) do
+          EM.stop 
+        end      
+      end
+    end
+    
+    class Pipe < Command
+      
+      def initialize(string_or_io,delay=nil)
+        if string_or_io.kind_of?(String)
+          @io = File.open(string_or_io,'r')
+        else
+          @io = string_or_io
+        end
+        @delay = delay
+      end
+      
+      def run(conn)
+        unless @io.eof?
+          chunk = @io.readline.chomp
+          conn.send_chunk(chunk)
+          if delay
+            EM.add_timer(delay) { run(conn) }
+          else
+            EM.schedule { run(conn) }
+          end
+        else
+          # Reset for future calls
+          @io.rewind
+          advance(conn)
+        end
+      end
+      
+      private
+        def delay
+          if @delay.respond_to?(:call)
+            @delay.call
+          else
+            @delay
+          end
+        end
+      
+    end  
+  end
+end

data/lib/mockingbird/connection_script.rb

@@ -0,0 +1,19 @@
+module Mockingbird
+  
+  class ConnectionScript
+    
+    attr_accessor :status, :headers, :body
+
+    def initialize
+      self.body = Commands::Command.new
+      @last_command = body
+    end
+    
+    def add_command(command=nil)
+      @last_command.next_command = command
+      @last_command = command
+    end
+    
+  end
+  
+end

data/lib/mockingbird/script.rb

@@ -0,0 +1,100 @@
+module Mockingbird
+  class Script
+    
+    def initialize(&block)
+      @connections = []
+      @default_connection = ConnectionScript.new
+      instance_eval(&block)
+    end
+    
+    def for_connection(id)
+      match = @connections.find do |selector, *|
+        case selector
+          when Range    then selector.include?(id)
+          when Numeric  then selector == id
+          when Proc     then selector.call(id)
+        end
+      end
+      match ? match.last : @default_connection
+    end
+    
+    # Configuration API
+    
+    # Specifies behavior to run for specific connections based on the id number 
+    # assigned to that connection. Connection ids are 1-based.
+    #
+    # The selector can be any of the following:
+    #   Number - Run the code on that connection id
+    #   Range - Run the code for a connection id in that range
+    #   Proc - Call the proc with the id and run if it matches
+    #   '*' - Run this code for any connection that doesn't match others
+    def on_connection(selector=nil,&block)
+      if selector.nil? || selector == '*'
+        instance_eval(&block)
+      else
+        @current_connection = ConnectionScript.new
+        instance_eval(&block)
+        @connections << [selector,@current_connection]
+        @current_connection = nil
+      end
+    end
+    
+    # Send an HTTP status code to the client. e.g. a 403 or 404
+    def status(code, message="")
+      current_connection.status = [code, message]
+    end
+    
+    # Send the hash of headers to the client.
+    def headers(hash)
+      current_connection.headers = hash
+    end
+    
+    # Send some text down to the client. If a block is specified that block 
+    # will be called on each connection to determine what text to send. This 
+    # permits sending randomized data.
+    def send(data=nil,&block)
+      add_command(Commands::Send.new(data,&block))
+    end
+    
+    # Wait a certain number of seconds. Fractional seconds are allowed. If a 
+    # block is specified, it will be called on each attempt. This permits things 
+    # like adding randomized waits.
+    def wait(time=nil,&block)
+      add_command(Commands::Wait.new(time,&block))
+    end
+    
+    # Perform a hard disconnect by just closing the connection
+    def disconnect!
+      add_command(Commands::Disconnect.new)
+    end
+    
+    # Do a clean close
+    def close
+      add_command(Commands::Close.new)
+    end
+    
+    # Exit the server entirely
+    def quit
+      add_command(Commands::Quit.new)
+    end
+    
+    # Send the lines from string_or_io down one at a time. The :wait option 
+    # can be used to specify a configurable delay between lines.
+    def pipe(string_or_io,opts={})
+      add_command(Commands::Pipe.new(string_or_io,opts[:wait]))
+    end
+    
+    # Not really part of the public API but users could use this to 
+    # implement their own fancy command
+    def add_command(command=nil,&block)
+      command = Commands::Command.new(&block) if block_given?
+      current_connection.add_command(command)
+    end
+    
+    private
+      def current_connection
+        @current_connection || @default_connection
+      end
+    
+  end
+end

data/lib/mockingbird/script_runner.rb

@@ -0,0 +1,41 @@
+module Mockingbird
+  
+  class ScriptRunner
+    
+    attr_accessor :conn, :script
+    
+    def initialize(conn,script)
+      self.conn = conn
+      self.script = script
+    end
+    
+    def run
+      send_status
+      send_headers
+      send_body
+    end
+    
+    def send_status
+      code, message = (script.status || [200,"OK"])
+      conn.send_status(code,message)  
+    end
+    
+    def send_headers
+      headers = {
+        "Transfer-Encoding"=>"chunked",
+        "Content-Type"=>"application/json",
+        "Server"=>"Mockingbird"
+      }.merge(script.headers||{})
+      headers.each do |name, value|
+        conn.send_header(name, value)      
+      end
+    end
+    
+    def send_body
+      conn.start_body
+      script.body.run(conn)
+    end
+    
+  end
+  
+end

data/lib/mockingbird/server.rb

@@ -0,0 +1,83 @@
+module Mockingbird
+
+  # A very simple eventmachine-based streaming server. Before you use a server
+  # it must be configured with configuration block:
+  #
+  #   Mockingbird::Server.configure do
+  #     # config goes here, see README for scripting
+  #   end
+  #
+  # Once configured, a server may be started using
+  # 
+  #   start!(:host=>'0.0.0.0',:port=>NNN)
+  #
+  # If you're using Mockingbird directly from test (test/unit, etc), it's 
+  # recommended that you use the simpler convenience interface defined on 
+  # the Mockingbird module.
+  module Server
+  
+    class << self
+     
+      def start!(opts={})
+        opts = {:host=>'0.0.0.0',:port=>8080}.merge(opts)
+        host = opts[:host]
+        port = opts[:port]
+        EventMachine::run do
+          puts "Mockingbird is mocking you on #{host}:#{port} (pid=#{$$})"
+          EventMachine::start_server host, port, self
+        end
+      end
+      
+      def configure(&block)
+        @script = Script.new(&block)
+      end
+      
+      def script
+        @script
+      end
+      
+      def new_connection_id
+        @connection_id ||= 0
+        @connection_id += 1
+      end
+      
+    end
+    
+    def receive_data(data)
+      conn_id = new_connection_id
+      runner = ScriptRunner.new(self,script.for_connection(conn_id))
+      runner.run
+    end
+    
+    def new_connection_id
+      Mockingbird::Server.new_connection_id
+    end
+    
+    def script
+      Mockingbird::Server.script
+    end
+    
+    def send_status(code=200,text="OK")
+      send_data "HTTP/1.1 #{code} #{text}\r\n"
+    end
+    
+    def send_header(name,value)
+      send_data "#{name}: #{value}\r\n"
+    end
+    
+    def start_body
+      send_data "\r\n"
+    end
+    
+    def send_chunk(chunk)
+      res = %Q(#{chunk}\r\n)
+      send_data "#{res.length.to_s(16)}\r\n"
+      send_data "#{res}\r\n"
+    end
+    
+    def send_terminal_chunk
+      send_data "0\r\n\r\n"
+    end
+    
+  end
+end

data/lib/mockingbird/version.rb

@@ -0,0 +1,5 @@
+module Mockingbird
+  
+  VERSION = Version = "0.1.0"
+  
+end

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification 
+name: mockingbird
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Hayes Davis
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-07-31 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: eventmachine
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 47
+        segments: 
+        - 0
+        - 12
+        - 0
+        version: 0.12.0
+  type: :runtime
+  version_requirements: *id001
+description: "    Mockingbird emulates the Twitter Streaming API using a simple script-like \n    configuration that makes it easy to test code that connects to the Streaming \n    API. Mockingbird can be used to simulate bad data, unexpected status codes, \n    hard disconnects, etc.\n    \n    Mockingbird uses eventmachine to run as an actual streaming http server so\n    it's a drop-in replacement for code that reads from the streaming api. \n    Simply change the host and port your code is connecting to from Twitter to \n    a running Mockingbird.\n"
+email: hayes@appozite.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.md
+files: 
+- README.md
+- lib/mockingbird/commands.rb
+- lib/mockingbird/connection_script.rb
+- lib/mockingbird/script.rb
+- lib/mockingbird/script_runner.rb
+- lib/mockingbird/server.rb
+- lib/mockingbird/version.rb
+- lib/mockingbird.rb
+- examples/examples.md
+- examples/overview.rb
+- examples/overview_output.txt
+- examples/reconnects.rb
+- examples/status_and_headers.rb
+- LICENSE
+has_rdoc: true
+homepage: http://github.com/hayesdavis/mockingbird
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Mockingbird is a mock server for testing with the Twitter Streaming API.
+test_files: []
+