webmachine 0.2.0 → 0.3.0

data/lib/webmachine/dispatcher.rb

@@ -12,9 +12,12 @@ module Webmachine
     # order they are added.
     # @see Route#new
     def add_route(*args)
-      @routes << Route.new(*args)
+      route = Route.new(*args)
+      @routes << route
+      route
     end
-
+    alias :add :add_route
+    
     # Dispatches a request to the appropriate {Resource} in the
     # dispatch list. If a matching resource is not found, a "404 Not
     # Found" will be rendered.
@@ -37,4 +40,14 @@ module Webmachine
       @routes = []
     end
   end
+
+  # Evaluates the passed block in the context of
+  # {Webmachine::Dispatcher} for use in adding a number of routes at
+  # once.
+  # @return [Webmachine] self
+  # @see Webmachine::Dispatcher.add_route
+  def self.routes(&block)
+    Dispatcher.module_eval(&block)
+    self
+  end
 end

data/lib/webmachine/dispatcher/route.rb

@@ -10,6 +10,10 @@ module Webmachine
       #   subclass of {Resource}
       attr_reader :resource
 
+      # @return [Array<String|Symbol>] the list of path segments
+      #   used to define this route (see #initialize).
+      attr_reader :path_spec
+
       # When used in a path specification, will match all remaining
       # segments
       MATCH_ALL = '*'.freeze

data/lib/webmachine/fiber18.rb

@@ -0,0 +1,88 @@
+# -*- coding: utf-8 -*-
+# Poor Man's Fiber (API compatible Thread based Fiber implementation for Ruby 1.8)
+# (c) 2008 Aman Gupta (tmm1)
+
+unless defined? Fiber
+  require 'thread'
+
+  # Raised by {Fiber} when they are used improperly
+  class FiberError < StandardError; end
+
+  # Implements a reasonably-compatible Fiber class that can be used on
+  # Rubies that have 1.8-style APIs.
+  class Fiber
+    # @yield the block that should be executed inside the Fiber
+    def initialize
+      raise ArgumentError, 'new Fiber requires a block' unless block_given?
+
+      @yield = Queue.new
+      @resume = Queue.new
+
+      @thread = Thread.new{ @yield.push [ *yield(*@resume.pop) ] }
+      @thread.abort_on_exception = true
+      @thread[:fiber] = self
+    end
+    attr_reader :thread
+
+    # Returns true if the fiber can still be resumed (or transferred
+    # to). After finishing execution of the fiber block this method
+    # will always return false.
+    def alive?
+      @thread.alive?
+    end
+
+    # Resumes the fiber from the point at which the last Fiber.yield
+    # was called, or starts running it if it is the first call to
+    # resume. Arguments passed to resume will be the value of the
+    # Fiber.yield expression or will be passed as block parameters to
+    # the fiber’s block if this is the first resume.
+    #
+    # Alternatively, when resume is called it evaluates to the arguments
+    # passed to the next Fiber.yield statement inside the fiber’s block or
+    # to the block value if it runs to completion without any Fiber.yield
+    def resume *args
+      raise FiberError, 'dead fiber called' unless @thread.alive?
+      @resume.push(args)
+      result = @yield.pop
+      result.size > 1 ? result : result.first
+    end
+
+    # Yields control back to the context that resumed this fiber,
+    # passing along any arguments that were passed to it. The fiber
+    # will resume processing at this point when resume is called
+    # next. Any arguments passed to the next resume will be the value
+    # that this Fiber.yield expression evaluates to.
+    # @note This method is only called internally. In your code, use
+    #   {Fiber.yield}.
+    def yield *args
+      @yield.push(args)
+      result = @resume.pop
+      result.size > 1 ? result : result.first
+    end
+
+    # Yields control back to the context that resumed the fiber,
+    # passing along any arguments that were passed to it. The fiber
+    # will resume processing at this point when resume is called
+    # next. Any arguments passed to the next resume will be the value
+    # that this Fiber.yield expression evaluates to.  This will raise
+    # a {FiberError} if you are not inside a {Fiber}.
+    # @raise FiberError
+    def self.yield *args
+      raise FiberError, "can't yield from root fiber" unless fiber = Thread.current[:fiber]
+      fiber.yield(*args)
+    end
+
+    # Returns the current fiber.  If you are not running in the
+    # context of a fiber this method will raise a {FiberError}.
+    # @raise FiberError
+    def self.current
+      Thread.current[:fiber] or raise FiberError, 'not inside a fiber'
+    end
+
+    # Returns a string containing a human-readable representation of
+    # this Fiber.
+    def inspect
+      "#<#{self.class}:0x#{self.object_id.to_s(16)}>"
+    end
+  end
+end

data/lib/webmachine/headers.rb

@@ -1,18 +1,33 @@
 module Webmachine
   # Case-insensitive Hash of Request headers
   class Headers < ::Hash
