verquest 0.6.4 → 0.7.0

data/lib/verquest/query/coercer.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Verquest
+  module Query
+    # Converts parsed query parameters to the types their schema expects
+    #
+    # Query strings carry only strings, so `"2"` has to become `2` and `"a,b"`
+    # has to become `["a", "b"]` before the params are validated. The coercer
+    # walks the version's validation schema next to the params. A value no rule
+    # converts is left unchanged, so the validation reports it.
+    #
+    # @example
+    #   schema = {"type" => "object", "properties" => {"page" => {"type" => "integer"}}}
+    #   Verquest::Query::Coercer.new(schema:, explodes: {}).call({"page" => "2"})
+    #   # => {"page" => 2}
+    class Coercer
+      # Returned by a rule that doesn't apply to a value
+      NO_MATCH = ::Object.new.freeze
+
+      # The JSON type of each class an enum or const value can have
+      JSON_TYPES = {
+        ::Integer => "integer",
+        ::Float => "number",
+        ::String => "string",
+        ::TrueClass => "boolean",
+        ::FalseClass => "boolean",
+        ::NilClass => "null"
+      }.freeze
+
+      # Strings converted to an Integer
+      INTEGER_PATTERN = /\A-?\d+\z/
+
+      # Strings converted to an Integer or a Float
+      NUMBER_PATTERN = /\A-?\d+(\.\d+)?\z/
+
+      # Strings converted to a boolean
+      BOOLEANS = {"true" => true, "false" => false}.freeze
+
+      # @param schema [Hash] The version's validation schema
+      # @param explodes [Hash{Array<String> => Boolean}] The explode value of each array property, by path
+      def initialize(schema:, explodes:)
+        @schema = schema
+        @explodes = explodes
+      end
+
+      # Converts the params
+      #
+      # @param params [Hash] The parsed query parameters, with string or symbol keys
+      # @return [Hash] A copy of the params with converted values
+      def call(params)
+        coerce_properties(params, schema, [])
+      end
+
+      private
+
+      attr_reader :schema, :explodes
+
+      # @return [Hash] A copy of the hash with each known property converted
+      def coerce_properties(hash, object_schema, path)
+        properties = object_schema.fetch("properties", {})
+        additional = object_schema["additionalProperties"]
+
+        hash.each_with_object(hash.dup) do |(key, value), result|
+          property_schema = properties.fetch(key.to_s) { additional if additional.is_a?(Hash) }
+          next unless property_schema
+
+          coerced = coerce(value, property_schema, path + [key.to_s])
+          result[key] = coerced unless coerced.equal?(NO_MATCH)
+        end
+      end
+
+      # Tries the schema's types, then its anyOf and oneOf variants
+      #
+      # @return [Object] The converted value or NO_MATCH
+      def coerce(value, value_schema, path)
+        types(value_schema).each do |type|
+          coerced = coerce_type(type, value, value_schema, path)
+          return coerced unless coerced.equal?(NO_MATCH)
+        end
+
+        value_schema.values_at("anyOf", "oneOf").compact.flatten.each do |variant|
+          coerced = coerce(value, variant, path)
+          return coerced unless coerced.equal?(NO_MATCH)
+        end
+
+        NO_MATCH
+      end
+
+      # @return [Array<String>] The schema's types, inferred from enum and const values without a type
+      def types(value_schema)
+        if value_schema.key?("type")
+          Array(value_schema["type"])
+        elsif value_schema.key?("enum")
+          value_schema["enum"].filter_map { |value| JSON_TYPES[value.class] }.uniq
+        elsif value_schema.key?("const")
+          [JSON_TYPES[value_schema["const"].class]].compact
+        else
+          []
+        end
+      end
+
+      # @return [Object] The value converted to the type or NO_MATCH
+      def coerce_type(type, value, value_schema, path)
+        case type
+        when "integer" then coerce_integer(value)
+        when "number" then coerce_number(value)
+        when "boolean" then coerce_boolean(value)
+        when "null" then (value.nil? || value == "") ? nil : NO_MATCH
+        when "string" then value.is_a?(::String) ? value : NO_MATCH
+        when "array" then coerce_array(value, value_schema, path)
+        when "object" then value.is_a?(::Hash) ? coerce_properties(value, value_schema, path) : NO_MATCH
+        else NO_MATCH
+        end
+      end
+
+      # @return [Integer, Object] The integer or NO_MATCH
+      def coerce_integer(value)
+        return value if value.is_a?(::Integer)
+        return NO_MATCH unless value.is_a?(::String) && INTEGER_PATTERN.match?(value)
+
+        Integer(value, 10)
+      end
+
+      # @return [Numeric, Object] The number or NO_MATCH
+      def coerce_number(value)
+        return value if value.is_a?(::Numeric)
+        return NO_MATCH unless value.is_a?(::String) && NUMBER_PATTERN.match?(value)
+
+        value.include?(".") ? Float(value) : Integer(value, 10)
+      end
+
+      # @return [Boolean, Object] The boolean or NO_MATCH
+      def coerce_boolean(value)
+        return value if value == true || value == false
+
+        BOOLEANS.fetch(value, NO_MATCH)
+      end
+
+      # Splits a string by the array's explode value and converts each item;
+      # an item no rule converts is kept as it is
+      def coerce_array(value, array_schema, path)
+        items = split(value, path)
+        return items if items.equal?(NO_MATCH) || !array_schema.key?("items")
+
+        items.map do |item|
+          coerced = coerce(item, array_schema["items"], path)
+          coerced.equal?(NO_MATCH) ? item : coerced
+        end
+      end
+
+      # @return [Array, Object] The items of the value or NO_MATCH
+      def split(value, path)
+        return value if value.is_a?(::Array)
+        return NO_MATCH unless value.is_a?(::String)
+
+        explode?(path) ? [value] : value.split(",")
+      end
+
+      # @return [Boolean] Whether the array at the path is sent as repeated keys
+      def explode?(path)
+        explodes.fetch(path) { Verquest.configuration.query_array_explode }
+      end
+    end
+  end
+end

