committee 1.15.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: d5fcb82a192f894e1baec1dcab89f081782d222f
-  data.tar.gz: 54d056b8be5b297b6a524166363f955db7a1bd15
+SHA256:
+  metadata.gz: 284c8c1198255435e959dcee2b92cb25c3d80dd5fe6d4622b8077a69525712ed
+  data.tar.gz: b306ec0ad5e628d9cc7b6382781c4b710c99bedb127a7000edadf9d0e0b8fa84
 SHA512:
-  metadata.gz: f22924efd2696d884eb499978cdb2a9f6e81ead9d25dacbe3ea331b9fb4d771886a4ccea1926fe2d09256886433a451fdbe25ef47cbe8d4c80a07a4157e0b9bc
-  data.tar.gz: db8d1aa50e4f4fa854bda1d5484df09e7262801bd845195c1340a718fc6d0792666360698ea2fe8722f1c57a287fcfb4b1f0258706032f47a2ef7cceaffd7df9
+  metadata.gz: 687d9a47d2a17786313bde939339d464a8d775795458b09ad7d7784bfa337f848a9ffabe240e9f39173c4466589c026f64a8eede768e7abfff4b01b2672339f5
+  data.tar.gz: 4ee7781341de9ebafae28d01d98c0f72d54067c425f3ee10b221c4eb88da85e79b36853bbda4818b20348177f8d975103cc5be694ff7e8252a6634a856853b7c

data/bin/committee-stub

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require 'optparse'
 require 'yaml'
@@ -6,45 +7,17 @@ require 'yaml'
 require_relative "../lib/committee"
 
 args = ARGV.dup
-options = { port: 9292, tolerant: false }
-opt_parser = OptionParser.new do |opts|
-  opts.banner = "Usage: rackup [options] [JSON Schema file]"
+bin = Committee::Bin::CommitteeStub.new
+options, parser = bin.get_options_parser
 
-  opts.separator ""
-  opts.separator "Options:"
+parser.parse!(args)
 
-  opts.on_tail("-h", "-?", "--help", "Show this message") {
-    puts opts
-    exit
-  }
+if options[:help] || !options[:driver] || args.length < 1
+  # shows help information
+  puts parser.to_s
+else
+  driver = Committee::Drivers.driver_from_name(options[:driver])
+  schema = driver.parse(::YAML.load(File.read(args[0])))
 
-  opts.on("-t", "--tolerant", "don't perform request/response validations") {
-    options[:tolerant] = true
-  }
-
-  opts.on("-p", "--port PORT", "use PORT (default: 9292)") { |port|
-    options[:port] = port
-  }
-end
-opt_parser.parse!(args)
-
-unless args.count == 1
-  puts opt_parser.to_s
-  exit
+  Rack::Server.start(app: bin.get_app(schema, options), Port: options[:port])
 end
-
-schema = ::YAML.load(File.read(args[0]))
-
-app = Rack::Builder.new {
-  unless options[:tolerant]
-    use Committee::Middleware::RequestValidation, schema: schema
-    use Committee::Middleware::ResponseValidation, schema: schema
-  end
-
-  use Committee::Middleware::Stub, schema: schema
-  run lambda { |_|
-    [404, {}, ["Not found"]]
-  }
-}
-
-Rack::Server.start(app: app, Port: options[:port])

