verquest 0.6.3 → 0.7.0

data/lib/verquest/version.rb

@@ -20,6 +20,8 @@ module Verquest
   #   mapping = version.mapping
   class Version
     include HelperMethods::RequiredProperties
+    include HelperMethods::ConditionalProperties
+    include HelperMethods::UnnamedOneOf
 
     # @!attribute [r] name
     #   @return [String] The name/identifier of the version (e.g., "2023-01")
@@ -41,7 +43,10 @@ module Verquest
     #
     # @!attribute [r] external_mapping
     #   @return [Hash] The mapping from internal attribute paths back to external paths
-    attr_reader :name, :properties, :schema, :validation_schema, :mapping, :transformer, :external_mapping
+    #
+    # @!attribute [r] location
+    #   @return [Symbol] Where the params come from, `:body`, `:query` or `:path`
+    attr_reader :name, :properties, :schema, :validation_schema, :mapping, :transformer, :external_mapping, :location
 
     # @!attribute [rw] schema_options
     #   @return [Hash] Additional JSON schema options for this version
@@ -53,11 +58,17 @@ module Verquest
     # Initialize a new Version instance
     #
     # @param name [String] The name/identifier of the version
+    # @param location [Symbol] Where the params come from, `:body`, `:query` or `:path`
     # @return [Version] A new Version instance
-    def initialize(name:)
+    def initialize(name:, location: :body)
       @name = name.to_s
+      @location = location
       @schema_options = {}
       @properties = {}
+      @conditions = []
+      # Filled after the version is frozen, so it is created here; freeze is shallow
+      @validation_schemers = {}
+      @validation_schemers_lock = Mutex.new
     end
 
     # Add a property to this version
@@ -65,6 +76,7 @@ module Verquest
     # @param property [Verquest::Properties::Base] The property to add
     # @return [Verquest::Properties::Base] The added property
     def add(property)
+      check_unnamed_one_of(property)
       properties[property.name] = property
     end
 
@@ -85,7 +97,17 @@ module Verquest
       properties.key?(property_name.to_s)
     end
 
-    # Copy properties from another version
+    # Returns the regular properties followed by the branch properties
+    #
+    # Stored when the version is prepared, because the version is frozen
+    # afterwards and `process` reads it on every request.
+    #
+    # @return [Hash<String, Verquest::Properties::Base>] All properties listed in the schema
+    def all_properties
+      @all_properties || super
+    end
+
+    # Copy properties and conditions from another version
     #
     # @param version [Verquest::Version] The version to copy properties from
     # @param exclude_properties [Array<Symbol>] Names of properties to not copy
@@ -99,6 +121,8 @@ module Verquest
 
         add(property)
       end
+
+      version.conditions.each { |condition| add_condition(condition) }
     end
 
     # Prepare this version by generating schema and creating transformer
@@ -112,21 +136,22 @@ module Verquest
       end
 
       schema_options.delete_if { |_, v| v.nil? }
+      @all_properties = all_properties
 
       if combination?
         prepare_combination_schema
         prepare_combination_validation_schema
         prepare_combination_mapping
         prepare_combination_external_mapping
-        @transformer = Transformer.new(mapping: mapping, discriminator: combination_discriminator)
       else
         prepare_schema
         prepare_validation_schema
         prepare_mapping
         prepare_external_mapping
-        @transformer = Transformer.new(mapping: mapping)
       end
 
+      prepare_parameters if parameters?
+      @transformer = Transformer.new(layout: transformer_layout)
       freeze
     end
 
@@ -167,13 +192,7 @@ module Verquest
     # @param params [Hash] The request parameters to validate
     # @return [Array<Hash>] An array of validation error details, or empty if valid
     def validate_params(params:)
