webmachine 1.0.0 → 1.1.0

data/lib/webmachine/decision/fsm.rb

@@ -1,5 +1,4 @@
 require 'webmachine/decision/helpers'
-require 'webmachine/decision/fsm'
 require 'webmachine/translation'
 
 module Webmachine
@@ -25,7 +24,7 @@ module Webmachine
         trace_request(request)
         loop do
           trace_decision(state)
-          result = send(state)
+          result = handle_exceptions { send(state) }
           case result
           when Fixnum # Response code
             respond(result)
@@ -36,18 +35,26 @@ module Webmachine
             raise InvalidResource, t('fsm_broke', :state => state, :result => result.inspect)
           end
         end
-      rescue MalformedRequest => malformed
-        Webmachine.render_error(400, request, response, :message => malformed.message)
-        respond(400)
-      rescue Exception => e # Handle all exceptions without crashing the server
-        code = resource.handle_exception(e)
-        code = (100...600).include?(code) ? (code) : (500)
-        respond(code)
+      rescue Exception => e
+        Webmachine.render_error(500, request, response, :message => e.message)
+      ensure
+        trace_response(response)
       end
 
       private
 
+      def handle_exceptions
+        yield
+      rescue MalformedRequest => e
+        Webmachine.render_error(400, request, response, :message => e.message)
+        400
+      rescue Exception => e
+        code = resource.handle_exception(e)
+        (100...600).include?(code) ? (code) : (500)
+      end
+
       def respond(code, headers={})
+        response.code = code
         response.headers.merge!(headers)
         case code
         when 404
@@ -56,10 +63,13 @@ module Webmachine
           response.headers.delete('Content-Type')
           add_caching_headers
         end
-        response.code = code
-        resource.finish_request
+
+        response.code = handle_exceptions do
+          resource.finish_request
+          response.code
+        end
+
         ensure_content_length
-        trace_response(response)
       end
 
       # When tracing is disabled, this does nothing.

data/lib/webmachine/decision/helpers.rb

@@ -1,12 +1,15 @@
+require 'stringio'
 require 'webmachine/streaming'
 require 'webmachine/media_type'
+require 'webmachine/quoted_string'
+require 'webmachine/etags'
 
 module Webmachine
   module Decision
     # Methods that assist the Decision {Flow}.
     module Helpers
-      # Pattern for quoted headers
-      QUOTED = /^"(.*)"$/
+      include QuotedString
+      include Streaming
 
       # Determines if the response has a body/entity set.
       def has_response_body?
@@ -29,6 +32,8 @@ module Webmachine
         response.body = case body
                         when String # 1.8 treats Strings as Enumerable
                           resource.send(encoder, resource.send(charsetter, body))
+                        when IO, StringIO
+                          IOEncoder.new(resource, encoder, charsetter, body)
                         when Fiber
                           FiberEncoder.new(resource, encoder, charsetter, body)
                         when Enumerable
@@ -40,7 +45,7 @@ module Webmachine
                             resource.send(encoder, resource.send(charsetter, body))
                           end
                         end
-        if String === response.body
+        if body_is_fixed_length?
           set_content_length
         else
           response.headers.delete 'Content-Length'
@@ -48,24 +53,6 @@ module Webmachine
         end
       end
 
-      # Ensures that a header is quoted (like ETag)
-      def ensure_quoted_header(value)
-        if value =~ QUOTED
-          value
-        else
-          '"' << value << '"'
-        end
-      end
-
-      # Unquotes request headers (like ETag)
-      def unquote_header(value)
-        if value =~ QUOTED
-          $1
-        else
-          value
-        end
-      end
-
       # Assists in receiving request bodies
       def accept_helper
         content_type = MediaType.parse(request.content_type || 'application/octet-stream')
@@ -90,7 +77,7 @@ module Webmachine
       # Adds caching-related headers to the response.
       def add_caching_headers
         if etag = resource.generate_etag
-          response.headers['ETag'] = ensure_quoted_header(etag)
+          response.headers['ETag'] = ETag.new(etag).to_s
         end
         if expires = resource.expires
           response.headers['Expires'] = expires.httpdate
@@ -106,7 +93,7 @@ module Webmachine
         case
         when response.headers['Transfer-Encoding']
           return
-        when [204, 304].include?(response.code)
+        when [204, 205, 304].include?(response.code)
           response.headers.delete 'Content-Length'
         when has_response_body?
           set_content_length
@@ -123,6 +110,13 @@ module Webmachine
           response.headers['Content-Length'] = response.body.length.to_s
         end
       end
+
+      # Determines whether the response is of a fixed lenghth, i.e. it
+      # is a String or IO with known size.
+      def body_is_fixed_length?
+        response.body.respond_to?(:bytesize) &&
+          Fixnum === response.body.bytesize
+      end
     end # module Helpers
   end # module Decision
 end # module Webmachine

data/lib/webmachine/etags.rb

