stubb 0.1.rc.1

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2011 Johannes Emerich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,159 @@
+Stubb
+=====
+
+Stubb allows to **set up a REST API stub by putting responses in files** organized in a directory tree. Which file is picked in response to a particular HTTP request is primarily determined by the request's **method**, **path** and **accept header**. Thus adding a response for a certain type of request is as easy as adding a file with a matching name. For example, the file
+
+    whales/narwhal.GET.json
+
+in your base directory will be picked to deliver the response to the request
+
+    GET /whales/narwhal.json HTTP/1.1
+
+or alternatively
+
+    GET /whales/narwhal HTTP/1.1
+    Accept: application/json
+
+.
+
+Additionally, **sequences of responses** to repeated identical requests can be defined through infix numerals in file names.
+
+Directory Structure and Response Files
+--------------------------------------
+
+All requests are served from the *base directory*, that is the directory Stubb was started from. The directory tree in your base directory determines the path hierarchy of your stubbed REST API. Request paths are mapped to relative paths within the base directory to locate a response file.
+
+### Response Files
+
+A *response file* is a file containing an API response. There are two kinds of response files, member response files and collection response files. They differ only in concept and naming.
+
+#### Member Response Files
+
+A *member response file* is a file containing an API response for a member resource, named after the scheme
+
+    REQUEST_PATH_WITHOUT_EXTENSION.HTTP_METHOD[.SEQUENCE_NUMBER][.FILE_TYPE]
+
+, where `SEQUENCE_NUMBER` is optional and only needed when defining response sequences, and `FILE_TYPE` is also optional and only needed when a file type is implied by request path or accept header.
+
+Examples:
+
+    whales/narwhal.GET
+    whales/narwhal.GET.json
+    whales/narwhal.GET.1
+    whales/narwhal.GET.1.json
+
+#### Collection Response Files
+
+A *collection response file* is a file containing an API response for a collection resource, named after the scheme
+
+    REQUEST_PATH_WITHOUT_EXTENSION/HTTP_METHOD[.SEQUENCE_NUMBER][.FILE_TYPE]
+
+, where `SEQUENCE_NUMBER` is optional and only needed when defining response sequences, and `FILE_TYPE` is also optional and only needed when a file type is implied by request path or accept header.
+
+Examples:
+
+    whales/GET
+    whales/GET.json
+    whales/GET.1
+    whales/GET.1.json
+
+### Response Files as ERB Templates
+
+Any matching response file will be evaluated as an ERB template, with `GET` or `POST` parameters available in a `params` hash. This can come in handy when stubbing `POST` and `PUT` requests or serving JSONP.
+
+### YAML Frontmatter
+
+Response files may contain YAML frontmatter before the response text, allowing to set custom values for response status and header:
+
+    ---
+    status: 201
+    header:
+      Cache-Control: no-cache
+    ---
+    {"name":"Stubb"}
+
+### Missing Responses
+
+If no matching response file is found, Stubb replies with a status of `404`. You can customize error responses for types of requests by creating a matching response file that contains your custom response.
+
+Path Matching
+-------------
+
+Paths in the base directory may include wildcards to allow one response file to match for a whole range of request paths instead of just one. Both Directory names and file names may be wildcards. Wildcards are marked by starting and ending in an underscore (`_`). A wildcard segment matches any equally positioned segment of a request path.
+
+For example
+
+    whales/_default_whale_.GET.json
+
+matches
+
+    GET /whales/pygmy_sperm_whale.json HTTP/1.1
+
+as well as
+
+    GET /whales/blackfish.json HTTP/1.1
+
+.
+
+If a literal match exists, it will be chosen over a wildcard match.
+
+Response Sequences
+------------------
+
+A *response sequence* is a sequence of response files whose members are being used as responses to a sequence of requests of the same type. This allows for controlled stubbing of changes in the API.
+
+### Stalling Sequences (1..._n_)
+
+A *stalling sequence* keeps responding with the last response file in the response sequence after _n_ requests of the same type. Stalling sequences are specified by adding response files with indices 1 through _n_.
+
+    GET.1.format, GET.2.format, ..., GET._n-1_.format, GET._n_.format
+
+Example:
+
+    whales/GET.1.json
+    whales/GET.2.json
+    whales/GET.3.json
+
+From the third request on, the response to
+
+    GET /whales.json HTTP/1.1
+
+will be the one given in `whales/GET.3.json`.
+
+### Looping Sequences (0..._n-1_)
+
+A *stalling sequence* starts from the first response file in the response sequence after _n_ requests of the same type. Looping sequences are specified by adding response files with indices 0 through _n_-1.
+
+    GET.0.format, GET.1.format, ..., GET._n-2_.format, GET._n-1_.format
+
+Example:
+
+    whales/GET.0.json
+    whales/GET.1.json
+    whales/GET.2.json
+
+The response to the fourth request to
+
+    GET /whales.json HTTP/1.1
+
+will again be the one given in `whales/GET.0.json`, and so forth.
+
+Dependencies
+------------
+
+Stubb depends on
+
+  - <a href="http://github.com/rack/rack">Rack</a> for processing and serving requests, and
+  - <a href="https://github.com/wycats/thor">Thor</a> for adding a CLI executable.
+
+License
+-------
+
+Copyright (c) 2011 Johannes Emerich
+
+MIT-style licensing, for details see file `LICENSE`.
+
+<hr>
+
+_'Why,' thinks I, 'what's the row? It's not a real leg, only a false leg.'_  
+--Stubb in _Moby Dick_

