RubyGems - webmachine - Versions diffs - 0.2.0 → 0.3.0 - Mend

webmachine 0.2.0 → 0.3.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 (33) hide show

data/Gemfile +11 -7
data/Guardfile +1 -1
data/README.md +88 -36
data/Rakefile +10 -0
data/lib/webmachine/adapters/mongrel.rb +9 -13
data/lib/webmachine/adapters/rack.rb +50 -0
data/lib/webmachine/adapters/webrick.rb +2 -0
data/lib/webmachine/chunked_body.rb +43 -0
data/lib/webmachine/decision/conneg.rb +2 -1
data/lib/webmachine/decision/flow.rb +4 -2
data/lib/webmachine/decision/helpers.rb +4 -0
data/lib/webmachine/dispatcher.rb +15 -2
data/lib/webmachine/dispatcher/route.rb +4 -0
data/lib/webmachine/fiber18.rb +88 -0
data/lib/webmachine/headers.rb +16 -1
data/lib/webmachine/media_type.rb +3 -0
data/lib/webmachine/request.rb +17 -7
data/lib/webmachine/resource.rb +2 -1
data/lib/webmachine/resource/authentication.rb +35 -0
data/lib/webmachine/resource/callbacks.rb +15 -10
data/lib/webmachine/response.rb +5 -4
data/lib/webmachine/streaming.rb +44 -8
data/lib/webmachine/translation.rb +7 -0
data/lib/webmachine/version.rb +5 -1
data/spec/tests.org +24 -1
data/spec/webmachine/adapters/rack_spec.rb +64 -0
data/spec/webmachine/chunked_body_spec.rb +30 -0
data/spec/webmachine/decision/helpers_spec.rb +11 -0
data/spec/webmachine/dispatcher_spec.rb +13 -0
data/spec/webmachine/request_spec.rb +5 -0
data/spec/webmachine/resource/authentication_spec.rb +68 -0
data/webmachine.gemspec +6 -3
metadata +251 -58

data/Gemfile CHANGED Viewed

@@ -9,13 +9,17 @@ gem 'bundler'
 unless ENV['TRAVIS']
   gem 'guard-rspec'
-  case RbConfig::CONFIG['host_os']
-  when /darwin/
-    gem 'rb-fsevent'
-    gem 'growl_notify'
-  when /linux/
-    gem 'rb-inotify'
-    gem 'libnotify'
+  platform :mri do
+    gem 'redcarpet'
+    case RbConfig::CONFIG['host_os']
+    when /darwin/
+      gem 'rb-fsevent'
+      gem 'growl_notify'
+    when /linux/
+      gem 'rb-inotify'
+      gem 'libnotify'
+    end
   end
 end

data/Guardfile CHANGED Viewed

@@ -1,7 +1,7 @@
 gemset = ENV['RVM_GEMSET'] || 'webmachine'
 gemset = "@#{gemset}" unless gemset.to_s == ''
-rvms = %W[  1.9.2 ].map {|v| "#{v}#{gemset}" }
+rvms = %W[ 1.8.7 1.9.2 jruby rbx ].map {|v| "#{v}#{gemset}" }
 guard 'rspec', :cli => "--color --profile", :growl => true, :rvm => rvms do
   watch(%r{^lib/webmachine/locale/.+$}) { "spec" }

data/README.md CHANGED Viewed

@@ -11,14 +11,14 @@ toolkit for building HTTP-friendly applications. For example, it does
 not provide a templating engine or a persistence layer; those choices
 are up to you.
-**NOTE**: _Webmachine is NOT compatible with Rack._ This is
-intentional! Rack obscures HTTP in a way that makes it hard for
-Webmachine to do its job properly, and encourages people to add
-middleware that might break Webmachine's behavior. Rack is also built
-on the tradition of CGI, which is nice for backwards compatibility but
-also an antiquated paradigm and should be scuttled (IMHO). _Rack may
-be supported in the future, but only as a shim to support other web
-application servers._
+## A Note about Rack
+Webmachine has a Rack adapter -- thanks to Jamis Buck -- but when
+using it, we recommend you ensure that NO middleware is used.  The
+behaviors that are encapsulated in Webmachine could be broken by
+middlewares that sit above it, and there is no way to detect them at
+runtime. _Caveat emptor_. That said, Webmachine should behave properly
+when given a clear stack.
 ## Getting Started