data/lib/verquest/query/definition_check.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Verquest
+  module Query
+    # Rejects query and path versions with shapes their location can't express
+    #
+    # Query parameters are scalars, arrays of scalars, or one level of objects
+    # sent as `deepObject` (`filter[status]=open`). Path parameters are required
+    # scalars. Anything else, and oneOf properties, raise when the version is
+    # prepared.
+    class DefinitionCheck
+      # @param version [Verquest::Version] The query or path version to check
+      def initialize(version)
+        @version = version
+      end
+
+      # @return [void]
+      # @raise [Verquest::DefinitionError] If the version uses an unsupported shape
+      def call
+        raise DefinitionError, "Version '#{version.name}' has a root-level one_of, which #{version.location} parameters can't express" if version.combination?
+
+        version.all_properties.each_value do |property|
+          reject([property.name], "a one_of") if property.is_a?(Properties::OneOf)
+        end
+
+        version.validation_schema.fetch("properties", {}).each do |name, property_schema|
+          (version.location == :path) ? check_path(property_schema, name) : check(property_schema, [name], nested: false)
+        end
+      end
+
+      private
+
+      attr_reader :version
+
+      # Rejects path parameters that aren't required scalars
+      #
+      # @return [void]
+      def check_path(property_schema, name)
+        types = variants(property_schema).flat_map { |variant| Array(variant["type"]) }
+
+        reject([name], "an array") if types.include?("array")
+        reject([name], "an object") if types.include?("object")
+        return if version.validation_schema.fetch("required", []).include?(name)
+
+        raise DefinitionError, "Property '#{name}' in version '#{version.name}' is optional, but path parameters are always required"
+      end
+
+      # Checks the objects and arrays of a property schema and its variants
+      #
+      # @return [void]
+      def check(property_schema, path, nested:)
+        variants(property_schema).each do |variant|
+          types = Array(variant["type"])
+
+          check_object(variant, path, nested:) if types.include?("object")
+          check_items(variant["items"], path) if types.include?("array") && variant.key?("items")
+        end
+      end
+
+      # Rejects a nested object, then checks the object's properties
+      #
+      # @return [void]
+      def check_object(object_schema, path, nested:)
+        reject(path, "a nested object") if nested
+
+        object_schema.fetch("properties", {}).each do |name, child_schema|
+          check(child_schema, path + [name], nested: true)
+        end
+      end
+
+      # Rejects array items that are objects or arrays
+      #
+      # @return [void]
+      def check_items(items_schema, path)
+        item_types = variants(items_schema).flat_map { |variant| Array(variant["type"]) }
+
+        reject(path, "an array of objects or arrays") if item_types.intersect?(%w[object array])
+      end
+
+      # @return [Array<Hash>] The schema and its anyOf and oneOf variants
+      def variants(schema)
+        [schema, *schema.values_at("anyOf", "oneOf").compact.flatten]
+      end
+
+      # @raise [Verquest::DefinitionError] Always
+      def reject(path, shape)
+        raise DefinitionError, "Property '#{path.join("/")}' in version '#{version.name}' is #{shape}, which #{version.location} parameters can't express"
+      end
+    end
+  end
+end

