committee 1.15.0 → 2.0.0.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d5fcb82a192f894e1baec1dcab89f081782d222f
-  data.tar.gz: 54d056b8be5b297b6a524166363f955db7a1bd15
+  metadata.gz: 5911eb64b8a07bb45eaf264399bebeb95ea2395b
+  data.tar.gz: 35d800d2dd5cd0c3d402b26813d7b156f0809006
 SHA512:
-  metadata.gz: f22924efd2696d884eb499978cdb2a9f6e81ead9d25dacbe3ea331b9fb4d771886a4ccea1926fe2d09256886433a451fdbe25ef47cbe8d4c80a07a4157e0b9bc
-  data.tar.gz: db8d1aa50e4f4fa854bda1d5484df09e7262801bd845195c1340a718fc6d0792666360698ea2fe8722f1c57a287fcfb4b1f0258706032f47a2ef7cceaffd7df9
+  metadata.gz: 86c361cc0bd1f4d0e340335402ab452b99a0c0d0eae814aa3296794ed0a076177f9dc3ebc772ae95a66afbe45efcbeccc77e2851ef3a0e385171fc549e31092c
+  data.tar.gz: 306a67c72463d3879dd7fb4e9aff88a17d34e54d83c209a439cabc47b912027178c5d23fc9b5270cc6b0f9d65d4957f152ec630c7e3484931bba1bda46ed4bd0

data/bin/committee-stub

@@ -6,45 +6,19 @@ 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:"
+if $0 == __FILE__
+  parser.parse!(args)
 
-  opts.on_tail("-h", "-?", "--help", "Show this message") {
-    puts opts
+  unless args.count == 1 || options[:help]
+    puts parser.to_s
     exit
-  }
-
-  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
-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"]]
-  }
-}
+  driver = Committee::Drivers.driver_from_name(options[:driver])
+  schema = driver.parse(::YAML.load(File.read(args[0])))
 
-Rack::Server.start(app: app, Port: options[:port])
+  Rack::Server.start(app: bin.get_app(schema, options), Port: options[:port])
+end

data/lib/committee/bin/committee_stub.rb

@@ -0,0 +1,61 @@
+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)
+        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"]]
+          }
+        }
+      end
+
+      # Gets an option parser for command line arguments.
+      def get_options_parser
+        options = {
+          :driver   => :hyper_schema,
+          :help     => false,
+          :port     => 9292,
+          :tolerant => false,
+        }
+
+        parser = OptionParser.new do |opts|
+          opts.banner = "Usage: rackup [options] [JSON Schema file]"
+
+          opts.separator ""
+          opts.separator "Options:"
+
+          opts.on_tail("-h", "-?", "--help", "Show this message") {
+            options[:help] = true
+          }
+
+          opts.on("-d", "--driver NAME", "name of driver [open_api_2|hyper_schema]") { |name|
+            options[:driver] = name.to_sym
+          }
+
+          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
+
+      def get_schema(driver_name, data)
+      end
+    end
+  end
+end

data/lib/committee/drivers/hyper_schema.rb

@@ -0,0 +1,151 @@
+module Committee::Drivers
+  class HyperSchema < Committee::Drivers::Driver
+    # 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 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
+
+    # 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)
+        self.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
+
+    class Schema < Committee::Drivers::Schema
+      # A link back to the derivative instace of Committee::Drivers::Driver
+      # that create this schema.
+      attr_accessor :driver
+
+      attr_accessor :routes
+    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

data/lib/committee/drivers/open_api_2.rb