data/bin/stubb

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), *%w[.. lib])
+
+require 'thor'
+require 'stubb'
+
+module Stubb
+  class CLI < Thor
+    map '-v' => :version
+
+    desc 'server', 'Starts the server'
+    method_option :port, :type => :numeric, :default => 4040, :aliases => '-p', :desc => 'Specifies the port for the server to use'
+    method_option :root, :type => :string, :default => '', :aliases => '-r', :desc => 'Specifies the root directory to serve from'
+    method_option :verbose, :type => :boolean, :aliases => '-v', :desc => 'Print debug messages'
+    def server
+      Stubb.run :Port => options[:port], :root => options[:root], :verbose => options[:verbose]
+    end
+
+    desc 'version', 'Print the version of Stubb'
+    def version
+      puts Stubb::VERSION
+    end
+  end
+end
+
+Stubb::CLI.start

data/lib/stubb/combined_logger.rb

@@ -0,0 +1,30 @@
+module Stubb
+
+  class CombinedLogger < Rack::CommonLogger
+    FORMAT = %{%s - %s [%s] "%s %s%s %s" %d %s %0.4f "%s" "%s"\n}
+
+    def log(env, status, header, began_at)
+      now = Time.now
+      length = extract_content_length(header)
+
+      logger = @logger || env['rack.errors']
+      logger.write FORMAT % [
+        env['HTTP_X_FORWARDED_FOR'] || env['REMOTE_ADDR'] || '-',
+        env['REMOTE_USER'] || '-',
+        now.strftime('%d/%b/%Y %H:%M:%S'),
+        env['REQUEST_METHOD'],
+        env['PATH_INFO'],
+        env['QUERY_STRING'].empty? ? '' : '?'+env['QUERY_STRING'],
+        env['HTTP_VERSION'],
+        status.to_s[0..3],
+        length,
+        now - began_at,
+        header.delete('stubb.response_file') || 'NONE',
+        "YAML Frontmatter: #{header.delete('stubb.yaml_frontmatter') || 'No'}"
+      ]
+
+    end
+
+  end
+
+end

data/lib/stubb/counter.rb

@@ -0,0 +1,33 @@
+module Stubb
+
+  class Counter
+  
+    def initialize(app)
+      @app = app
+      @request_history = {}
+      trap(:INT) { |signal| reset_or_quit signal }
+    end
+
+    def call(env)
+      env['stubb.request_sequence_index'] = count(env['REQUEST_METHOD'], env['PATH_INFO'], env['HTTP_ACCEPT'])
+      @app.call(env)
+    end
+
+    private
+    def count(method, path, accept)
+      fingerprint = "#{method}-#{path}-#{accept}"
+      @request_history[fingerprint] = (@request_history[fingerprint] || 0) + 1
+    end
+
+    def reset_or_quit(signal)
+      if @request_history.empty?
+        exit! signal
+      else
+        @request_history.clear
+        puts "\n\nReset request history. Interrupt again to quit.\n\n"
+      end
+    end
+
+  end
+
+end

data/lib/stubb/finder.rb

