webbed 0.1.1 → 0.2.0

data/.gitignore

@@ -0,0 +1,22 @@
+coverage
+rdoc
+pkg
+test/tmp
+test/version_tmp
+tmp
+pkg
+*.gem
+*.rbc
+lib/bundler/man
+spec/reports
+.config
+InstalledFiles
+.bundle
+
+# YARD artifacts
+.yardoc
+_yardoc
+doc/
+
+# Gem-specific
+Gemfile.lock

data/.travis.yml

@@ -0,0 +1,7 @@
+script: 'rake test'
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - ree
+  - rbx
+  - jruby

data/.yardopts

@@ -0,0 +1,6 @@
+--readme          README.md
+--markup          markdown
+--markup-provider maruku
+--default-return  ""
+--title           "Webbed Documentation"
+--hide-void-return

data/Gemfile

@@ -1,15 +1,7 @@
-source 'http://rubygems.org'
+source :gemcutter
 
-gem 'webbed', :path => File.expand_path("..", __FILE__)
-gem 'addressable', '~> 2.1'
+# This is temporary until guard-minitest accepts my patch.
+gem 'guard-minitest', :git => 'git://github.com/CapnKernul/guard-minitest.git'
+gem 'rb-fsevent'
 
-group :development do
-  gem 'rake'
-end
-
-group :test do
-  gem 'rspec', '~> 1.3', :require => 'spec'
-  gem 'bourne'
-  gem 'heckle'
-  gem 'ruby2ruby', '1.2.2'
-end
+gemspec

data/Guardfile

@@ -0,0 +1,5 @@
+guard 'minitest', :notify => true do
+  watch(/^test\/(.*)_test.rb/)
+  watch(/^lib\/(.*)\.rb/) { |m| "test/#{m[1]}_test.rb" }
+  watch(/^test\/test_helper.rb/) { 'test' }
+end

data/README.md

