committee 1.15.0 → 2.0.0.pre

data/lib/committee/middleware/base.rb

@@ -6,19 +6,12 @@ module Committee::Middleware
       @error_class = options.fetch(:error_class, Committee::ValidationError)
       @params_key = options[:params_key] || "committee.params"
       @raise = options[:raise]
+      @schema = get_schema(options[:schema] ||
+        raise(ArgumentError, "Committee: need option `schema`"))
 
-      schema = options[:schema] || raise("need option `schema`")
-      if schema.is_a?(String)
-        warn_string_deprecated
-        schema = JSON.parse(schema)
-      end
-      if schema.is_a?(Hash)
-        schema = JsonSchema.parse!(schema)
-        schema.expand_references!
-      end
-      @schema = schema
-
-      @router = Committee::Router.new(@schema, options)
+      @router = Committee::Router.new(@schema,
+        prefix: options[:prefix]
+      )
     end
 
     def call(env)
@@ -33,8 +26,54 @@ module Committee::Middleware
 
     private
 
+    # For modern use of the library a schema should be an instance of
+    # Committee::Drivers::Schema so that we know that all the computationally
+    # difficult parsing is already done by the time we try to handle any
+    # request.
+    #
+    # However, for reasons of backwards compatibility we also allow schema
+    # input to be a string, a data hash, or a JsonSchema::Schema. In the former
+    # two cases we just parse as if we were sent hyper-schema. In the latter,
+    # we have the hyper-schema driver wrap it in a new Committee object.
+    def get_schema(schema)
+      # These are in a separately conditional ladder so that we only show the
+      # user one warning.
+      if schema.is_a?(String)
+        warn_string_deprecated
+      elsif schema.is_a?(Hash)
+        warn_hash_deprecated
+      end
+
+      if schema.is_a?(String)
+        schema = JSON.parse(schema)
+      end
+
+      if schema.is_a?(Hash) || schema.is_a?(JsonSchema::Schema)
+        driver = Committee::Drivers::HyperSchema.new
+
+        # The driver itself has its own special cases to be able to parse
+        # either a hash or JsonSchema::Schema object.
+        schema = driver.parse(schema)
+      end
+
+      # Expect the type we want by now. If we don't have it, the user passed
+      # something else non-standard in.
+      if !schema.is_a?(Committee::Drivers::Schema)
+        raise ArgumentError, "Committee: schema expected to be a hash or " \
+          "an instance of Committee::Drivers::Schema."
+      end
+
+      schema
+    end
+
+    def warn_hash_deprecated
+      Committee.warn_deprecated("Committee: passing a hash to schema " \
+        "option is deprecated; please send a driver object instead.")
+    end
+
     def warn_string_deprecated
-      Committee.warn_deprecated("Committee: passing a string to `schema` option is deprecated; please send a deserialized hash instead.")
+      Committee.warn_deprecated("Committee: passing a string to schema " \
+        "option is deprecated; please send a driver object instead.")
     end
   end
 end

data/lib/committee/middleware/request_validation.rb

@@ -2,27 +2,48 @@ module Committee::Middleware
   class RequestValidation < Base
     def initialize(app, options={})
       super
+
       @allow_form_params   = options.fetch(:allow_form_params, true)
       @allow_query_params  = options.fetch(:allow_query_params, true)
       @check_content_type  = options.fetch(:check_content_type, true)
       @optimistic_json     = options.fetch(:optimistic_json, false)
-      @coerce_query_params = options.fetch(:coerce_query_params, false)
       @strict              = options[:strict]
 
+      @coerce_path_params = options.fetch(:coerce_path_params,
+        @schema.driver.default_path_params)
+      @coerce_query_params = options.fetch(:coerce_query_params,
+        @schema.driver.default_query_params)
+
       # deprecated
       @allow_extra = options[:allow_extra]
     end
 
     def handle(request)
-      link = @router.find_request_link(request)
-
-      if link && @coerce_query_params && !request.GET.nil? && !link.schema.nil?
-        request.env["rack.request.query_hash"].merge!(
-          Committee::QueryParamsCoercer.new(
-            request.GET,
-            link.schema
-          ).call
-        )
+      link, param_matches = @router.find_request_link(request)
+      path_params = {}
+
+      if link
+        # Attempts to coerce parameters that appear in a link's URL to Ruby
+        # types that can be validated with a schema.
+        if @coerce_path_params
+          path_params = param_matches.merge(
+            Committee::StringParamsCoercer.new(
+              param_matches,
+              link.schema
+            ).call
+          )
+        end
+
+        # Attempts to coerce parameters that appear in a query string to Ruby
+        # types that can be validated with a schema.
+        if @coerce_query_params && !request.GET.nil? && !link.schema.nil?
+          request.env["rack.request.query_hash"].merge!(
+            Committee::StringParamsCoercer.new(
+              request.GET,
+              link.schema
+            ).call
+          )
+        end
       end
 
       request.env[@params_key] = Committee::RequestUnpacker.new(
@@ -32,6 +53,8 @@ module Committee::Middleware
         optimistic_json:    @optimistic_json
       ).call
 
