rackful 0.1.4 → 0.2.0

data/lib/rackful/server.rb

@@ -1,81 +1,68 @@
-# Required for parsing:
-#require 'forwardable' # Used to be for ResourceFactoryWrapper.
-
-# Required for running:
-
 module Rackful
 
-=begin markdown
-Rack compliant server class for implementing RESTful web services.
-=end
+# Rack compliant server class for implementing RESTful web services.
 class Server
 
 
-=begin markdown
-An object responding thread safely to method `#[]`.
-
-A {Server} has no knowledge, and makes no presumptions, about your URI namespace.
-It requires a _Resource Factory_ which produces {Resource Resources} given
-a certain absolute path.
-
-The Resource Factory you provide need only implement one method, with signature
-`Resource #[]( String path )`.
-This method will be called with a URI-encoded path string, and must return a
-{Resource}, or `nil` if there's no resource at the given path.
-
-For example, if a Rackful client
-tries to access a resource with URI {http://example.com/your/resource http://example.com/some/resource},
-then your Resource Factory can expect to be called like this:
-
-    resource = resource_factory[ '/your/resource' ]
-
-If there's no resource at the given path, but you'd still like to respond to
-`POST` or `PUT` requests to this path, you must return an
-{Resource#empty? empty resource}.
-@return [#[]]
-@see #initialize
-=end
-  attr_reader :resource_factory
+  # Constructor.
+  #
+  # This generic server class has no knowledge, and makes no presumptions,
+  # about your URI namespace. It depends on the code block you provide here
+  # to produce the {Resource} object which lives at a certain URI.
+  # This block will be called with a {URI::Generic#normalize! normalized}
+  # URI, and must return a {Resource}, or `nil` if there’s no
+  # resource at the given URI.
+  #
+  # If there’s no resource at the given URI, but you’d still like to respond to
+  # `POST` or `PUT` requests to this URI, you can return an
+  # {Resource#empty? empty resource}.
+  #
+  # The provided code block must be thread-safe and reentrant.
+  # @yieldparam uri [URI::Generic] The {URI::Generic::normalize! normalized}
+  #   URI of the requested resource.
+  # @yieldreturn [Resource] A (possibly {Resource#empty? empty}) resource, or nil.
+  def initialize( &resource_registry )
+    @resource_registry = resource_registry
+  end
 
 
-=begin markdown
-@param resource_factory [#[]] see Server#resource_factory
-=end
-  def initialize(resource_factory)
-    super()
-    @resource_factory = resource_factory
+  # Calls the code block passed to the {#initialize constructor}.
+  # @param uri [URI::HTTP, String]
+  # @return [Resource]
+  # @raise [HTTP404NotFound]
+  def resource_at(uri)
+    uri = URI(uri) unless uri.kind_of?( URI::Generic )
+    retval = @resource_registry.call( uri.normalize )
+    raise HTTP404NotFound unless retval
+    retval
   end
 
 
-=begin markdown
-As required by the Rack specification.
-
-For thread safety, this method clones `self`, which handles the request in
-{#call!}. A similar approach is taken by the Sinatra library.
-@return [Array<(status_code, response_headers, response_body)>]
-=end
-  def call(p_env)
-    start = Time.now
-    retval = dup.call! p_env
-    #$stderr.puts( p_env.inspect )
-    retval
+  # As required by the Rack specification.
+  #
+  # For thread safety, this method clones `self`, which handles the request in
+  # {#call!}.
+  # For reentrancy, the clone is stored in the environment.
+  # @param env [{String => Mixed}]
+  # @return [(status_code, response_headers, response_body)]
+  def call( env )
+    ( env['rackful.server'] ||= self.dup ).call!( env )
   end
 
 
-=begin markdown
-@return [Array<(status_code, response_headers, response_body)>]
-=end
-  def call!(p_env)
-    request = Request.new( self.resource_factory, p_env )
-    # See also Request::current():
-    Thread.current[:rackful_request] = request
+  # @see #call
+  # @return [(status_code, response_headers, response_body)]
+  def call!( env )
+    request = Request.new( env )
     response = Rack::Response.new
     begin
-      raise HTTP404NotFound, request.path \
-        unless resource = self.resource_factory[Path.new(request.path)]
-      unless resource.path == request.path
-        response.header['Content-Location'] = resource.path
-        request.content_path = resource.path
+      resource = resource_at( request.url )
+      request.canonical_uri = resource.uri
+      if request.url != request.canonical_uri.to_s
+        if %w{HEAD GET}.include?( request.request_method )
+          raise HTTP301MovedPermanently, request.canonical_uri
+        end
+        response.header['Content-Location'] = request.canonical_uri.to_s
       end
       request.assert_if_headers resource
       if %w{HEAD GET OPTIONS PUT DELETE}.include?( request.request_method )
@@ -84,32 +71,35 @@ For thread safety, this method clones `self`, which handles the request in
         resource.http_method request, response
       end
     rescue HTTPStatus => e
-      # Already handled by HTTPStatus#initialize:
-      #raise if $DEBUG && 500 <= e.status
-      bct = e.class.best_content_type request.accept, false
-      serializer = e.serializer(bct)
-      response = Rack::Response.new serializer, e.status, e.headers
-    ensure
-      # The next line fixes a small peculiarity in RFC2616: the response body of
-      # a `HEAD` request _must_ be empty, even for responses outside 2xx.
-      if request.head?
-        response.body = []
+      serializer = e.serializer(request)
+      response = Rack::Response.new
+      response['Content-Type'] = serializer.content_type
+      response.status = e.status
+      if serializer.respond_to? :headers
+        response.headers.merge!( serializer.headers )
       end
+      response.body = serializer
     end
-    if  201 == response.status &&
-        ( location = response['Location'] ) &&
-        ( new_resource = request.resource_factory[location] ) &&
-        ! new_resource.empty? \
-    or  ( (200...300) === response.status ||
-           304        ==  response.status ) &&
-        ! response['Location'] &&
-        ( new_resource = request.resource_factory[request.path] ) &&
-        ! new_resource.empty?
-      response.headers.merge! new_resource.default_headers
+    # The next line fixes a small peculiarity in RFC2616: the response body of
+    # a `HEAD` request _must_ be empty, even for responses outside 2xx.
+    if request.head?
+      response.body = []
+    end
+    begin
+      if  201 == response.status &&
+          ( location = response['Location'] ) &&
+          ( new_resource = resource_at( location ) ) &&
+          ! new_resource.empty? \
+      or  ( (200...300) === response.status ||
+             304        ==  response.status ) &&
+          ! response['Location'] &&
+          ( new_resource = resource_at( request.canonical_uri ) ) &&
+          ! new_resource.empty?
+        response.headers.merge! new_resource.default_headers
+      end
+    rescue HTTP404NotFound => e
     end
-    r = response.finish
-    #~ $stderr.puts r.inspect
-    r
+    response.finish
   end
 
 

data/lib/rackful/uri.rb

@@ -0,0 +1,150 @@
+# Extension and monkeypatch of Ruby’s StdLib URI::Generic class.
+class URI::Generic
+
+  unless method_defined? :uri_generic_normalize!
+    # Copy of the original StdLib
+    # [URI::Generic::normalize!](http://ruby-doc.org/stdlib/libdoc/uri/rdoc/URI/Generic.html#method-i-normalize-21)
+    # method.
+    alias_method :uri_generic_normalize!, :normalize!
+  end
+  
+  unless method_defined? :uri_generic_normalize
+    # Copy of the original StdLib
+    # [URI::Generic::normalize!](http://ruby-doc.org/stdlib/libdoc/uri/rdoc/URI/Generic.html#method-i-normalize-21)
+    # method.
+    alias_method :uri_generic_normalize, :normalize
+  end
+  
+  # (see #normalize!)
+  # @return [URI::Generic] a normalized copy of `self`.
+  def normalize
+    r = self.dup
+    r.normalize!
+    r
+  end
+
+  # Monkeypatch of [Ruby’s StdLib implementation](http://ruby-doc.org/stdlib/libdoc/uri/rdoc/URI/Generic.html#method-i-normalize-21).
+  # In addition to the default implementation, this implementation ensures that
+  #
+  # 1.  _no_ unreserved characters are pct-encoded, and
+  # 2.  all non-unreserved characters _are_ pct-encoded.
+  #
+  # Check [RFC3986](http://tools.ietf.org/html/rfc3986) syntax:
+  #
+  #     abempty = *( "/" *(unreserved / pct-encoded / sub-delims / ":" / "@") )
+  #     unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
+  #     sub-delims = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "="
+  # @return [self, nil] `self` if the URI was modified, or `nil` of the uri was
+  #   already in normal form.
+  def normalize!
+    #unless %r{\A(?:/(?:[a-z0-9\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})*)*\z}i === self.path
+    #  raise TypeError, "Can’t convert String #{self.path.inspect} to Rackful::Path"
+    #end
+    self.uri_generic_normalize!
+    path = '/' + self.segments( Encoding::BINARY ).collect do |segment|
+      segment.gsub(/([^a-zA-Z0-9\-._~]+)/n) {
+        '%'+$1.unpack('H2'*bytesize($1)).join('%').upcase
+      }
+    end.join('/')
+    if path == self.path
+      nil
+    else
+      self.path = path
+      self
+    end
+  end
+
+
+  # @return [Path] a copy of `self`, with a trailing slash.
+  def slashify
+    r = self.dup
+    r.slashify!
+    r
+  end
+
+
+  # Adds a trailing slash to `self` if necessary.
+  # @return [self]
+  def slashify!
+    if '/' != self.path[-1,1]
+      self.path += '/'
+      self
+    else
+      nil
+    end
+  end
+
+
+  # @return [Path] a copy of `self` without trailing slashes.
+  def unslashify
+    r = self.dup
+    r.unslashify!
+    r
+  end
+
+
+  # Removes trailing slashes from `self`.
+  # @return [self]
+  def unslashify!
+    path = self.path.sub( %r{/+\z}, '' )
+    if path == self.path
+      nil
+    else
+      self.path = path
+      self
+    end
+  end
+
+
+  # @return [Array<String>] Unencoded segments
+  def segments( encoding = Encoding::UTF_8 )
+    r = self.path.split(%r{/+}).collect do |s|
+      Rack::Utils.unescape( s, encoding )
+    end
+    r.shift
+    r
+  end
+
+
+  # Turns a relative URI (starting with `/`) into a relative path (starting with `./` or `../`)
+  # @param base_path [Path]
+  # @return [String] a relative URI
+  # @deprecated
+  def relative_deprecated base_path
+    case self
+    when base_path
+      # RFC2396, Section 4.2
+      return ''
+    when %r{(?:\A|/)\.\.?(?:/|\z)}
+      # self has abnormal absolute path,
+      # like "/./", "/../", "/x/../", ...
+      return self.dup
+    end
+
+    src_path = base_path.scan(%r{(?:\A|[^/]+)/})
+    dst_path = self.scan(%r{(?:\A|[^/]+)/?})
+
+    # discard same parts
+    while !dst_path.empty? && dst_path.first == src_path.first
+      src_path.shift
+      dst_path.shift
+    end
+
+    tmp = dst_path.join
+
+    # calculate
+    if src_path.empty?
+      if tmp.empty?
+        return './'
+      elsif dst_path.first.include?(':') # (see RFC2396 Section 5)
+        return './' + tmp
+      else
+        return tmp
+      end
+    end
+
+    return '../' * src_path.size + tmp
+  end
+
+
+end # class URI::Generic

data/mkdoc.sh

@@ -1,6 +1,8 @@
 #!/bin/bash
+# Nice options: server --reload
 
-cd "`dirname "$0"`"
+cd "`dirname "${BASH_SOURCE[0]}"`"
 
 rm -rf doc/* .yardoc/
-exec yard "$@"
+yard --yardopts .yardopts.user
+yard --yardopts .yardopts.devel

data/rackful.gemspec

@@ -2,14 +2,14 @@ Gem::Specification.new do |s|
 
   # Required properties:
   s.name        = 'rackful'
-  s.version     = '0.1.4'
+  s.version     = '0.2.0'
   s.summary     = "Library for building ReSTful web services with Rack"
   s.description = <<EOS
 Rackful provides a minimal interface for developing ReSTful web services with
-Rack and Ruby. Instead of writing HTTP method handlers, you'll implement
+Rack and Ruby. Instead of writing HTTP method handlers, you’ll implement
 resource objects, which expose their state at URLs.
 
-This version is not backward compatible with v0.0.x.
+This version is not backward compatible with v0.1.x.
 EOS
   s.files       = Dir[ '{*.md,example/*.ru,lib/**/*.rb}' ] +
                   %w( rackful.gemspec mkdoc.sh )
@@ -18,8 +18,9 @@ EOS
   s.author      = 'Pieter van Beek'
   s.email       = 'rackful@djinnit.com'
   s.license     = 'Apache License 2.0'
-  s.homepage    = 'http://pieterb.github.com/Rackful/'
+  s.homepage    = 'http://github.com/pieterb/Rackful'
 
-  s.add_runtime_dependency 'rack', '>= 1.4'
+  s.add_runtime_dependency 'rack',     '~> 1.5'
+  s.add_runtime_dependency 'nokogiri', '~> 1.6'
 
 end

metadata

@@ -1,87 +1,95 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: rackful
-version: !ruby/object:Gem::Version 
-  prerelease: 
-  version: 0.1.4
+version: !ruby/object:Gem::Version
+  version: 0.2.0
 platform: ruby
-authors: 
+authors:
 - Pieter van Beek
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-
-date: 2012-11-26 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2014-02-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: rack
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  prerelease: false
+  type: :runtime
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
   prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "1.4"
   type: :runtime
-  version_requirements: *id001
 description: |
   Rackful provides a minimal interface for developing ReSTful web services with
-  Rack and Ruby. Instead of writing HTTP method handlers, you'll implement
+  Rack and Ruby. Instead of writing HTTP method handlers, you’ll implement
   resource objects, which expose their state at URLs.
-  
-  This version is not backward compatible with v0.0.x.
 
+  This version is not backward compatible with v0.1.x.
 email: rackful@djinnit.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
+- CHANGES.md
+- LICENSE.md
 - RACKFUL.md
 - README.md
-- LICENSE.md
-- CHANGES.md
 - example/config.ru
+- lib/rackful.rb
+- lib/rackful/httpstatus.rb
+- lib/rackful/middleware.rb
+- lib/rackful/middleware/headerspoofing.rb
+- lib/rackful/middleware/methodoverride.rb
+- lib/rackful/parser.rb
+- lib/rackful/request.rb
 - lib/rackful/resource.rb
-- lib/rackful/path.rb
-- lib/rackful/http_status.rb
 - lib/rackful/serializer.rb
 - lib/rackful/server.rb
-- lib/rackful/request.rb
-- lib/rackful/middleware.rb
-- lib/rackful/middleware/method_spoofing.rb
-- lib/rackful/middleware/header_spoofing.rb
-- lib/rackful/middleware/relative_location.rb
-- lib/rackful.rb
-- rackful.gemspec
+- lib/rackful/uri.rb
 - mkdoc.sh
-homepage: http://pieterb.github.com/Rackful/
-licenses: 
+- rackful.gemspec
+homepage: http://github.com/pieterb/Rackful
+licenses:
 - Apache License 2.0
-post_install_message: 
+metadata: {}
+post_install_message:
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
-  none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
-  none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
-rubyforge_project: 
-rubygems_version: 1.8.24
-signing_key: 
-specification_version: 3
+rubyforge_project:
+rubygems_version: 2.2.0
+signing_key:
+specification_version: 4
 summary: Library for building ReSTful web services with Rack
 test_files: []
-
+has_rdoc: