webbed 0.1.1 → 0.2.0

data/lib/webbed/helpers/rack_response_helper.rb

@@ -0,0 +1,56 @@
+module Webbed
+  module Helpers
+    # Response helper for converting Responses into Rack response arrays.
+    module RackResponseHelper
+      module ClassMethods
+        # Converts a Rack response array to a Response.
+        # 
+        # The array has the same format as that defined in the Rack specification.
+        # 
+        # @param [Array] rack_array
+        # @return [Response]
+        def from_rack(rack_array)
+          Response.new(*rack_array)
+        end
+      end
+      
+      module InstanceMethods
+        # Converts the Response to a Rack response array.
+        # 
+        # The array has the same format as that defined in the Rack specification.
+        # 
+        # @return [Array]
+        # @note Due to limitations in Rack, Reason Phrases are not included in the
+        #   array.
+        def to_rack
+          if entity_body.respond_to?(:each)
+            [status_code.to_i, headers, entity_body]
+          else
+            [status_code.to_i, headers, [entity_body]]
+          end
+        end
+        
+        # Converts the Response to an array.
+        # 
+        # The array has a similar format to the format defined in the Rack specification with some modifications:
+        # 
+        # 1. The Reason Phrase is included with the Status Code.
+        # 2. The Entity Body does not need to respond to `#each`.
+        # 
+        # @return [Array]
+        # @note This will *not* return a Rack-compatible response array.
+        # @see Response#initialize
+        def to_a
+          ["#{status_code} #{reason_phrase}", headers, entity_body]
+        end
+      end
+      
+      # @see ClassMethods
+      # @see InstanceMethods
+      def self.included(base)
+        base.send :include, InstanceMethods
+        base.send :extend, ClassMethods
+      end
+    end
+  end
+end

data/lib/webbed/helpers/request_headers_helper.rb

@@ -0,0 +1,62 @@
+module Webbed
+  module Helpers
+    # Request helper for Request Headers
+    module RequestHeadersHelper
+      # The Host of the Request (as defined in the Host Header)
+      # 
+      # @return [String, nil]
+      def host
+        headers['Host']
+      end
+      
+      # Sets the Host of the Request (as defined in the Host Header)
+      # 
+      # @param [String] host
+      def host=(host)
+        headers['Host'] = host
+      end
+      
+      # The From email of the Request (as defined in the From Header)
+      # 
+      # @return [String, nil]
+      def from
+        headers['From']
+      end
+      
+      # Sets the From email of the Request (as defined in the From Header)
+      # 
+      # @param [String] from
+      def from=(from)
+        headers['From'] = from
+      end
+      
+      # The Max-Forwards of the Request (as defined in the Max-Forwards Header)
+      # 
+      # @return [Fixnum, nil]
+      def max_forwards
+        headers['Max-Forwards'] ? headers['Max-Forwards'].to_i : nil
+      end
+      
+      # Sets the Max-Forwards of the Request (as defined in the Max-Forwards Header)
+      # 
+      # @param [#to_s] max_forwards
+      def max_forwards=(max_forwards)
+        headers['Max-Forwards'] = max_forwards.to_s
+      end
+      
+      # The Referer of the Request (as defined in the Referer Header)
+      # 
+      # @return [Addressable::URI, nil]
+      def referer
+        headers['Referer'] ? Addressable::URI.parse(headers['Referer']) : nil
+      end
+      
+      # Sets the Referer of the Request (as defined in the Referer Header)
+      # 
+      # @param [#to_s] referer
+      def referer=(referer)
+        headers['Referer'] = referer.to_s
+      end
+    end
+  end
+end

data/lib/webbed/helpers/request_uri_helper.rb

@@ -0,0 +1,34 @@
+module Webbed
+  module Helpers
+    # Request helper for the Request-URI
+    module RequestURIHelper
+      # Aliases the {Request#request_uri} method to `#request_url`.
+      def self.included(base)
+        base.class_eval do
+          alias :request_url :request_uri
+        end
+      end
+      
+      # The URI of the actual location of the requested resource.
+      # 
+      # If the Request-URI is an absolute URI or there is no Host header, it
+      # returns the Request-URI.
+      # 
+      # If the Request-URI is a relative URI, it combines the Host header with
+      # the Request-URI.
+      # 
+      # @return [Addressable::URI]
+      def uri
+        if host && !request_uri.host
+          request_uri.dup.tap do |uri|
+            uri.scheme = 'http'
+            uri.host = host
+          end
+        else
+          request_uri
+        end
+      end
+      alias :url :uri
+    end
+  end
+end

