RubyGems - webmachine - Versions diffs - 0.1.0 - Mend

webmachine 0.1.0

Files changed (37) hide show

data/.gitignore +28 -0
data/Gemfile +16 -0
data/Guardfile +11 -0
data/README.md +89 -0
data/Rakefile +31 -0
data/examples/webrick.rb +19 -0
data/lib/webmachine/adapters/webrick.rb +74 -0
data/lib/webmachine/adapters.rb +15 -0
data/lib/webmachine/decision/conneg.rb +304 -0
data/lib/webmachine/decision/flow.rb +502 -0
data/lib/webmachine/decision/fsm.rb +79 -0
data/lib/webmachine/decision/helpers.rb +80 -0
data/lib/webmachine/decision.rb +12 -0
data/lib/webmachine/dispatcher/route.rb +85 -0
data/lib/webmachine/dispatcher.rb +40 -0
data/lib/webmachine/errors.rb +37 -0
data/lib/webmachine/headers.rb +16 -0
data/lib/webmachine/locale/en.yml +28 -0
data/lib/webmachine/request.rb +56 -0
data/lib/webmachine/resource/callbacks.rb +362 -0
data/lib/webmachine/resource/encodings.rb +36 -0
data/lib/webmachine/resource.rb +48 -0
data/lib/webmachine/response.rb +49 -0
data/lib/webmachine/streaming.rb +27 -0
data/lib/webmachine/translation.rb +11 -0
data/lib/webmachine/version.rb +4 -0
data/lib/webmachine.rb +19 -0
data/spec/spec_helper.rb +13 -0
data/spec/tests.org +57 -0
data/spec/webmachine/decision/conneg_spec.rb +152 -0
data/spec/webmachine/decision/flow_spec.rb +1030 -0
data/spec/webmachine/dispatcher/route_spec.rb +109 -0
data/spec/webmachine/dispatcher_spec.rb +34 -0
data/spec/webmachine/headers_spec.rb +19 -0
data/spec/webmachine/request_spec.rb +24 -0
data/webmachine.gemspec +44 -0
metadata +137 -0

data/.gitignore ADDED Viewed

@@ -0,0 +1,28 @@
+## MAC OS
+.DS_Store
+## TEXTMATE
+*.tmproj
+tmtags
+## EMACS
+*~
+\#*
+.\#*
+## VIM
+*.swp
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+## PROJECT::SPECIFIC
+doc
+.yardoc
+.bundle
+Gemfile.lock
+**/bin
+*.rbc
+.rvmrc

data/Gemfile ADDED Viewed

@@ -0,0 +1,16 @@
+source :rubygems
+gemspec
+gem 'bundler'
+unless ENV['TRAVIS']
+  gem 'guard-rspec'
+  gem 'rb-fsevent'
+  gem 'growl'
+  gem 'growl_notify'
+end
+platforms :jruby do
+  gem 'jruby-openssl'
+end

data/Guardfile ADDED Viewed

