webmachine 1.1.0 → 1.2.0

data/lib/webmachine/adapters/webrick.rb

@@ -9,16 +9,22 @@ module Webmachine
   module Adapters
     # Connects Webmachine to WEBrick.
     class WEBrick < Adapter
+      # Used to override default WEBRick options (useful in testing)
+      DEFAULT_OPTIONS = {}
 
       # Starts the WEBrick adapter
       def run
-        options = {
+        options = DEFAULT_OPTIONS.merge({
           :Port => configuration.port,
           :BindAddress => configuration.ip
-        }.merge(configuration.adapter_options)
-        server = Webmachine::Adapters::WEBrick::Server.new(dispatcher, options)
-        trap("INT"){ server.shutdown }
-        Thread.new { server.start }.join
+        }).merge(configuration.adapter_options)
+        @server = Server.new(dispatcher, options)
+        trap("INT") { shutdown }
+        @server.start
+      end
+
+      def shutdown
+        @server.shutdown if @server
       end
 
       # WEBRick::HTTPServer that is run by the WEBrick adapter.
@@ -51,7 +57,7 @@ module Webmachine
           when String
             wres.body << response.body
           when Enumerable
-            wres.chunked = true
+            wres.chunked = response.headers['Transfer-Encoding'] == 'chunked'
             response.body.each {|part| wres.body << part }
           else
             if response.body.respond_to?(:call)

data/lib/webmachine/application.rb

@@ -1,6 +1,7 @@
 require 'forwardable'
 require 'webmachine/configuration'
 require 'webmachine/dispatcher'
+require 'webmachine/events'
 
 module Webmachine
   # How to get your Webmachine app running:

data/lib/webmachine/cookie.rb

@@ -87,7 +87,7 @@ module Webmachine
         when :secure
           "Secure" if @attributes[a]
         when :maxage
-          "MaxAge=" + @attributes[a].to_s
+          "Max-Age=" + @attributes[a].to_s
         when :expires
           "Expires=" + rfc2822(@attributes[a])
         when :comment

data/lib/webmachine/dispatcher.rb

@@ -40,7 +40,13 @@ module Webmachine
     # @param [Response] response the response object
     def dispatch(request, response)
       if resource = find_resource(request, response)
-        Webmachine::Decision::FSM.new(resource, request, response).run
+        Webmachine::Events.instrument('wm.dispatch') do |payload|
+          Webmachine::Decision::FSM.new(resource, request, response).run
+
+          payload[:resource] = resource.class.name
+          payload[:request] = request.dup
+          payload[:code] = response.code
+        end
       else
         Webmachine.render_error(404, request, response)
       end

data/lib/webmachine/events.rb

