hyperdrive 0.0.5 → 0.0.6

data/lib/hyperdrive/param.rb

@@ -0,0 +1,44 @@
+# encoding: utf-8
+
+module Hyperdrive
+  class Param
+    attr_reader :name, :description, :required, :type, :constraints
+
+    def initialize(name, description, options = {})
+      @name = name.to_s
+      @description = description
+      options = default_options.merge(options)
+      @required = if options[:required] == true
+                    %w(POST PUT PATCH)
+                  elsif options[:required] == false
+                    []
+                  else
+                    Array(options[:required])
+                  end
+      @type = options[:type]
+      @constraints = "#{required_constraint} #{options[:constraints]}"
+    end
+
+    def required?(http_request_method)
+      @required.include? http_request_method
+    end
+
+    def to_hash
+      { name: @name, description: @description, type: @type, constraints: @constraints }
+    end
+
+    private
+
+    def default_options
+      { required: true, type: 'String', constraints: nil }
+    end
+
+    def required_constraint
+      if @required.empty?
+        ''
+      else
+        "Required for: #{@required.join(', ')}."
+      end
+    end
+  end
+end

data/lib/hyperdrive/resource.rb

@@ -2,37 +2,62 @@
 
 module Hyperdrive
   class Resource
-    attr_reader :endpoint, :allowed_params, :filters, :request_handlers
-    attr_accessor :name, :desc
+    include Hyperdrive::Values
+    attr_reader :id, :namespace, :endpoint, :params, :filters, :request_handlers, :version
+    attr_accessor :name, :description
 
-    def initialize(key)
-      @key = key
-      @endpoint = "/#{@key.to_s.en.plural}"
-      @allowed_params = default_allowed_params
+    def initialize(name, hyperdrive_config = hyperdrive.config)
+      @namespace = name.to_s.en.plural
+      @endpoint = "/#{namespace}"
+      @params = default_params
       @filters = default_filters
       @request_handlers = default_request_handlers
+      @config = hyperdrive_config
+      @id = [@config[:vendor], @namespace].join(':')
     end
 
-    def register_param(key, description, options = {})
-      options = default_param_options.merge(options)
-      @allowed_params[key] = { desc: description }.merge(options)
+    def register_param(param, description, options = {})
+      @params[param] = Param.new(param, description, options)
     end
 
-    def register_filter(key, description, options = {})
-      options = default_filter_options.merge(options)
-      @filters[key] = { desc: description }.merge(options)
+    def register_filter(filter, description, options = {})
+      @filters[filter] = Filter.new(filter, description, options)
     end
 
-    def define_request_handler(request_method, block)
-      @request_handlers[request_method] = block
+    def register_request_handler(request_method, request_handler, version = 'v1')
+      @request_handlers[request_method] ||= {}
+      @request_handlers[request_method].merge!({ version => request_handler })
       if request_method == :get
-        @request_handlers[:head] = block
+        @request_handlers[:head] ||= {}
+        @request_handlers[:head].merge!({ version => @request_handlers[:get][version] })
       end
     end
 
-    def request_handler(http_request_method)
-      request_method = Hyperdrive::Values.request_methods_string_map[http_request_method]
-      request_handlers[request_method]
+    def request_handler(http_request_method, version = nil)
+      version ||= latest_version(http_request_method)
+      request_method = http_request_methods[http_request_method]
+      request_handlers[request_method][version]
+    end
+
+    def acceptable_content_types(http_request_method)
+      content_types = []
+      @config[:media_types].each do |media_type|
+        available_versions(http_request_method).each do |version|
+          content_types << "application/vnd.#{@config[:vendor]}.#{namespace}.#{version}+#{media_type}"
+        end
+        content_types << "application/vnd.#{@config[:vendor]}.#{namespace}+#{media_type}"
+        content_types << "application/vnd.#{@config[:vendor]}+#{media_type}"
+      end
+      content_types
+    end
+
+    def available_versions(http_request_method)
+      request_method = http_request_methods[http_request_method]
+      @request_handlers[request_method].keys.sort.reverse
+    end
+
+    def latest_version(http_request_method)
+      available_versions(http_request_method).first
     end
 
     def request_method_allowed?(http_request_method)
@@ -40,33 +65,52 @@ module Hyperdrive
     end
 
     def allowed_methods
-      Hyperdrive::Values.request_methods_symbol_map.values_at(*request_handlers.keys)
+      request_methods.values_at(*request_handlers.keys)
     end
 