+    # Convert CGI-style Hash into Request headers
+    # @param [Hash] env a hash of CGI-style env/headers
+    def self.from_cgi(env)
+      env.inject(new) do |h,(k,v)|
+        if k =~ /^HTTP_(\w+)$/
+          h[$1.tr("_", "-")] = v
+        end
+        h
+      end
+    end
+
+    # Fetch a header
     def [](key)
       super transform_key(key)
     end
 
+    # Set a header
     def []=(key,value)
       super transform_key(key), value
     end
 
+    # Delete a header
     def delete(key)
       super transform_key(key)
     end
-    
+
+    # Select matching headers
     def grep(pattern)
       self.class[select { |k,_| pattern === k }]
     end

data/lib/webmachine/media_type.rb

@@ -51,6 +51,9 @@ module Webmachine
       @type == "*/*" && @params.empty?
     end
 
+    # @return [true,false] Are these two types strictly equal?
+    # @param other the other media type.
+    # @see MediaType.parse
     def ==(other)
       other = self.class.parse(other)
       other.type == type && other.params == params

data/lib/webmachine/request.rb

@@ -1,20 +1,30 @@
+require 'cgi'
 require 'forwardable'
 
 module Webmachine
-  # This represents a single HTTP request sent from a client.
+  # Request represents a single HTTP request sent from a client. It
+  # should be instantiated by {Adapters} when a request is received
   class Request
     extend Forwardable
     attr_reader :method, :uri, :headers, :body
     attr_accessor :disp_path, :path_info, :path_tokens
 
-    def initialize(meth, uri, headers, body)
-      @method, @uri, @headers, @body = meth, uri, headers, body
+    # @param [String] method the HTTP request method
+    # @param [URI] uri the requested URI, including host, scheme and
+    #   port
+    # @param [Headers] headers the HTTP request headers
+    # @param [String,#to_s,#each,nil] body the entity included in the
+    #   request, if present
+    def initialize(method, uri, headers, body)
+      @method, @uri, @headers, @body = method, uri, headers, body
     end
 
     def_delegators :headers, :[]
 
-    # @private
-    def method_missing(m, *args)
+    # Enables quicker access to request headers by using a
+    # lowercased-underscored version of the header name, e.g.
+    # `if_unmodified_since`.
+    def method_missing(m, *args, &block)
       if m.to_s =~ /^(?:[a-z0-9])+(?:_[a-z0-9]+)*$/i
         # Access headers more easily as underscored methods.
         self[m.to_s.tr('_', '-')]
@@ -23,7 +33,7 @@ module Webmachine
       end
     end
 
-    # Whether the request body is present.
+    # @return[true, false] Whether the request body is present.
     def has_body?
       !(body.nil? || body.empty?)
     end
@@ -46,7 +56,7 @@ module Webmachine
       unless @query
         @query = {}
         uri.query.split(/&/).each do |kv|
-          k, v = URI.unescape(kv).split(/=/)
+          k, v = CGI.unescape(kv).split(/=/)
           @query[k] = v if k && v
         end
       end

data/lib/webmachine/resource.rb

@@ -1,5 +1,6 @@
 require 'webmachine/resource/callbacks'
 require 'webmachine/resource/encodings'
+require 'webmachine/resource/authentication'
 
 module Webmachine
   # Resource is the primary building block of Webmachine applications,
@@ -24,7 +25,7 @@ module Webmachine
     attr_reader :request, :response
 
     # Creates a new {Resource}, initializing it with the request and
-    # response. Note that you may still override {#initialize} to
+    # response. Note that you may still override the `initialize` method to
     # initialize your resource. It will be called after the request
     # and response ivars are set.
     # @param [Request] request the request object

data/lib/webmachine/resource/authentication.rb

@@ -0,0 +1,35 @@
+module Webmachine
+  class Resource
+    # Helper methods that can be included in your
+    # {Webmachine::Resource} to assist in performing HTTP
+    # Authentication.
+    module Authentication
+      # Pattern for matching Authorization headers that use the Basic
+      # auth scheme.
+      BASIC_HEADER = /^Basic (.*)$/i.freeze
+
+      # A simple implementation of HTTP Basic auth. Call this from the
+      # {Webmachine::Resource::Callbacks#is_authorized?} callback,
+      # giving it a block which will be yielded the username and
+      # password and return true or false.      
+      # @param [String] header the value of the Authentication request
+      #   header, passed to the {Callbacks#is_authorized?} callback.
+      # @param [String] realm the "realm", or description of the
+      #   resource that requires authentication
+      # @return [true, String] true if the client is authorized, or
+      #   the appropriate WWW-Authenticate header
+      # @yield [user, password] a block that will verify the client-provided user/password
+      #   against application constraints
+      # @yieldparam [String] user the passed username
+      # @yieldparam [String] password the passed password
+      # @yieldreturn [true,false] whether the username/password is correct
+      def basic_auth(header, realm="Webmachine")
+        if header =~ BASIC_HEADER && (yield *$1.unpack('m*').first.split(/:/,2))
+          true
+        else
+          %Q[Basic realm="#{realm}"]
+        end
+      end
+    end
+  end
+end