@@ -0,0 +1,179 @@
+require 'securerandom' # For AS::Notifications
+require 'as/notifications'
+require 'webmachine/events/instrumented_event'
+
+module Webmachine
+  # {Webmachine::Events} implements the
+  # [ActiveSupport::Notifications](http://rubydoc.info/gems/activesupport/ActiveSupport/Notifications)
+  # instrumentation API. It delegates to the configured backend.
+  # The default backend is
+  # [AS::Notifications](http://rubydoc.info/gems/as-notifications/AS/Notifications).
+  #
+  # # Published events
+  #
+  # Webmachine publishes some internal events by default. All of them use
+  # the `wm.` prefix.
+  #
+  # ## `wm.dispatch` ({.instrument})
+  #
+  # The payload hash includes the following keys.
+  #
+  # * `:resource` - The resource class name
+  # * `:request` - A copy of the request object
+  # * `:code` - The response code
+  #
+  module Events
+    class << self
+      # The class that {Webmachine::Events} delegates all messages to.
+      # (default [AS::Notifications](http://rubydoc.info/gems/as-notifications/AS/Notifications))
+      #
+      # It can be changed to an
+      # [ActiveSupport::Notifications](http://rubydoc.info/gems/activesupport/ActiveSupport/Notifications)
+      # compatible backend early in the application startup process.
+      #
+      # @example
+      #   require 'webmachine'
+      #   require 'active_support/notifications'
+      #
+      #   Webmachine::Events.backend = ActiveSupport::Notifications
+      #
+      #   Webmachine::Application.new {|app|
+      #     # setup application
+      #   }.run
+      attr_accessor :backend
+
+      # Publishes the given arguments to all listeners subscribed to the given
+      # event name.
+      # @param name [String] the event name
+      # @example
+      #   Webmachine::Events.publish('wm.foo', :hello => 'world')
+      def publish(name, *args)
+        backend.publish(name, *args)
+      end
+
+      # Instrument the given block by measuring the time taken to execute it
+      # and publish it. Notice that events get sent even if an error occurs
+      # in the passed-in block.
+      #
+      # If an exception happens during an instrumentation the payload will
+      # have a key `:exception` with an array of two elements as value:
+      # a string with the name of the exception class, and the exception
+      # message. (when using the default
+      # [AS::Notifications](http://rubydoc.info/gems/as-notifications/AS/Notifications)
+      # backend)
+      #
+      # @param name [String] the event name
+      # @param payload [Hash] the initial payload
+      #
+      # @example
+      #   Webmachine::Events.instrument('wm.dispatch') do |payload|
+      #     execute_some_method
+      #
+      #     payload[:custom_payload_value] = 'important'
+      #   end
+      def instrument(name, payload = {}, &block)
+        backend.instrument(name, payload, &block)
+      end
+
+      # Subscribes to the given event name.
+      #
+      # @note The documentation of this method describes its behaviour with the
+      #   default backed [AS::Notifications](http://rubydoc.info/gems/as-notifications/AS/Notifications).
+      #   It can change if a different backend is used.
+      #
+      # @overload subscribe(name)
+      #   Subscribing to an {.instrument} event. The block arguments can be
+      #   passed to {Webmachine::Events::InstrumentedEvent}.
+      #
+      #   @param name [String, Regexp] the event name to subscribe to
+      #   @yieldparam name [String] the event name
+      #   @yieldparam start [Time] the event start time
+      #   @yieldparam end [Time] the event end time
+      #   @yieldparam event_id [String] the event id
+      #   @yieldparam payload [Hash] the event payload
+      #   @return [Object] the subscriber object (type depends on the backend implementation)
+      #
+      #   @example
+      #     # Subscribe to all 'wm.dispatch' events
+      #     Webmachine::Events.subscribe('wm.dispatch') {|*args|
+      #       event = Webmachine::Events::InstrumentedEvent.new(*args)
+      #     }
+      #
+      #     # Subscribe to all events that start with 'wm.'
+      #     Webmachine::Events.subscribe(/wm\.*/) {|*args| }
+      #
+      # @overload subscribe(name)
+      #   Subscribing to a {.publish} event.
+      #
+      #   @param name [String, Regexp] the event name to subscribe to
+      #   @yieldparam name [String] the event name
+      #   @yieldparam *args [Array] the published arguments
+      #   @return [Object] the subscriber object (type depends on the backend implementation)
+      #
+      #   @example
+      #     Webmachine::Events.subscribe('custom.event') {|name, *args|
+      #       args #=> [obj1, obj2, {:num => 1}]
+      #     }
+      #
+      #     Webmachine::Events.publish('custom.event', obj1, obj2, {:num => 1})
+      #
+      # @overload subscribe(name, listener)
+      #   Subscribing with a listener object instead of a block. The listener
+      #   object must respond to `#call`.
+      #
+      #   @param name [String, Regexp] the event name to subscribe to
+      #   @param listener [#call] a listener object
+      #   @return [Object] the subscriber object (type depends on the backend implementation)
+      #
+      #   @example
+      #     class CustomListener
+      #       def call(name, *args)
+      #         # ...
+      #       end
+      #     end
+      #
+      #     Webmachine::Events.subscribe('wm.dispatch', CustomListener.new)
+      #
+      def subscribe(name, *args, &block)
+        backend.subscribe(name, *args, &block)
+      end
+
+      # Subscribe to an event temporarily while the block runs.
+      #
+      # @note The documentation of this method describes its behaviour with the
+      #   default backed [AS::Notifications](http://rubydoc.info/gems/as-notifications/AS/Notifications).
+      #   It can change if a different backend is used.
+      #
+      # The callback in the following example will be called for all
+      # "sql.active_record" events instrumented during the execution of the
+      # block. The callback is unsubscribed automatically after that.
+      #
+      # @example
+      #   callback = lambda {|name, *args| handle_event(name, *args) }
+      #
+      #   Webmachine::Events.subscribed(callback, 'sql.active_record') do
+      #     call_active_record
+      #   end
+      def subscribed(callback, name, &block)
+        backend.subscribed(callback, name, &block)
+      end
+
+      # Unsubscribes the given subscriber.
+      #
+      # @note The documentation of this method describes its behaviour with the
+      #   default backed [AS::Notifications](http://rubydoc.info/gems/as-notifications/AS/Notifications).
+      #   It can change if a different backend is used.
+      #
+      # @param subscriber [Object] the subscriber object (type depends on the backend implementation)
+      # @example
+      #   subscriber = Webmachine::Events.subscribe('wm.dispatch') {|*args| }
+      #
+      #   Webmachine::Events.unsubscribe(subscriber)
+      def unsubscribe(subscriber)
+        backend.unsubscribe(subscriber)
+      end
+    end
+
+    self.backend = AS::Notifications
+  end
+end