@@ -1,32 +1,37 @@
-Webbed
-======
-Take control of HTTP.
-
-Note on Releases
-----------------
-Releases are tagged on GitHub and also released as gems on RubyGems. The branch `master` is pushed to whenever I add a patch or a new feature. To build from master, you can clone the code, generate the updated `gemspec`, build the gem and install.
-
- * `rake gemspec`
- * `gem build webbed.gemspec`
- * `gem install` the gem that was built
-
-Note on Patches/Pull Requests
------------------------------
- * Fork the project.
- * Make your feature addition or bug fix.
- * Add tests for it. This is important so I don't break it in a future version unintentionally.
- * Commit, do not mess with the `Rakefile`, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself in another branch so I can ignore when I pull)
- * Send me a pull request. Bonus points for topic branches.
-
-Requirements
-------------
- * [Bundler](http://github.com/carlhuda/bundler)
- * [Addressable](http://github.com/sporkmonger/addressable)
-
-Install
--------
-* `gem install webbed`
-
-License
--------
+# webbed - take control of HTTP [![StillMaintained Status](http://stillmaintained.com/CapnKernul/webbed.png)](http://stillmaintained.com/CapnKernul/webbed) [![Build Status](http://travis-ci.org/CapnKernul/webbed.png)](http://travis-ci.org/CapnKernul/webbed) #
+
+Webbed provides useful abstractions on top of the basic parts of the HTTP
+specification, most notably HTTP Requests and Responses. It is far more
+full-featured than `Rack::Request` and `Rack::Response`, allowing you to easily
+access the complex features of HTTP.
+
+## Usage ##
+
+Coming soon. Check out the tests and documentation in the meantime.
+
+## Installation ##
+
+Without bundler:
+
+    gem install webbed
+
+With bundler:
+
+    gem 'webbed'
+
+## Note on Patches/Pull Requests ##
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a future version unintentionally.
+* Commit, but do not mess with the `Rakefile`. If you want to have your own version, that is fine but bump the version in a commit by itself in another branch so I can ignore it when I pull.
+* Send me a pull request. Bonus points for git flow feature branches.
+
+## Resources ##
+
+* [GitHub Repository](https://github.com/CapnKernul/webbed)
+* [Documentation](http://rubydoc.info/github/CapnKernul/webbed)
+
+## License ##
+
 Webbed is licensed under the MIT License. See `LICENSE` for details.

data/Rakefile

@@ -1,18 +1,11 @@
 require 'bundler'
-Bundler.setup :default, :development, :test
+Bundler::GemHelper.install_tasks
 
-require 'webbed'
-require 'spec/rake/spectask'
+task :default => :test
 
-Spec::Rake::SpecTask.new do |t|
-  t.libs << 'lib'
-end
-
-gemspec = eval(File.read('webbed.gemspec'))
-
-task :build => "#{gemspec.full_name}.gem"
-
-file "#{gemspec.full_name}.gem" => gemspec.files + ['webbed.gemspec'] do
-  system 'gem build webbed.gemspec'
-  system "gem install webbed-#{Webbed::VERSION}.gem"
+require 'rake/testtask'
+Rake::TestTask.new do |t|
+  t.ruby_opts += ['-rubygems']
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
 end

data/lib/webbed.rb

@@ -1,9 +1,31 @@
+# Webbed provides two important abstraction on the HTTP specification (RFC
+# 2616), {Request} and {Response}. Although the core classes have the
+# bare-minimum of functionality for interacting with the two classes, they have
+# been extended with a variety of helper modules, adding a significant amount of
+# semantic meaning to the instances of each class.
+# 
+# Webbed can be used with or without Rack, but it includes Rack helpers for
+# convenience.
+# 
+# @todo Add exmaples of webbed in action.
 module Webbed
-  autoload :Headers, 'webbed/headers'
-  autoload :HTTPVersion, 'webbed/http_version'
+  autoload :Headers,        'webbed/headers'
+  autoload :HTTPVersion,    'webbed/http_version'
   autoload :GenericMessage, 'webbed/generic_message'
-  autoload :Method, 'webbed/method'
-  autoload :StatusCode, 'webbed/status_code'
-  autoload :Request, 'webbed/request'
-  autoload :Response, 'webbed/response'
+  autoload :MediaType,      'webbed/media_type'
+  autoload :Method,         'webbed/method'
+  autoload :StatusCode,     'webbed/status_code'
+  autoload :Request,        'webbed/request'
+  autoload :Response,       'webbed/response'
+  
+  module Helpers
+    autoload :MethodHelper,          'webbed/helpers/method_helper'
+    autoload :RackRequestHelper,     'webbed/helpers/rack_request_helper'
+    autoload :RackResponseHelper,    'webbed/helpers/rack_response_helper'
+    autoload :RequestURIHelper,      'webbed/helpers/request_uri_helper'
+    autoload :SchemeHelper,          'webbed/helpers/scheme_helper'
+    autoload :RequestHeadersHelper,  'webbed/helpers/request_headers_helper'
+    autoload :ResponseHeadersHelper, 'webbed/helpers/response_headers_helper'
+    autoload :EntityHeadersHelper,   'webbed/helpers/entity_headers_helper'
+  end
 end

data/lib/webbed/generic_message.rb

@@ -1,28 +1,40 @@
 module Webbed
+  # Generic methods used for both {Request}'s and {Response}'s.
+  # 
+  # @abstract Include and implement `#status_line`.
   module GenericMessage
-    
+    # The HTTP-Version of the message.
+    # 
+    # The method automatically converts the new value to an instance of
+    # {HTTPVersion} if it is not already one.
+    # 
+    # @return [HTTPVersion]
     attr_reader :http_version
-    attr_accessor :entity_body
-    
-    # This is purely for test/spec purposes.
-    def initialize
-      self.http_version = 'HTTP/1.1'
-      self.entity_body = ''
-    end
-    
-    # Must be overridden!
-    def start_line
-      "Invalid Start Line\r\n"
-    end
     
     def http_version=(http_version)
       @http_version = Webbed::HTTPVersion.new(http_version)
     end
     
-    def headers
-      @headers ||= Webbed::Headers.new
+    # The Headers of the message.
+    # 
+    # The method automatically converts the new value to an instance of
+    # {Headers} if it is not already one.
+    # 
+    # @return [Headers]
+    attr_reader :headers
+    
+    def headers=(headers)
+      @headers = Webbed::Headers.new(headers)
     end
     
+    # The Entity Body of the message.
+    # 
+    # @return [#to_s]
+    attr_accessor :entity_body
+    
+    # Converts the message into an HTTP Message as per RFC 2616.
+    # 
+    # @return [String]
     def to_s
       "#{start_line}#{headers.to_s}\r\n#{entity_body}"
     end

data/lib/webbed/headers.rb

@@ -1,4 +1,6 @@
 module Webbed
+  # Representation of HTTP headers.
+  # 
   # This class is stolen directly from Rack.
   class Headers < Hash
     def self.new(hash={})

data/lib/webbed/helpers/entity_headers_helper.rb

@@ -0,0 +1,62 @@
+module Webbed
+  module Helpers
+    # Request and Response helper for Entity Headers
+    module EntityHeadersHelper
+      # The Content-Length of the Entity (as defined in the Content-Length Header).
+      # 
+      # @return [Fixnum, nil]
+      def content_length
+        headers['Content-Length'] ? headers['Content-Length'].to_i : nil
+      end
+      
+      # Sets the Content-Length of the Entity (as defined in the Content-Length Header).
+      # 
+      # @param [#to_s] content_length
+      def content_length=(content_length)
+        headers['Content-Length'] = content_length.to_s
+      end
+      
+      # The Content-Location of the Entity (as defined in the Content-Location Header).
+      # 
+      # @return [Addressable::URI, nil]
+      def content_location
+        headers['Content-Location'] ? Addressable::URI.parse(headers['Content-Location']) : nil
+      end
+      
+      # Sets the Content-Location of the Entity (as defined in the Content-Location Header).
+      # 
+      # @param [#to_s] content_location
+      def content_location=(content_location)
+        headers['Content-Location'] = content_location.to_s
+      end
+      
+      # The Content-MD5 of the Entity (as defined in the Content-MD5 Header).
+      # 
+      # @return [String, nil]
+      def content_md5
+        headers['Content-MD5']
+      end
+      
+      # Sets the Content-MD5 of the Entity (as defined in the Content-MD5 Header).
+      # 
+      # @param [String] content_md5
+      def content_md5=(content_md5)
+        headers['Content-MD5'] = content_md5
+      end
+      
+      # The Content-Type of the Entity (as defined in the Content-Type Header).
+      # 
+      # @return [MediaType, nil]
+      def content_type
+        headers['Content-Type'] ? Webbed::MediaType.new(headers['Content-Type']) : nil
+      end
+      
+      # Sets the Content-Type of the Entity (as defined in the Content-Type Header).
+      # 
+      # @param [#to_s] content_type
+      def content_type=(content_type)
+        headers['Content-Type'] = content_type.to_s
+      end
+    end
+  end
+end

data/lib/webbed/helpers/method_helper.rb

@@ -0,0 +1,83 @@
+module Webbed
+  module Helpers
+    # Request helper for the Method
+    module MethodHelper
+      # Whether or not the Request is safe based on the Method
+      # 
+      # @return [Boolean]
+      def safe?
+        method.safe?
+      end
+      
+      # Whether or not the Request is idempotent based on the Method
+      # 
+      # @return [Boolean]
+      def idempotent?
+        method.idempotent?
+      end
+      
+      # Whether or not the Request uses the OPTIONS Method
+      # 
+      # @return [Boolean]
+      def options?
+        method == 'OPTIONS'
+      end
+      
+      # Whether or not the Request uses the GET Method
+      # 
+      # @return [Boolean]
+      def get?
+        method == 'GET'
+      end
+      
+      # Whether or not the Request uses the HEAD Method
+      # 
+      # @return [Boolean]
+      def head?
+        method == 'HEAD'
+      end
+      
+      # Whether or not the Request uses the POST Method
+      # 
+      # @return [Boolean]
+      def post?
+        method == 'POST'
+      end
+      
+      # Whether or not the Request uses the PUT Method
+      # 
+      # @return [Boolean]
+      def put?
+        method == 'PUT'
+      end
+      
+      # Whether or not the Request uses the DELETE Method
+      # 
+      # @return [Boolean]
+      def delete?
+        method == 'DELETE'
+      end
+      
+      # Whether or not the Request uses the TRACE Method
+      # 
+      # @return [Boolean]
+      def trace?
+        method == 'TRACE'
+      end
+      
+      # Whether or not the Request uses the CONNECT Method
+      # 
+      # @return [Boolean]
+      def connect?
+        method == 'CONNECT'
+      end
+      
+      # Whether or not the Request uses the PATCH Method
+      # 
+      # @return [Boolean]
+      def patch?
+        method == 'PATCH'
+      end
+    end
+  end
+end

data/lib/webbed/helpers/rack_request_helper.rb

@@ -0,0 +1,86 @@
+module Webbed
+  module Helpers
+    # Request helper for converting Rack environments into Requests
+    module RackRequestHelper
+      module ClassMethods
+        # Create a new Request from a Rack environment
+        # 
+        # This method will take the HTTP-Version, Method, Request-URI, Headers,
+        # Entity Body, and scheme from the Rack environment and create a new
+        # Request using that data. The Rack environment can be accessed through
+        # `#rack_env`.
+        # 
+        # @param [Hash{String => String}] rack_env
+        # @return [Request]
+        # @note The Rack environment will never be modified.
+        def from_rack(rack_env)
+          env          = rack_env.dup
+          method       = env.delete('REQUEST_METHOD')
+          request_uri  = "#{env['PATH_INFO']}?#{env['QUERY_STRING']}"
+          http_version = env.delete('HTTP_VERSION') || 'HTTP/1.1'
+          scheme       = env.delete('rack.url_scheme')
+          entity_body  = env.delete('rack.input')
+          
+          headers = env.inject({}) do |memo, h|
+            memo[$1.gsub('_', '-')] = h[1] if h[0] =~ /^HTTP_(.*)/
+            memo
+          end
+          
+          headers['Content-Type']   = env.delete('CONTENT_TYPE')
+          headers['Content-Length'] = env.delete('CONTENT_LENGTH')
+          
+          request = new(method, request_uri, headers, entity_body, {
+            :http_version => http_version,
+            :scheme       => scheme
+          })
+          
+          request.rack_env = rack_env
+          
+          request
+        end
+      end
+      
+      module InstanceMethods
+        # The Rack environment of the Request
+        # 
+        # @return [Hash{String => String}]
+        attr_accessor :rack_env
+        
+        # Generate the Rack enivronment equivalent of the Request.
+        # 
+        # If the Request was created with an environment, the generated
+        # environment will be merged with the original environment. The original
+        # will not be modified.
+        # 
+        # @return [Hash{String => String}]
+        def to_rack
+          env = rack_env ? rack_env.dup : {}
+          env['REQUEST_METHOD'] = method.to_s
+          env['PATH_INFO'] = request_uri.path
+          env['QUERY_STRING'] = request_uri.query
+          env['HTTP_VERSION'] = http_version.to_s
+          env['rack.url_scheme'] = scheme
+          env['rack.input'] = entity_body
+          
+          rack_headers = headers.dup
+          env['CONTENT_TYPE'] = rack_headers.delete('Content-Type')
+          env['CONTENT_LENGTH'] = rack_headers.delete('Content-Length')
+          
+          rack_headers.each do |header, value|
+            header = header.upcase.gsub('-', '_')
+            env["HTTP_#{header}"] = value
+          end
+          
+          env
+        end
+      end
+      
+      # @see ClassMethods
+      # @see InstanceMethods
+      def self.included(base)
+        base.send :include, InstanceMethods
+        base.send :extend, ClassMethods
+      end
+    end
+  end
+end