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

webmachine 0.4.2 → 1.0.0

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