@@ -0,0 +1,69 @@
+require 'webmachine/quoted_string'
+
+module Webmachine
+  # A wrapper around entity tags that encapsulates their semantics.
+  # This class by itself represents a "strong" entity tag.
+  class ETag
+    include QuotedString
+    # The pattern for a weak entity tag
+    WEAK_ETAG = /^W\/#{QUOTED_STRING}$/.freeze
+
+    def self.new(etag)
+      return etag if ETag === etag
+      klass = etag =~ WEAK_ETAG ? WeakETag : self
+      klass.send(:allocate).tap do |obj|
+        obj.send(:initialize, etag)
+      end
+    end
+
+    attr_reader :etag
+
+    def initialize(etag)
+      @etag = quote(etag)
+    end
+
+    # An entity tag is equivalent to another entity tag if their
+    # quoted values are equivalent. It is also equivalent to a String
+    # which represents the equivalent ETag.
+    def ==(other)
+      case other
+      when ETag
+        other.etag == @etag
+      when String
+        quote(other) == @etag
+      end
+    end
+
+    # Converts the entity tag into a string appropriate for use in a
+    # header.
+    def to_s
+      quote @etag
+    end
+  end
+
+  # A Weak Entity Tag, which can be used to compare entities which are
+  # semantically equivalent, but do not have the same byte-content. A
+  # WeakETag is equivalent to another entity tag if the non-weak
+  # portions are equivalent. It is also equivalent to a String which
+  # represents the equivalent strong or weak ETag.
+  class WeakETag < ETag
+    # Converts the WeakETag to a String for use in a header.
+    def to_s
+      "W/#{super}"
+    end
+
+    private
+    def unquote(str)
+      if str =~ WEAK_ETAG
+        unescape_quotes $1
+      else
+        super
+      end
+    end
+
+    def quote(str)
+      str = unescape_quotes($1) if str =~ WEAK_ETAG
+      super
+    end
+  end
+end

data/lib/webmachine/headers.rb

@@ -3,6 +3,7 @@ module Webmachine
   class Headers < ::Hash
     # Convert CGI-style Hash into Request headers
     # @param [Hash] env a hash of CGI-style env/headers
+    # @return [Webmachine::Headers]
     def self.from_cgi(env)
       env.inject(new) do |h,(k,v)|
         if k =~ /^HTTP_(\w+)$/ || k =~ /^(CONTENT_(?:TYPE|LENGTH))$/
@@ -12,6 +13,24 @@ module Webmachine
       end
     end
 
+    # Creates a new headers object populated with the given objects.
+    # It supports the same forms as {Hash.[]}.
+    #
+    # @overload [](key, value, ...)
+    #   Pairs of keys and values
+    #   @param [Object] key
+    #   @param [Object] value
+    # @overload [](array)
+    #   Array of key-value pairs
+    #   @param [Array<Object, Object>, ...]
+    # @overload [](object)
+    #   Object convertible to a hash
+    #   @param [Object]
+    # @return [Webmachine::Headers]
+    def self.[](*args)
+      super(super(*args).map {|k, v| [k.to_s.downcase, v]})
+    end
+
     # Fetch a header
     def [](key)
       super transform_key(key)
@@ -22,6 +41,29 @@ module Webmachine
       super transform_key(key), value
     end
 
+    # Returns the value for the given key. If the key can't be found,
+    # there are several options:
+    # With no other arguments, it will raise a KeyError exception;
+    # if default is given, then that will be returned;
+    # if the optional code block is specified, then that will be run and its
+    # result returned.
+    #
+    # @overload fetch(key)
+    #   A key
+    #   @param [Object] key
+    # @overload fetch(key, default)
+    #   A key and a default value
+    #   @param [Object] key
+    #   @param [Object] default
+    # @overload fetch(key) {|key| block }
+    #   A key and a code block
+    #   @param [Object]
+    #   @yield [key] Passes the key to the block
+    # @return [Object] the value for the key or the default
+    def fetch(*args, &block)
+      super(transform_key(args.shift), *args, &block)
+    end
+
     # Delete a header
     def delete(key)
       super transform_key(key)

data/lib/webmachine/quoted_string.rb