data/lib/webmachine/events/instrumented_event.rb

@@ -0,0 +1,19 @@
+require 'delegate'
+require 'as/notifications/instrumenter'
+
+module Webmachine
+  module Events
+    # {Webmachine::Events::InstrumentedEvent} delegates to
+    # [AS::Notifications::Event](http://rubydoc.info/gems/as-notifications/AS/Notifications/Event).
+    #
+    # The class
+    # [AS::Notifications::Event](http://rubydoc.info/gems/as-notifications/AS/Notifications/Event)
+    # is able to take the arguments of an {Webmachine::Events.instrument} event
+    # and provide an object-oriented interface to that data.
+    class InstrumentedEvent < SimpleDelegator
+      def initialize(*args)
+        super(AS::Notifications::Event.new(*args))
+      end
+    end
+  end
+end

data/lib/webmachine/response.rb

@@ -45,7 +45,7 @@ module Webmachine
     # @param [String] value the value of the cookie
     # @param [Hash] attributes for the cookie. See RFC2109.
     def set_cookie(name, value, attributes = {})
-      cookie = Webmachine::Cookie.new(name, value).to_s
+      cookie = Webmachine::Cookie.new(name, value, attributes).to_s
       case headers['Set-Cookie']
       when nil
         headers['Set-Cookie'] = cookie

data/lib/webmachine/streaming/io_encoder.rb

@@ -13,7 +13,7 @@ module Webmachine
       # @yield [chunk]
       # @yieldparam [String] chunk a chunk of the response, encoded
       def each
-        while chunk = body.read(CHUNK_SIZE) && chunk != ""
+        while chunk = body.read(CHUNK_SIZE) and chunk != ""
           yield resource.send(encoder, resource.send(charsetter, chunk))
         end
       end
@@ -50,6 +50,10 @@ module Webmachine
         end
       end
 
+      def empty?
+        size == 0
+      end
+
       alias bytesize size
 
       private

data/lib/webmachine/trace.rb

@@ -2,6 +2,7 @@ require 'webmachine/trace/resource_proxy'
 require 'webmachine/trace/fsm'
 require 'webmachine/trace/pstore_trace_store'
 require 'webmachine/trace/trace_resource'
+require 'webmachine/trace/listener'
 
 module Webmachine
   # Contains means to enable the Webmachine visual debugger.
@@ -13,6 +14,11 @@ module Webmachine
       :pstore => PStoreTraceStore
     }
 
+    DEFAULT_TRACE_SUBSCRIBER = Webmachine::Events.subscribe(
+      /wm\.trace\..+/,
+      Webmachine::Trace::Listener.new
+    )
+
     # Determines whether this resource instance should be traced.
     # @param [Webmachine::Resource] resource a resource instance
     # @return [true, false] whether to trace the resource
@@ -70,5 +76,17 @@ module Webmachine
                        end
     end
     private :trace_store
+
+    # Sets the trace listener objects.
+    # Defaults to Webmachine::Trace::Listener.new.
+    # @param [Array<Object>] listeners a list of event listeners
+    # @return [Array<Object>] a list of event subscribers
+    def trace_listener=(listeners)
+      Webmachine::Events.unsubscribe(DEFAULT_TRACE_SUBSCRIBER)
+
+      Array(listeners).map do |listener|
+        Webmachine::Events.subscribe(/wm\.trace\..+/, listener)
+      end
+    end
   end
 end

data/lib/webmachine/trace/fsm.rb

@@ -27,7 +27,10 @@ module Webmachine
           :body => trace_response_body(response.body)
         }
       ensure
-        Trace.record(resource.object_id.to_s, response.trace)
+        Webmachine::Events.publish('wm.trace.record', {
+          :trace_id => resource.object_id.to_s,
+          :trace => response.trace
+        })
       end
 
       # Adds a decision to the trace.

data/lib/webmachine/trace/listener.rb

@@ -0,0 +1,12 @@
+module Webmachine
+  module Trace
+    class Listener
+      def call(name, payload)
+        key = payload.fetch(:trace_id)
+        trace = payload.fetch(:trace)
+
+        Webmachine::Trace.record(key, trace)
+      end
+    end
+  end
+end

data/lib/webmachine/version.rb

@@ -1,6 +1,6 @@
 module Webmachine
   # Library version
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 
   # String for use in "Server" HTTP response header, which includes
   # the {VERSION}.

data/spec/spec_helper.rb

@@ -4,17 +4,28 @@ $LOAD_PATH << File.expand_path("../../lib", __FILE__)
 require 'rubygems'
 require 'webmachine'
 require 'rspec'