data/lib/webbed/helpers/response_headers_helper.rb

@@ -0,0 +1,48 @@
+module Webbed
+  module Helpers
+    # Response helper for Response Headers
+    module ResponseHeadersHelper
+      # The ETag of the Response (as defined in the ETag Header)
+      # 
+      # @return [String, nil]
+      def etag
+        headers['ETag']
+      end
+      
+      # Sets the ETag of the Response (as defined in the ETag Header)
+      # 
+      # @param [String] etag
+      def etag=(etag)
+        headers['ETag'] = etag
+      end
+      
+      # The Age of the Response (as defined in the Age Header)
+      # 
+      # @return [Fixnum, nil]
+      def age
+        headers['Age'] ? headers['Age'].to_i : nil
+      end
+      
+      # Sets the Age of the Response (as defined in the Age Header)
+      # 
+      # @param [#to_s] age
+      def age=(age)
+        headers['Age'] = age.to_s
+      end
+      
+      # The Location of the Response (as defined in the Location Header)
+      # 
+      # @return [Addressable::URI, nil]
+      def location
+        headers['Location'] ? Addressable::URI.parse(headers['Location']) : nil
+      end
+      
+      # Sets the Location of the Response (as defined in the Location Header)
+      # 
+      # @param [#to_s] location
+      def location=(location)
+        headers['Location'] = location.to_s
+      end
+    end
+  end
+end

data/lib/webbed/helpers/scheme_helper.rb

@@ -0,0 +1,26 @@
+module Webbed
+  module Helpers
+    # Request helper for the schemes
+    module SchemeHelper
+      # Whether or not the request was sent securely (using HTTPS)
+      # 
+      # @return [Boolean]
+      def secure?
+        scheme == 'https'
+      end
+      
+      # The default port for the designated scheme
+      # 
+      # This method returns `80` if you're using HTTP and `443` if you're using
+      # HTTPS.
+      # 
+      # @return [Fixnum, nil]
+      def default_port
+        case scheme
+        when 'http' then 80
+        when 'https' then 443
+        end
+      end
+    end
+  end
+end

data/lib/webbed/http_version.rb

@@ -1,55 +1,110 @@
 module Webbed
+  # Representation of an HTTP HTTP Version.
+  # 
+  # Webbed supports both primary versions of HTTP, HTTP/1.0 and HTTP/1.1.
+  # Although the use of HTTP/1.1 has been strongly encouraged since its creation
+  # in 1999, it remains relatively common for older command line tools (such as
+  # wget) and some search engines. Webbed can also be extended in the future to
+  # support new versions of HTTP, should one ever come into existence.
+  # 
+  # {HTTPVersion} is a small abstraction on top of the HTTP-Version as defined
+  # in RFC 2616. According to the RFC, its simple format is:
+  # 
+  #     HTTP-Version = "HTTP" "/" 1*DIGIT "." 1*DIGIT
+  # 
+  # While this is perhaps the simplest of all the abstractions in Webbed, it
+  # does offer some nice helper methods for treating the version string more
+  # Ruby-like.
+  # 
+  # HTTP/1.0 and HTTP/1.1 {HTTPVersion}'s are cached. In every case I can think
+  # of, you will not have to create a new {HTTPVersion}, just use the constants
+  # {ONE_POINT_OH} and {ONE_POINT_ONE} when creating messages.
   class HTTPVersion
-    
     include Comparable
-    REGEX = /^HTTP\/(\d+\.\d+)$/
-    
-    def self.new(http_version, dup = false)
-      unless dup
-        if ['HTTP/1.1', 1.1].include? http_version
-          return ONE_POINT_ONE
-        end
-        
-        if ['HTTP/1.0', 1.0].include? http_version
-          return ONE_POINT_OH
-        end
-      end
-      
-      super(http_version)
-    end
     