@@ -26,25 +26,25 @@ Webmachine is very young, but it's still easy to construct an
 application for it!
 ```ruby
-    require 'webmachine'
-    # Require any of the files that contain your resources here
-    require 'my_resource'
-    # Point all URIs at the MyResource class
-    Webmachine::Dispatcher.add_route(['*'], MyResource)
-    # Start the server, binds to port 3000 using WEBrick
-    Webmachine.run
+require 'webmachine'
+# Require any of the files that contain your resources here
+require 'my_resource'
+# Point all URIs at the MyResource class
+Webmachine::Dispatcher.add_route(['*'], MyResource)
+# Start the server, binds to port 8080 using WEBrick
+Webmachine.run
 ```
 Your resource will look something like this:
 ```ruby
-    class MyResource < Webmachine::Resource
-      def to_html
-        "<html><body>Hello, world!</body></html>"
-      end
-    end
+class MyResource < Webmachine::Resource
+  def to_html
+    "<html><body>Hello, world!</body></html>"
+  end
+end
 ```
 Run the first file and your application is up. That's all there is to
@@ -54,19 +54,44 @@ might want to enable "gzip" compression on your resource, for which
 you can simply add an `encodings_provided` callback method:
 ```ruby
-    class MyResource < Webmachine::Resource
-      def encodings_provided
-        {"gzip" => :encode_gzip, "identity" => :encode_identity}
-      end
-      def to_html
-        "<html><body>Hello, world!</body></html>"
-      end
-    end
+class MyResource < Webmachine::Resource
+  def encodings_provided
+    {"gzip" => :encode_gzip, "identity" => :encode_identity}
+  end
+  def to_html
+    "<html><body>Hello, world!</body></html>"
+  end
+end
 ```
 There are many other HTTP features exposed to your resource through
-callbacks. Give them a try!
+{Webmachine::Resource::Callbacks}. Give them a try!
+### Configurator
+There's a configurator that allows you to set the ip address and port
+bindings as well as a different webserver adapter.  You can also add
+your routes in a block. Both of these call return the `Webmachine`
+module, so you could chain them if you like.
+```ruby
+require 'webmachine'
+require 'my_resource'
+Webmachine.routes do
+  add ['*'], MyResource
+end
+Webmachine.configure do |config|
+  config.ip = '127.0.0.1'
+  config.port = 3000
+  config.adapter = :Mongrel
+end
+# Start the server.
+Webmachine.run
+```
 ## Features
@@ -75,14 +100,14 @@ callbacks. Give them a try!
 * Most callbacks can interrupt the decision flow by returning an
   integer response code. You generally only want to do this when new
   information comes to light, requiring a modification of the response.
-* Supports WEBrick and Mongrel (1.2pre+). Other host servers are being
-  investigated.
-* Streaming/chunked response bodies are permitted as Enumerables or Procs.
+* Supports WEBrick and Mongrel (1.2pre+), and a Rack shim. Other host
+  servers are being investigated.
+* Streaming/chunked response bodies are permitted as Enumerables,
+  Procs, or Fibers!
 * Unlike the Erlang original, it does real Language negotiation.
 ## Problems/TODOs
-* Support streamed responses as Fibers.
 * 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
@@ -90,6 +115,33 @@ callbacks. Give them a try!
 ## Changelog
+### 0.3.0 November 9, 2011
+0.3.0 introduces some new features, refactorings, and now has 100%
+documentation coverage! Among the new features are minimal Rack
+compatibility, streaming responses via Fibers and a friendlier route
+definition syntax. Added Jamis Buck as a committer. Thank you for your
+contributions!
+* Chunked bodies are now wrapped in a way that works on webservers
+  that don't automatically produce them.
+* HTTP Basic Authentication is easy to add to resources, just include
+  `Webmachine::Resource::Authentication`.
+* Routes are a little less painful to add, you can now specify them
+  with `Webmachine.routes` which will be evaled into the `Dispatcher`.
+* The new default port is 8080.
+* Rack is minimally supported as a host server. _Don't put middleware
+  above Webmachine!_
+* Fibers can be used as streamed response bodies.
+* `Dispatcher#add_route` will now return the added `Route` instance.
+* The header-conversion code for CGI-style servers has been extracted
+  into `Webmachine::Headers`.
+* `Route#path_spec` is now public so that applications can inspect
+  existing routes, perhaps for URL generation.
+* `Request#query` now uses `CGI.unescape` so '+' characters are
+  correctly parsed.
+* YARD documentation has 100% coverage.
 ### 0.2.0 September 11, 2011
 0.2.0 includes an adapter for Mongrel and a central place for