data/lib/committee/bin/committee_stub.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+# Don't Support OpenAPI3
+
+module Committee
+  module Bin
+    # CommitteeStub internalizes the functionality of bin/committee-stub so
+    # that we can test code that would otherwise be difficult to get at in an
+    # executable.
+    class CommitteeStub
+      # Gets a Rack app suitable for use as a stub.
+      def get_app(schema, options)
+        cache = {}
+
+        raise Committee::OpenAPI3Unsupported.new("Stubs are not yet supported for OpenAPI 3") unless schema.supports_stub?
+
+        Rack::Builder.new {
+          unless options[:tolerant]
+            use Committee::Middleware::RequestValidation, schema: schema
+            use Committee::Middleware::ResponseValidation, schema: schema
+          end
+
+          use Committee::Middleware::Stub, cache: cache, schema: schema
+
+          run lambda { |_|
+            [404, {}, ["Not found"]]
+          }
+        }
+      end
+
+      # Gets an option parser for command line arguments.
+      def get_options_parser
+        options = {
+          driver: nil,
+          help: false,
+          port: 9292,
+          tolerant: false,
+        }
+
+        parser = OptionParser.new do |opts|
+          opts.banner = "Usage: rackup [options] [JSON Schema file]"
+
+          opts.separator ""
+          opts.separator "Options:"
+
+          # required
+          opts.on("-d", "--driver NAME", "name of driver [open_api_2|hyper_schema]") { |name|
+            options[:driver] = name.to_sym
+          }
+
+          opts.on_tail("-h", "-?", "--help", "Show this message") {
+            options[:help] = true
+          }
+
+          opts.on("-t", "--tolerant", "don't perform request/response validations") {
+            options[:tolerant] = true
+          }
+
+          opts.on("-p", "--port PORT", "use PORT (default: 9292)") { |port|
+            options[:port] = port
+          }
+        end
+        [options, parser]
+      end
+    end
+  end
+end

data/lib/committee/drivers/driver.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Committee
+  module Drivers
+    # Driver is a base class for driver implementations.
+    class Driver
+      # Whether parameters that were form-encoded will be coerced by default.
+      def default_coerce_form_params
+        raise "needs implementation"
+      end
+
+      # Use GET request body to request parameter (request body merge to parameter)
+      def default_allow_get_body
+        raise "needs implementation"
+      end
+
+      # Whether parameters in a request's path will be considered and coerced
+      # by default.
+      def default_path_params
+        raise "needs implementation"
+      end
+
+      # Whether parameters in a request's query string will be considered and
+      # coerced by default.
+      def default_query_params
+        raise "needs implementation"
+      end
+
+      def name
+        raise "needs implementation"
+      end
+
+      # Parses an API schema and builds a set of route definitions for use with
+      # Committee.
+      #
+      # The expected input format is a data hash with keys as strings (as
+      # opposed to symbols) like the kind produced by JSON.parse or YAML.load.
+      def parse(data)
+        raise "needs implementation"
+      end
+
+      def schema_class
+        raise "needs implementation"
+      end
+    end
+  end
+end

