rackful 0.1.4 → 0.2.0

data/lib/rackful/middleware.rb

@@ -1,3 +1,2 @@
-require 'rackful/middleware/header_spoofing.rb'
-require 'rackful/middleware/method_spoofing.rb'
-require 'rackful/middleware/relative_location.rb'
+require 'rackful/middleware/headerspoofing.rb'
+require 'rackful/middleware/methodoverride.rb'

data/lib/rackful/middleware/headerspoofing.rb

@@ -0,0 +1,49 @@
+# encoding: utf-8
+# Required for parsing:
+require 'rackful'
+
+# Required for running:
+
+
+# Rack middleware that provides header spoofing.
+#
+# If you use this middleware, then clients are allowed to spoof an HTTP header
+# by specifying a `_http_SOME_HEADER=...` request parameter, for example
+# `http://example.com/some_resource?_http_DEPTH=infinity`.
+#
+# This can be useful if you want to specify certain request headers from within
+# a normal web browser.
+#
+# This middleware won’t work well together with Digest Authentication.
+# @example Using this middleware
+#   require 'rackful/middleware/header_spoofing'
+#   use Rackful::HeaderSpoofing
+class Rackful::HeaderSpoofing
+
+def initialize app
+  @app = app
+end
+
+def call env
+  new_query_string = env['QUERY_STRING'].
+    split('&', -1).
+    select {
+      |p|
+      p = p.split('=', 2)
+      if  /\A_http_([a-z]+(?:[\-_][a-z]+)*)\z/i === p[0]
+        header_name = p[0].gsub('-', '_').upcase[1..-1]
+        env[header_name] = p[1]
+        false
+      else
+        true
+      end
+    }.
+    join('&')
+  if env['QUERY_STRING'] != new_query_string
+    env['rackful.header_spoofing.QUERY_STRING'] = env['QUERY_STRING']
+    env['QUERY_STRING'] = new_query_string
+  end
+  @app.call env
+end
+
+end # Rackful::HeaderSpoofing

data/lib/rackful/middleware/methodoverride.rb