-    private
+    def required_param?(param, http_request_method)
+      return false if %w(GET HEAD OPTIONS).include? http_request_method
+      params.key?(param) and params[param].required?(http_request_method)
+    end
 
-    def default_allowed_params
+    def required_filter?(filter, http_request_method)
+      return false unless %w(GET HEAD OPTIONS).include? http_request_method
+      filters.key?(filter) and filters[filter].required?(http_request_method)
+    end
+
+    def required?(param, http_request_method)
+      required_param?(param, http_request_method) or required_filter?(param, http_request_method)
+    end
+
+    def to_hash
       {
-        id: { desc: 'Resource Identifier', required: %w(PUT PATCH DELETE) }
+        _links: { 'self' => { href: endpoint } },
+        id: id,
+        name: name,
+        description: description,
+        methods: allowed_methods,
+        params: params.map { |_,param| param.to_hash },
+        filters: filters.map { |_,filter| filter.to_hash },
+        media_types: allowed_methods.map { |method| acceptable_content_types(method) }.uniq
       }
     end
 
-    def default_param_options
-      { required: true }.freeze
-    end
+    private
 
-    def default_filters
+    def default_params
       {
-        id: { desc: 'Resource Identifier', required: false }
+        id: Param.new(:id, 'Identifier', required: %w(PUT PATCH DELETE))
       }
     end
 
-    def default_filter_options
-      { required: false }.freeze
+    def default_filters
+      {
+        id: Filter.new(:id, 'Resource Identifier', required: false)
+      }
     end
 
     def default_request_handlers
-      { options: proc { '' } }
+      { options: { 'v1' => proc { |env| '' } } }
     end
   end
 end

data/lib/hyperdrive/server.rb

@@ -10,30 +10,29 @@ module Hyperdrive
 
     def self.server
       Rack::Builder.new do
-        use Rack::Runtime
         use Rack::Lint
+        use Rack::Runtime
+        use Rack::MethodOverride
         use Rack::Head
+        use Rack::ConditionalGet
+        use Hyperdrive::Middleware::Error
+        use Hyperdrive::Middleware::Accept
+        use Rack::Deflater
+        use Rack::ETag, "max-age=0,private,must-revalidate", "public,max-age=86400,s-maxage=86400"
 
         map '/' do
-          info = ''
-          hyperdrive.resources.each do |type, resource|
-            info += %Q({"id":"#{resource.endpoint}","name":"#{resource.name}","desc":"#{resource.desc}","type":"#{type}"})
-          end
-
-          run ->(env) {
-            [200, { 'Content-Type' => 'application/json', 'Allow' => Hyperdrive::Values.request_methods.join(",") }, ["[#{info}]"]]
-          }
+          run Hyperdrive::HATEOAS
         end
 
-        hyperdrive.resources.each do |key, resource|
+        hyperdrive.resources.each do |key, resource| 
           map resource.endpoint do
-            run ->(env) {
-              begin
-                Hyperdrive::Response.new(env, resource).response
-              rescue Hyperdrive::Errors::HTTPError => error
-                [error.http_status_code, { 'Allow' => resource.allowed_methods.join(',') }, [error.message]]
-              end
-            }
+            use Hyperdrive::Middleware::Resource, resource
+            use Hyperdrive::Middleware::RequestMethod
+            use Hyperdrive::Middleware::SanitizeParams
+            use Hyperdrive::Middleware::RequiredParams
+            use Hyperdrive::Middleware::CORS, hyperdrive.config[:cors]
+            use Hyperdrive::Middleware::ContentNegotiation
+            run Hyperdrive::Endpoint
           end
         end
       end.to_app

data/lib/hyperdrive/utils.rb

@@ -0,0 +1,27 @@
+# encoding: utf-8
+
+module Hyperdrive
+  module Utils
+    def self.sanitize_keys(keys_to_keep, hash)
+      Hash[hash.select do |key, value|
+        keys_to_keep.include? key
+      end]
+    end
+
+    def self.symbolize_keys(hash)
+      hash.inject({}) do |result, (key, value)|
+       result.merge!(Hash[
+          case key
+          when String then key.to_sym
+          else key
+          end,
+          case value
+          when Hash then symbolize_keys(value)
+          when Array then value.map! { |v| v.is_a?(Hash) ? symbolize_keys(v) : v } ; value
+          else value
+          end
+        ])
+      end
+    end
+  end
+end

data/lib/hyperdrive/values.rb