@@ -0,0 +1,297 @@
+module Committee::Drivers
+  class OpenAPI2 < Committee::Drivers::Driver
+    # 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 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
+      # appraoch 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
+
+    # Link abstracts an API link specifically for OpenAPI 2.
+    class Link
+      # The link's input media type. i.e. How requests should be encoded.
+      attr_accessor :enc_type
+
+      attr_accessor :href
+
+      # The link's output media type. i.e. How responses should be encoded.
+      attr_accessor :media_type
+
+      attr_accessor :method
+
+      # The link's input schema. i.e. How we validate an endpoint's incoming
+      # parameters.
+      attr_accessor :schema
+
+      attr_accessor :status_success
+
+      # The link's output schema. i.e. How we validate an endpoint's response
+      # data.
+      attr_accessor :target_schema
+
+      def rel
+        raise "Committee: rel not implemented for OpenAPI"
+      end
+    end
+
+    # ParameterSchemaBuilder converts OpenAPI 2 link parameters, which are not
+    # quite JSON schemas (but will be in OpenAPI 3) into synthetic schemas that
+    # we can use to do some basic request validation.
+    class ParameterSchemaBuilder
+      def initialize(link_data)
+        self.link_data = link_data
+      end
+
+      def call
+        link_schema = JsonSchema::Schema.new
+        link_schema.properties = {}
+        link_schema.required = []
+
+        if link_data["parameters"]
+          link_data["parameters"].each do |param_data|
+            LINK_REQUIRED_FIELDS.each do |field|
+              if !param_data[field]
+                raise ArgumentError,
+                  "Committee: no #{field} section in link data."
+              end
+            end
+
+            param_schema = JsonSchema::Schema.new
+
+            # We could probably use more validation here, but the formats of
+            # OpenAPI 2 are based off of what's available in JSON schema, and
+            # therefore this should map over quite well.
+            param_schema.type = [param_data["type"]]
+
+            # And same idea: despite parameters not being schemas, the items
+            # key (if preset) is actually a schema that defines each item of an
+            # array type, so we can just reflect that directly onto our
+            # artifical schema.
+            if param_data["type"] == "array" && param_data["items"]
+              param_schema.items = param_data["items"]
+            end
+
+            link_schema.properties[param_data["name"]] = param_schema
+            if param_data["required"] == true
+              link_schema.required << param_data["name"]
+            end
+          end
+        end
+
+        link_schema
+      end
+
+      private
+
+      LINK_REQUIRED_FIELDS = [
+        :name
+      ].map(&:to_s).freeze
+
+      attr_accessor :link_data
+    end
+
+    class Schema < Committee::Drivers::Schema
+      attr_accessor :base_path
+      attr_accessor :consumes
+
+      # A link back to the derivative instace of Committee::Drivers::Driver
+      # that create this schema.
+      attr_accessor :driver
+
+      attr_accessor :definitions
+      attr_accessor :produces
+      attr_accessor :routes
+    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"]
+        [200, response_data]
+      elsif 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 =~ /[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.
+      target_schemas_data = { "properties" => {} }
+
+      data['paths'].each do |path, methods|
+        href = schema.base_path + path
+        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 = ParameterSchemaBuilder.new(link_data).call
+
+          # 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.
+      target_schemas = rewrite_references(target_schemas_data)
+
+      target_schemas = JsonSchema.parse!(target_schemas)
+      target_schemas.expand_references!(store: 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)|
+          link.target_schema =
+            target_schemas.properties[link.href].properties[method]
+        end
+      end
+
+      routes
+    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

data/lib/committee/drivers.rb

@@ -0,0 +1,57 @@
+module Committee
+  module Drivers
+    # Gets a driver instance from the specified name. Raises ArgumentError for
+    # an unknown driver name.
+    def self.driver_from_name(name)
+      case name
+      when :hyper_schema
+        Committee::Drivers::HyperSchema.new
+      when :open_api_2
+        Committee::Drivers::OpenAPI2.new
+      else
+        raise ArgumentError, %{Committee: unknown driver "#{name}".}
+      end
+    end
+
+    # Driver is a base class for driver implementations.
+    class Driver
+      # 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
+
+    # Schema is a base class for driver schema implementations.
+    class Schema
+      # A link back to the derivative instace of Committee::Drivers::Driver
+      # that create this schema.
+      def driver
+        raise "needs implementation"
+      end
+    end
+  end
+end