+      request.env[@params_key].merge!(path_params)
+
       if link
         validator = Committee::RequestValidator.new(link, check_content_type: @check_content_type)
         validator.call(request, request.env[@params_key])

data/lib/committee/middleware/response_validation.rb

@@ -10,7 +10,8 @@ module Committee::Middleware
     def handle(request)
       status, headers, response = @app.call(request.env)
 
-      if validate?(status) && link = @router.find_request_link(request)
+      link, _ = @router.find_request_link(request)
+      if validate?(status) && link
         full_body = ""
         response.each do |chunk|
           full_body << chunk

data/lib/committee/middleware/stub.rb

@@ -2,16 +2,27 @@ module Committee::Middleware
   class Stub < Base
     def initialize(app, options={})
       super
-      @cache = {}
-      @call  = options[:call]
+
+      # A bug in Committee's cache implementation meant that it wasn't working
+      # for a very long time, even for people who thought they were taking
+      # advantage of it. I repaired the caching feature, but have disable it by
+      # default so that we don't need to introduce any class-level variables
+      # that could have memory leaking implications. To enable caching, just
+      # pass an empty hash to this option.
+      @cache = options[:cache]
+
+      @call = options[:call]
     end
 
     def handle(request)
-      if link = @router.find_request_link(request)
+      link, _ = @router.find_request_link(request)
+      if link
         headers = { "Content-Type" => "application/json" }
-        data = cache(link.method, link.href) do
+
+        data = cache(link) do
           Committee::ResponseGenerator.new.call(link)
         end
+
         if @call
           request.env["committee.response"] = data
           call_status, call_headers, call_body = @app.call(request.env)
@@ -29,8 +40,8 @@ module Committee::Middleware
           # will be the same one that we set above)
           data = request.env["committee.response"]
         end
-        status = link.rel == "create" ? 201 : 200
-        [status, headers, [JSON.pretty_generate(data)]]
+
+        [link.status_success, headers, [JSON.pretty_generate(data)]]
       else
         @app.call(request.env)
       end
@@ -38,8 +49,13 @@ module Committee::Middleware
 
     private
 
-    def cache(method, href)
-      key = "#{method}+#{href}"
+    def cache(link)
+      return yield unless @cache
+
+      # Just the object ID is enough to uniquely identify the link, but store
+      # the method and href so that we can more easily introspect the cache if
+      # necessary.
+      key = "#{link.object_id}##{link.method}+#{link.href}"
       if @cache[key]
         @cache[key]
       else

data/lib/committee/request_validator.rb

@@ -24,7 +24,7 @@ module Committee
 
     def check_content_type!(request, data)
       content_type = request_media_type(request)
-      if content_type && !empty_request?(request)
+      if content_type && @link.enc_type && !empty_request?(request)
         unless Rack::Mime.match?(content_type, @link.enc_type)
           raise Committee::InvalidRequest,
             %{"Content-Type" request header must be set to "#{@link.enc_type}".}

data/lib/committee/response_generator.rb

@@ -1,35 +1,80 @@
 module Committee
   class ResponseGenerator
     def call(link)
-      data = generate_properties(link.target_schema || link.parent)
+      data = generate_properties(link, target_schema(link))
 
-      # list is a special case; wrap data in an array
-      data = [data] if link.rel == "instances"
+      # List is a special case; wrap data in an array.
+      #
+      # This is poor form that's here so as not to introduce breaking behavior.
+      # The "instances" value of "rel" is a Heroku-ism and was originally
+      # introduced before we understood how to use "targetSchema". It's not
+      # meaningful with the context of the hyper-schema specification and
+      # should be eventually be removed.
+      if legacy_hyper_schema_rel?(link)
+        data = [data]
+      end
 
       data
     end
 
     private
 