@@ -1,10 +1,18 @@
+# encoding: utf-8
+
 module Hyperdrive
   module Values
-    def self.request_methods
+    module_function
+
+    def definable_request_methods
+      [:get, :post, :put, :patch, :delete].freeze
+    end
+
+    def supported_request_methods
       %w(GET HEAD OPTIONS POST PUT PATCH DELETE).freeze
     end
 
-    def self.request_methods_symbol_map
+    def request_methods
       {
         get:     'GET',
         head:    'HEAD',
@@ -16,7 +24,7 @@ module Hyperdrive
       }.freeze
     end
 
-    def self.request_methods_string_map
+    def http_request_methods
       {
         'GET'     => :get,
         'HEAD'    => :head,
@@ -27,5 +35,31 @@ module Hyperdrive
         'DELETE'  => :delete
       }.freeze
     end
+
+    def default_cors_options
+      {
+          origins: '*',
+          allow_headers: 'Content-Type, Accept, Authorization, If-None-Match',
+          credentials: 'false',
+          expose_headers: 'Allow, Cache-Control, Content-Language, Content-Type, ETag',
+          max_age: 86400
+      }.freeze
+    end
+
+    def default_config
+      {
+        cors: default_cors_options,
+        name: 'Hyperdrive API',
+        description: "v#{Hyperdrive::VERSION}",
+        vendor: 'hyperdrive',
+        media_types: %w(hal+json json)
+      }.freeze
+    end
+
+    def default_headers
+      {
+        'X-Powered-By' => "Hyperdrive (v#{Hyperdrive::VERSION})"
+      }
+    end
   end
 end

data/lib/hyperdrive/version.rb

@@ -1,3 +1,3 @@
 module Hyperdrive
-  VERSION = "0.0.5"
+  VERSION = "0.0.6"
 end

data/lib/hyperdrive.rb

@@ -1,16 +1,30 @@
 # encoding: utf-8
 
-# stdlib
+# prepare for hyperspace!
+
+## stdlib
 require 'rack'
-require 'linguistics'
-Linguistics.use(:en)
+require 'rack/accept'
+require 'linguistics'; Linguistics.use(:en)
+require 'oj'
 
-# prepare for hyperspace!
+## immutable values
+require 'hyperdrive/values'
+require 'hyperdrive/version'
+
+## helpers
 require 'hyperdrive/docs'
+require 'hyperdrive/utils'
+
+## sugary syntax and state mangagement
 require 'hyperdrive/dsl'
 require 'hyperdrive/errors'
+require 'hyperdrive/param'
+require 'hyperdrive/filter' # must come after param
 require 'hyperdrive/resource'
-require 'hyperdrive/response'
+
+## rack apps and middleware
+require 'hyperdrive/endpoint'
+require 'hyperdrive/hateoas'
+require 'hyperdrive/middleware'
 require 'hyperdrive/server'
-require 'hyperdrive/values'
-require 'hyperdrive/version'

data/spec/hyperdrive/docs_spec.rb

@@ -4,17 +4,20 @@ require 'spec_helper'
 
 describe Hyperdrive::Docs do
   before do
-    sample_api
-    @docs = Hyperdrive::Docs.new(hyperdrive.resources)
+    @resources = { :thing => default_resource }
+    @docs = Hyperdrive::Docs.new(@resources)
   end
 
   it 'generates a header with size 1 as default' do
     @docs.header('Thing Resource').must_equal "\n\n# Thing Resource\n\n"
   end
 
-  it 'generates a header only between size 1 and 6' do
-    proc {@docs.header('Thing Resource', 0)}.must_raise ArgumentError
-    proc {@docs.header('Thing Resource', 8)}.must_raise ArgumentError
+  it 'raises an error if header size is less than 1' do
+    proc { @docs.header('Thing Resource', 0) }.must_raise ArgumentError
+  end
+
+  it 'raises an error if header size is greater than 6' do
+    proc { @docs.header('Thing Resource', 8) }.must_raise ArgumentError    
   end
 
   it 'generates a paragraph' do
@@ -33,11 +36,14 @@ describe Hyperdrive::Docs do
     @docs.bullet('test').must_equal "  - test\n"
   end
 
-  it 'generates a bullet with nest level between 1 and 3' do
-    proc {@docs.bullet('test', 4)}.must_raise ArgumentError
+  it 'raises an error if bullet indention size is less than 1' do
     proc {@docs.bullet('test', 0)}.must_raise ArgumentError
   end
 