@@ -0,0 +1,71 @@
+module Stubb
+
+  class NotFound < Exception; end
+
+  class Finder
+    
+    attr_accessor :request, :root
+
+    def initialize(options = {})
+      @root = File.expand_path options[:root] || ''
+      @verbose = options[:verbose] || false
+    end
+
+    def call(env)
+      @request = Request.new env
+
+      respond
+
+    rescue Errno::ENOENT, Errno::ELOOP
+      [404, {"Content-Type" => "text/plain"}, ["Not found."]]
+    rescue Exception => e
+      debug e.message, e.backtrace.join("\n")
+      [500, {'Content-Type' => 'text/plain'}, ['Internal server error.']]
+    end
+
+    private
+    def respond
+      response_file_path = projected_path
+      response_body = File.open(response_file_path, 'r')  {|f| f.read }
+      Response.new(
+        response_body,
+        request.params,
+        200,
+        {'Content-Type' => content_type, 'stubb.response_file' => response_file_path}
+      ).finish
+    rescue NotFound => e
+      debug e.message
+      [404, {}, e.message]
+    end
+
+    def request_options_as_file_ending
+      "#{request.request_method}#{request.extension}"
+    end
+
+    def exists?(relative_path)
+      File.exists? local_path_for(relative_path)
+    end
+
+    def local_path_for(relative_path)
+      File.join root, relative_path
+    end
+
+    def content_type
+      Rack::Mime.mime_type(request.extension) || "text/html"
+    end
+
+    def debug(*messages)
+      log(*messages) if @verbose
+    end
+
+    def log(*messages)
+      if request.env['rack.errors'] && request.env['rack.errors'].respond_to?('write')
+        request.env['rack.errors'].write messages.join(" ") << "\n"
+      else
+        puts messages.join(" ")
+      end
+    end
+
+  end
+
+end

data/lib/stubb/match_finder.rb

@@ -0,0 +1,62 @@
+module Stubb
+
+  class NoMatch < NotFound; end
+
+  class MatchFinder < Finder
+    private
+    def projected_path
+      built_path  = []
+      last_is_dir = false
+      request.path_parts.each_with_index do |level, index|
+        if match = literal_directory(built_path, level)
+          last_is_dir = true
+        elsif match = literal_file(built_path, level)
+          last_is_dir = false
+        elsif match = matching_directory(built_path)
+          last_is_dir = true
+        elsif match = matching_file(built_path)
+          last_is_dir = false
+        else
+          raise NoMatch
+        end
+
+        built_path << match
+      end
+
+      if last_is_dir
+        File.join local_path_for(built_path), request_options_as_file_ending
+      else
+        local_path_for built_path
+      end
+    end
+
+    def literal_directory(current_path, level)
+      File.directory?(local_path_for(current_path + [level])) ? level: nil
+    end
+
+    def literal_file(current_path, level)
+      parts = level.split('.')
+      level = parts.size > 1 ? parts[0..-2].join('.') : parts.first
+      filename = "#{level}.#{request_options_as_file_ending}"
+      File.exists?(local_path_for(current_path + [filename])) ? filename : nil
+    end
+
+    def matching_directory(current_path)
+      matches = Dir.glob local_path_for(current_path + [Stubb.matcher_pattern])
+      for match in matches
+        continue unless File.directory? match
+        return File.split(match).last
+      end
+      nil
+    end
+
+    def matching_file(current_path)
+      matches = Dir.glob local_path_for(current_path + ["#{Stubb.matcher_pattern}.#{request_options_as_file_ending}"])
+
+      matches.empty? ? nil : File.split(matches.first).last
+    end
+
+  end
+
+
+end

data/lib/stubb/naive_finder.rb

@@ -0,0 +1,18 @@
+module Stubb
+
+  class NaiveFinder < Finder
+    
+    private
+    def projected_path
+      relative_path = if File.directory? local_path_for(request.resource_path)
+        File.join request.resource_path, request_options_as_file_ending
+      else
+        "#{request.resource_path}.#{request_options_as_file_ending}"
+      end
+
+      local_path_for relative_path
+    end
+
+  end
+
+end

data/lib/stubb/request.rb