-    def generate_properties(schema)
+    # These are basic types that are part of the JSON schema for which we'll
+    # emit zero values when generating a response. For a schema that allows
+    # multiple of the types in the list, types are preferred in the order in
+    # which they're defined.
+    SCALAR_TYPES = {
+      "boolean" => false,
+      "integer" => 0,
+      "number"  => 0.0,
+      "string"  => "",
+
+      # Prefer null last.
+      "null" => nil,
+    }.freeze
+
+    def generate_properties(link, schema)
       # special example attribute was included; use its value
-      if !schema.data["example"].nil?
+      if schema.data && !schema.data["example"].nil?
         schema.data["example"]
-      # null is allowed; use that
-      elsif schema.type.include?("null")
-        nil
-      elsif schema.type.include?("array") && !schema.items.nil?
-        [generate_properties(schema.items)]
-      elsif !schema.properties.empty?
+      elsif !schema.all_of.empty? || !schema.properties.empty?
         data = {}
+        schema.all_of.each do |subschema|
+          data.merge!(generate_properties(link, subschema))
+        end
         schema.properties.map do |key, value|
-          data[key] = generate_properties(value)
+          data[key] = generate_properties(link, value)
         end
         data
+      elsif schema.type.include?("array") && !schema.items.nil?
+        [generate_properties(link, schema.items)]
+      elsif schema.type.any? { |t| SCALAR_TYPES.include?(t) }
+        SCALAR_TYPES.each do |k, v|
+          break(v) if schema.type.include?(k)
+        end
       else