+  it 'raises an error if bullet indention size is greater than 3' do
+    proc {@docs.bullet('test', 4)}.must_raise ArgumentError
+  end
+
   it 'generates a nested bulleted list' do
     @docs.bullet('test', 2).must_equal "    - test\n"
   end
@@ -53,4 +59,4 @@ describe Hyperdrive::Docs do
   it 'outputs a string of the completed doc' do
     @docs.output.must_be_kind_of String
   end
-end
+end

data/spec/hyperdrive/dsl/resource_spec.rb

@@ -3,56 +3,46 @@
 require 'spec_helper'
 
 describe Hyperdrive::DSL::Resource do
-
-  it "sets the name of the endpoint" do
+  before do
     hyperdrive do
       resource(:thing) do
-        name "Thing Resource"
+        name 'Thing Resource'
+        description 'Thing Description'
+        param :name, 'Thing Name'
+        filter :parent_id, "Parent ID"
+        request(:get) do
+          'ok'
+        end
       end
-    end.resources[:thing].name.must_equal 'Thing Resource'
+    end
   end
 
-  it "describes the endpoint" do
-    hyperdrive do
-      resource(:thing) do
-        desc "Thing Description"
-      end
-    end.resources[:thing].desc.must_equal 'Thing Description'
+  after do
+    hyperdrive.send(:reset!)
   end
 
-  it "registers an allowed param on a resource" do
-    hyperdrive do
-      resource(:thing) do
-        param :name, "Thing's Name"
-      end
-    end.resources[:thing].allowed_params[:name][:desc].must_equal "Thing's Name"
+  it "sets the name of the resource" do
+    hyperdrive.resources[:thing].name.must_equal 'Thing Resource'
   end
 
-  it "registers an allowed param on a resource" do
-    hyperdrive do
-      resource(:thing) do
-        filter :parent_id, "Thing's Parent ID"
-      end
-    end.resources[:thing].filters[:parent_id][:desc].must_equal "Thing's Parent ID"
+  it "sets the description of the resource" do
+    hyperdrive.resources[:thing].description.must_equal 'Thing Description'
+  end
+
+  it "registers a param for the resource" do
+    hyperdrive.resources[:thing].params[:name].description.must_equal "Thing Name"
+  end
+
+  it "registers a filter for the resource" do
+    hyperdrive.resources[:thing].filters[:parent_id].description.must_equal "Parent ID"
   end
 
   it "defines how requests are handled" do
-    hyperdrive do
-      resource(:thing) do
-        request(:get) do
-          'ok'
-        end
-      end
-    end.resources[:thing].request_handlers[:get].call.must_equal 'ok'
+    hyperdrive.resources[:thing].request_handlers[:get]['v1'].must_be :===, Proc
   end
 
-  it "raises an exception if request method argument is unknown" do
-    proc do
-      hyperdrive do
-        resource(:thing) do
-          request(:verb)
-        end
-      end
-    end.must_raise Hyperdrive::Errors::DSL::UnknownArgument
+  it "throws an error if request method is unknown" do 
+    bad_resource = -> { hyperdrive { resource(:thing) { request(:verb) } } }
+    bad_resource.must_raise Hyperdrive::Errors::DSL::UnknownArgument
   end
 end

data/spec/hyperdrive/dsl_spec.rb

@@ -0,0 +1,52 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe Hyperdrive::DSL do
+  before do
+    hyperdrive do
+      name 'Example'
+      description 'Example Description'
+      vendor 'example'
+      media_types %w(json)
+      cors({ origins: '*', allow_headers: %w(Accept), test: 'test'})
+      resource(:thing) {}
+    end
+  end
+
+  after do
+    hyperdrive.send(:reset!)
+  end
+
+  it "has a name" do
+    hyperdrive.config[:name].must_equal 'Example'
+  end
+
+  it "has a description" do
+    hyperdrive.config[:description].must_equal 'Example Description'
+  end
+
+  it "has a vendor" do
+    hyperdrive.config[:vendor].must_equal 'example'
+  end
+
+  it "has media types" do
+    hyperdrive.config[:media_types].must_equal ['json']
+  end
+
+  it "registers a resource" do
+    hyperdrive.resources[:thing].must_be_instance_of ::Hyperdrive::Resource
+  end
+
+  it "can configure cors options" do
+    hyperdrive.config[:cors][:allow_headers].must_equal ['Accept']
+  end
+
+  it "ensures missing options have default values" do
+    hyperdrive.config[:cors][:credentials].must_equal 'false'
+  end
+
+  it "removes unsupported cors options" do
+    hyperdrive.config[:cors].key?(:test).must_equal false
+  end
+end