data/lib/verquest/query/parameters.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Verquest
+  module Query
+    # Builds OpenAPI parameter objects from a query or path version's validation schema
+    #
+    # Each property becomes one `in: :query` (or `in: :path`) parameter. Keys are symbols,
+    # including inside `schema`, because rswag reads them that way
+    # (`param[:in]`, `param[:style]`, `param[:schema][:type]`).
+    #
+    # @example
+    #   schema = {"type" => "object", "required" => [], "properties" => {"page" => {"type" => "integer"}}}
+    #   Verquest::Query::Parameters.new(schema:, options: {}).call
+    #   # => [{name: "page", in: :query, required: false, schema: {type: "integer"}}]
+    class Parameters
+      # Schema keys moved to the parameter itself
+      DOCUMENTATION_KEYS = %w[description deprecated].freeze
+
+      # @param schema [Hash] The version's validation schema
+      # @param options [Hash{Array<String> => Hash}] The `explode:` and `examples:` of each property path
+      # @param location [Symbol] `:query` or `:path`, written as `in:`
+      def initialize(schema:, options:, location: :query)
+        @schema = schema
+        @options = options
+        @location = location
+      end
+
+      # @return [Array<Hash>] The parameter objects, in property order
+      def call
+        required = schema.fetch("required", [])
+
+        schema.fetch("properties", {}).map do |name, property_schema|
+          parameter(name, property_schema, required: required.include?(name))
+        end
+      end
+
+      private
+
+      attr_reader :schema, :options, :location
+
+      # @return [Hash] The parameter object of one property
+      def parameter(name, property_schema, required:)
+        {name:, in: location, required:}
+          .merge(property_schema.slice(*DOCUMENTATION_KEYS).transform_keys(&:to_sym))
+          .merge(serialization(name, property_schema))
+          .merge(examples(name))
+          .merge(schema: symbolize(property_schema.except(*DOCUMENTATION_KEYS)))
+      end
+
+      # @return [Hash] The style and explode of an array or object parameter
+      def serialization(name, property_schema)
+        types = [property_schema, *property_schema.fetch("anyOf", [])].flat_map { |variant| Array(variant["type"]) }
+
+        if types.include?("object")
+          {style: :deepObject, explode: true}
+        elsif types.include?("array")
+          {style: :form, explode: options.fetch([name], {}).fetch(:explode) { Verquest.configuration.query_array_explode }}
+        else
+          {}
+        end
+      end
+
+      # @return [Hash] The named Example Objects of the parameter, if it has any
+      def examples(name)
+        examples = options.dig([name], :examples)
+        examples ? {examples: symbolize(examples)} : {}
+      end
+
+      # @return [Object] The value with symbol keys in every hash
+      def symbolize(value)
+        case value
+        when ::Hash then value.to_h { |key, child| [key.to_sym, symbolize(child)] }
+        when ::Array then value.map { |child| symbolize(child) }
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/verquest/query.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Verquest
+  # Support for query and path requests (`location :query`, `location :path`)
+  #
+  # Query strings and paths carry only strings and flat keys, so these versions
+  # convert their params before validating them ({Query::Coercer}), reject
+  # shapes their location can't express ({Query::DefinitionCheck}), and
+  # document their properties as OpenAPI parameters ({Query::Parameters}).
+  #
+  # @example
+  #   class ListQuery < Verquest::Base
+  #     location :query
+  #
+  #     version "2025-06" do
+  #       field :page, type: :integer
+  #       array :status, type: :string, explode: false
+  #     end
+  #   end
+  #
+  #   ListQuery.process({"page" => "2", "status" => "open,won"}, version: "2025-06")
+  #   # => {"page" => 2, "status" => ["open", "won"]}
+  module Query
+  end
+end

data/lib/verquest/transformer/collection.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Verquest
+  class Transformer
+    # A collection whose items are transformed one by one, because they hold a oneOf
+    #
+    # @!attribute [r] source
+    #   @return [Path] The collection in the data of the parent scope
+    # @!attribute [r] target
+    #   @return [Path] The collection in the result of the parent scope
+    # @!attribute [r] scope
+    #   @return [Scope] The mapping of each item, with item-level paths
+    #
+    # Internal to the transformer, not part of the public API.
+    Collection = Data.define(:source, :target, :scope) do
+      # Transforms the collection items into the result
+      #
+      # A null collection, or one below a null parent, stays null.
+      #
+      # @param data [Object] The data of the parent scope
+      # @param result [Hash] The result of the parent scope
+      # @return [Hash] The result
+      # @raise [Verquest::MappingError] If an item's oneOf matches no variant or more than one
+      def call(data, result)
+        items = source.extract(data, nulls: true)
+        return result if items.equal?(Path::NOT_FOUND)
+
+        target.set(result, items.is_a?(Array) ? items.map { |item| scope.call(item) } : items)
+      end
+    end
+  end
+end