@@ -0,0 +1,136 @@
+# encoding: utf-8
+# Required for parsing:
+require 'rackful'
+
+# Required for running:
+require 'set'
+
+
+# Middleware that provides method spoofing, like {Rack::MethodOverride}.
+#
+# If you use this middleware, then clients are allowed to spoof an HTTP method
+# by specifying a `_method=...` request parameter, for example
+# `http://example.com/some_resource?_method=DELETE`.
+#
+# This can be useful if you want to perform `PUT` and `DELETE` requests from
+# within a browser, of when you want to perform a `GET` requests with (too)
+# many parameters, exceeding the maximum URI length in your client or server.
+# In that case, you can put the parameters in a `POST` body, like this:
+#
+#     POST /some_resource HTTP/1.1
+#     Host: example.com
+#     Content-Type: application/x-www-form-urlencoded
+#     Content-Length: 123456789
+#      
+#     param_1=hello&param_2=world&param_3=...
+#
+# Caveats:
+#
+# *   this middleware won’t work well together with Digest Authentication.
+# *   When a `POST` request is converted to a `GET` request, the entire request
+#     body is loaded into memory, which creates an attack surface for
+#     DoS-attacks. Hence, the maximum request body size is limited (see
+#     {POST_TO_GET_REQUEST_BODY_MAX_SIZE} and {#initialize}). You should choose this
+#     limit carefully, and/or include this middleware *after* your security
+#     middlewares.
+#
+# Improvements over Rack::MethodOverride (v1.5.2):
+#
+# *   Rack::MethodOverride requires the original method to be `POST`. We allow
+#     the following overrides (`ORIGINAL_METHOD` → `OVERRIDE_WITH`):
+#     *   `GET` → `DELETE`, `HEAD` and `OPTIONS`
+#     *   `POST` → `GET`, `PATCH` and `PUT`
+# *   Rack::MethodOverride doesn’t touch `env['QUERY_STRING']`. We remove
+#     parameter `_method` if it was handled (but still leave it there if it
+#     wasn’t handled for some reason).
+# *   Rackful::MethodOverride is documented ;-)
+# @example Using this middleware
+#   require 'rackful/middleware/method_override'
+#   use Rackful::MethodOverride
+class Rackful::MethodOverride
+
+  METHOD_OVERRIDE_PARAM_KEY = '_method'.freeze
+  
+  POST_TO_GET_REQUEST_BODY_MAX_SIZE = 1024 * 1024
+
+  ALLOWED_OVERRIDES = {
+    'GET'.freeze  => [ 'DELETE', 'HEAD',  'OPTIONS' ].to_set.freeze,
+    'POST'.freeze => [ 'PATCH', 'PUT'     ].to_set.freeze
+  }.freeze
+
+  # Constructor.
+  # @param app [#call]
+  # @param options [Hash{Symbol => Mixed}] Configuration options. The following
+  #   options are supported:
+  #   *   **`:max_size`** the maximum size (in bytes) of the request body of a
+  #       `POST` request that is converted to a `GET` request.
+  def initialize( app, options = {} )
+    @app = app
+    @max_size = options[:max_size]
+  end
+
+
+  def call env
+    before_call env
+    @app.call env
+  end
+
+  private
+
+
+  def before_call env
+    return unless ['GET', 'POST'].include? env['REQUEST_METHOD']
+    new_method = nil
+    new_query_string = env['QUERY_STRING'].
+    split('&', -1).
+    select { |p|
+      p = p.split('=', 2)
+      if new_method.nil? && METHOD_OVERRIDE_PARAM_KEY == p[0]
+        new_method = p[1].upcase
+        false
+      else
+        true
+      end
+    }.
+    join('&')
+    if new_method
+      if  'GET' == new_method &&
+          'POST' == env['REQUEST_METHOD']
+        raise HTTP415
+          'application/x-www-form-urlencoded' == env['CONTENT_TYPE'] &&
+          env['CONTENT_LENGTH'].to_i <= @max_size
+        if env.key?('rack.input')
+          new_query_string += '&' unless new_query_string.empty?
+          new_query_string += env['rack.input'].read
+          if  env['rack.input'].respond_to?( :rewind )
+              env['rack.input'].rewind
+              env['rackful.method_override.input'] = env['rack.input']
+          end
+          env.delete 'rack.input'
+        end
+        env.delete 'CONTENT_TYPE'
+        env.delete 'CONTENT_LENGTH'
+        update_env( env, new_method, new_query_string )
+      elsif ALLOWED_OVERRIDES[env['REQUEST_METHOD']].include?( new_method )
+        update_env( env, new_method )
+      elsif logger = env['rack.logger']
+        logger.warn('Rackful::MethodOverride') {
+          "Client tried to override request method #{env['REQUEST_METHOD']} with #{new_method} (ignored)."
+        }
+      else
+        STDERR << "warning: Client tried to override request method #{env['REQUEST_METHOD']} with #{new_method} (ignored).\n"
+      end
+    end
+  end
+
+
+  def update_env env, new_method, new_query_string = nil
+    unless new_query_string.nil?
+      env['rackful.method_override.QUERY_STRING'] = env['QUERY_STRING']
+      env['QUERY_STRING'] = new_query_string
+    end
+    env['rackful.method_override.REQUEST_METHOD'] = env['REQUEST_METHOD']
+    env['REQUEST_METHOD'] = new_method
+  end
+
+end # Rackful::MethodOverride

data/lib/rackful/parser.rb

