RubyGems - webmachine - Versions diffs - 0.4.2 → 1.0.0 - Mend

webmachine 0.4.2 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (52) hide show

data/README.md +70 -7
data/Rakefile +19 -0
data/examples/debugger.rb +32 -0
data/examples/webrick.rb +6 -2
data/lib/webmachine.rb +2 -0
data/lib/webmachine/adapters/rack.rb +16 -3
data/lib/webmachine/adapters/webrick.rb +7 -1
data/lib/webmachine/application.rb +10 -10
data/lib/webmachine/cookie.rb +168 -0
data/lib/webmachine/decision/conneg.rb +1 -1
data/lib/webmachine/decision/flow.rb +1 -1
data/lib/webmachine/decision/fsm.rb +19 -12
data/lib/webmachine/decision/helpers.rb +25 -1
data/lib/webmachine/dispatcher.rb +34 -5
data/lib/webmachine/dispatcher/route.rb +2 -0
data/lib/webmachine/media_type.rb +3 -3
data/lib/webmachine/request.rb +11 -0
data/lib/webmachine/resource.rb +3 -1
data/lib/webmachine/resource/authentication.rb +1 -1
data/lib/webmachine/resource/callbacks.rb +16 -0
data/lib/webmachine/resource/tracing.rb +20 -0
data/lib/webmachine/response.rb +38 -8
data/lib/webmachine/trace.rb +74 -0
data/lib/webmachine/trace/fsm.rb +60 -0
data/lib/webmachine/trace/pstore_trace_store.rb +39 -0
data/lib/webmachine/trace/resource_proxy.rb +107 -0
data/lib/webmachine/trace/static/http-headers-status-v3.png +0 -0
data/lib/webmachine/trace/static/trace.erb +54 -0
data/lib/webmachine/trace/static/tracelist.erb +14 -0
data/lib/webmachine/trace/static/wmtrace.css +123 -0
data/lib/webmachine/trace/static/wmtrace.js +725 -0
data/lib/webmachine/trace/trace_resource.rb +129 -0
data/lib/webmachine/version.rb +1 -1
data/spec/spec_helper.rb +19 -0
data/spec/webmachine/adapters/rack_spec.rb +77 -41
data/spec/webmachine/configuration_spec.rb +1 -1
data/spec/webmachine/cookie_spec.rb +99 -0
data/spec/webmachine/decision/conneg_spec.rb +9 -8
data/spec/webmachine/decision/flow_spec.rb +52 -4
data/spec/webmachine/decision/helpers_spec.rb +36 -6
data/spec/webmachine/dispatcher_spec.rb +1 -1
data/spec/webmachine/headers_spec.rb +1 -1
data/spec/webmachine/media_type_spec.rb +1 -1
data/spec/webmachine/request_spec.rb +10 -0
data/spec/webmachine/resource/authentication_spec.rb +3 -3
data/spec/webmachine/response_spec.rb +45 -0
data/spec/webmachine/trace/fsm_spec.rb +32 -0
data/spec/webmachine/trace/resource_proxy_spec.rb +36 -0
data/spec/webmachine/trace/trace_store_spec.rb +29 -0
data/spec/webmachine/trace_spec.rb +17 -0
data/webmachine.gemspec +2 -0
metadata +130 -15

data/README.md CHANGED

@@ -28,7 +28,7 @@ application for it!
 ```ruby
 require 'webmachine'
 # Require any of the files that contain your resources here
-require 'my_resource'
+require 'my_resource'
 # Create an application which encompasses routes and configruation
 MyApp = Webmachine::Application.new do |app|
@@ -63,7 +63,7 @@ class MyResource < Webmachine::Resource
   def encodings_provided
     {"gzip" => :encode_gzip, "identity" => :encode_identity}
   end
   def to_html
     "<html><body>Hello, world!</body></html>"
   end
@@ -85,7 +85,7 @@ object, `Webmachine.application` will return a global one.
 ```ruby
 require 'webmachine'
 require 'my_resource'
 Webmachine.application.routes do
   add ['*'], MyResource
 end