+    REGEX = /^HTTP\/(\d+)\.(\d+)$/
+    
+    # Creates a new HTTP-Version.
+    # 
+    # Only HTTP/1.0 and HTTP/1.1 versions are cached. All other versions will be
+    # created at runtime each time this method is called.
+    # 
+    # @example
+    #   Webbed::HTTPVersion.new(1.1)
+    #   Webbed::HTTPVersion.new('HTTP/1.1')
+    # 
+    # @param [#to_s] http_version the HTTP-Version to create
     def initialize(http_version)
-      @http_version = to_f(http_version)
+      if REGEX =~ http_version.to_s
+        @http_version = http_version.to_s
+      else
+        @http_version = "HTTP/#{http_version}"
+      end
     end
     
+    # Converts the HTTP-Version to a string according to RFC 2616.
+    # 
+    # @example
+    #   version = Webbed::HTTPVersion.new(1.1)
+    #   version.to_s # => 'HTTP/1.1'
+    # 
+    # @return [String]
     def to_s
-      "HTTP/#{to_f}"
+      @http_version
     end
-    alias :inspect :to_s
     
-    # This feels like a hack. Oh well.
-    def to_f(http_version = @http_version)
-      if http_version.respond_to? :match
-        REGEX.match(http_version)[1].to_f
-      else
-        http_version.to_f
-      end
+    # Converts the HTTP-Version to a float.
+    # 
+    # @example
+    #   version = Webbed::HTTPVersion.new('HTTP/1.1')
+    #   version.to_f # => 1.1
+    # 
+    # @return [Float]
+    def to_f
+      REGEX =~ @http_version
+      "#{$1}.#{$2}".to_f
     end
     
-    def <=>(other_version)
-      to_f <=> to_f(other_version)
+    # Compares the HTTP-Version to another HTTP-Version.
+    # 
+    # @example
+    #   version_1_1 = Webbed::HTTPVersion.new(1.1)
+    #   version_5_0 = Webbed::HTTPVersion.new('HTTP/5.0')
+    #   version_1_1 == version_5_0 # => false
+    #   version_5_0 < version_5_0 # => false
+    #   version_5_0 > version_1_1 # => true
+    # 
+    # @param [#to_f] other_http_version the other HTTP-Version
+    # @return [Fixnum] the sign of the comparison (either `1`, `0`, or `-1`)
+    def <=>(other_http_version)
+      to_f <=> other_http_version.to_f
     end
     
+    # The major HTTP-Version number.
+    # 
+    # @example
+    #   version = Webbed::HTTPVersion.new('HTTP/6.9')
+    #   version.major # => 6
+    # 
+    # @return [Fixnum]
     def major
-      to_f.floor
+      REGEX =~ @http_version
+      $1.to_i
     end
     
-    # TODO: Fix this ugly hack! :x
+    # The minor HTTP-Version number.
+    # 
+    # @example
+    #   version = Webbed::HTTPVersion.new('HTTP/4.2')
+    #   version.minor # => 2
+    # 
+    # @return [Fixnum]
     def minor
-      (to_f - to_f.floor).to_s[2..-1].to_i
+      REGEX =~ @http_version
+      $2.to_i
     end
     
-    ONE_POINT_ONE = HTTPVersion.new(1.1, true)
-    ONE_POINT_OH = HTTPVersion.new(1.0, true)
+    ONE_POINT_ONE = HTTPVersion.new(1.1)
+    ONE_POINT_OH = HTTPVersion.new(1.0)
   end
 end

data/lib/webbed/media_type.rb