data/Rakefile CHANGED Viewed

@@ -1,6 +1,16 @@
 require 'rubygems'
 require 'rubygems/package_task'
+begin
+  require 'yard'
+  require 'yard/rake/yardoc_task'
+  YARD::Rake::YardocTask.new do |doc|
+    doc.files = Dir["lib/**/*.rb"] + ['README.md']
+    doc.options = ["-m", "markdown"]
+  end
+rescue LoadError
+end
 def gemspec
   $webmachine_gemspec ||= Gem::Specification.load("webmachine.gemspec")
 end

data/lib/webmachine/adapters/mongrel.rb CHANGED Viewed

@@ -4,6 +4,7 @@ require 'webmachine/headers'
 require 'webmachine/request'
 require 'webmachine/response'
 require 'webmachine/dispatcher'
+require 'webmachine/chunked_body'
 module Webmachine
   module Adapters
@@ -26,9 +27,11 @@ module Webmachine
         config.join
       end
+      # A Mongrel handler for Webmachine
       class Handler < ::Mongrel::HttpHandler
+        # Processes an individual request from Mongrel through Webmachine.
         def process(wreq, wres)
-          header = http_headers(wreq.params, Webmachine::Headers.new)
+          header = Webmachine::Headers.from_cgi(wreq.params)
           request = Webmachine::Request.new(wreq.params["REQUEST_METHOD"],
                                             URI.parse(wreq.params["REQUEST_URI"]),
@@ -55,29 +58,22 @@ module Webmachine
               wres.write response.body
               wres.socket.flush
             when Enumerable
-              response.body.each { |part|
+              Webmachine::ChunkedBody.new(response.body).each { |part|
                 wres.write part
                 wres.socket.flush
               }
             else
               if response.body.respond_to?(:call)
-                wres.write part
-                wres.socket.flush
+                Webmachine::ChunkedBody.new(Array(response.body.call)).each { |part|
+                  wres.write part
+                  wres.socket.flush
+                }
               end
             end
           ensure
             response.body.close if response.body.respond_to? :close
           end
         end
-        def http_headers(env, headers)
-          env.inject(headers) do |h,(k,v)|
-            if k =~ /^HTTP_(\w+)$/
-              h[$1.tr("_", "-")] = v
-            end
-            h
-          end
-        end
       end
     end
   end

data/lib/webmachine/adapters/rack.rb ADDED Viewed

@@ -0,0 +1,50 @@
+require 'rack/request'
+require 'webmachine/version'
+require 'webmachine/headers'
+require 'webmachine/request'
+require 'webmachine/response'
+require 'webmachine/dispatcher'
+module Webmachine
+  module Adapters
+    # A minimal "shim" adapter to allow Webmachine to interface with Rack. The
+    # intention here is to allow Webmachine to run under Rack-compatible
+    # web-servers, like unicorn and pow, and is not intended to allow Webmachine
+    # to be "plugged in" to an existing Rack app as middleware.
+    #
+    # To use this adapter, create a config.ru file and populate it like so:
+    #
+    #     require 'webmachine/adapters/rack'
+    #
+    #     # put your own Webmachine resources in another file:
+    #     require 'my/resources'
+    #
+    #     run Webmachine::Adapters::Rack.new
+    #
+    # Servers like pow and unicorn will read config.ru by default and it should
+    # all "just work".
+    class Rack
+      # Handles a Rack-based request.
+      # @param [Hash] env the Rack environment
+      def call(env)
+        headers = Webmachine::Headers.from_cgi(env)
+        rack_req = ::Rack::Request.new env
+        request = Webmachine::Request.new(rack_req.request_method,
+                                          URI.parse(rack_req.url),
+                                          headers,
+                                          rack_req.body)
+        response = Webmachine::Response.new
+        Webmachine::Dispatcher.dispatch request, response
+        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
+        [response.code.to_i, response.headers, body || []]
+      end
+    end
+  end
+end

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

@@ -21,7 +21,9 @@ module Webmachine
         Thread.new { server.start }.join
       end
+      # WEBRick::HTTPServer that is run by the WEBrick adapter.
       class Server < ::WEBrick::HTTPServer
+        # Handles a request
         def service(wreq, wres)
           header = Webmachine::Headers.new
           wreq.each {|k,v| header[k] = v }

data/lib/webmachine/chunked_body.rb ADDED Viewed

@@ -0,0 +1,43 @@
+module Webmachine
+  # {ChunkedBody} is used to wrap an {Enumerable} object (like an enumerable
+  # {Response#body}) so it yields proper chunks for chunked transfer encoding.
+  #
+  #     case response.body
+  #     when String
+  #       socket.write(response.body)
+  #     when Enumerable
+  #       Webmachine::ChunkedBody.new(response.body).each do |chunk|
+  #         socket.write(chunk)
+  #       end
+  #     end
+  #
+  # This is needed for Ruby webservers which don't do the chunking themselves.
+  class ChunkedBody
+    # Delimiter for chunked encoding
+    CRLF = "\r\n"
+    # Final chunk in any chunked-encoding response
+    FINAL_CHUNK = "0#{CRLF}#{CRLF}"
+    # Creates a new {ChunkedBody} from the given {Enumerable}.
+    # @param [Enumerable] body the enumerable response body
+    # @return [ChunkedBody] the wrapped response body
+    def initialize(body)
+      @body = body
+    end
+    # Calls the given block once for each chunk, passing that chunk as a
+    # parameter.
+    # Returns an {Enumerator} if no block is given.
+    def each
+      return self.to_enum unless block_given?
+      @body.each do |chunk|
+        size = chunk.bytesize
+        next if size == 0
+        yield([size.to_s(16), CRLF, chunk, CRLF].join)
+      end
+      yield(FINAL_CHUNK)
+    end
+  end
+end

data/lib/webmachine/decision/conneg.rb CHANGED Viewed

@@ -87,6 +87,7 @@ module Webmachine
       # equals the tag, or if it exactly equals a prefix of the
       # tag such that the first tag character following the prefix
       # is "-".
+      # @api private
       def language_match(range, tag)
         range.downcase == tag.downcase || tag =~ /^#{Regexp.escape(range)}\-/i
       end
@@ -215,7 +216,7 @@ module Webmachine
         end
       end
-      # Like a {PriorityList}, but for {MediaTypes}, since they have
+      # Like a {PriorityList}, but for {MediaType}s, since they have
       # parameters in addition to q.
       # @private
       class MediaTypeList < PriorityList

data/lib/webmachine/decision/flow.rb CHANGED Viewed

@@ -6,8 +6,9 @@ require 'webmachine/translation'
 module Webmachine
   module Decision
     # This module encapsulates all of the decisions in Webmachine's
-    # flow-chart. These invoke {Resource} {Callbacks} to determine the
-    # appropriate response code, headers, and body for the response.
+    # flow-chart. These invoke {Webmachine::Resource::Callbacks} methods to
+    # determine the appropriate response code, headers, and body for
+    # the response.
     #
     # This module is included into {FSM}, which drives the processing
     # of the chart.
@@ -390,6 +391,7 @@ module Webmachine
         decision_test(resource.delete_resource, true, :m20b, 500)
       end
+      # Did the DELETE complete?
       def m20b
         decision_test(resource.delete_completed?, true, :o20, 202)
       end

data/lib/webmachine/decision/helpers.rb CHANGED Viewed

@@ -5,6 +5,7 @@ module Webmachine
   module Decision
     # Methods that assist the Decision {Flow}.
     module Helpers
+      # Pattern for quoted headers
       QUOTED = /^"(.*)"$/
       # Determines if the response has a body/entity set.
@@ -28,6 +29,8 @@ module Webmachine
         response.body = case body
                         when String # 1.8 treats Strings as Enumerable
                           resource.send(encoder, resource.send(charsetter, body))
+                        when Fiber
+                          FiberEncoder.new(resource, encoder, charsetter, body)
                         when Enumerable
                           EnumerableEncoder.new(resource, encoder, charsetter, body)
                         else
@@ -84,6 +87,7 @@ module Webmachine
         end
       end
+      # Adds caching-related headers to the response.
       def add_caching_headers
         if etag = resource.generate_etag
           response.headers['ETag'] = ensure_quoted_header(etag)