@@ -95,11 +95,52 @@ Webmachine.application.configure do |config|
   config.port = 3000
   config.adapter = :Mongrel
 end
 # Start the server.
 Webmachine.application.run
 ```
+### Visual debugger
+It can be hard to understand all of the decisions that Webmachine
+makes when servicing a request to your resource, which is why we have
+the "visual debugger". In development, you can turn on tracing of the
+decision graph for a resource by implementing the `#trace?` callback
+so that it returns true:
+```ruby
+class MyTracedResource < Webmachine::Resource
+  def trace?
+    true
+  end
+  # The rest of your callbacks...
+end
+```
+Then enable the visual debugger resource by adding a route to your
+configuration:
+```ruby
+Webmachine.application.routes do
+  # This can be any path as long as it ends with '*'
+  add ['trace', '*'], Webmachine::Trace::TraceResource
+  # The rest of your routes...
+end
+```
+Now when you visit your traced resource, a trace of the request
+process will be recorded in memory. Open your browser to `/trace` to
+list the recorded traces and inspect the result. The response from your
+traced resource will also include the `X-Webmachine-Trace-Id` that you
+can use to lookup the trace. It might look something like this:
+![preview calls at decision](http://seancribbs-skitch.s3.amazonaws.com/Webmachine_Trace_2156885920-20120625-100153.png)
+Refer to
+[examples/debugger.rb](/seancribbs/webmachine-ruby/blob/master/examples/debugger.rb)
+for an example of how to enable the debugger.
 ## Features
 * Handles the hard parts of content negotiation, conditional
@@ -112,13 +153,12 @@ Webmachine.application.run
 * Streaming/chunked response bodies are permitted as Enumerables,
   Procs, or Fibers!
 * Unlike the Erlang original, it does real Language negotiation.
+* Includes the visual debugger so you can look through the decision
+  graph to determine how your resources are behaving.
 ## Problems/TODOs
 * Command-line tools, and general polish.
-* Tracing is exposed as an Array of decisions visited on the response
-  object. You should be able to turn this off and on, and visualize
-  the decisions on the sequence diagram.
 ## LICENSE
@@ -128,6 +168,29 @@ LICENSE for details.
 ## Changelog
+### 1.0.0 July 7, 2012
+1.0.0 is a major feature release that finally includes the visual
+debugger, some nice cookie support, and some new extension
+points. Added Peter Johanson and Armin Joellenbeck as
+contributors. Thank you for your contributions!
+* A cookie parsing and manipulation API was added.
+* Conneg headers now accept any amount of whitespace around commas,
+  including none.
+* `Callbacks#handle_exception` was added so that resources can handle
+  exceptions that they generate and produce more friendly responses.
+* Chunked and non-chunked response bodies in the Rack adapter were
+  fixed.
+* The WEBrick example was updated to use the new API.
+* `Dispatcher` was refactored so that you can modify how resources
+  are initialized before dispatching occurs.
+* `Route` now includes the `Translation` module so that exception
+  messages are properly rendered.
+* The visual debugger was added (more details in the README).
+* The `Content-Length` header will always be set inside Webmachine and
+  is no longer reliant on the adapter to set it.
 ### 0.4.2 March 22, 2012
 0.4.2 is a bugfix release that corrects a few minor issues. Added Lars

data/Rakefile CHANGED

@@ -32,6 +32,25 @@ task :release => :gem do
   system "gem push pkg/#{gemspec.name}-#{gemspec.version}.gem"
 end
+desc "Cleans up white space in source files"
+task :clean_whitespace do
+  no_file_cleaned = true
+  Dir["**/*.rb"].each do |file|
+    contents = File.read(file)
+    cleaned_contents = contents.gsub(/([ \t]+)$/, '')
+    unless cleaned_contents == contents
+      no_file_cleaned = false
+      puts " - Cleaned #{file}"
+      File.open(file, 'w') { |f| f.write(cleaned_contents) }
+    end
+  end
+  if no_file_cleaned
+    puts "No files with trailing whitespace found"
+  end
+end
 require 'rspec/core'
 require 'rspec/core/rake_task'

data/examples/debugger.rb ADDED

@@ -0,0 +1,32 @@
+require 'webmachine'
+require 'webmachine/trace'
+class MyTracedResource < Webmachine::Resource
+  def trace?; true; end
+  def resource_exists?
+    case request.query['e']
+    when 'true'
+      true
+    when 'fail'
+      raise "BOOM"
+    else
+      false
+    end
+  end
+  def to_html
+    "<html>You found me.</html>"
+  end
+end
+# Webmachine::Trace.trace_store = :pstore, "./trace"
+TraceExample = Webmachine::Application.new do |app|
+  app.routes do
+    add ['trace', '*'], Webmachine::Trace::TraceResource
+    add [], MyTracedResource
+  end
+end
+TraceExample.run

data/examples/webrick.rb CHANGED

@@ -14,6 +14,10 @@ class HelloResource < Webmachine::Resource
   end
 end
-Webmachine::Dispatcher.add_route([], HelloResource)
+App = Webmachine::Application.new do |app|
+  app.routes do
+    add [], HelloResource
+  end
+end
-Webmachine.run
+App.run

data/lib/webmachine.rb CHANGED

@@ -1,4 +1,5 @@
 require 'webmachine/configuration'
+require 'webmachine/cookie'
 require 'webmachine/headers'
 require 'webmachine/request'
 require 'webmachine/response'
@@ -10,6 +11,7 @@ require 'webmachine/adapters'
 require 'webmachine/dispatcher'
 require 'webmachine/application'
 require 'webmachine/resource'
+require 'webmachine/trace'
 require 'webmachine/version'
 # Webmachine is a toolkit for making well-behaved HTTP applications.

data/lib/webmachine/adapters/rack.rb CHANGED

@@ -4,6 +4,7 @@ require 'webmachine/headers'
 require 'webmachine/request'
 require 'webmachine/response'
 require 'webmachine/dispatcher'
+require 'webmachine/chunked_body'
 module Webmachine
   module Adapters
@@ -58,10 +59,22 @@ module Webmachine
         response.headers['Server'] = [Webmachine::SERVER_STRING, "Rack/#{::Rack.version}"].join(" ")
-        body = response.body.respond_to?(:call) ? response.body.call : response.body
-        body = body.is_a?(String) ? [ body ] : body
+        rack_status = response.code
+        rack_headers = response.headers.flattened("\n")
+        rack_body = case response.body
+                    when String # Strings are enumerable in ruby 1.8
+                      [response.body]
+                    else
+                      if response.body.respond_to?(:call)
+                        Webmachine::ChunkedBody.new(Array(response.body.call))
+                      elsif response.body.respond_to?(:each)
+                        Webmachine::ChunkedBody.new(response.body)
+                      else
+                        [response.body.to_s]
+                      end
+                    end
-        [response.code.to_i, response.headers, body || []]
+        [rack_status, rack_headers, rack_body]
       end
       # Wraps the Rack input so it can be treated like a String or

data/lib/webmachine/adapters/webrick.rb CHANGED

@@ -39,7 +39,13 @@ module Webmachine
           response = Webmachine::Response.new
           @dispatcher.dispatch(request, response)
           wres.status = response.code.to_i
-          response.headers.each { |k,v| wres[k] = v }
+          headers = response.headers.flattened.reject { |k,v| k == 'Set-Cookie' }
+          headers.each { |k,v| wres[k] = v }
+          cookies = [response.headers['Set-Cookie'] || []].flatten
+          cookies.each { |c| wres.cookies << c }
           wres['Server'] = [Webmachine::SERVER_STRING, wres.config[:ServerSoftware]].join(" ")
           case response.body
           when String

data/lib/webmachine/application.rb CHANGED

@@ -4,19 +4,19 @@ require 'webmachine/dispatcher'
 module Webmachine
   # How to get your Webmachine app running:
-  #
+  #
   #   MyApp = Webmachine::Application.new do |app|
   #     app.routes do
   #       add ['*'], AssetResource
   #     end
-  #
+  #
   #     app.configure do |config|
   #       config.port = 8888
   #     end
   #   end
-  #
+  #
   #   MyApp.run
-  #
+  #
   class Application
     extend Forwardable
@@ -32,17 +32,17 @@ module Webmachine
     #
     # An instance of application contains Adapter configuration and
     # a Dispatcher instance which can be configured with Routes.
-    #
+    #
     # @param [Webmachine::Configuration] configuration
     #   a Webmachine::Configuration
-    #
+    #
     # @yield [app]
     #   a block in which to configure this Application
     # @yieldparam [Application]
     #   the Application instance being initialized
-    def initialize(configuration = Configuration.default)
+    def initialize(configuration = Configuration.default, dispatcher = Dispatcher.new)
       @configuration = configuration
-      @dispatcher    = Dispatcher.new
+      @dispatcher    = dispatcher
       yield self if block_given?
     end
@@ -66,10 +66,10 @@ module Webmachine
     # Evaluates the passed block in the context of {Webmachine::Dispatcher}
     # for use in adding a number of routes at once.
-    #
+    #
     # @return [Application, Array<Route>]
     #   self if configuring, or an Array of Routes otherwise
-    #
+    #
     # @see Webmachine::Dispatcher#add_route
     def routes(&block)
       if block_given?

data/lib/webmachine/cookie.rb ADDED

@@ -0,0 +1,168 @@
+require 'uri'
+module Webmachine
+  # An HTTP Cookie for a response, including optional attributes
+  class Cookie
+    # Parse a Cookie header, with any number of cookies, into a hash
+    # @param [String] the Cookie header
+    # @param [Boolean] whether to include duplicate cookie values in the
+    #    response
+    # @return [Hash] cookie name/value pairs.
+    def self.parse(cstr, include_dups = false)
+      cookies = {}
+      (cstr || '').split(/\s*[;,]\s*/n).each { |c|
+        k,v = c.split(/\s*=\s*/, 2).map { |s| unescape(s) }
+        case cookies[k]
+        when nil
+          cookies[k] = v
+        when Array
+          cookies[k] << v
+        else
+          cookies[k] = [cookies[k], v] if include_dups
+        end
+      }
+      cookies
+    end
+    attr_reader :name, :value
+    # Allowed keys for the attributes parameter of
+    # {Webmachine::Cookie#initialize}
+    ALLOWED_ATTRIBUTES = [:secure, :httponly, :path, :domain,
+                          :comment, :maxage, :expires, :version]
+    # If the cookie is HTTP only
+    def http_only?
+      @attributes[:httponly]
+    end
+    # If the cookie should be treated as a secure one by the client
+    def secure?
+      @attributes[:secure]
+    end
+    # The path for which the cookie is valid
+    def path
+      @attributes[:path]
+    end
+    # The domain for which the cookie is valid
+    def domain
+      @attributes[:domain]
+    end
+    # A comment allowing documentation on the intended use for the cookie
+    def comment
+      @attributes[:comment]
+    end
+    # Which version of the state management specification the cookie conforms
+    def version
+      @attributes[:version]
+    end
+    # The Max-Age, in seconds, for which the cookie is valid
+    def maxage
+      @attributes[:maxage]
+    end
+    # The expiration {DateTime} of the cookie
+    def expires
+      @attributes[:expires]
+    end
+    def initialize(name, value, attributes = {})
+      @name, @value, @attributes = name, value, attributes
+    end
+    # Convert to an RFC2109 valid cookie string
+    # @return [String] The RFC2109 valid cookie string
+    def to_s
+      attributes = ALLOWED_ATTRIBUTES.select { |a| @attributes[a] }.map do |a|
+        case a
+        when :httponly
+          "HttpOnly" if @attributes[a]
+        when :secure
+          "Secure" if @attributes[a]
+        when :maxage
+          "MaxAge=" + @attributes[a].to_s
+        when :expires
+          "Expires=" + rfc2822(@attributes[a])
+        when :comment
+          "Comment=" + escape(@attributes[a].to_s)
+        else
+          a.to_s.sub(/^\w/) { $&.capitalize } + "="  + @attributes[a].to_s
+        end
+      end
+      ([escape(name) + "=" + escape(value)] + attributes).join("; ")
+    end
+    private
+    def rfc2822(time)
+      wday = Time::RFC2822_DAY_NAME[time.wday]
+      mon = Time::RFC2822_MONTH_NAME[time.mon - 1]
+      time.strftime("#{wday}, %d-#{mon}-%Y %H:%M:%S GMT")
+    end
+    if URI.respond_to?(:decode_www_form_component) and defined?(::Encoding)
+      # Escape a cookie
+      def escape(s)
+        URI.encode_www_form_component(s)
+      end
+      # Unescape a cookie
+      # @private
+      def self.unescape(s, encoding = Encoding::UTF_8)
+        URI.decode_www_form_component(s, encoding)
+      end
+    else # We're on 1.8.7, or JRuby or Rubinius in 1.8 mode
+      # Copied and modified from 1.9.x URI
+      # @private
+      TBLENCWWWCOMP_ = {}
+      256.times do |i|
+        TBLENCWWWCOMP_[i.chr] = '%%%02X' % i
+      end
+      TBLENCWWWCOMP_[' '] = '+'
+      TBLENCWWWCOMP_.freeze
+      # @private
+      TBLDECWWWCOMP_ = {}
+      256.times do |i|
+        h, l = i>>4, i&15
+        TBLDECWWWCOMP_['%%%X%X' % [h, l]] = i.chr
+        TBLDECWWWCOMP_['%%%x%X' % [h, l]] = i.chr
+        TBLDECWWWCOMP_['%%%X%x' % [h, l]] = i.chr
+        TBLDECWWWCOMP_['%%%x%x' % [h, l]] = i.chr
+      end
+      TBLDECWWWCOMP_['+'] = ' '
+      TBLDECWWWCOMP_.freeze
+      # Decode given +str+ of URL-encoded form data.
+      #
+      # This decodes + to SP.
+      #
+      # @private
+      def self.unescape(str, enc=nil)
+        raise ArgumentError, "invalid %-encoding (#{str})" unless /\A(?:%\h\h|[^%]+)*\z/ =~ str
+        str.gsub(/\+|%\h\h/){|c| TBLDECWWWCOMP_[c] }
+      end
+      # Encode given +str+ to URL-encoded form data.
+      #
+      # This method doesn't convert *, -, ., 0-9, A-Z, _, a-z, but does convert SP
+      # (ASCII space) to + and converts others to %XX.
+      #
+      # This is an implementation of
+      # http://www.w3.org/TR/html5/forms.html#url-encoded-form-data
+      #
+      # @private
+      def escape(str)
+        str.to_s.gsub(/[^*\-.0-9A-Z_a-z]/){|c| TBLENCWWWCOMP_[c] }
+      end
+    end
+  end
+end