data/spec/hyperdrive/endpoint_spec.rb

@@ -0,0 +1,22 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe Hyperdrive::Endpoint do
+  def app
+    Hyperdrive::Endpoint
+  end
+
+  before do
+    sample_api
+  end
+
+  after do
+    hyperdrive.send(:reset!)
+  end
+
+  it "responds to requests" do
+    get '/', {}, default_rack_env(hyperdrive.resources[:thing])
+    last_response.successful?.must_equal true
+  end
+end

data/spec/hyperdrive/filter_spec.rb

@@ -0,0 +1,34 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe Hyperdrive::Filter do
+  before do
+    @filter = default_filter
+  end
+
+  it "has a name" do
+    @filter.name.must_equal 'parent_id'
+  end
+
+  it "has a description" do
+    @filter.description.must_equal 'Parent Identifier'
+  end
+
+  it "returns an array of HTTP methods it's required for" do
+    @filter.required.must_equal %w(GET HEAD)
+  end
+
+  it "returns true if the param is required for the given HTTP method" do
+    @filter.required?('GET').must_equal true
+  end
+
+  it "returns false if the param is not required for the given HTTP method" do
+    @filter.required?('OPTIONS').must_equal false
+  end
+
+  it "converts itself as a hash" do
+    constraints = { name: 'parent_id', description: 'Parent Identifier', type: 'String', constraints: 'Required for: GET, HEAD. Must be a valid BSON Object ID.' }
+    @filter.to_hash.must_equal constraints
+  end
+end

data/spec/hyperdrive/hateoas_spec.rb

@@ -0,0 +1,42 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe Hyperdrive::HATEOAS do
+  def app
+    Hyperdrive::HATEOAS
+  end
+
+  context 'without Resources' do
+    it "throws a Not Found error" do
+      ->{ get '/' }.must_raise Hyperdrive::Errors::NotFound
+    end
+  end
+
+  context 'with Resources' do
+    before do
+      sample_api
+      get '/', {}, default_rack_env
+    end
+
+    after do
+      hyperdrive.send(:reset!)
+    end
+
+    it "responds successfully" do
+      last_response.successful?.must_equal true
+    end
+
+    it "sets the content type" do
+      last_response.headers['Content-Type'].must_equal 'application/json'
+    end
+
+    it "sets the allow header" do
+      last_response['Allow'].must_equal 'GET, HEAD, OPTIONS'
+    end
+
+    it "responds with a description of all resources" do
+      last_response.body.must_equal %Q({"_links":{"self":{"href":"/"}},"name":"Hyperdrive API","description":"v0.0.5","vendor":"hyperdrive","resources":[{"_links":{"self":{"href":"/things"}},"id":"hyperdrive:things","name":"Thing Resource","description":"Description of Thing Resource","methods":["OPTIONS","GET","HEAD","POST","PUT","PATCH","DELETE"],"params":[{"name":"id","description":"Identifier","type":"String","constraints":"Required for: PUT, PATCH, DELETE. "},{"name":"name","description":"50 Chars or less","type":"String","constraints":"Required for: POST, PUT, PATCH. "}],"filters":[{"name":"id","description":"Resource Identifier","type":"String","constraints":" "},{"name":"parent_id","description":"Parent ID of Thing","type":"String","constraints":"Required for: GET, HEAD. "}],"media_types":[["application/vnd.hyperdrive.things.v1+hal+json","application/vnd.hyperdrive.things+hal+json","application/vnd.hyperdrive+hal+json","application/vnd.hyperdrive.things.v1+json","application/vnd.hyperdrive.things+json","application/vnd.hyperdrive+json"]]}]})
+    end
+  end
+end

data/spec/hyperdrive/middleware/accept_spec.rb

@@ -0,0 +1,15 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe Hyperdrive::Middleware::Accept do
+  def app
+    inner_app = ->(env) { [200, {}, env['hyperdrive.accept'].values.join(", ")] }
+    Hyperdrive::Middleware::Accept.new(inner_app)
+  end
+
+  it "parses the accept header" do
+    get '/', {}, default_rack_env
+    last_response.body.must_equal 'application/vnd.hyperdrive.things+hal+json, application/json'
+  end
+end