@@ -0,0 +1,55 @@
+module Stubb
+
+  class Request < Rack::Request
+
+    def path_parts
+      relative_path.split '/'
+    end
+
+    def path_dir_parts
+      parts = path_parts
+      parts.size > 1 ? parts[0..-2] : []
+    end
+
+    def file_name
+      path_parts.last
+    end
+
+    def resource_name
+      parts = file_name.split('.')
+      parts.size > 1 ? parts[0..-2].join('.') : parts.first
+    end
+
+    def resource_path
+      File.join((path_dir_parts << resource_name).compact)
+    end
+
+    def extension
+      extension_by_path.empty? ? extension_by_header : extension_by_path
+    end
+
+    def extension_by_path
+      File.extname(relative_path)
+    end
+
+    def extension_by_header
+      Rack::Mime::MIME_TYPES.invert[accept]
+    end
+
+    # TODO parse, sort
+    def accept
+      @env['HTTP_ACCEPT'].to_s.split(',').first
+    end
+
+    def relative_path
+      # Strip slashes at string end and start
+      path_info.gsub /(\A\/|\/\Z)/, ''
+    end
+
+    def sequence_index
+      @env['stubb.request_sequence_index'] || 1
+    end
+
+  end
+
+end

data/lib/stubb/response.rb

@@ -0,0 +1,46 @@
+require 'erb'
+
+module Stubb
+
+  class Response < Rack::Response
+
+    attr_accessor :body, :params, :status, :header
+
+    def initialize(body=[], params={}, status=200, header={})
+      @body   = body
+      @params = params
+      @status = status
+      @header = header
+
+      process_yaml
+      render_template
+
+      super self.body, self.status, self.header
+    end
+
+    private
+    def process_yaml
+      if self.body =~ /^(---\s*\n.*?\n?)^(---\s*$\n?)/m
+        self.body = self.body[($1.size + $2.size)..-1]
+        begin
+          data = YAML.load($1)
+
+          # Use specified HTTP status
+          self.status = data['status'] if data['status']
+          # Fill header information
+          data['header'].each { |field, value| self.header[field] = value } if data['header'].kind_of? Hash
+          self.header['stubb.yaml_frontmatter'] = 'Yes'
+        rescue => e
+          self.header['stubb.yaml_frontmatter'] = 'Error'
+        end
+      end
+    end
+
+    def render_template
+      erb = ERB.new @body
+      @body = erb.result binding
+    end
+
+  end
+
+end

data/lib/stubb/sequence_finder.rb

@@ -0,0 +1,45 @@
+module Stubb
+
+  class NoSuchSequence < NotFound; end
+
+  class SequenceFinder < Finder
+    private
+    def projected_path
+      sequence_members = Dir.glob local_path_for(sequenced_path_pattern)
+      raise NoSuchSequence.new("Nothing found for sequence pattern `#{sequenced_path_pattern}`.") if sequence_members.empty?
+
+      loop? ?  pick_loop_member(sequence_members) : pick_stall_member(sequence_members)
+    end
+
+    def pick_loop_member(sequence_members)
+        sequence_members[(request.sequence_index - 1) % sequence_members.size]
+    end
+
+    def pick_stall_member(sequence_members)
+        request.sequence_index > sequence_members.size ? sequence_members.last : sequence_members[request.sequence_index - 1]
+    end
+
+    def sequenced_path(index)
+      if File.directory? local_path_for(request.relative_path)
+        File.join request.relative_path, request_options_as_file_ending(index)
+      else
+        "#{request.relative_path}.#{request_options_as_file_ending(index)}"
+      end
+    end
+
+    def sequenced_path_pattern
+      sequenced_path('[0-9]')
+    end
+
+    def request_options_as_file_ending(index)
+      "#{request.request_method}.#{index}#{request.extension}"
+    end
+
+    def loop?
+      exists? sequenced_path(0)
+    end
+
+  end
+
+
+end

data/lib/stubb/sequence_match_finder.rb