@@ -0,0 +1,160 @@
+module Webbed
+  # Representation of an HTTP Media Type.
+  class MediaType
+    MIME_TYPE_REGEX = /^([-\w.+]+)\/([-\w.+]*)$/
+    PARAMETERS_REGEX = /=|\s*;\s*/
+    
+    # The type of the MIME type.
+    # 
+    # According to RFC 2616, this is the part *before* the slash.
+    # 
+    # @example
+    #     media_type = Webbed::MediaType.new('text/html')
+    #     media_type.type # => 'text'
+    # 
+    # @return [String]
+    attr_accessor :type
+    
+    # The subtype of the MIME type.
+    # 
+    # According to RFC 2616, this is the *after* before the slash.
+    # 
+    # @example
+    #     media_type = Webbed::MediaType.new('text/html')
+    #     media_type.type # => 'html'
+    # 
+    # @return [String]
+    attr_accessor :subtype
+    
+    # The parameters of the Media Type.
+    # 
+    # According to RFC 2616, parameters are separated from the MIME type and
+    # each other using a semicolon.
+    # 
+    # @example
+    #     media_type = Webbed::MediaType.new('text/html; q=1.0')
+    #     media_type.parameters # => { 'q' => '1.0' }
+    # 
+    # @return [Hash{String => String}]
+    attr_accessor :parameters
+    
+    # Creates a new Media Type.
+    # 
+    # @example Create a MediaType without parameters
+    #     media_type = Webbed::MediaType.new('text/html')
+    #     media_type.mime_type # => 'text/html'
+    #     media_type.parameters # => {}
+    # 
+    # @example Create a MediaType with parameters
+    #     media_type = Webbed::MediaType.new('text/html; q=1.0')
+    #     media_type.mime_type # => 'text/html'
+    #     media_type.parameters # => { 'q' => '1.0' }
+    # 
+    # @param [String] media_type the Media Type to create as defined in RFC 2616
+    def initialize(media_type)
+      self.mime_type, *parameters = media_type.split(PARAMETERS_REGEX)
+      self.parameters = Hash[*parameters] || {}
+    end
+    
+    # The MIME type of the Media Type.
+    # 
+    # @return [String]
+    def mime_type
+      "#{type}/#{subtype}"
+    end
+    
+    # Sets the MIME type of the Media Type.
+    # 
+    # @param [String] mime_type
+    def mime_type=(mime_type)
+      MIME_TYPE_REGEX =~ mime_type
+      self.type = $1
+      self.subtype = $2
+    end
+    
+    # Converts the Media Type to a string.
+    # 
+    # @return [String]
+    def to_s
+      if parameters.empty?
+        mime_type
+      else
+        parameters = self.parameters.map { |k, v| "#{k}=#{v}" }.join('; ')
+        "#{mime_type}; #{parameters}"
+      end
+    end
+    
+    # Whether or not the Media Type is vendor-specific.
+    # 
+    # The method uses the `vnd.` prefix convention to determine whether or not
+    # it was created for a specific vendor.
+    # 
+    # @example
+    #     media_type = Webbed::MediaType.new('application/json')
+    #     media_type.vendor_specific? # => false
+    #     
+    #     media_type = Webbed::MediaType.new('application/vnd.my-special-type')
+    #     media_type.vendor_specific? # => true
+    # 
+    # @return [Boolean]
+    def vendor_specific?
+      subtype[0..3] == 'vnd.'
+    end
+    
+    # The suffix of the MIME type.
+    # 
+    # Suffixes follow the convention set forth by the Atom specification:
+    # separated from the rest of the MIME Type by a `+`.
+    # 
+    # @example
+    #     media_type = Webbed::MediaType.new('application/xml')
+    #     media_type.suffix # => nil
+    #     
+    #     media_type = Webbed::MediaType.new('application/atom+xml')
+    #     media_type.suffix # => 'xml'
+    # 
+    # @return [String, nil]
+    def suffix
+      suffix = subtype.split('+')[-1]
+      
+      if suffix != subtype
+        suffix
+      else
+        nil
+      end
+    end
+    
+    # Compares the Media Type to another Media Type.
+    # 
+    # Two Media Types are equal if their `#mime_type`'s are equal.
+    # 
+    # @param [#mime_type] other_media_type the other Media Type
+    # @return [Boolean]
+    def ==(other_media_type)
+      mime_type == other_media_type.mime_type
+    end
+    
+    # The MIME types that the Media Type can be interpreted as.
+    # 
+    # This uses the suffix to generate a list of MIME types that can be used to
+    # interpret the Media Type. It's useful if you need to be able to parse XML
+    # or JSON Media Types that may or may not have suffixes using general XML
+    # or JSON parsers.
+    # 
+    # @example
+    #     media_type = Webbed::MediaType.new('application/xml')
+    #     media_type.interpretable_as # ['application/xml']
+    #     
+    #     media_type = Webbed::MediaType.new('application/atom+xml')
+    #     media_type.interpretable_as # => ['application/atom+xml', 'application/xml']
+    # 
+    # @return [Array<String>]
+    def interpretable_as
+      if suffix
+        [mime_type, "#{type}/#{suffix}"]
+      else
+        [mime_type]
+      end
+    end
+  end
+end