RubyGems - webmachine - Versions diffs - 0.1.0 - Mend

webmachine 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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