versponse 0.1.0 → 0.2.0

data/lib/versponse/expansion.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Frozen tree of requested expand paths, passed down while rendering. Each node answers whether
+  # a key is expanded and hands out the node for that key's children.
+  #
+  # @api private
+  class Expansion
+    # @param paths [Array<String, Symbol>] dotted paths
+    # @return [Expansion] the tree (NONE for no paths)
+    def self.build(paths)
+      tree = {}
+      paths.map(&:to_s).each { |path| path.split(".").reduce(tree) { |node, key| node[key] ||= {} } }
+      from_hash(tree)
+    end
+
+    # @param hash [Hash{String => Hash}] nested keys
+    # @return [Expansion] the frozen node
+    def self.from_hash(hash)
+      return NONE if hash.empty?
+
+      new(hash.transform_values { |child| from_hash(child) })
+    end
+
+    # @param children [Hash{String => Expansion}] expanded keys and their nodes
+    def initialize(children = {})
+      @children = children.freeze
+      freeze
+    end
+
+    # @param key [String] output key
+    # @return [Boolean] whether the association under key is expanded
+    def expand?(key)
+      @children.key?(key)
+    end
+
+    # @param key [String] output key
+    # @return [Expansion] the node for the key's children
+    def child(key)
+      @children.fetch(key, NONE)
+    end
+
+    # Nothing expanded
+    NONE = new
+  end
+end

data/lib/versponse/extractors/block.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Extractors
+    # Calls a value block with (object, context)
+    #
+    # @api private
+    class Block
+      # @param block [Proc] value block
+      def initialize(block)
+        @block = block
+        freeze
+      end
+
+      # @param object [Object] source
+      # @param _hash [Boolean] unused
+      # @param context [Hash] serialize context
+      # @return [Object] the block's result
+      def call(object, _hash, context)
+        @block.call(object, context)
+      end
+    end
+  end
+end

data/lib/versponse/extractors/fallback.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Extractors
+    # Reads with another extractor and falls back to a callable when the value is nil (default:, on_nil)
+    #
+    # @api private
+    class Fallback
+      # @param extractor [#call] value reader
+      # @param fallback [#call] called with (object, context) for a nil value
+      def initialize(extractor, fallback)
+        @extractor = extractor
+        @fallback = fallback
+        freeze
+      end
+
+      # @param object [Object] source
+      # @param hash [Boolean] whether the source is a Hash
+      # @param context [Hash] serialize context
+      # @return [Object] the value, or the fallback's for nil
+      def call(object, hash, context)
+        value = @extractor.call(object, hash, context)
+        value.nil? ? @fallback.call(object, context) : value
+      end
+    end
+  end
+end

data/lib/versponse/extractors/itself.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Extractors
+    # Returns the source object (map: ".")
+    #
+    # @api private
+    class Itself
+      # Shared instance
+      INSTANCE = new.freeze
+
+      # @param object [Object] source
+      # @param _hash [Boolean] unused
+      # @param _context [Hash] unused
+      # @return [Object] the source object
+      def call(object, _hash, _context)
+        object
+      end
+    end
+  end
+end

data/lib/versponse/extractors/key.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Extractors
+    # Reads a method, or a Symbol then String key of a Hash
+    #
+    # @api private
+    class Key
+      # @param name [String, Symbol] method or key name
+      def initialize(name)
+        @symbol = name.to_sym
+        @string = name.to_s.freeze
+        freeze
+      end
+
+      # @param object [Object] source
+      # @param hash [Boolean] whether the source is a Hash
+      # @param _context [Hash] unused
+      # @return [Object] the value
+      # @raise [KeyError] when a Hash has neither key
+      def call(object, hash, _context)
+        return object.public_send(@symbol) unless hash
+
+        object.fetch(@symbol) { object.fetch(@string) }
+      end
+    end
+  end
+end

data/lib/versponse/extractors/path.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Extractors
+    # Reads a nested value like "address/city", returning nil when a step is nil
+    #
+    # @api private
+    class Path
+      # @param segments [Array<String>] path segments
+      def initialize(segments)
+        @keys = segments.map { |segment| Key.new(segment) }.freeze
+        freeze
+      end
+
+      # @param object [Object] source
+      # @param _hash [Boolean] unused, each step checks its own source
+      # @param context [Hash] serialize context
+      # @return [Object, nil] the value
+      def call(object, _hash, context)
+        @keys.reduce(object) do |current, key|
+          return nil if current.nil?
+
+          key.call(current, current.is_a?(Hash), context)
+        end
+      end
+    end
+  end
+end