data/lib/webmachine/resource/callbacks.rb

@@ -1,6 +1,10 @@
 module Webmachine
   class Resource
-    # These
+    # These methods are the primary way your {Webmachine::Resource}
+    # instance interacts with HTTP and the
+    # {Webmachine::Decision::FSM}. Implementing a callback can change
+    # the portions of the graph that are made available to your
+    # application.
     module Callbacks
       # Does the resource exist? Returning a falsey value (false or nil)
       # will result in a '404 Not Found' response. Defaults to true.
@@ -195,12 +199,13 @@ module Webmachine
 
       # This should return an array of pairs where each pair is of the
       # form [mediatype, :handler] where mediatype is a String of
-      # Content-Type format and :handler is a Symbol naming the method
-      # which can provide a resource representation in that media
-      # type. For example, if a client request includes an 'Accept'
-      # header with a value that does not appear as a first element in
-      # any of the return pairs, then a '406 Not Acceptable' will be
-      # sent.  Default is [['text/html', :to_html]].
+      # Content-Type format (or {Webmachine::MediaType}) and :handler
+      # is a Symbol naming the method which can provide a resource
+      # representation in that media type. For example, if a client
+      # request includes an 'Accept' header with a value that does not
+      # appear as a first element in any of the return pairs, then a
+      # '406 Not Acceptable' will be sent.  Default is [['text/html',
+      # :to_html]].
       # @return an array of mediatype/handler pairs
       # @api callback
       def content_types_provided
@@ -233,9 +238,9 @@ module Webmachine
       # This should return a list of language tags provided by the
       # resource. Default is the empty Array, in which the content is
       # in no specific language.
-      # @return [Array<String>] a list of provided languages      
+      # @return [Array<String>] a list of provided languages
       # @api callback
-      def languages_provided        
+      def languages_provided
         []
       end
 
@@ -247,7 +252,7 @@ module Webmachine
       def language_chosen(lang)
         @language = lang
       end
-      
+
       # This should return a hash of encodings mapped to encoding
       # methods for Content-Encodings your resource wants to
       # provide. The encoding will be applied to the response body

data/lib/webmachine/response.rb

@@ -33,10 +33,11 @@ module Webmachine
     end
 
     # Indicate that the response should be a redirect. This is only
-    # used when processing a POST request in {Callbacks#process_post}
-    # to indicate that the client should request another resource
-    # using GET. Either pass the URI of the target resource, or
-    # manually set the Location header using {#headers}.
+    # used when processing a POST request in
+    # {Resource::Callbacks#process_post} to indicate that the client
+    # should request another resource using GET. Either pass the URI
+    # of the target resource, or manually set the Location header
+    # using {#headers}.
     # @param [String, URI] location the target of the redirection
     def do_redirect(location=nil)
       headers['Location'] = location.to_s if location

data/lib/webmachine/streaming.rb

@@ -1,27 +1,63 @@
+begin
+  require 'fiber'
+rescue LoadError
+  require 'webmachine/fiber18'
+end
+
 module Webmachine
-  class StreamingEncoder
-    def initialize(resource, encoder, charsetter, body)
-      @resource, @encoder, @charsetter, @body = resource, encoder, charsetter, body
-    end
-  end
+  # 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))
+      body.each do |block|
+        yield resource.send(encoder, resource.send(charsetter, block.to_s))
       end
     end
   end
 
+  # 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))
+      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
+
+  # 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
 end

data/lib/webmachine/translation.rb

@@ -3,7 +3,14 @@ require 'i18n'
 I18n.config.load_path << File.expand_path("../locale/en.yml", __FILE__)
 
 module Webmachine
+  # Provides an interface to the I18n library specifically for
+  # {Webmachine}'s messages.
   module Translation
+    # Interpolates an internationalized string.
+    # @param [String] key the name of the string to interpolate
+    # @param [Hash] options options to pass to I18n, including
+    #   variables to interpolate.
+    # @return [String] the interpolated string
     def t(key, options={})
       ::I18n.t(key, options.merge(:scope => :webmachine))
     end

data/lib/webmachine/version.rb

@@ -1,4 +1,8 @@
 module Webmachine
-  VERSION = "0.2.0"
+  # Library version
+  VERSION = "0.3.0"
+
+  # String for use in "Server" HTTP response header, which includes
+  # the {VERSION}.
   SERVER_STRING = "Webmachine-Ruby/#{VERSION}"
 end