@@ -0,0 +1,315 @@
+# encoding: utf-8
+
+
+module Rackful
+
+
+=begin markdown
+Base class for all parsers.
+@abstract Subclasses must implement method `#parse`, and define constant
+  {MEDIA_TYPES} as an array of media types this parser accepts.
+@example Subclassing this class
+  class MyTextParser < Rackful::Parser
+    MEDIA_TYPES = [ 'text/plain' ]
+    def parse
+      # YOUR CODE HERE...
+    end
+  end
+=end
+class Parser
+
+
+=begin markdown
+  An array of media type strings.
+  @!parse MEDIA_TYPES = [ 'example/type1', 'example/type2' ]
+=end
+
+
+  # @return [Request]
+  attr_reader :request
+  # @return [Resource]
+  attr_reader :resource
+
+
+=begin markdown
+@param request [Request]
+@param resource [Resource]
+=end
+  def initialize request, resource
+    @request, @resource = request, resource
+  end
+
+
+end # class Parser
+
+
+=begin markdown
+Parent class of all XML-parsing parsers.
+@abstract
+@since 0.2.0
+=end
+class Parser::DOM < Parser
+
+
+=begin markdown
+The media types parsed by this parser.
+@see Parser
+=end
+  MEDIA_TYPES = [
+    'text/xml',
+    'application/xml'
+  ]
+
+
+=begin markdown
+@return [Nokogiri::XML::Document]
+=end
+  attr_reader :document
+
+
+=begin markdown
+@raise [HTTP400BadRequest] if the document is malformed.
+=end
+  def initialize request, resource
+    super request, resource
+    # TODO Is ISO-8859-1 indeed the default encoding for XML documents? If so,
+    # that fact must be documented and referenced.
+    encoding = self.request.media_type_params['charset'] || 'ISO-8859-1'
+    begin
+      @document = Nokogiri.XML(
+        self.request.env['rack.input'].read,
+        self.request.canonical_uri.to_s,
+        encoding
+      ) do |config|
+        config.strict.nonet
+      end
+    rescue
+      raise HTTP400BadRequest, $!.to_s
+    end
+    raise( HTTP400BadRequest, $!.to_s ) unless @document.root
+  end
+
+
+end # class Parser::DOM
+
+
+=begin markdown
+Parses XHTML as generated by {Serializer::XHTML}.
+=end
+class Parser::XHTML < Parser::DOM
+
+
+=begin markdown
+The media types parsed by this parser.
+@see Parser
+=end
+  MEDIA_TYPES = Parser::DOM::MEDIA_TYPES + [
+    'application/xhtml+xml',
+    'text/html'
+  ]
+
+
+=begin markdown
+@see Parser#parse
+=end
+  def parse
+    # Try to find the actual content:
+    content = self.document.root.xpath(
+      '//html:div[@id="rackful-content"]',
+      'html' => 'http://www.w3.org/1999/xhtml'
+    )
+    # There must be exactly one element <div id="rackful_content"/> in the document:
+    if content.empty?
+      raise HTTP400BadRequest, 'Couldn’t find div#rackful-content in request body.'
+    end
+    if content.length > 1
+      raise HTTP400BadRequest, 'Multiple instances of div#rackful-content found in request body.'
+    end
+    # Initialize @base_url:
+    base_url = self.document.root.xpath(
+      '/html:html/html:head/html:base',
+      'html' => 'http://www.w3.org/1999/xhtml'
+    )
+    if base_url.empty?
+      @base_url = self.request.canonical_uri.dup
+    else
+      @base_url = URI( base_url.first.attribute('href').text ).normalize
+      if @base_url.relative?
+        @base_url = self.request.canonical_uri + @base_url
+      end
+    end
+    # Parse the f*cking thing:
+    self.parse_recursive content.first
+  end
+
+
+=begin markdown
+@api private
+=end
+  def parse_recursive node
+
+    # A URI:
+    if ( nodelist = node.xpath( 'html:a', 'html' => 'http://www.w3.org/1999/xhtml' ) ).length == 1
+      r = URI( nodelist.first.attribute('href').text )
+      r.relative? ? @base_url + r : r
+
+    # An Object (AKA a Hash)
+    elsif ( nodelist = node.xpath( 'html:dl', 'html' => 'http://www.w3.org/1999/xhtml' ) ).length == 1
+      self.parse_object nodelist.first
+
+    # A list of Objects with identical keys:
+    elsif ( nodelist = node.xpath( 'html:table', 'html' => 'http://www.w3.org/1999/xhtml' ) ).length == 1
+      self.parse_object_list nodelist.first
+
+    # A list of things (AKA an Array):
+    elsif ( nodelist = node.xpath( 'html:ul', 'html' => 'http://www.w3.org/1999/xhtml' ) ).length == 1
+      nodelist.first.xpath(
+        'html:li',
+        'html' => 'http://www.w3.org/1999/xhtml'
+      ).collect do |n| self.parse_recursive n end
+
+    # A simple type:
+    elsif type = node.attribute_with_ns( 'type', 'http://www.w3.org/2001/XMLSchema' )
+      prefix, typename = type.text.split(':', 2)
+      unless typename && 'http://www.w3.org/2001/XMLSchema' == node.namespaces["xmlns:#{prefix}"]
+        raise HTTP400BadRequest, "Unknown XML Schema type: #{type}"
+      end
+      self.parse_simple_type node, typename
+    else
+      raise HTTP400BadRequest, 'Can’t parse:<br/>' + Rack::Utils.escape_html(node.to_xml)
+    end
+  end
+
+
+=begin markdown
+@api private
+=end
+  def parse_simple_type node, typename
+    case typename
+    when 'boolean'
+      case node.inner_text.strip
+      when 'true'  then true
+      when 'false' then false
+      else nil
+      end
+    when 'integer'
+      node.inner_text.strip.to_i
+    when 'numeric'
+      node.inner_text.strip.to_f
+    when 'dateTime'
+      Time.xmlschema(node.inner_text.strip)
+    when 'base64Binary'
+      Base64.decode64(node.inner_text)
+    when 'string'
+      node.inner_text
+    else
+      raise HTTP400BadRequest, "Unknown XML Schema type: #{type}"
+    end
+  end
+
+
+=begin markdown
+@api private
+=end
+  def parse_object node
+    current_property = nil
+    r = {}
+    node.children.each do |child|
+      if 'dt' == child.name &&
+         'http://www.w3.org/1999/xhtml' == child.namespace.href
+        if current_property
+          raise HTTP400BadRequest, 'Can’t parse:<br/>' + Rack::Utils.escape_html(node.to_xml)
+        end
+        current_property = child.inner_text.strip.split(' ').join('_').to_sym
+      elsif 'dd' == child.name &&
+            'http://www.w3.org/1999/xhtml' == child.namespace.href
+        unless current_property
+          raise HTTP400BadRequest, 'Can’t parse:<br/>' + Rack::Utils.escape_html(node.to_xml)
+        end
+        r[current_property] = self.parse_recursive( child )
+        current_property = nil
+      end
+    end
+    r
+  end
+
+
+=begin markdown
+@api private
+=end
+  def parse_object_list node
+    properties = node.xpath(
+      'html:thead/html:tr/html:th',
+      'html' => 'http://www.w3.org/1999/xhtml'
+    ).collect do |th|
+      th.inner_text.strip.split(' ').join('_').to_sym
+    end
+    if properties.empty?
+      raise HTTP400BadRequest, 'Can’t parse:<br/>' + Rack::Utils.escape_html(node.to_xml)
+    end
+    n = properties.length
+    node.xpath(
+      'html:tbody/html:tr',
+      'html' => 'http://www.w3.org/1999/xhtml'
+    ).collect do |row|
+      values = row.xpath(
+        'html:td', 'html' => 'http://www.w3.org/1999/xhtml'
+      )
+      unless values.length == n
+        raise HTTP400BadRequest, 'Can’t parse:<br/>' + Rack::Utils.escape_html(row.to_xml)
+      end
+      object = {}
+      Range.new(0,n-1).each do |i|
+        object[properties[i]] = self.parse_recursive( values[i] )
+      end
+      object
+    end
+  end
+
+
+end # class Parser::XHTML
+
+
+class Parser::JSON < Parser
+
+
+  MEDIA_TYPES = [
+    'application/json',
+    'application/x-json'
+  ]
+
+
+  def parse
+    r = ::JSON.parse(
+      self.request.env['rack.input'].read,
+      :symbolize_names => true
+    )
+    self.recursive_datetime_parser r
+  end
+
+
+  def recursive_datetime_parser p
+    if p.kind_of?(String)
+      begin
+        return Time.xmlschema(p)
+      rescue
+      end
+    elsif p.kind_of?(Hash)
+      p.keys.each do
+        |key|
+        p[key] = self.recursive_datetime_parser( p[key] )
+      end
+    elsif p.kind_of?(Array)
+      (0 ... p.size).each do
+        |i|
+        p[i] = self.recursive_datetime_parser( p[i] )
+      end
+    end
+    p
+  end
+
+
+end # class Parser::JSON
+
+
+end # module Rackful