data/lib/versponse/extractors.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Value readers chosen once at compile time. Each is called with (object, hash, context),
+  # where hash tells whether the object is a Hash.
+  #
+  # @api private
+  module Extractors
+    # @param name [Symbol] property name
+    # @param map [String, nil] map: path
+    # @param block [Proc, nil] value block
+    # @return [#call] the extractor for the property
+    def self.for(name:, map:, block:)
+      return Block.new(Callable.normalize(block)) if block
+      return Key.new(name) if map.nil?
+      return Itself::INSTANCE if map == "."
+      raise DefinitionError, "map: #{map.inspect} must be a non-empty path without empty segments" if map.empty? || map.split("/", -1).any?(&:empty?)
+      return Path.new(map.split("/")) if map.include?("/")
+
+      Key.new(map)
+    end
+  end
+end

data/lib/versponse/field_order.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Orders properties as config.field_order says
+  #
+  # @api private
+  module FieldOrder
+    # Values accepted by config.field_order
+    VALUES = %i[declaration alphabetical].freeze
+
+    # :alphabetical matches blueprinter's sort_fields_by :name_asc: identifiers first, then by output key
+    #
+    # @param properties [Array<Versponse::Properties::Base>] properties in declaration order
+    # @param identifiers [Array<String>] identifier keys, which go first when alphabetical
+    # @return [Array<Versponse::Properties::Base>] the properties in the configured order
+    def self.call(properties, identifiers: [])
+      return properties if Versponse.configuration.field_order == :declaration
+
+      first, rest = properties.partition { |property| identifiers.include?(property.key) }
+      first + rest.sort_by(&:key)
+    end
+  end
+end

data/lib/versponse/field_type.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Built-in field types, and custom ones from config.custom_field_types in verquest's shape
+  #
+  # @api private
+  module FieldType
+    # Built-in types; "object" is a free-form map whose value passes through
+    BUILT_IN = %w[string number integer boolean object].freeze
+
+    # Keys of a custom type definition; required: is accepted for verquest and ignored
+    KEYS = %i[type schema_options required].freeze
+
+    # @param name [Symbol, String] custom type name
+    # @param definition [Hash] type: and schema_options: (required: is ignored)
+    # @return [Hash{String => Object}] frozen {"type" => base type, "schema_options" => camelized keywords}
+    # @raise [ArgumentError] for a built-in name, unknown keys or an unsupported type:
+    # @raise [Versponse::DefinitionError] for a Regexp pattern ECMA-262 can't express
+    def self.normalize(name, definition)
+      definition = check!(name.to_s, definition)
+      DeepFreeze.call({"type" => definition[:type].to_s, "schema_options" => Naming.camelize_keys(definition[:schema_options] || {})})
+    end
+
+    # @param type [Symbol, String, Array<Symbol, String>] built-in or custom type name, or a union of built-in types
+    # @param key [String] property key, for the error message
+    # @return [Array(String, Hash), Array(Array<String>, Hash)] the base type (or the union's types) and the custom type's schema options
+    # @raise [Versponse::DefinitionError] for an unknown type or an invalid union
+    def self.resolve(type, key)
+      return [union(type, key), {}] if type.is_a?(Array)
+
+      type = type.to_s
+      return [type, {}] if BUILT_IN.include?(type)
+
+      custom = Versponse.configuration.custom_field_types.fetch(type) do
+        raise DefinitionError, "#{key}: type must be one of #{names.join(", ")}"
+      end
+      custom.values_at("type", "schema_options")
+    end
+
+    # Null comes from nullable:, and custom types can't take part, because their schema options would apply to every type
+    #
+    # @param types [Array<Symbol, String>] two or more distinct built-in types
+    # @param key [String] property key, for the error message
+    # @return [Array<String>] frozen type names in declaration order, without duplicates
+    # @raise [Versponse::DefinitionError] for fewer than two distinct types, or a type that isn't built in
+    def self.union(types, key)
+      names = types.map(&:to_s).uniq
+      invalid = names - BUILT_IN
+      raise DefinitionError, "#{key}: type unions take only built-in types (#{BUILT_IN.join(", ")}), not #{invalid.join(", ")}" unless invalid.empty?
+      raise DefinitionError, "#{key}: a type union needs at least two distinct types" if names.size < 2
+
+      names.freeze
+    end
+
+    # The union's anyOf and a declared anyOf (or allOf) are combined by {SchemaMerge}
+    #
+    # OpenAPI 3.0's nullable only applies next to a type, so a nullable union sets it on each branch
+    #
+    # @param types [Array<String>] union types
+    # @param options [Hash{String => Object}] the property's (or its items') schema keywords
+    # @param nullable [Boolean] whether null is allowed
+    # @return [Hash] OpenAPI 3.0 schema: an anyOf of single types with the keywords alongside
+    def self.openapi30_union(types, options, nullable: false)
+      branch = nullable ? {"nullable" => true} : {}
+      SchemaMerge.call({"anyOf" => types.map { |type| {"type" => type}.merge(branch) }}, options)
+    end
+
+    # @return [Array<String>] built-in and custom type names
+    def self.names
+      BUILT_IN + Versponse.configuration.custom_field_types.keys
+    end
+
+    def self.check!(name, definition)
+      raise ArgumentError, "Custom field type #{name} shadows a built-in type" if BUILT_IN.include?(name)
+      raise ArgumentError, "Custom field type #{name} must be a Hash" unless definition.is_a?(Hash)
+
+      definition.transform_keys(&:to_sym).tap { |symbolized| check_keys!(name, symbolized) }
+    end
+
+    def self.check_keys!(name, definition)
+      unknown = definition.keys - KEYS
+      raise ArgumentError, "Custom field type #{name} has unknown keys: #{unknown.join(", ")}" unless unknown.empty?
+      raise ArgumentError, "Custom field type #{name} needs type: one of #{BUILT_IN.join(", ")}" unless BUILT_IN.include?(definition[:type].to_s)
+    end
+
+    private_class_method :check!, :check_keys!
+  end
+end