@@ -0,0 +1,39 @@
+module Webmachine
+  # Helper methods for dealing with the 'quoted-string' type often
+  # present in header values.
+  module QuotedString
+    # The pattern for a 'quoted-string' type
+    QUOTED_STRING = /"((?:\\"|[^"])*)"/.freeze
+
+    # The pattern for a 'quoted-string' type, without any other content.
+    QS_ANCHORED = /^#{QUOTED_STRING}$/.freeze
+
+    # Removes surrounding quotes from a quoted-string
+    def unquote(str)
+      if str =~ QS_ANCHORED
+        unescape_quotes $1
+      else
+        str
+      end
+    end
+
+    # Ensures that quotes exist around a quoted-string
+    def quote(str)
+      if str =~ QS_ANCHORED
+        str
+      else
+        %Q{"#{escape_quotes str}"}
+      end
+    end
+
+    # Escapes quotes within a quoted string.
+    def escape_quotes(str)
+      str.gsub(/"/, '\\"')
+    end
+
+    # Unescapes quotes within a quoted string
+    def unescape_quotes(str)
+      str.gsub(%r{\\}, '')
+    end
+  end
+end

data/lib/webmachine/resource.rb

@@ -1,5 +1,6 @@
 require 'webmachine/resource/callbacks'
 require 'webmachine/resource/encodings'
+require 'webmachine/resource/entity_tags'
 require 'webmachine/resource/authentication'
 require 'webmachine/resource/tracing'
 
@@ -22,6 +23,7 @@ module Webmachine
   class Resource
     include Callbacks
     include Encodings
+    include EntityTags
     include Tracing
 
     attr_reader :request, :response
@@ -41,6 +43,21 @@ module Webmachine
       instance
     end
 
+    #
+    # Starts a web server that serves requests for a subclass of
+    # Webmachine::Resource.
+    #
+    # @return [void]
+    #
+    def self.run
+      resource = self
+      Application.new do |app|
+        app.routes do |router|
+          router.add ["*"], resource
+        end
+      end.run
+    end
+
     private
     # When no specific charsets are provided, this acts as an identity
     # on the response body. Probably deserves some refactoring.

data/lib/webmachine/resource/callbacks.rb

@@ -88,7 +88,7 @@ module Webmachine
 
       # If the request includes any invalid Content-* headers, this
       # should return false, which will result in a '501 Not
-      # Implemented' response. Defaults to false.
+      # Implemented' response. Defaults to true.
       # @param [Hash] content_headers Request headers that begin with
       #     'Content-'
       # @return [true,false] Whether the Content-* headers are invalid

data/lib/webmachine/resource/entity_tags.rb

@@ -0,0 +1,17 @@
+require 'webmachine/etags'
+
+module Webmachine
+  class Resource
+    module EntityTags
+      # Marks a generated entity tag (etag) as "weak", meaning that
+      # other representations of the resource may be semantically equivalent.
+      # @return [WeakETag] a weak version of the given ETag string
+      # @param [String] str the ETag to mark as weak
+      # @see http://tools.ietf.org/html/rfc2616#section-13.3.3
+      # @see http://tools.ietf.org/html/rfc2616#section-14.19
+      def weak_etag(str)
+        WeakETag.new(str)
+      end
+    end
+  end
+end

data/lib/webmachine/streaming.rb

@@ -1,63 +1,11 @@
-begin
-  require 'fiber'
-rescue LoadError
-  require 'webmachine/fiber18'
-end
-
 module Webmachine
-  # Subclasses of this class implement means for streamed/chunked
-  # response bodies to be coerced to the negotiated character set and
-  # encoded automatically as they are output to the client.
-  # @api private
-  StreamingEncoder = Struct.new(:resource, :encoder, :charsetter, :body)
-
-  # Implements a streaming encoder for Enumerable response bodies, such as
-  # Arrays.
-  # @api private
-  class EnumerableEncoder < StreamingEncoder
-    include Enumerable
-
-    # Iterates over the body, encoding and yielding individual chunks
-    # of the response entity.
-    # @yield [chunk]
-    # @yieldparam [String] chunk a chunk of the response, encoded
-    def each
-      body.each do |block|
-        yield resource.send(encoder, resource.send(charsetter, block.to_s))
-      end
-    end
-  end # class EnumerableEncoder
-
-  # Implements a streaming encoder for callable bodies, such as
-  # Proc. (essentially futures)
-  # @api private
-  class CallableEncoder < StreamingEncoder
-    # Encodes the output of the body Proc.
-    # @return [String]
-    def call
-      resource.send(encoder, resource.send(charsetter, body.call.to_s))
-    end
-
-    # Converts this encoder into a Proc.
-    # @return [Proc] a closure that wraps the {#call} method
-    # @see #call
-    def to_proc
-      method(:call).to_proc
-    end
-  end # class CallableEncoder
-
-  # Implements a streaming encoder for Fibers with the same API as the
-  # EnumerableEncoder. This will resume the Fiber until it terminates
-  # or returns a falsey value.
-  # @api private
-  class FiberEncoder < EnumerableEncoder
-
-    # Iterates over the body by yielding to the fiber.
-    # @api private
-    def each
-      while body.alive? && chunk = body.resume
-        yield resource.send(encoder, resource.send(charsetter, chunk.to_s))
-      end
-    end
-  end # class FiberEncoder
+  # Namespace for classes that support streaming response bodies.
+  module Streaming
+  end # module Streaming
 end # module Webmachine
+
+require 'webmachine/streaming/encoder'
+require 'webmachine/streaming/enumerable_encoder'
+require 'webmachine/streaming/io_encoder'
+require 'webmachine/streaming/callable_encoder'
+require 'webmachine/streaming/fiber_encoder'