data/lib/committee/drivers/hyper_schema/driver.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Committee
+  module Drivers
+    module HyperSchema
+      class Driver < ::Committee::Drivers::Driver
+        def default_coerce_date_times
+          false
+        end
+
+        # Whether parameters that were form-encoded will be coerced by default.
+        def default_coerce_form_params
+          false
+        end
+
+        def default_allow_get_body
+          true
+        end
+
+        # Whether parameters in a request's path will be considered and coerced by
+        # default.
+        def default_path_params
+          false
+        end
+
+        # Whether parameters in a request's query string will be considered and
+        # coerced by default.
+        def default_query_params
+          false
+        end
+
+        def default_validate_success_only
+          true
+        end
+
+        def name
+          :hyper_schema
+        end
+
+        # Parses an API schema and builds a set of route definitions for use with
+        # Committee.
+        #
+        # The expected input format is a data hash with keys as strings (as opposed
+        # to symbols) like the kind produced by JSON.parse or YAML.load.
+        def parse(schema)
+          # Really we'd like to only have data hashes passed into drivers these
+          # days, but here we handle a JsonSchema::Schema for now to maintain
+          # backward compatibility (this library used to be hyper-schema only).
+          if schema.is_a?(JsonSchema::Schema)
+            hyper_schema = schema
+          else
+            hyper_schema = JsonSchema.parse!(schema)
+            hyper_schema.expand_references!
+          end
+
+          schema = Schema.new
+          schema.driver = self
+          schema.routes = build_routes(hyper_schema)
+          schema
+        end
+
+        def schema_class
+          Committee::Drivers::HyperSchema::Schema
+        end
+
+        private
+
+        def build_routes(hyper_schema)
+          routes = {}
+
+          hyper_schema.links.each do |link|
+            method, href = parse_link(link)
+            next unless method
+
+            rx = %r{^#{href}$}
+            Committee.log_debug "Created route: #{method} #{href} (regex #{rx})"
+
+            routes[method] ||= []
+            routes[method] << [rx, Link.new(link)]
+          end
+
+          # recursively iterate through all `properties` subschemas to build a
+          # complete routing table
+          hyper_schema.properties.each do |_, subschema|
+            routes.merge!(build_routes(subschema)) { |_, r1, r2| r1 + r2 }
+          end
+
+          routes
+        end
+
+        def href_to_regex(href)
+          href.gsub(/\{(.*?)\}/, "[^/]+")
+        end
+
+        def parse_link(link)
+          return nil, nil if !link.method || !link.href
+          method = link.method.to_s.upcase
+          # /apps/{id} --> /apps/([^/]+)
+          href = href_to_regex(link.href)
+          [method, href]
+        end
+      end
+    end
+  end
+end

data/lib/committee/drivers/hyper_schema/link.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Committee
+  module Drivers
+    module HyperSchema
+      # Link abstracts an API link specifically for JSON hyper-schema.
+      #
+      # For most operations, it's a simple pass through to a
+      # JsonSchema::Schema::Link, but implements some exotic behavior in a few
+      # places.
+      class Link
+        def initialize(hyper_schema_link)
+          @hyper_schema_link = hyper_schema_link
+        end
+
+        # The link's input media type. i.e. How requests should be encoded.
+        def enc_type
+          hyper_schema_link.enc_type
+        end
+
+        def href
+          hyper_schema_link.href
+        end
+
+        # The link's output media type. i.e. How responses should be encoded.
+        def media_type
+          hyper_schema_link.media_type
+        end
+
+        def method
+          hyper_schema_link.method
+        end
+
+        # Passes through a link's parent resource. Note that this is *not* part
+        # of the Link interface and is here to support a legacy Heroku-ism
+        # behavior that allowed a link tagged with rel=instances to imply that a
+        # list will be returned.
+        def parent
+          hyper_schema_link.parent
+        end
+
+        def rel
+          hyper_schema_link.rel
+        end
+
+        # The link's input schema. i.e. How we validate an endpoint's incoming
+        # parameters.
+        def schema
+          hyper_schema_link.schema
+        end
+
+        def status_success
+          hyper_schema_link.rel == "create" ? 201 : 200
+        end
+
+        # The link's output schema. i.e. How we validate an endpoint's response
+        # data.
+        def target_schema
+          hyper_schema_link.target_schema
+        end
+
+        private
+
+        attr_accessor :hyper_schema_link
+      end
+    end
+  end
+end

data/lib/committee/drivers/hyper_schema/schema.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Committee
+  module Drivers
+    module HyperSchema
+      class Schema < ::Committee::Drivers::Schema
+        # A link back to the derivative instance of Committee::Drivers::Driver
+        # that create this schema.
+        attr_accessor :driver
+
+        attr_accessor :routes
+
+        attr_reader :validator_option
+
+        def build_router(options)
+          @validator_option = Committee::SchemaValidator::Option.new(options, self, :hyper_schema)
+          Committee::SchemaValidator::HyperSchema::Router.new(self, @validator_option)
+        end
+      end
+    end
+  end
+end

data/lib/committee/drivers/hyper_schema.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Committee
+  module Drivers
+    module HyperSchema
+    end
+  end
+end
+
+require_relative 'hyper_schema/driver'
+require_relative 'hyper_schema/link'
+require_relative 'hyper_schema/schema'

data/lib/committee/drivers/open_api_2/driver.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+module Committee
+  module Drivers
+    module OpenAPI2
+      class Driver < ::Committee::Drivers::Driver
+        def default_coerce_date_times
+          false
+        end
+
+        # Whether parameters that were form-encoded will be coerced by default.
+        def default_coerce_form_params
+          true
+        end
+
+        def default_allow_get_body
+          true
+        end
+
+        # Whether parameters in a request's path will be considered and coerced by
+        # default.
+        def default_path_params
+          true
+        end
+
+        # Whether parameters in a request's query string will be considered and
+        # coerced by default.
+        def default_query_params
+          true
+        end
+
+        def default_validate_success_only
+          true
+        end
+
+        def name
+          :open_api_2
+        end
+
+        # Parses an API schema and builds a set of route definitions for use with
+        # Committee.
+        #
+        # The expected input format is a data hash with keys as strings (as opposed
+        # to symbols) like the kind produced by JSON.parse or YAML.load.
+        def parse(data)
+          REQUIRED_FIELDS.each do |field|
+            if !data[field]
+              raise ArgumentError, "Committee: no #{field} section in spec data."
+            end
+          end
+
+          if data['swagger'] != '2.0'
+            raise ArgumentError, "Committee: driver requires OpenAPI 2.0."
+          end
+
+          schema = Schema.new
+          schema.driver = self
+
+          schema.base_path = data['basePath'] || ''
+
+          # Arbitrarily choose the first media type found in these arrays. This
+          # approach could probably stand to be improved, but at least users will
+          # for now have the option of turning media type validation off if they so
+          # choose.
+          schema.consumes = data['consumes'].first
+          schema.produces = data['produces'].first
+
+          schema.definitions, store = parse_definitions!(data)
+          schema.routes = parse_routes!(data, schema, store)
+
+          schema
+        end
+
+        def schema_class
+          Committee::Drivers::OpenAPI2::Schema
+        end
+
+        private
+
+        DEFINITIONS_PSEUDO_URI = "http://json-schema.org/committee-definitions"
+
+        # These are fields that the OpenAPI 2 spec considers mandatory to be
+        # included in the document's top level.
+        REQUIRED_FIELDS = [
+          :consumes,
+          :definitions,
+          :paths,
+          :produces,
+          :swagger,
+        ].map(&:to_s).freeze
+
+        def find_best_fit_response(link_data)
+          if response_data = link_data["responses"]["200"] || response_data = link_data["responses"][200]
+            [200, response_data]
+          elsif response_data = link_data["responses"]["201"] || response_data = link_data["responses"][201]
+            [201, response_data]
+          else
+            # Sort responses so that we can try to prefer any 3-digit status code.
+            # If there are none, we'll just take anything from the list.
+            ordered_responses = link_data["responses"].
+              select { |k, v| k.to_s =~ /[0-9]{3}/ }
+            if first = ordered_responses.first
+              [first[0].to_i, first[1]]
+            else
+              [nil, nil]
+            end
+          end
+        end
+
+        def href_to_regex(href)
+          href.gsub(/\{(.*?)\}/, '(?<\1>[^/]+)')
+        end
+
+        def parse_definitions!(data)
+          # The "definitions" section of an OpenAPI 2 spec is a valid JSON schema.
+          # We extract it from the spec and parse it as a schema in isolation so
+          # that all references to it will still have correct paths (i.e. we can
+          # still find a resource at '#/definitions/resource' instead of
+          # '#/resource').
+          schema = JsonSchema.parse!({
+            "definitions" => data['definitions'],
+          })
+          schema.expand_references!
+          schema.uri = DEFINITIONS_PSEUDO_URI
+
+          # So this is a little weird: an OpenAPI specification is _not_ a valid
+          # JSON schema and yet it self-references like it is a valid JSON schema.
+          # To work around this what we do is parse its "definitions" section as a
+          # JSON schema and then build a document store here containing that. When
+          # trying to resolve a reference from elsewhere in the spec, we build a
+          # synthetic schema with a JSON reference to the document created from
+          # "definitions" and then expand references against this store.
+          store = JsonSchema::DocumentStore.new
+          store.add_schema(schema)
+
+          [schema, store]
+        end
+
+        def parse_routes!(data, schema, store)
+          routes = {}
+
+          # This is a performance optimization: instead of going through each link
+          # and parsing out its JSON schema separately, instead we just aggregate
+          # all schemas into one big hash and then parse it all at the end. After
+          # we parse it, go through each link and assign a proper schema object. In
+          # practice this comes out to somewhere on the order of 50x faster.
+          schemas_data = { "properties" => {} }
+
+          # Exactly the same idea, but for response schemas.
+          target_schemas_data = { "properties" => {} }
+
+          data['paths'].each do |path, methods|
+            href = schema.base_path + path
+            schemas_data["properties"][href] = { "properties" => {} }
+            target_schemas_data["properties"][href] = { "properties" => {} }
+
+            methods.each do |method, link_data|
+              method = method.upcase
+              link = Link.new
+              link.enc_type = schema.consumes
+              link.href = href
+              link.media_type = schema.produces
+              link.method = method
+
+              # Convert the spec's parameter pseudo-schemas into JSON schemas that
+              # we can use for some basic request validation.
+              link.schema, schema_data = ParameterSchemaBuilder.new(link_data).call
+              link.header_schema = HeaderSchemaBuilder.new(link_data).call
+
+              # If data came back instead of a schema (this occurs when a route has
+              # a single `body` parameter instead of a collection of URL/query/form
+              # parameters), store it for later parsing.
+              if schema_data
+                schemas_data["properties"][href]["properties"][method] = schema_data
+              end
+
+              # Arbitrarily pick one response for the time being. Prefers in order:
+              # a 200, 201, any 3-digit numerical response, then anything at all.
+              status, response_data = find_best_fit_response(link_data)
+              if status
+                link.status_success = status
+
+                # A link need not necessarily specify a target schema.
+                if response_data["schema"]
+                  target_schemas_data["properties"][href]["properties"][method] =
+                    response_data["schema"]
+                end
+              end
+
+              rx = %r{^#{href_to_regex(link.href)}$}
+              Committee.log_debug "Created route: #{link.method} #{link.href} (regex #{rx})"
+
+              routes[method] ||= []
+              routes[method] << [rx, link]
+            end
+          end
+
+          # See the note on our DocumentStore's initialization in
+          # #parse_definitions!, but what we're doing here is prefixing references
+          # with a specialized internal URI so that they can reference definitions
+          # from another document in the store.
+          schemas =
+            rewrite_references_and_parse(schemas_data, store)
+          target_schemas =
+            rewrite_references_and_parse(target_schemas_data, store)
+
+          # As noted above, now that we've parsed our aggregate response schema, go
+          # back through each link and them their response schema.
+          routes.each do |method, method_routes|
+            method_routes.each do |(_, link)|
+              # request
+              #
+              # Differs slightly from responses in that the schema may already have
+              # been set for endpoints with non-body parameters, so check for nil
+              # before we set it.
+              if schema = schemas.properties[link.href].properties[method]
+                link.schema = schema
+              end
+
+              # response
+              link.target_schema =
+                target_schemas.properties[link.href].properties[method]
+            end
+          end
+
+          routes
+        end
+
+        def rewrite_references_and_parse(schemas_data, store)
+          schemas = rewrite_references(schemas_data)
+          schemas = JsonSchema.parse!(schemas_data)
+          schemas.expand_references!(store: store)
+          schemas
+        end
+
+        def rewrite_references(schema)
+          if schema.is_a?(Hash)
+            ref = schema["$ref"]
+            if ref && ref.is_a?(String) && ref[0] == "#"
+              schema["$ref"] = DEFINITIONS_PSEUDO_URI + ref
+            else
+              schema.each do |_, v|
+                rewrite_references(v)
+              end
+            end
+          end
+          schema
+        end
+      end
+    end
+  end
+end

data/lib/committee/drivers/open_api_2/header_schema_builder.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Committee
+  module Drivers
+    module OpenAPI2
+      class HeaderSchemaBuilder < SchemaBuilder
+        def call
+          if link_data["parameters"]
+            link_schema = JsonSchema::Schema.new
+            link_schema.properties = {}
+            link_schema.required = []
+
+            header_parameters = link_data["parameters"].select { |param_data| param_data["in"] == "header" }
+            header_parameters.each do |param_data|
+              check_required_fields!(param_data)
+
+              param_schema = JsonSchema::Schema.new
+
+              param_schema.type = [param_data["type"]]
+
+              link_schema.properties[param_data["name"]] = param_schema
+              if param_data["required"] == true
+                link_schema.required << param_data["name"]
+              end
+            end
+
+            link_schema
+          end
+        end
+      end
+    end
+  end
+end