data/lib/verquest/transformer/const_as_enum.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Verquest
+  class Transformer
+    # Rewrites `const` as a one-value `enum` in a schema
+    #
+    # Draft 4 and OpenAPI 3.0 have no `const`, so variants that differ only by
+    # a const would all match during variant inference. A one-value `enum`
+    # means the same and works in every JSON Schema version.
+    #
+    # @example
+    #   ConstAsEnum.call({"properties" => {"const" => {"const" => "a"}}})
+    #   # => {"properties" => {"const" => {"enum" => ["a"]}}}
+    #
+    # Internal to the transformer, not part of the public API.
+    module ConstAsEnum
+      # Keywords whose value is a map from names to schemas
+      SCHEMA_MAPS = %w[properties patternProperties definitions $defs dependentSchemas].freeze
+
+      # Keywords whose value is data, not a schema
+      DATA_KEYWORDS = %w[enum default examples].freeze
+
+      module_function
+
+      # @param schema [Object] The schema, or a part of it
+      # @return [Object] The schema with every `const` rewritten
+      def call(schema)
+        case schema
+        when Hash then schema.to_h { |keyword, value| rewrite(keyword, value) }
+        when Array then schema.map { |item| call(item) }
+        else schema
+        end
+      end
+
+      # @param keyword [String] The schema keyword
+      # @param value [Object] Its value
+      # @return [Array(String, Object)] The rewritten keyword and value
+      def rewrite(keyword, value)
+        return ["enum", [value]] if keyword == "const"
+        return [keyword, value] if DATA_KEYWORDS.include?(keyword)
+        return [keyword, value.transform_values { |subschema| call(subschema) }] if SCHEMA_MAPS.include?(keyword) && value.is_a?(Hash)
+
+        [keyword, call(value)]
+      end
+    end
+  end
+end

data/lib/verquest/transformer/layout.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Verquest
+  class Transformer
+    # The source and target paths of a request, before they are grouped into scopes
+    #
+    # Properties add themselves with full paths from the params root
+    # (Properties::Base#layout), and Plan groups them into the scopes the
+    # transformer applies. A oneOf variant gets its own layout, so it can hold
+    # oneOfs and collections too. Its paths are full paths as well, like the
+    # parent's. Each variant gets a copy of its parent's collections: Plan looks
+    # up a collection's target by its source path, and same-named collections
+    # in different variants can have different targets.
+    #
+    # A layout is filled while a version is prepared, then only read; the
+    # hashes and arrays its readers return are not meant to be changed.
+    #
+    # @example
+    #   layout = Layout.new
+    #   layout.add_pair("user/firstName", "user/first_name")
+    #   layout.add_collection("items[]", "lines[]")
+    #
+    # Internal to the transformer, not part of the public API.
+    class Layout
+      # A oneOf with full paths
+      #
+      # The paths are Strings; Plan turns them into Paths relative to the
+      # scope that holds the oneOf. The variant layouts hold full paths too.
+      #
+      # @!attribute [r] path
+      #   @return [String] The oneOf source path, empty for a root-level oneOf
+      # @!attribute [r] discriminator
+      #   @return [String, nil] The discriminator source path
+      # @!attribute [r] variants
+      #   @return [Hash<String, Layout>] The layout of each variant by name
+      # @!attribute [r] variant_schemas
+      #   @return [Hash<String, Hash>, nil] Validation schemas by variant name, without a discriminator
+      # @!attribute [r] null_target
+      #   @return [String, nil] Where a null oneOf goes, nil for its source path
+      OneOfLayout = Data.define(:path, :discriminator, :variants, :variant_schemas, :null_target)
+
+      # @!attribute [r] pairs
+      #   @return [Hash<String, String>] Target path by source path
+      # @!attribute [r] one_ofs
+      #   @return [Array<OneOfLayout>] The oneOfs
+      # @!attribute [r] collections
+      #   @return [Hash<String, String>] Target path by source path of each collection, both ending with "[]"
+      attr_reader :pairs, :one_ofs, :collections
+
+      # @param collections [Hash<String, String>] The collections, shared with the parent layout
+      def initialize(collections: {})
+        @pairs = {}
+        @one_ofs = []
+        @collections = collections
+      end
+
+      # @param source [String] The source path
+      # @param target [String] The target path
+      # @return [void]
+      def add_pair(source, target)
+        pairs[source] = target
+      end
+
+      # @param one_of [OneOfLayout] The oneOf
+      # @return [void]
+      def add_one_of(one_of)
+        one_ofs << one_of
+      end
+
+      # @param source [String] The collection source path, ending with "[]"
+      # @param target [String] The collection target path, ending with "[]"
+      # @return [void]
+      def add_collection(source, target)
+        collections[source] = target
+      end
+
+      # @return [Layout] An empty layout for a oneOf variant, with a copy of the collections
+      def variant
+        Layout.new(collections: collections.dup)
+      end
+    end
+  end
+end