-        raise(%{At "#{schema.pointer}": no "example" attribute and "null" } +
+        raise(%{At "#{link.method} #{link.href}" "#{schema.pointer}": no } +
+          %{"example" attribute and "null" } +
           %{is not allowed; don't know how to generate property.})
       end
     end
+
+    def legacy_hyper_schema_rel?(link)
+      link.is_a?(Committee::Drivers::HyperSchema::Link) &&
+        link.rel == "instances" &&
+        !link.target_schema
+    end
+
+    # Gets the target schema of a link. This is normally just the standard
+    # response schema, but we allow some legacy behavior for hyper-schema links
+    # tagged with rel=instances to instead use the schema of their parent
+    # resource.
+    def target_schema(link)
+      if link.target_schema
+        link.target_schema
+      elsif legacy_hyper_schema_rel?(link)
+        link.parent
+      end
+    end
   end
 end

data/lib/committee/response_validator.rb

@@ -6,10 +6,7 @@ module Committee
       @link = link
       @validate_errors = options[:validate_errors]
 
-      # we should eventually move off of validating against parent schema too
-      # ... this is a Herokuism and not in the specification
-      schema = link.target_schema || link.parent
-      @validator = JsonSchema::Validator.new(schema)
+      @validator = JsonSchema::Validator.new(target_schema(link))
     end
 
     def self.validate?(status, options = {})
@@ -24,7 +21,14 @@ module Committee
         check_content_type!(response)
       end
 
-      if @link.rel == "instances" && !@link.target_schema
+      # List is a special case; expect data in an array.
+      #
+      # This is poor form that's here so as not to introduce breaking behavior.
+      # The "instances" value of "rel" is a Heroku-ism and was originally
+      # introduced before we understood how to use "targetSchema". It's not
+      # meaningful with the context of the hyper-schema specification and
+      # should be eventually be removed.
+      if legacy_hyper_schema_rel?(@link)
         if !data.is_a?(Array)
           raise InvalidResponse, "List endpoints must return an array of objects."
         end
@@ -50,9 +54,29 @@ module Committee
     end
 
     def check_content_type!(response)
-      unless Rack::Mime.match?(response_media_type(response), @link.media_type)
-        raise Committee::InvalidResponse,
-          %{"Content-Type" response header must be set to "#{@link.media_type}".}
+      if @link.media_type
+        unless Rack::Mime.match?(response_media_type(response), @link.media_type)
+          raise Committee::InvalidResponse,
+            %{"Content-Type" response header must be set to "#{@link.media_type}".}
+        end
+      end
+    end
+
+    def legacy_hyper_schema_rel?(link)
+      link.is_a?(Committee::Drivers::HyperSchema::Link) &&
+        link.rel == "instances" &&
+        !link.target_schema
+    end
+
+    # Gets the target schema of a link. This is normally just the standard
+    # response schema, but we allow some legacy behavior for hyper-schema links
+    # tagged with rel=instances to instead use the schema of their parent
+    # resource.
+    def target_schema(link)
+      if link.target_schema
+        link.target_schema
+      elsif legacy_hyper_schema_rel?(link)
+        link.parent
       end
     end
   end

data/lib/committee/router.rb

@@ -1,9 +1,9 @@
 module Committee
   class Router
     def initialize(schema, options = {})
-      @routes = build_routes(schema)
       @prefix = options[:prefix]
       @prefix_regexp = /\A#{Regexp.escape(@prefix)}/.freeze if @prefix
+      @schema = schema
     end
 
     def includes?(path)
@@ -16,10 +16,11 @@ module Committee
 
     def find_link(method, path)
       path = path.gsub(@prefix_regexp, "") if @prefix
-      if method_routes = @routes[method]
+      if method_routes = @schema.routes[method]
         method_routes.each do |pattern, link|
-          if path =~ pattern
-            return link
+          if matches = pattern.match(path)
+            hash = Hash[matches.names.zip(matches.captures)]
+            return link, hash
           end
         end
       end
@@ -29,34 +30,5 @@ module Committee
     def find_request_link(request)
       find_link(request.request_method, request.path_info)
     end
-
-    private
-
-    def build_routes(schema)
-      routes = {}
-
-      schema.links.each do |link|
-        method, href = parse_link(link)
-        next unless method
-        routes[method] ||= []
-        routes[method] << [%r{^#{href}$}, link]
-      end
-
-      # recursively iterate through all `properties` subschemas to build a
-      # complete routing table
-      schema.properties.each do |_, subschema|
-        routes.merge!(build_routes(subschema)) { |_, r1, r2| r1 + r2 }
-      end
-
-      routes
-    end
-
-    def parse_link(link)
-      return nil, nil if !link.method || !link.href
-      method = link.method.to_s.upcase
-      # /apps/{id} --> /apps/([^/]+)
-      href = link.href.gsub(/\{(.*?)\}/, "[^/]+")
-      [method, href]
-    end
   end
 end

data/lib/committee/{query_params_coercer.rb → string_params_coercer.rb}

@@ -1,10 +1,15 @@
-# Attempts to coerce params given in the query hash (which are all strings) into
-# the types specified by the schema.
-# Currently supported types: null, integer, number and boolean.
-# +call+ returns a hash of all params which could be coerced - coercion errors
-# are simply ignored and expected to be handled later by schema validation.
 module Committee
-  class QueryParamsCoercer
+  # StringParamsCoercer takes parameters that are specified over a medium that
+  # can only accept strings (for example in a URL path or in query parameters)
+  # and attempts to coerce them into known types based of a link's schema
+  # definition.
+  #
+  # Currently supported types: null, integer, number and boolean.
+  #
+  # +call+ returns a hash of all params which could be coerced - coercion
+  # errors are simply ignored and expected to be handled later by schema
+  # validation.
+  class StringParamsCoercer
     def initialize(query_hash, schema)
       @query_hash = query_hash
       @schema = schema

data/lib/committee/test/methods.rb

@@ -1,19 +1,42 @@
 module Committee::Test
   module Methods
     def assert_schema_conform
-      if (data = schema_contents).is_a?(String)
-        warn_string_deprecated
-        data = JSON.parse(data)
-      end
+      @committee_schema ||= begin
+        # The preferred option. The user has already parsed a schema elsewhere
+        # and we therefore don't have to worry about any performance
+        # implications of having to do it for every single test suite.
+        if committee_schema
+          committee_schema
+        else
+          schema = schema_contents
+
+          if schema.is_a?(String)
+            warn_string_deprecated
+          elsif schema.is_a?(Hash)
+            warn_hash_deprecated
+          end
+
+          if schema.is_a?(String)
+            schema = JSON.parse(schema)
+          end
 
-      @schema ||= begin
-        schema = JsonSchema.parse!(data)
-        schema.expand_references!
-        schema
+          if schema.is_a?(Hash) || schema.is_a?(JsonSchema::Schema)
+            driver = Committee::Drivers::HyperSchema.new
+
+            # The driver itself has its own special cases to be able to parse
+            # either a hash or JsonSchema::Schema object.
+            schema = driver.parse(schema)
+          end
+
+          schema
+        end
       end
-      @router ||= Committee::Router.new(@schema, prefix: schema_url_prefix)
 
-      unless link = @router.find_request_link(last_request)
+      @committee_router ||= Committee::Router.new(@committee_schema,
+        prefix: schema_url_prefix)
+
+      link, _ = @committee_router.find_request_link(last_request)
+      unless link
         response = "`#{last_request.request_method} #{last_request.path_info}` undefined in schema."
         raise Committee::InvalidResponse.new(response)
       end
@@ -28,6 +51,12 @@ module Committee::Test
       Committee.warn_deprecated("Committee: use of #assert_schema_content_type is deprecated; use #assert_schema_conform instead.")
     end
 
+    # Can be overridden with a different driver name for other API definition
+    # formats.
+    def committee_schema
+      nil
+    end
+
     # can be overridden alternatively to #schema_path in case the schema is
     # easier to access as a string
     # blob
@@ -36,15 +65,23 @@ module Committee::Test
     end
 
     def schema_path
-      raise "Please override #schema_contents or #schema_path."
+      raise "Please override #commitee_schema."
     end
 
     def schema_url_prefix
       nil
     end
 
+    def warn_hash_deprecated
+      Committee.warn_deprecated("Committee: returning a hash from " \
+        "#schema_contents and using #schema_path is deprecated; please " \
+        "override #committee_schema instead.")
+    end
+
     def warn_string_deprecated
-      Committee.warn_deprecated("Committee: returning a string from `#schema_contents` is deprecated; please return a deserialized hash instead.")
+      Committee.warn_deprecated("Committee: returning a string from " \
+        "#schema_contents is deprecated; please override #committee_schema " \
+        "instead.")
     end
 
     def validate_response?(status)

data/lib/committee.rb

@@ -3,7 +3,7 @@ require "json_schema"
 require "rack"
 
 require_relative "committee/errors"
-require_relative "committee/query_params_coercer"
+require_relative "committee/string_params_coercer"
 require_relative "committee/request_unpacker"
 require_relative "committee/request_validator"
 require_relative "committee/response_generator"
@@ -11,14 +11,28 @@ require_relative "committee/response_validator"
 require_relative "committee/router"
 require_relative "committee/validation_error"
 
+require_relative "committee/drivers"
+require_relative "committee/drivers/hyper_schema"
+require_relative "committee/drivers/open_api_2"
+
 require_relative "committee/middleware/base"
 require_relative "committee/middleware/request_validation"
 require_relative "committee/middleware/response_validation"
 require_relative "committee/middleware/stub"
 
+require_relative "committee/bin/committee_stub"
+
 require_relative "committee/test/methods"
 
 module Committee
+  def self.debug?
+    ENV["COMMITTEE_DEBUG"]
+  end
+
+  def self.log_debug(message)
+    $stderr.puts(message) if debug?
+  end
+
   def self.warn_deprecated(message)
     if !$VERBOSE.nil?
       $stderr.puts(message)

data/test/bin/committee_stub_test.rb

@@ -0,0 +1,45 @@
+require_relative "../test_helper"
+
+describe Committee::Bin::CommitteeStub do
+  before do
+    @bin = Committee::Bin::CommitteeStub.new
+  end
+
+  it "produces a Rack app" do
+    app = @bin.get_app(hyper_schema, {})
+    assert_kind_of Rack::Builder, app
+  end
+
+  it "parses command line options" do
+    options, parser = @bin.get_options_parser
+
+    parser.parse!(["--help"])
+    assert_equal true, options[:help]
+
+    parser.parse!([
+      "--driver", "open_api_2",
+      "--tolerant", "true",
+      "--port", "1234"
+    ])
+    assert_equal :open_api_2, options[:driver]
+    assert_equal true, options[:tolerant]
+    assert_equal "1234", options[:port]
+  end
+end
+
+describe Committee::Bin::CommitteeStub, "app" do
+  include Rack::Test::Methods
+
+  before do
+    @bin = Committee::Bin::CommitteeStub.new
+  end
+
+  def app
+    @bin.get_app(hyper_schema, {})
+  end
+
+  it "defaults to a 404" do
+    get "/foos"
+    assert_equal 404, last_response.status
+  end
+end

data/test/bin_test.rb

@@ -0,0 +1,20 @@
+require_relative "test_helper"
+
+#
+# The purpose of this sets of tests is just to include our Ruby executables
+# where possible so that we can get very basic sanity checks on their syntax
+# (which is something that of course Ruby can't do by default).
+#
+# We can do this without actually executing them because they're gated by `if
+# $0 == __FILE__` statements.
+#
+
+describe "executables in bin/" do
+  before do
+    @bin_dir = File.expand_path("../../bin", __FILE__)
+  end
+
+  it "has roughly valid Ruby structure for committee-stub" do
+    load File.join(@bin_dir, "committee-stub")
+  end
+end