data/lib/versponse/formatters.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Default formatters, keyed by JSON Schema format, applied to non-nil field values
+  module Formatters
+    # Formats times, datetimes and dates (as midnight) as ISO 8601 in UTC with the given fraction digits,
+    # always with a Z suffix, without changing the original object. The Strings it builds are frozen, so inline
+    # validation checks them once (see InlineValidation::Builder); any other value is returned as it is.
+    #
+    # @param precision [Integer] fraction digits, 0 for whole seconds
+    # @return [Proc] date-time formatter
+    def self.date_time(precision)
+      lambda do |value|
+        # A UTC Time needs no getutc copy
+        if value.instance_of?(Time) && value.utc?
+          value.iso8601(precision).freeze
+        elsif value.respond_to?(:getutc)
+          value.getutc.iso8601(precision).freeze
+        elsif value.respond_to?(:new_offset)
+          value.new_offset(0).to_time.utc.iso8601(precision).freeze
+        elsif value.is_a?(Date)
+          Time.utc(value.year, value.month, value.day).iso8601(precision).freeze
+        else
+          value
+        end
+      end
+    end
+
+    # Formats date-times with milliseconds, like Rails' JSON
+    DATE_TIME = date_time(3)
+
+    # Formats dates, and times or datetimes (converted to their date), as frozen ISO 8601 Strings
+    DATE = ->(value) { (value.is_a?(Date) || value.is_a?(Time)) ? value.to_date.iso8601.freeze : value }
+
+    # Formatters used when none are configured
+    DEFAULTS = {"date-time" => DATE_TIME, "date" => DATE}.freeze
+  end
+end

data/lib/versponse/gem_version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Gem version (Versponse::Version is the version definition class)
+  GEM_VERSION = "0.2.0"
+end