@@ -0,0 +1,11 @@
+gemset = ENV['RVM_GEMSET'] || 'webmachine'
+gemset = "@#{gemset}" unless gemset.to_s == ''
+rvms = %W[  1.9.2 ].map {|v| "#{v}#{gemset}" }
+guard 'rspec', :cli => "--color --profile", :growl => true, :rvm => rvms do
+  watch(%r{^lib/webmachine/locale/.+$}) { "spec" }
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$}){ |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb') { "spec" }
+end

data/README.md ADDED Viewed

@@ -0,0 +1,89 @@
+# webmachine for Ruby [![travis](https://secure.travis-ci.org/seancribbs/webmachine-ruby.png)](http://travis-ci.org/seancribbs/webmachine-ruby)
+webmachine-ruby is a port of
+[Webmachine](https://github.com/basho/webmachine), which is written in
+Erlang.  The goal of both projects is to expose interesting parts of
+the HTTP protocol to your application in a declarative way.  This
+means that you are less concerned with handling requests directly and
+more with describing the behavior of the resources that make up your
+application. Webmachine is not a web framework _per se_, but more of a
+toolkit for building HTTP-friendly applications. For example, it does
+not provide a templating engine or a persistence layer; those choices
+are up to you.
+**NOTE**: _Webmachine is NOT compatible with Rack._ This is
+intentional! Rack obscures HTTP in a way that makes it hard for
+Webmachine to do its job properly, and encourages people to add
+middleware that might break Webmachine's behavior. Rack is also built
+on the tradition of CGI, which is nice for backwards compatibility but
+also an antiquated paradigm and should be scuttled (IMHO). _Rack may
+be supported in the future, but only as a shim to support other web
+application servers._
+## Getting Started
+Webmachine is very young, but it's still easy to construct an
+application for it!
+```ruby
+require 'webmachine'
+# Require any of the files that contain your resources here
+require 'my_resource'
+# Point all URIs at the MyResource class
+Webmachine::Dispatcher.add_route(['*'], MyResource)
+# Start the server, binds to port 3000 using WEBrick
+Webmachine.run
+```
+Your resource will look something like this:
+```ruby
+class MyResource < Webmachine::Resource
+  def to_html
+    "<html><body>Hello, world!</body></html>"
+  end
+end
+```
+Run the first file and your application is up. That's all there is to
+it! If you want to customize your resource more, look at the available
+callbacks in lib/webmachine/resource/callbacks.rb. For example, you
+might want to enable "gzip" compression on your resource, for which
+you can simply add an `encodings_provided` callback method:
+```ruby
+class MyResource < Webmachine::Resource
+  def encodings_provided
+    {"gzip" => :encode_gzip, "identity" => :encode_identity}
+  end
+  def to_html
+    "<html><body>Hello, world!</body></html>"
+  end
+end
+```
+There are many other HTTP features exposed to your resource through
+callbacks. Give them a try!
+## Features
+* Handles the hard parts of content negotiation, conditional
+  requests, and response codes for you.
+* Most callbacks can interrupt the decision flow by returning an
+  integer response code. You generally only want to do this when new
+  information comes to light, requiring a modification of the response.
+* Currently supports WEBrick. Other host servers are planned.
+* Streaming/chunked response bodies are permitted as Enumerables or Procs.
+## Problems/TODOs
+* Support streamed responses as Fibers.
+* Configuration, command-line tools, and general polish.
+* An effort has been made to make the code feel as Ruby-ish as
+  possible, but there is still work to do.
+* Tracing is exposed as an Array of decisions visited on the response
+  object. You should be able to turn this off and on, and visualize
+  the decisions on the sequence diagram.

data/Rakefile ADDED Viewed

@@ -0,0 +1,31 @@
+require 'rubygems'
+require 'rubygems/package_task'
+def gemspec
+  $webmachine_gemspec ||= Gem::Specification.load("webmachine.gemspec")
+end
+Gem::PackageTask.new(gemspec) do |pkg|
+  pkg.need_zip = false
+  pkg.need_tar = false
+end
+task :gem => :gemspec
+desc %{Validate the gemspec file.}
+task :gemspec do
+  gemspec.validate
+end
+desc %{Release the gem to RubyGems.org}
+task :release => :gem do
+  system "gem push pkg/#{gemspec.name}-#{gemspec.version}.gem"
+end
+require 'rspec/core'
+require 'rspec/core/rake_task'
+desc "Run specs"
+RSpec::Core::RakeTask.new(:spec)
+task :default => :spec

data/examples/webrick.rb ADDED Viewed

@@ -0,0 +1,19 @@
+require 'webmachine'
+class HelloResource < Webmachine::Resource
+  def last_modified
+    File.mtime(__FILE__)
+  end
+  def encodings_provided
+    { "gzip" => :encode_gzip, "identity" => :encode_identity }
+  end
+  def to_html
+    "<html><head><title>Hello from Webmachine</title></head><body>Hello, world!</body></html>"
+  end
+end
+Webmachine::Dispatcher.add_route([], HelloResource)
+Webmachine.run

data/lib/webmachine/adapters/webrick.rb ADDED Viewed

@@ -0,0 +1,74 @@
+require 'webrick'
+require 'webmachine/version'
+require 'webmachine/headers'
+require 'webmachine/request'
+require 'webmachine/response'
+require 'webmachine/dispatcher'
+module Webmachine
+  module Adapters
+    # Connects Webmachine to WEBrick.
+    module WEBrick
+      # Starts the WEBrick adapter
+      def self.run
+        server = Webmachine::Adapters::WEBrick::Server.new :Port => 3000
+        trap("INT"){ server.shutdown }
+        Thread.new { server.start }.join
+      end
+      class Server < ::WEBrick::HTTPServer
+        def service(wreq, wres)
+          header = Webmachine::Headers.new
+          wreq.each {|k,v| header[k] = v }
+          request = Webmachine::Request.new(wreq.request_method,
+                                            wreq.request_uri,
+                                            header,
+                                            RequestBody.new(wreq))
+          response = Webmachine::Response.new
+          Webmachine::Dispatcher.dispatch(request, response)
+          wres.status = response.code.to_i
+          response.headers.each do |k,v|
+            wres[k] = v
+          end
+          wres['Server'] = [Webmachine::SERVER_STRING, wres.config[:ServerSoftware]].join(" ")
+          case response.body
+          when String
+            wres.body << response.body
+          when Enumerable
+            response.body.each {|part| wres.body << part }
+          when response.body.respond_to?(:call)
+            wres.body << response.body.call
+          end
+        end
+      end
+      # Wraps the WEBrick request body so that it can be passed to
+      # {Request} while still lazily evaluating the body.
+      class RequestBody
+        def initialize(request)
+          @request = request
+        end
+        # Converts the body to a String so you can work with the entire
+        # thing.
+        def to_s
+          @value ? @value.join : @request.body
+        end
+        # Iterates over the body in chunks. If the body has previously
+        # been read, this method can be called again and get the same
+        # sequence of chunks.
+        # @yield [chunk]
+        # @yieldparam [String] chunk a chunk of the request body
+        def each
+          if @value
+            @value.each {|chunk| yield chunk }
+          else
+            @value = []
+            @request.body {|chunk| @value << chunk; yield chunk }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/webmachine/adapters.rb ADDED Viewed

@@ -0,0 +1,15 @@
+require 'webmachine/adapters/webrick'
+module Webmachine
+  # Contains classes and modules that connect Webmachine to Ruby
+  # application servers.
+  module Adapters
+  end
+  class << self
+    # @return [Symbol] the current webserver adapter
+    attr_accessor :adapter
+  end
+  self.adapter = :WEBrick
+end

data/lib/webmachine/decision/conneg.rb ADDED Viewed

@@ -0,0 +1,304 @@
+require 'webmachine/translation'
+module Webmachine
+  module Decision
+    # Contains methods concerned with Content Negotiation,
+    # specifically, choosing media types, encodings, character sets
+    # and languages.
+    module Conneg
+      HAS_ENCODING = defined?(::Encoding) # Ruby 1.9 compat
+      # Given the 'Accept' header and provided types, chooses an
+      # appropriate media type.
+      # @api private
+      def choose_media_type(provided, header)
+        requested = MediaTypeList.build(header.split(/\s*,\s*/))
+        provided = provided.map do |p| # normalize_provided
+          MediaType.new(*Array(p))
+        end
+        # choose_media_type1
+        chosen = nil
+        requested.each do |_, requested_type|
+          break if chosen = media_match(requested_type, provided)
+        end
+        chosen
+      end
+      # Given the 'Accept-Encoding' header and provided encodings, chooses an appropriate
+      # encoding.
+      # @api private
+      def choose_encoding(provided, header)
+        encodings = provided.keys
+        if encoding = do_choose(encodings, header, "identity")
+          response.headers['Content-Encoding'] = encoding unless encoding == 'identity'
+          metadata['Content-Encoding'] = encoding
+        end
+      end
+      # Given the 'Accept-Charset' header and provided charsets,
+      # chooses an appropriate charset.
+      # @api private
+      def choose_charset(provided, header)
+        if provided && !provided.empty?
+          charsets = provided.map {|c| c.first }
+          if charset = do_choose(charsets, header, HAS_ENCODING ? Encoding.default_external.name : kcode_charset)
+            metadata['Charset'] = charset
+          end
+        else
+          true
+        end
+      end
+      # Given the 'Accept-Language' header and provided languages,
+      # chooses an appropriate language.
+      # @api private
+      def choose_language(provided, header)
+        if provided && !provided.empty?
+          requested = PriorityList.build(header.split(/\s*,\s*/))
+          star_priority = requested.priority_of("*")
+          any_ok = star_priority && star_priority > 0.0
+          accepted = requested.find do |priority, range|
+            if priority == 0.0
+              provided.delete_if {|tag| language_match(range, tag) }
+              false
+            else
+              provided.any? {|tag| language_match(range, tag) }
+            end
+          end
+          chosen = if accepted
+                     provided.find {|tag| language_match(accepted.last, tag) }
+                   elsif any_ok
+                     provided.first
+                   end
+          if chosen
+            metadata['Language'] = chosen
+            response.headers['Content-Language'] = chosen
+          end
+        else
+          true
+        end
+      end
+      # RFC2616, section 14.14:
+      #
+      # A language-range matches a language-tag if it exactly
+      # equals the tag, or if it exactly equals a prefix of the
+      # tag such that the first tag character following the prefix
+      # is "-".
+      def language_match(range, tag)
+        range.downcase == tag.downcase || tag =~ /^#{Regexp.escape(range)}\-/i
+      end
+      # Makes an conneg choice based what is accepted and what is
+      # provided.
+      # @api private
+      def do_choose(choices, header, default)
+        choices = choices.dup.map {|s| s.downcase }
+        accepted = PriorityList.build(header.split(/\s*,\s/))
+        default_priority = accepted.priority_of(default)
+        star_priority = accepted.priority_of("*")
+        default_ok = (default_priority.nil? && star_priority != 0.0) || default_priority
+        any_ok = star_priority && star_priority > 0.0
+        chosen = accepted.find do |priority, acceptable|
+          if priority == 0.0
+            choices.delete(acceptable.downcase)
+            false
+          else
+            choices.include?(acceptable.downcase)
+          end
+        end
+        (chosen && chosen.last) ||  # Use the matching one
+          (any_ok && choices.first) || # Or first if "*"
+          (default_ok && choices.include?(default) && default) # Or default
+      end
+      private
+      # Matches acceptable items that include 'q' values
+      CONNEG_REGEX = /^\s*(\S+);\s*q=(\S*)\s*$/
+      # Matches sub-type parameters
+      PARAMS_REGEX = /;([^=]+)=([^;=\s]+)/
+      # Matches valid media types
+      MEDIA_TYPE_REGEX = /^\s*([^;\s]+)\s*((?:;\S+\s*)*)\s*$/
+      # Encapsulates a MIME media type, with logic for matching types.
+      class MediaType
+        # Creates a new MediaType by parsing its string representation.
+        def self.parse(str)
+          if str =~ MEDIA_TYPE_REGEX
+            type, raw_params = $1, $2
+            params = Hash[raw_params.scan(PARAMS_REGEX)]
+            new(type, params)
+          end
+        end
+        # @return [String] the MIME media type
+        attr_accessor :type
+        # @return [Hash] any type parameters, e.g. charset
+        attr_accessor :params
+        def initialize(type, params={})
+          @type, @params = type, params
+        end
+        # Detects whether the {MediaType} represents an open wildcard
+        # type, that is, "*/*" without any {#params}.
+        def matches_all?
+          @type == "*/*" && @params.empty?
+        end
+        def ==(other)
+          other = self.class.parse(other) if String === other
+          other.type == type && other.params == params
+        end
+        # Detects whether this {MediaType} matches the other {MediaType},
+        # taking into account wildcards.
+        def match?(other)
+          type_matches?(other) && other.params == params
+        end
+        # Reconstitutes the type into a String
+        def to_s
+          [type, *params.map {|k,v| "#{k}=#{v}" }].join(";")
+        end
+        # @return [String] The major type, e.g. "application", "text", "image"
+        def major
+          type.split("/").first
+        end
+        # @return [String] the minor or sub-type, e.g. "json", "html", "jpeg"
+        def minor
+          type.split("/").last
+        end
+        def type_matches?(other)
+          if ["*", "*/*", type].include?(other.type)
+            true
+          else
+            other.major == major && other.minor == "*"
+          end
+        end
+      end
+      # Matches the requested media type (with potential modifiers)
+      # against the provided types (with potential modifiers).
+      # @param [MediaType] requested the requested media type
+      # @param [Array<MediaType>] provided the provided media
+      #     types
+      # @return [MediaType] the first media type that matches
+      def media_match(requested, provided)
+        return provided.first if requested.matches_all?
+        provided.find do |p|
+          p.match?(requested)
+        end
+      end
+      # Translate a KCODE value to a charset name
+      def kcode_charset
+        case $KCODE
+        when /^U/i
+          "UTF-8"
+        when /^S/i
+          "Shift-JIS"
+        when /^B/i
+          "Big5"
+        else #when /^A/i, nil
+          "ASCII"
+        end
+      end
+      # @private
+      # Content-negotiation priority list that takes into account both
+      # assigned priority ("q" value) as well as order, since items
+      # that come earlier in an acceptance list have higher priority
+      # by fiat.
+      class PriorityList
+        # Given an acceptance list, create a PriorityList from them.
+        def self.build(list)
+          new.tap do |plist|
+            list.each {|item| plist.add_header_val(item) }
+          end
+        end
+        include Enumerable
+        # Creates a {PriorityList}.
+        # @see PriorityList::build
+        def initialize
+          @hash = Hash.new {|h,k| h[k] = [] }
+          @index = {}
+        end
+        # Adds an acceptable item with the given priority to the list.
+        # @param [Float] q the priority
+        # @param [String] choice the acceptable item
+        def add(q, choice)
+          @index[choice] = q
+          @hash[q] << choice
+        end
+        # Given a raw acceptable value from an acceptance header,
+        # parse and add it to the list.
+        # @param [String] c the raw acceptable item
+        # @see #add
+        def add_header_val(c)
+          if c =~ CONNEG_REGEX
+            choice, q = $1, $2
+            q = "0" << q if q =~ /^\./ # handle strange FeedBurner Accept
+            add(q.to_f,choice)
+          else
+            add(1.0, c)
+          end
+        end
+        # @param [Float] q the priority to lookup
+        # @return [Array<String>] the list of acceptable items at
+        #     the given priority
+        def [](q)
+          @hash[q]
+        end
+        # @param [String] choice the acceptable item
+        # @return [Float] the priority of that value
+        def priority_of(choice)
+          @index[choice]
+        end
+        # Iterates over the list in priority order, that is, taking
+        # into account the order in which items were added as well as
+        # their priorities.
+        # @yield [q,v]
+        # @yieldparam [Float] q the acceptable item's priority
+        # @yieldparam [String] v the acceptable item
+        def each
+          @hash.to_a.sort.reverse_each do |q,l|
+            l.each {|v| yield q, v }
+          end
+        end
+      end
+      # Like a {PriorityList}, but for {MediaTypes}, since they have
+      # parameters in addition to q.
+      # @private
+      class MediaTypeList < PriorityList
+        include Translation
+        # Overrides {PriorityList#add_header_val} to insert
+        # {MediaType} items instead of Strings.
+        # @see PriorityList#add_header_val
+        def add_header_val(c)
+          if mt = MediaType.parse(c)
+            q = mt.params.delete('q') || 1.0
+            add(q.to_f, mt)
+          else
+            raise MalformedRequest, t('invalid_media_type', :type => c)
+          end
+        end
+      end
+    end
+  end
+end