-      schemer = JSONSchemer.schema(
-        validation_schema,
-        meta_schema: Verquest.configuration.json_schema_uri,
-        insert_property_defaults: Verquest.configuration.insert_property_defaults
-      )
-
-      schemer.validate(params).map do |error|
+      validation_schemer.validate(params).map do |error|
         {
           pointer: error["data_pointer"],
           type: error["type"],
@@ -185,17 +204,48 @@ module Verquest
 
     # Get the mapping for a specific property
     #
-    # @param property [Symbol, String] The property name to get the mapping for
+    # @param property [Symbol, String] The property name (regular or declared in a condition branch)
     # @return [Hash] The mapping for the property
     # @raise [PropertyNotFoundError] If the property doesn't exist
     def mapping_for(property)
-      raise PropertyNotFoundError.new("Property '#{property}' is not defined on '#{name}'") unless has?(property)
-
       {}.tap do |mapping|
-        properties[property.to_s].mapping(key_prefix: [], value_prefix: [], mapping: mapping, version: name)
+        fetch_property(property).mapping(key_prefix: [], value_prefix: [], mapping: mapping, version: name)
+      end
+    end
+
+    # Get a property by name
+    #
+    # @param property [Symbol, String] The property name (regular or declared in a condition branch)
+    # @return [Verquest::Properties::Base] The property
+    # @raise [PropertyNotFoundError] If the property doesn't exist
+    def fetch_property(property)
+      all_properties.fetch(property.to_s) do
+        raise PropertyNotFoundError.new("Property '#{property}' is not defined on '#{name}'")
       end
     end
 
+    # Check if this version reads its params from the query string or the path
+    #
+    # @return [Boolean] true for a query or path version
+    def parameters?
+      location != :body
+    end
+
+    # Converts query or path strings to the types the validation schema expects
+    #
+    # @param params [Hash] The parsed request parameters
+    # @return [Hash] Converted params for a query or path version, the same params otherwise
+    def coerce_params(params)
+      parameters? ? query_coercer.call(params) : params
+    end
+
+    # Returns OpenAPI parameter objects for this query or path version
+    #
+    # @return [Array<Hash>] A new array of parameter objects on each call
+    def parameters
+      Query::Parameters.new(schema: validation_schema, options: query_options, location:).call
+    end
+
     # Map request parameters to internal representation using the transformer
     #
     # @param params [Hash] The request parameters to map
@@ -232,19 +282,55 @@ module Verquest
       nested_one_of_count > 1
     end
 
-    # Returns the count of nested oneOf properties (computed once and cached)
+    # Returns the count of nested oneOf properties
+    #
+    # Not memoized, because the version is frozen once it is prepared.
     #
     # @return [Integer] Number of nested oneOf properties
     def nested_one_of_count
-      return @_nested_one_of_count if defined?(@_nested_one_of_count)
-
-      @_nested_one_of_count = properties.values.count do |p|
+      properties.values.count do |p|
         p.is_a?(Verquest::Properties::OneOf) && !p.name.nil?
       end
     end
 
     private
 
+    # @return [Verquest::Query::Coercer, nil] The coercer of a query or path version
+    attr_reader :query_coercer
+
+    # @return [Hash{Array<String> => Hash}, nil] The parameter options of each property path of a query or path version
+    attr_reader :query_options
+
+    # Checks a query or path version and builds its coercer
+    #
+    # @return [void]
+    # @raise [Verquest::DefinitionError] If the version uses a shape its location can't express
+    def prepare_parameters
+      Query::DefinitionCheck.new(self).call
+
+      @query_options = all_properties.each_value.with_object({}) do |property, options|
+        options.merge!(property.query_options(prefix: [], version: name))
+      end.freeze
+      explodes = query_options.filter_map { |path, options| [path, options[:explode]] if options.key?(:explode) }.to_h
+      @query_coercer = Query::Coercer.new(schema: validation_schema, explodes:)
+    end
+
+    # Returns the compiled validation schema for the current configuration
+    #
+    # Compiling is much slower than validating, so each configuration is
+    # compiled once and reused. The lock keeps threads from compiling at the
+    # same time.
+    #
+    # @return [JSONSchemer::Schema] The compiled validation schema
+    def validation_schemer
+      configuration = Verquest.configuration
+      key = [configuration.json_schema_uri, configuration.insert_property_defaults]
+
+      @validation_schemers_lock.synchronize do
+        @validation_schemers[key] ||= JSONSchemer.schema(validation_schema, meta_schema: key[0], insert_property_defaults: key[1])
+      end
+    end
+
     # Generates the JSON schema for this version
     #
     # Creates a schema object with type, description, required properties,
@@ -256,10 +342,11 @@ module Verquest
       @schema = {
         "type" => "object",
         "required" => required_properties,
-        "properties" => properties.transform_values { |property| property.to_schema[property.name] }
+        "properties" => all_properties.transform_values { |property| property.to_schema[property.name] }
       }.merge(schema_options).tap do |schema|
         schema["dependentRequired"] = dependent_required_properties if dependent_required_properties.any?
         schema["description"] = description if description
+        add_conditions(schema, documentation: true)
       end.freeze
     end
 
@@ -269,7 +356,10 @@ module Verquest
     # property since it represents the entire request structure.
     #
     # @return [Hash] The schema from the oneOf property
+    # @raise [ArgumentError] If the version also has conditions
     def prepare_combination_schema
+      raise ArgumentError, "Conditions can not be declared next to a root-level one_of" if conditions.any?
+
       @schema = properties.values.first.to_schema
     end
 
@@ -283,10 +373,11 @@ module Verquest
       @validation_schema = {
         "type" => "object",
         "required" => required_properties,
-        "properties" => properties.transform_values { |property| property.to_validation_schema(version: name)[property.name] }
+        "properties" => all_properties.transform_values { |property| property.to_validation_schema(version: name)[property.name] }
       }.merge(schema_options).tap do |schema|
         schema["dependentRequired"] = dependent_required_properties if dependent_required_properties.any?
         schema["description"] = description if description
+        add_conditions(schema)
       end.freeze
     end
 
@@ -312,8 +403,8 @@ module Verquest
     # @raise [MappingError] If duplicate mappings are detected
     def prepare_mapping
       # Separate oneOf properties from regular properties
-      one_of_properties = properties.values.select { |p| p.is_a?(Verquest::Properties::OneOf) }
-      regular_properties = properties.values.reject { |p| p.is_a?(Verquest::Properties::OneOf) }
+      one_of_properties = all_properties.values.select { |p| p.is_a?(Verquest::Properties::OneOf) }
+      regular_properties = all_properties.values.reject { |p| p.is_a?(Verquest::Properties::OneOf) }
 
       if one_of_properties.size == 1
         prepare_single_nested_one_of_mapping(one_of_properties.first, regular_properties)
@@ -335,6 +426,7 @@ module Verquest
       regular_properties.each do |property|
         property.mapping(key_prefix: [], value_prefix: [], mapping: regular_mapping, version: name)
       end
+      return prepare_multiple_nested_one_of_mapping([one_of_property], regular_properties) if regular_mapping.key?("_oneOfs")
 
       # Collect oneOf property mappings
       one_of_mapping = {}
@@ -344,12 +436,12 @@ module Verquest
       @mapping = {}
 
       # Preserve metadata keys
-      %w[_discriminator _variant_schemas _variant_path _nullable _nullable_path _nullable_target_path].each do |metadata_key|
+      Transformer::METADATA_KEYS.each do |metadata_key|
         @mapping[metadata_key] = one_of_mapping[metadata_key] if one_of_mapping.key?(metadata_key)
       end
 
       one_of_mapping.each do |discriminator_value, variant_mapping|
-        next if discriminator_value.start_with?("_") # Skip metadata keys
+        next if Transformer::METADATA_KEYS.include?(discriminator_value)
 
         @mapping[discriminator_value] = regular_mapping.merge(variant_mapping)
       end
@@ -368,8 +460,8 @@ module Verquest
         property.mapping(key_prefix: [], value_prefix: [], mapping: @mapping, version: name)
       end
 
-      # Collect each oneOf's mapping into _oneOfs array
-      @mapping["_oneOfs"] = one_of_properties.map do |one_of_property|
+      # Collect each oneOf's mapping into _oneOfs array, after the ones nested in objects
+      @mapping["_oneOfs"] = @mapping.fetch("_oneOfs", []) + one_of_properties.map do |one_of_property|
         one_of_mapping = {}
         one_of_property.mapping(key_prefix: [], value_prefix: [], mapping: one_of_mapping, version: name)
         one_of_mapping
@@ -387,7 +479,7 @@ module Verquest
       end
 
       seen = Set.new
-      duplicates = mapping.values.select { |v| !seen.add?(v) }
+      duplicates = mapping.except(*Transformer::METADATA_KEYS).values.select { |v| !seen.add?(v) }
       if duplicates.any?
         raise MappingError.new("Mapping must be unique. Found duplicates in version '#{name}': #{duplicates.uniq.join(", ")}")
       end
@@ -406,53 +498,39 @@ module Verquest
     #   paths and values are the corresponding external schema paths
     # @see #prepare_mapping
     def prepare_external_mapping
-      @external_mapping = if has_multiple_nested_one_of?
-        invert_multiple_one_of_mapping
-      elsif has_nested_one_of?
-        invert_single_one_of_mapping
+      # A single top-level oneOf is keyed by variant; any other mapping is a path mapping, with oneOfs in _oneOfs.
+      @external_mapping = if has_nested_one_of? && !mapping.key?("_oneOfs")
+        invert_one_of_mapping(mapping)
       else
-        mapping.invert.freeze
-      end
-    end
-
-    # Inverts mapping for single nested oneOf
-    #
-    # @return [Hash] The inverted mapping
-    def invert_single_one_of_mapping
-      mapping.each_with_object({}) do |(key, value), result|
-        result[key] = if key.start_with?("_")
-          value
-        else
-          value.invert
-        end
+        invert_path_mapping(mapping)
       end.freeze
     end
 
-    # Inverts mapping for multiple nested oneOf
+    # Inverts the source and target pairs of a mapping, and the oneOfs in its `_oneOfs`
+    #
+    # A path mapping holds only pairs and `_oneOfs`; a oneOf's other metadata
+    # sits in its own mapping, which {#invert_one_of_mapping} keeps as it is.
     #
+    # @param path_mapping [Hash] The mapping of source paths to target paths
     # @return [Hash] The inverted mapping
-    def invert_multiple_one_of_mapping
-      result = {}
-
-      mapping.each do |key, value|
+    def invert_path_mapping(path_mapping)
+      path_mapping.each_with_object({}) do |(key, value), result|
         if key == "_oneOfs"
-          result["_oneOfs"] = value.map do |one_of_mapping|
-            one_of_mapping.each_with_object({}) do |(k, v), inverted|
-              inverted[k] = if k.start_with?("_")
-                v
-              else
-                v.invert
-              end
-            end
-          end
-        elsif key.start_with?("_")
-          result[key] = value
+          result[key] = value.map { |one_of_mapping| invert_one_of_mapping(one_of_mapping) }
         else
-          result[value] = key # Invert base properties
+          result[value] = key
         end
       end
+    end
 
-      result.freeze
+    # Inverts each variant mapping of a oneOf mapping, keeping its metadata
+    #
+    # @param one_of_mapping [Hash] The oneOf mapping (variant name => variant mapping, plus metadata)
+    # @return [Hash] The oneOf mapping with each variant mapping inverted
+    def invert_one_of_mapping(one_of_mapping)
+      one_of_mapping.to_h do |key, value|
+        [key, Transformer::METADATA_KEYS.include?(key) ? value : invert_path_mapping(value)]
+      end
     end
 
     # Prepares the parameter mapping for combination schemas (oneOf)
@@ -473,23 +551,18 @@ module Verquest
     #
     # @return [Hash] The frozen inverted mapping for each discriminator value
     def prepare_combination_external_mapping
-      @external_mapping = mapping.each_with_object({}) do |(key, value), result|
-        # Skip metadata keys, only invert variant mapping hashes
-        result[key] = if key.start_with?("_")
-          value
-        else
-          value.invert
-        end
-      end.freeze
+      @external_mapping = invert_one_of_mapping(mapping).freeze
     end
 
-    # Returns the discriminator property name for combination schemas
+    # Returns the full paths of this version's properties for the transformer
     #
-    # @return [String, nil] The discriminator property name
-    def combination_discriminator
-      return nil unless combination?
-
-      properties.values.first.send(:discriminator)
+    # @return [Verquest::Transformer::Layout] The layout
+    def transformer_layout
+      Transformer::Layout.new.tap do |layout|
+        all_properties.each_value do |property|
+          property.layout(key_prefix: [], value_prefix: [], layout:, version: name)
+        end
+      end
     end
   end
 end

data/lib/verquest.rb

@@ -2,6 +2,8 @@
 
 require "zeitwerk"
 require "json_schemer"
+require "digest"
+require "json"
 
 require_relative "verquest/gem_version"
 
@@ -66,6 +68,10 @@ module Verquest
   # @api public
   MappingError = Class.new(Verquest::Error)
 
+  # Error raised when a request definition uses a shape its location can't express
+  # @api public
+  DefinitionError = Class.new(Verquest::Error)
+
   # Error raised when parameters do not match the expected schema
   # @api public
   InvalidParamsError = Class.new(Verquest::Error) do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verquest
 version: !ruby/object:Gem::Version
-  version: 0.6.3
+  version: 0.7.0
 platform: ruby
 authors:
 - Petr Hlavicka
@@ -37,10 +37,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.4'
-description: Verquest helps you version API requests, simplifying the management of
-  changes, handling the mapping for internal versus external names and structures,
-  validating parameters, and exporting your requests to JSON Schema components for
-  OpenAPI.
+description: Verquest describes API request bodies, query strings and path parameters
+  with a Ruby DSL, one definition per API version. It validates params against JSON
+  Schema, maps them from your public API structure to your internal one, and generates
+  JSON Schema components and OpenAPI parameters for documentation tools like rswag.
 email:
 - yes@petr.codes
 executables: []
@@ -54,14 +54,36 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/rails.md
 - lib/verquest.rb
 - lib/verquest/base.rb
+- lib/verquest/base/condition_class_methods.rb
 - lib/verquest/base/helper_class_methods.rb
 - lib/verquest/base/private_class_methods.rb
 - lib/verquest/base/public_class_methods.rb
+- lib/verquest/conditions.rb
+- lib/verquest/conditions/branch.rb
+- lib/verquest/conditions/condition.rb
+- lib/verquest/conditions/conjunction.rb
+- lib/verquest/conditions/fragment_merge.rb
+- lib/verquest/conditions/property_merge.rb
+- lib/verquest/conditions/rule_set.rb
+- lib/verquest/conditions/rules.rb
+- lib/verquest/conditions/rules/absent.rb
+- lib/verquest/conditions/rules/alternatives.rb
+- lib/verquest/conditions/rules/any.rb
+- lib/verquest/conditions/rules/equals.rb
+- lib/verquest/conditions/rules/names_rule.rb
+- lib/verquest/conditions/rules/none.rb
+- lib/verquest/conditions/rules/present.rb
+- lib/verquest/conditions/rules/property_rule.rb
+- lib/verquest/conditions/rules/satisfies.rb
+- lib/verquest/conditions/rules/value_in.rb
 - lib/verquest/configuration.rb
 - lib/verquest/gem_version.rb
+- lib/verquest/helper_methods/conditional_properties.rb
 - lib/verquest/helper_methods/required_properties.rb
+- lib/verquest/helper_methods/unnamed_one_of.rb
 - lib/verquest/properties.rb
 - lib/verquest/properties/array.rb
 - lib/verquest/properties/base.rb
@@ -71,9 +93,22 @@ files:
 - lib/verquest/properties/field.rb
 - lib/verquest/properties/object.rb
 - lib/verquest/properties/one_of.rb
+- lib/verquest/properties/one_of/discriminated_schema.rb
 - lib/verquest/properties/reference.rb
+- lib/verquest/query.rb
+- lib/verquest/query/coercer.rb
+- lib/verquest/query/definition_check.rb
+- lib/verquest/query/parameters.rb
 - lib/verquest/result.rb
 - lib/verquest/transformer.rb
+- lib/verquest/transformer/collection.rb
+- lib/verquest/transformer/const_as_enum.rb
+- lib/verquest/transformer/layout.rb
+- lib/verquest/transformer/mapping_layout.rb
+- lib/verquest/transformer/one_of.rb
+- lib/verquest/transformer/path.rb
+- lib/verquest/transformer/plan.rb
+- lib/verquest/transformer/scope.rb
 - lib/verquest/version.rb
 - lib/verquest/version_resolver.rb
 - lib/verquest/versions.rb
@@ -98,8 +133,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
-summary: Verquest is a Ruby gem that offers an elegant solution for versioning API
-  requests
+summary: Versioned API request definitions with JSON Schema validation, mapping and
+  OpenAPI output
 test_files: []