@@ -0,0 +1,58 @@
+module Stubb
+
+  class SequenceMatchFinder < SequenceFinder
+    private
+    def sequenced_path(sequence_index)
+      built_path  = []
+      last_is_dir = false
+      request.path_parts.each_with_index do |level, index|
+        if match = literal_directory(built_path, level)
+          last_is_dir = true
+        elsif match = literal_file(built_path, level, sequence_index)
+          last_is_dir = false
+        elsif match = matching_directory(built_path)
+          last_is_dir = true
+        elsif match = matching_file(built_path, sequence_index)
+          last_is_dir = false
+        else
+          return 'NOT FOUND'
+        end
+
+        built_path << match
+      end
+
+      if last_is_dir
+        File.join built_path, request_options_as_file_ending(sequence_index)
+      else
+        File.join built_path
+      end
+    end
+
+    def literal_directory(current_path, level)
+      File.directory?(local_path_for(current_path + [level])) ? level: nil
+    end
+
+    def literal_file(current_path, level, index)
+      filename = "#{level}.#{request_options_as_file_ending(index)}"
+      sequence_members = Dir.glob local_path_for(current_path + [filename])
+      sequence_members.empty? ? nil : filename
+    end
+
+    def matching_directory(current_path)
+      matches = Dir.glob local_path_for(current_path + [Stubb.matcher_pattern])
+      for match in matches
+        continue unless File.directory? match
+        return File.split(match).last
+      end
+      nil
+    end
+
+    def matching_file(current_path, index)
+      matches = Dir.glob local_path_for(current_path + ["#{Stubb.matcher_pattern}.#{request_options_as_file_ending(index)}"])
+
+      matches.empty? ? nil : File.split(matches.first).last
+    end
+
+  end
+
+end

data/lib/stubb.rb

@@ -0,0 +1,51 @@
+require 'rack'
+
+module Stubb
+
+  VERSION = '0.1.rc.1'
+
+  class ResponseNotFound < Exception
+  end
+
+  @config = {
+   :matcher_pattern => '_*_'
+  }
+
+  def self.method_missing(m, *attrs)
+    # Ease access to @config
+    if @config[m.to_sym]
+      @config[m.to_sym]
+    elsif @config[m.to_s.chomp('=').to_sym]
+      @config[m.to_s.chomp('=').to_sym] = attrs[0]
+    else
+      super
+    end
+  end
+
+  def self.app(options = {})
+    Rack::Builder.new {
+      use CombinedLogger
+      use Counter
+      
+      run Rack::Cascade.new([SequenceFinder.new(options), NaiveFinder.new(options), SequenceMatchFinder.new(options), MatchFinder.new(options)])
+    }.to_app
+  end
+
+  def self.run(options = {})
+    Rack::Handler.default.run(
+      app({:root => ''}.update(options)),
+      {:Port => 4040}.update(options)
+    )
+  end
+
+end
+
+require 'stubb/request'
+require 'stubb/response'
+require 'stubb/counter'
+require 'stubb/combined_logger'
+require 'stubb/finder'
+require 'stubb/naive_finder'
+require 'stubb/sequence_finder'
+require 'stubb/match_finder'
+require 'stubb/sequence_match_finder'

metadata

@@ -0,0 +1,125 @@
+--- !ruby/object:Gem::Specification 
+name: stubb
+version: !ruby/object:Gem::Version 
+  hash: 15424239
+  prerelease: true
+  segments: 
+  - 0
+  - 1
+  - rc
+  - 1
+  version: 0.1.rc.1
+platform: ruby
+authors: 
+- Johannes Emerich
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-02-24 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  requirement: *id001
+  name: rake
+  type: :development
+  prerelease: false
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 31
+        segments: 
+        - 1
+        - 2
+        - 0
+        version: 1.2.0
+  requirement: *id002
+  name: rack
+  type: :runtime
+  prerelease: false
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  requirement: *id003
+  name: thor
+  type: :runtime
+  prerelease: false
+description: Stubb is the second mate.
+email: johannes@emerich.de
+executables: 
+- stubb
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/stubb.rb
+- lib/stubb/request.rb
+- lib/stubb/response.rb
+- lib/stubb/counter.rb
+- lib/stubb/combined_logger.rb
+- lib/stubb/finder.rb
+- lib/stubb/naive_finder.rb
+- lib/stubb/sequence_finder.rb
+- lib/stubb/match_finder.rb
+- lib/stubb/sequence_match_finder.rb
+- bin/stubb
+- LICENSE
+- README.markdown
+has_rdoc: true
+homepage: http://github.com/knuton/stubb
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      hash: 25
+      segments: 
+      - 1
+      - 3
+      - 1
+      version: 1.3.1
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Specify REST API stubs using your file system
+test_files: []
+