+require 'logger'
 
 RSpec.configure do |config|
   config.mock_with :rspec
   config.filter_run :focus => true
   config.run_all_when_everything_filtered = true
   config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.formatter = :documentation if ENV['CI']
   if defined?(::Java)
     config.seed = Time.now.utc
   else
     config.order = :random
   end
+
+  config.before(:suite) do
+    options = {
+      :Logger => Logger.new("/dev/null"),
+      :AccessLog => []
+    }
+    Webmachine::Adapters::WEBrick::DEFAULT_OPTIONS.merge! options
+    Webmachine::Adapters::Rack::DEFAULT_OPTIONS.merge! options
+  end
 end
 
 # For use in specs that need a fully initialized resource

data/spec/support/adapter_lint.rb

@@ -0,0 +1,125 @@
+require "support/test_resource"
+require "net/http"
+
+shared_examples_for :adapter_lint do
+  attr_accessor :client
+
+  before(:all) do
+    configuration = Webmachine::Configuration.default
+    dispatcher = Webmachine::Dispatcher.new
+    dispatcher.add_route ["test"], Test::Resource
+
+    @adapter = described_class.new(configuration, dispatcher)
+    @client = Net::HTTP.new(configuration.ip, configuration.port)
+
+    Thread.abort_on_exception = true
+    @server_thread = Thread.new { @adapter.run }
+
+    # Wait until the server is responsive
+    timeout(5) do
+      begin
+        client.start
+      rescue Errno::ECONNREFUSED
+        sleep(0.1)
+        retry
+      end
+    end
+  end
+
+  after(:all) do
+    @adapter.shutdown
+    @client.finish
+    @server_thread.join
+  end
+
+  it "provides a string-like request body" do
+    request = Net::HTTP::Put.new("/test")
+    request.body = "Hello, World!"
+    request["Content-Type"] = "test/request.stringbody"
+    response = client.request(request)
+    response["Content-Length"].should eq("21")
+    response.body.should eq("String: Hello, World!")
+  end
+
+  it "provides an enumerable request body" do
+    request = Net::HTTP::Put.new("/test")
+    request.body = "Hello, World!"
+    request["Content-Type"] = "test/request.enumbody"
+    response = client.request(request)
+    response["Content-Length"].should eq("19")
+    response.body.should eq("Enum: Hello, World!")
+  end
+
+  it "handles missing pages" do
+    request = Net::HTTP::Get.new("/missing")
+    response = client.request(request)
+    response.code.should eq("404")
+    response["Content-Type"].should eq("text/html")
+  end
+
+  it "handles empty response bodies" do
+    request = Net::HTTP::Post.new("/test")
+    request.body = ""
+    response = client.request(request)
+    response.code.should eq("204")
+    # FIXME: Mongrel/WEBrick fail this test. Is there a bug?
+    #response["Content-Type"].should be_nil
+    response["Content-Length"].should be_nil
+    response.body.should be_nil
+  end
+
+  it "handles string response bodies" do
+    request = Net::HTTP::Get.new("/test")
+    request["Accept"] = "test/response.stringbody"
+    response = client.request(request)
+    response["Content-Length"].should eq("20")
+    response.body.should eq("String response body")
+  end
+
+  it "handles enumerable response bodies" do
+    request = Net::HTTP::Get.new("/test")
+    request["Accept"] = "test/response.enumbody"
+    response = client.request(request)
+    response["Transfer-Encoding"].should eq("chunked")
+    response.body.should eq("Enumerable response body")
+  end
+
+  it "handles proc response bodies" do
+    request = Net::HTTP::Get.new("/test")
+    request["Accept"] = "test/response.procbody"
+    response = client.request(request)
+    response["Transfer-Encoding"].should eq("chunked")
+    response.body.should eq("Proc response body")
+  end
+
+  it "handles fiber response bodies" do
+    request = Net::HTTP::Get.new("/test")
+    request["Accept"] = "test/response.fiberbody"
+    response = client.request(request)
+    response["Transfer-Encoding"].should eq("chunked")
+    response.body.should eq("Fiber response body")
+  end
+
+  it "handles io response bodies" do
+    request = Net::HTTP::Get.new("/test")
+    request["Accept"] = "test/response.iobody"
+    response = client.request(request)
+    response["Content-Length"].should eq("16")
+    response.body.should eq("IO response body")
+  end
+
+  it "handles request cookies" do
+    request = Net::HTTP::Get.new("/test")
+    request["Accept"] = "test/response.cookies"
+    request["Cookie"] = "echo=echocookie"
+    response = client.request(request)
+    response.body.should eq("echocookie")
+  end
+
+  it "handles response cookies" do
+    request = Net::HTTP::Get.new("/test")
+    request["Accept"] = "test/response.cookies"
+    response = client.request(request)
+    response["Set-Cookie"].should eq("cookie=monster, rodeo=clown")
+  end
+end