data/lib/versponse/inline_validation/builder.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Versponse
+  module InlineValidation
+    # Turns a plan into one that validates while rendering, when its validation schema proves it can: the object
+    # keywords hold by construction (a plan writes exactly its steps' String keys, unconditional ones always), and
+    # each step checks its value. Nested plans are proven against their subschema in the same tree; anything
+    # unproven checks its written value with the subschema's compiled checker.
+    #
+    # @api private
+    class Builder
+      # Object keywords a plan guarantees by construction (type object, additionalProperties false)
+      OBJECT_KEYWORDS = %w[type properties required additionalProperties].freeze
+
+      # Types a change in place can't turn into another type (not integer: json_schemer accepts any Numeric whose
+      # floor equals it, so a mutable Numeric can stop passing)
+      SCALAR_TYPES = %w[string number boolean null].freeze
+
+      # Types whose values can't be changed in place at all
+      IMMUTABLE_TYPES = %w[boolean null].freeze
+
+      # Keywords that only constrain the type (nullable: openapi30)
+      TYPE_KEYWORDS = %w[type nullable].freeze
+
+      # Leaf steps that have a checking variant
+      LEAVES = [Steps::Read, Steps::ReadFormatted, Steps::Value].freeze
+
+      # Keywords that never change validity, besides x- extensions
+      INERT = (Validator::Compiler::ANNOTATIONS + Validator::Compiler::ANCHORS).freeze
+
+      # @param compiler [Versponse::Validator::Compiler] compiler that compiled the whole validation schema
+      def initialize(compiler)
+        @compiler = compiler
+      end
+
+      # @param plan [Versponse::Plan] plain plan
+      # @param schema [Hash] its object schema, from the compiled tree
+      # @return [Versponse::Plan, nil] the validating plan, nil when the schema doesn't prove it
+      def prove(plan, schema)
+        return unless object_schema?(schema)
+
+        properties = schema.fetch("properties", {})
+        keys = plan.steps.map(&:key)
+        return unless keys.uniq.size == keys.size && keys.sort == properties.keys.sort
+        return unless plan.steps.reject(&:conditional?).map(&:key).sort == schema.fetch("required", []).sort
+
+        steps = plan.steps.map { |step| checked(step, properties.fetch(step.key)) }
+        Plan.new(label: plan.label, steps:, recoveries: plan.recoveries, always: plan.always) unless steps.include?(nil)
+      rescue Validator::Compiler::Unsupported
+        nil
+      end
+
+      private
+
+      def object_schema?(schema)
+        schema.is_a?(Hash) && schema["type"] == "object" && schema["additionalProperties"] == false &&
+          schema.each_key.all? { |key| OBJECT_KEYWORDS.include?(key) || inert?(key) }
+      end
+
+      def inert?(key)
+        INERT.include?(key) || key.start_with?("x-")
+      end
+
+      # Only these keys, besides inert ones
+      def only?(schema, keys)
+        schema.is_a?(Hash) && schema.each_key.all? { |key| keys.include?(key) || inert?(key) }
+      end
+
+      # Exact classes only (a subclass may write other keys, so it stays unproven until it is listed here)
+      def checked(step, schema)
+        klass = step.class
+        if LEAVES.include?(klass) then step.checked(@compiler.checker_for(schema), recheck: recheck?(schema))
+        elsif klass == Steps::Const then step if root(schema).valid?(step.value)
+        elsif klass == Steps::Nested then nested(step, schema)
+        elsif klass == Steps::OneOf then Steps::Checked.new(step, root(schema))
+        end
+      end
+
+      # Whether a value the schema accepts can stop passing when it is changed in place later in the render: not
+      # when only its type is constrained and every type is scalar (a change in place keeps the value's class), nor
+      # for booleans and nulls
+      def recheck?(schema)
+        return true unless schema.is_a?(Hash) && schema.key?("type")
+
+        types = Array(schema["type"])
+        return false if types.all? { |type| IMMUTABLE_TYPES.include?(type) }
+
+        !(types.all? { |type| SCALAR_TYPES.include?(type) } && only?(schema, TYPE_KEYWORDS))
+      end
+
+      def root(schema)
+        Validator::Root.new(@compiler.checker_for(schema))
+      end
+
+      def nested(step, schema)
+        target = step.collection? ? items(schema) : schema
+        plans = step.plans.map { |plan| proven(plan, target) } if target
+        return Steps::Checked.new(step, root(schema)) if plans.nil? || plans.include?(nil)
+
+        step.with_plans(plan: plans[0], collapsed_plan: plans[1], nil_fails: !root(schema).valid?(nil))
+      end
+
+      # {"type" => "array" or ["array", "null"], "items" => I}: the items schema I
+      def items(schema)
+        return unless only?(schema, %w[type items]) && schema.key?("items")
+
+        schema["items"] if [["array"], %w[array null]].include?(Array(schema["type"]).sort)
+      end
+
+      # The schema itself, or a branch of an anyOf (any branch passing satisfies it)
+      def proven(plan, schema)
+        plan = resolve(plan)
+        return unless plan
+
+        prove(plan, schema) || (schema["anyOf"].lazy.filter_map { |branch| prove(plan, branch) }.first if only?(schema, %w[anyOf]) && schema["anyOf"].is_a?(Array))
+      end
+
+      # Class-backed and inline plans; dispatchers and other plan objects stay unproven
+      def resolve(plan)
+        case plan
+        when Plan then plan
+        when LazyPlan then plan.resolve
+        end
+      rescue Error
+        nil
+      end
+    end
+  end
+end

data/lib/versponse/inline_validation/state.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Versponse
+  module InlineValidation
+    # A fiber's inline validation state, kept in one fiber-local so a render reads it once
+    #
+    # @api private
+    class State
+      # @return [Boolean, nil] whether a check failed in the current run, nil outside a run
+      attr_accessor :failed
+
+      # @return [Array, nil] checkers and values (alternating) to check once the render has finished
+      attr_accessor :rechecks
+    end
+  end
+end

data/lib/versponse/inline_validation.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Validation while rendering: checked steps report a failure through a fiber-local flag, and the finished output
+  # then goes through OutputValidator as before. Collections.items materializes collections (to_ary/to_a), so a
+  # render never switches fibers halfway; keep it that way.
+  #
+  # @api private
+  module InlineValidation
+    # Fiber-local key of the State (Thread#[] is fiber-local)
+    STATE = :versponse_inline_validation
+
+    # Marks the current run as failed; outside a run (a plain render's recovery) it does nothing
+    #
+    # @return [void]
+    def self.failed!
+      state = Thread.current[STATE]
+      state.failed = true if state && !state.failed.nil?
+    end
+
+    # @param check [#valid?] checker of the value's schema
+    # @param value [Object] value to check once the render has finished
+    # @return [void]
+    def self.recheck_later(check, value)
+      state = Thread.current[STATE]
+      (state.rechecks ||= []).push(check, value)
+    end
+
+    # @return [Boolean] true while a run is active in this fiber and one of its checks failed
+    def self.failed?
+      Thread.current[STATE]&.failed == true
+    end
+
+    # Checks a value a step wrote. A value that a later step of the same render could still change in place (it is
+    # often the source's own object) is checked once the render has finished instead: any value that isn't frozen
+    # all the way down, when the schema can be broken by such a change. A check that raises, or defers
+    # (UncaughtThrowError outside Root), fails.
+    #
+    # @param check [#valid?] checker of the value's schema
+    # @param value [Object] written value
+    # @param recheck [Boolean] whether a change in place can break the schema (see Builder)
+    # @return [void]
+    def self.check(check, value, recheck)
+      if recheck && !Ractor.shareable?(value)
+        recheck_later(check, value)
+      else
+        ok = begin
+          check.valid?(value)
+        rescue
+          false
+        end
+        failed! unless ok
+      end
+    end
+
+    # Runs a render with a clear flag; the previous state is restored, so a serialize inside a block is isolated
+    #
+    # @yield the render (it keeps its result itself, so nothing is allocated here)
+    # @return [Boolean] true when a check failed, during the render or when rechecked after it
+    def self.run
+      state = (Thread.current[STATE] ||= State.new)
+      previous = state.failed
+      previous_rechecks = state.rechecks
+      state.failed = false
+      state.rechecks = nil
+      yield
+      rechecks = state.rechecks
+      state.failed = true if rechecks && !rechecked?(rechecks)
+      state.failed
+    ensure
+      state.failed = previous
+      state.rechecks = previous_rechecks
+    end
+
+    # @param rechecks [Array] checkers and values, alternating
+    # @return [Boolean] true when every value passes its check
+    def self.rechecked?(rechecks)
+      rechecks.each_slice(2).all? do |check, value|
+        check.valid?(value)
+      rescue
+        false
+      end
+    end
+    private_class_method :rechecked?
+  end
+end