versponse 0.1.0 → 0.2.0

data/lib/versponse/registry.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Every response class (recorded by {Base.inherited}) and every declared version name
+  #
+  # @api private
+  module Registry
+    @classes = []
+    @anonymous = ObjectSpace::WeakMap.new
+    @version_names = [].freeze
+    @range_maxes = [].freeze
+    @after_max = {}.freeze
+    @canonical = Cache.new(limit: 256)
+    @mutex = Mutex.new
+
+    class << self
+      # @return [Array<String>] every version declared by any response class, plus every
+      #   supported_versions bound, oldest first
+      attr_reader :version_names
+
+      # Replaces a registered class with the same name, so code reloading doesn't keep stale classes.
+      # Anonymous classes (Class.new, mostly in tests) are held weakly, so they can be garbage collected;
+      # one later assigned to a constant stays alive through it.
+      #
+      # @param klass [Class] response class
+      # @return [void]
+      def add(klass)
+        name = klass.name
+        @mutex.synchronize do
+          next @anonymous[klass] = true unless name
+
+          @classes.reject! { |registered| registered.name == name }
+          @classes << klass
+        end
+      end
+
+      # @param name [String] declared version name
+      # @return [void]
+      def add_version_name(name)
+        @mutex.synchronize do
+          @version_names = (@version_names | [name]).sort.freeze
+          @after_max = {}.freeze
+          @canonical = Cache.new(limit: 256)
+        end
+      end
+
+      # Registers a supported_versions range, so canonical names never cross its bounds
+      #
+      # @param range [Versponse::SupportedVersions] declared range
+      # @return [void]
+      def add_range(range)
+        [range.min, range.max].compact.each { |name| add_version_name(name) }
+        return unless range.max
+
+        @mutex.synchronize do
+          @range_maxes = (@range_maxes | [range.max]).freeze
+          @canonical = Cache.new(limit: 256)
+        end
+      end
+
+      # Maps a requested version to the closest earlier registered name, so arbitrary client-sent
+      # strings can't grow the caches. Every declared version and supported_versions bound is
+      # registered, so two requests with the same canonical name resolve alike in every class.
+      # A request strictly after a max maps to the first such request seen instead of the max,
+      # so it stays outside that range.
+      #
+      # @param name [String] requested version
+      # @return [String] canonical version name, or name itself when it precedes every registered one
+      def canonical(name)
+        @canonical[name] || memoized_canonical(name)
+      end
+
+      # @param name [String] requested version
+      # @return [String] canonical name, stored when it's a registered name or a representative (a request before
+      #   every registered name maps to itself and isn't stored, so such strings can't fill the cache)
+      def memoized_canonical(name)
+        result = resolve_canonical(name)
+        (result.equal?(name) && !@version_names.include?(name)) ? result : @canonical.fetch(name) { result }
+      end
+
+      # @param name [String] requested version
+      # @return [String] closest registered name, or a representative after a max, or name itself
+      def resolve_canonical(name)
+        closest = Versponse.configuration.version_resolver.call(name, @version_names)
+        return name if closest.nil?
+        return closest if closest == name || !@range_maxes.include?(closest)
+
+        @after_max[closest] || @mutex.synchronize do
+          @after_max[closest] || (@after_max = @after_max.merge(closest => name).freeze)[closest]
+        end
+      end
+
+      private :memoized_canonical, :resolve_canonical
+
+      # Forgets the representatives of requests after a max, which depend on the version resolver
+      #
+      # @return [void]
+      def clear_canonical
+        @mutex.synchronize do
+          @after_max = {}.freeze
+          @canonical = Cache.new(limit: 256)
+        end
+      end
+
+      # @return [Array<Class>] every registered class, including anonymous ones
+      def all
+        @mutex.synchronize { @classes + @anonymous.keys }
+      end
+
+      # @return [Array<Class>] named classes still bound to their constant (skips stale reloaded classes)
+      def classes
+        all.select { |klass| live?(klass) }
+      end
+
+      private
+
+      def live?(klass)
+        klass.name && ::Object.const_defined?(klass.name) && ::Object.const_get(klass.name).equal?(klass)
+      rescue NameError
+        false
+      end
+    end
+  end
+end

data/lib/versponse/schema_context.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Versponse
+  # State of one schema generation. In validation mode referenced classes are inlined.
+  # A class that recurses into itself gets "$anchor": "<Name>" (or the configured JSON Schema version's
+  # equivalent, see Configuration#anchor) and is referenced as "#<Name>".
+  # Anchors (unlike "#/$defs/..." pointers) still resolve when the schema is embedded in
+  # another document, for example by verquest. Anchor names are unique within one generated
+  # schema only; keep component names unique across classes when several are embedded together.
+  #
+  # @api private
+  class SchemaContext
+    # @return [String] requested version name
+    attr_reader :version
+
+    # @param version [String] requested version name
+    # @param validation [Boolean] true to inline references
+    def initialize(version:, validation:)
+      @version = version
+      @validation = validation
+      @stack = []
+      @recursive = {}
+      @anchored = {}
+      @anchors = {}
+    end
+
+    # @return [Boolean] true when references are inlined
+    def validation?
+      @validation
+    end
+
+    # @param identity [Object] what is being inlined, e.g. [klass, view]; two classes can share a component name
+    # @param name [String] component name, used for the anchor
+    # @yieldreturn [Hash] the component schema
+    # @return [Hash] the schema, or an anchor reference when the identity is recursive
+    def inline(identity, name)
+      return anchor_ref(identity, name) if @anchored[identity]
+
+      if @stack.include?(identity)
+        @recursive[identity] = true
+        return anchor_ref(identity, name)
+      end
+
+      @stack.push(identity)
+      schema = yield
+      @stack.pop
+      return schema unless @recursive[identity]
+
+      @anchored[identity] = true
+      schema.merge(Versponse.configuration.anchor(anchor_name(identity, name)))
+    end
+
+    private
+
+    def anchor_ref(identity, name)
+      {"$ref" => "##{anchor_name(identity, name)}"}
+    end
+
+    def anchor_name(identity, name)
+      @anchors[identity] ||= begin
+        base = name.to_s.empty? ? "Anonymous" : name
+        candidate = base
+        suffix = 1
+        candidate = "#{base}#{suffix += 1}" while @anchors.value?(candidate)
+        candidate
+      end
+    end
+  end
+end

data/lib/versponse/schema_merge.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Merges a property's schema keywords into the schema Versponse generated for it without losing the generated
+  # combinators (a type union's anyOf, a nullable or wrapped $ref's anyOf/allOf), as verquest does: allOf lists
+  # are joined, and an anyOf or oneOf on both sides go into allOf side by side.
+  #
+  # @api private
+  module SchemaMerge
+    # Combinators that can't be merged key by key
+    EXCLUSIVE = %w[anyOf oneOf].freeze
+
+    # @param schema [Hash] generated schema
+    # @param options [Hash{String => Object}] the property's camelized schema keywords
+    # @return [Hash] the merged schema
+    def self.call(schema, options)
+      clashes = EXCLUSIVE.select { |keyword| schema.key?(keyword) && options.key?(keyword) }
+      return schema.merge(options) if clashes.empty? && !(schema.key?("allOf") && options.key?("allOf"))
+
+      all_of = [*options["allOf"], *schema["allOf"]] + clashes.flat_map { |keyword| [{keyword => schema[keyword]}, {keyword => options[keyword]}] }
+      schema.except(*clashes).merge(options.except(*clashes)).merge("allOf" => all_of)
+    end
+  end
+end

data/lib/versponse/selection/scope.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Versponse
+  class Selection
+    # A selected render's expand tree node paired with its selection node. Plans and steps take it where they take an
+    # Expansion, so renders without fields: pass the plain Expansion and run as before.
+    #
+    # @api private
+    class Scope
+      # @return [Versponse::Selection] selected fields of this object
+      attr_reader :selection
+
+      # @param expansion [Versponse::Expansion] expand tree node
+      # @param selection [Versponse::Selection] selection node (not ALL)
+      def initialize(expansion, selection)
+        @expansion = expansion
+        @selection = selection
+        freeze
+      end
+
+      # @param key [String] output key
+      # @return [Boolean] true when the association under key is expanded
+      def expand?(key)
+        @expansion.expand?(key)
+      end
+
+      # @param key [String] output key
+      # @return [Scope, Versponse::Expansion] the child's scope, or its plain expand tree node when the key is
+      #   selected whole
+      def child(key)
+        selection = @selection.child(key)
+        selection.all? ? @expansion.child(key) : Scope.new(@expansion.child(key), selection)
+      end
+    end
+  end
+end

data/lib/versponse/selection.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Tree of the fields a render selects (serialize fields:), built from dotted paths. A node selects some keys of
+  # one object; a key selected whole (or with ".*") has the ALL node. Each node memoizes the step indexes of each
+  # plan it meets; trees are cached per class, so the memo is thread-safe.
+  #
+  # @api private
+  class Selection
+    # @param paths [Array<String, Symbol>, nil] validated paths
+    # @return [Selection] ALL for none, or with a root "*"
+    def self.build(paths)
+      paths = Array(paths).map(&:to_s)
+      return ALL if paths.empty? || paths.include?("*")
+
+      paths = paths.map { |path| path.delete_suffix(".*") }.uniq.sort
+      tree = {}
+      paths.each { |path| add(tree, path.split(".")) }
+      from_hash(tree, signature: paths.join("\n").freeze)
+    end
+
+    # @return [Selection] a selection of no keys: plans render only what always renders (identifiers and consts)
+    def self.none
+      new({}.freeze, signature: "")
+    end
+
+    # @param tree [Hash{String => Hash, Symbol}] node being built (:all for a key selected whole)
+    # @param segments [Array<String>] path segments
+    # @return [void]
+    def self.add(tree, segments)
+      *parents, leaf = segments
+      node = parents.reduce(tree) do |current, segment|
+        child = current[segment]
+        break if child == :all
+
+        child || (current[segment] = {})
+      end
+      node[leaf] = :all if node
+    end
+
+    # @param tree [Hash{String => Hash, Symbol}] built tree
+    # @param signature [String, nil] the root's sorted paths
+    # @return [Selection] node
+    def self.from_hash(tree, signature: nil)
+      new(tree.transform_values { |child| (child == :all) ? ALL : from_hash(child) }.freeze, signature:)
+    end
+    private_class_method :add, :from_hash
+
+    # @return [String, nil] sorted paths of a root selection, for cache keys
+    attr_reader :signature
+
+    # @param children [Hash{String => Selection}, nil] selected keys and their nodes; nil selects everything
+    # @param signature [String, nil] sorted paths of a root selection
+    def initialize(children = nil, signature: nil)
+      @children = children
+      @signature = signature
+      @indexes = Cache.new unless children.nil?
+    end
+
+    # @return [Boolean] true when every key is selected
+    def all?
+      @children.nil?
+    end
+
+    # @param key [String] output key
+    # @return [Boolean] true when the key is selected
+    def selected?(key)
+      all? || @children.key?(key)
+    end
+
+    # @param key [String] output key
+    # @return [Selection] the key's node: ALL for a key selected whole, under ALL, or not selected (a plan only asks
+    #   for keys it renders)
+    def child(key)
+      all? ? ALL : @children.fetch(key, ALL)
+    end
+
+    # @param plan [#steps, #always] plan rendered at this node
+    # @return [Array<Integer>] frozen indexes of the plan's selected and always-emitted steps, memoized per plan
+    def indexes_for(plan)
+      @indexes[plan] || @indexes.fetch(plan) do
+        plan.steps.each_index.select do |index|
+          key = plan.steps[index].key
+          @children.key?(key) || plan.always.include?(key)
+        end.freeze
+      end
+    end
+
+    # Everything selected: today's output
+    ALL = new.freeze
+  end
+end

data/lib/versponse/selection_schema.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Versponse
+  # A validation schema for a selected render: walking the schema with the selection, each object schema at a
+  # selected node requires only the selected keys. Properties stay, so emitted values are still checked.
+  #
+  # Recursive classes are inlined once with an anchor and referenced below it. A reference met under a selection is
+  # replaced by the pruned anchored schema. Pruned copies drop the anchor, and the untouched anchored originals go
+  # under the definitions keyword, so references at fully selected nodes still resolve to the full shape.
+  #
+  # @api private
+  module SelectionSchema
+    # Prefix of the definitions holding the original anchored schemas
+    DEFINITION_PREFIX = "versponse_"
+
+    # @param schema [Hash] validation schema
+    # @param selection [Versponse::Selection] the render's selection
+    # @return [Hash] the pruned copy, or the schema itself for ALL
+    def self.call(schema, selection)
+      return schema if selection.all? || !schema.is_a?(Hash)
+
+      anchors = {}
+      collect_anchors(schema, anchors)
+      pruned = prune(schema, selection, anchors)
+      return pruned if anchors.empty?
+
+      keyword = definitions_keyword
+      pruned.merge(keyword => (pruned[keyword] || {}).merge(anchors.transform_keys { |name| "#{DEFINITION_PREFIX}#{name}" }))
+    end
+
+    # @param schema [Object] (sub)schema
+    # @param selection [Versponse::Selection] node for the instance this schema describes
+    # @param anchors [Hash{String => Hash}] anchored schemas by name
+    # @return [Object] the pruned copy
+    def self.prune(schema, selection, anchors)
+      return schema if selection.all? || !schema.is_a?(Hash)
+
+      target = anchors[ref_name(schema)]
+      return prune(target, selection, anchors) if target
+
+      pruned = schema.except(anchor_keyword)
+      %w[anyOf allOf].each { |keyword| pruned[keyword] = schema[keyword].map { |branch| prune(branch, selection, anchors) } if schema[keyword].is_a?(::Array) }
+      if schema["oneOf"].is_a?(::Array)
+        # Pruned variants can overlap; the render already picked one with match:, so any of them passing is enough
+        pruned.delete("oneOf")
+        pruned["allOf"] = [*pruned["allOf"], {"anyOf" => schema["oneOf"].map { |branch| prune(branch, selection, anchors) }}]
+      end
+      pruned["items"] = prune(schema["items"], selection, anchors) if schema["items"].is_a?(Hash)
+      return pruned unless schema["properties"].is_a?(Hash)
+
+      pruned["properties"] = schema["properties"].to_h do |key, property|
+        [key, selection.selected?(key) ? prune(property, selection.child(key), anchors) : property]
+      end
+      required = schema["required"].select { |key| selection.selected?(key) } if schema["required"].is_a?(::Array)
+      # OpenAPI 3.0 and draft 4 need at least one item in required
+      pruned.delete("required")
+      pruned["required"] = required if required&.any?
+      pruned
+    end
+
+    # @param schema [Object] (sub)schema
+    # @param anchors [Hash{String => Hash}] filled with anchored schemas by name
+    # @return [void]
+    def self.collect_anchors(schema, anchors)
+      case schema
+      when Hash
+        name = anchor_name(schema)
+        anchors[name] = schema if name
+        schema.each_value { |value| collect_anchors(value, anchors) }
+      when ::Array then schema.each { |value| collect_anchors(value, anchors) }
+      end
+    end
+
+    # @return [String] "$anchor", or "$id"/"id" for JSON Schema versions before 2019-09
+    def self.anchor_keyword
+      Versponse.configuration.anchor("x").keys.first
+    end
+
+    # @return [String] "$defs", or "definitions" for JSON Schema versions before 2019-09
+    def self.definitions_keyword
+      (anchor_keyword == "$anchor") ? "$defs" : "definitions"
+    end
+
+    # @param schema [Hash] (sub)schema
+    # @return [String, nil] the name it is anchored under
+    def self.anchor_name(schema)
+      value = schema[anchor_keyword]
+      return unless value.is_a?(String)
+
+      (anchor_keyword == "$anchor") ? value : value.delete_prefix("#")
+    end
+
+    # @param schema [Hash] (sub)schema
+    # @return [String, nil] the anchor a "#Name" $ref points at
+    def self.ref_name(schema)
+      ref = schema["$ref"]
+      ref.delete_prefix("#") if ref.is_a?(String) && ref.start_with?("#") && !ref.start_with?("#/")
+    end
+    private_class_method :prune, :collect_anchors, :anchor_keyword, :definitions_keyword, :anchor_name, :ref_name
+  end
+end

data/lib/versponse/steps/checked.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Steps
+    # Any step whose written value is checked afterwards (nested values, one_of); checks only when the step wrote
+    # its key, which is sound because validating plans have unique keys
+    #
+    # @api private
+    class Checked
+      # @return [String] output key
+      attr_reader :key
+
+      # @param step [#call] wrapped step
+      # @param check [#valid?] checker of the written value
+      def initialize(step, check)
+        @step = step
+        @key = step.key
+        @check = check
+        freeze
+      end
+
+      # @return [Boolean] true when the wrapped step has if:/unless:
+      def conditional?
+        @step.conditional?
+      end
+
+      # @param object [Object] source
+      # @param hash [Boolean] whether the source is a Hash
+      # @param context [Hash] serialize context
+      # @param output [Hash] Hash being built
+      # @param expansion [Versponse::Expansion] expand tree node of the parent
+      # @return [void]
+      def call(object, hash, context, output, expansion)
+        @step.call(object, hash, context, output, expansion)
+        return unless output.key?(@key)
+
+        # The written subtree holds the source's values (a one_of can even write a source String), so it is checked
+        # once the render has finished
+        InlineValidation.check(@check, output[@key], true)
+      end
+    end
+  end
+end

data/lib/versponse/steps/checked_read.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Steps
+    # A plain read that checks the value it writes
+    #
+    # @api private
+    class CheckedRead < Read
+      # @param key [String] output key
+      # @param name [String, Symbol] method or Hash key to read
+      # @param formatter [#call, nil] formatter (used by CheckedReadFormatted)
+      # @param check [#valid?] checker of the property's schema
+      # @param recheck [Boolean] a change in place can break the schema, so a value not frozen all the way down is
+      #   checked after the render (see InlineValidation.check)
+      def initialize(key:, name:, formatter:, check:, recheck:)
+        @check = check
+        @recheck = recheck
+        super(key:, name:, formatter:)
+      end
+
+      # The check is written out here, in CheckedReadFormatted and in CheckedValue, rather than calling
+      # InlineValidation.check: the extra call costs about 25 ns per field under YJIT
+      #
+      # @param object [Object] source
+      # @param hash [Boolean] whether the source is a Hash
+      # @param _context [Hash] unused
+      # @param output [Hash] Hash being built
+      # @param _expansion [Versponse::Expansion] unused
+      # @return [void]
+      def call(object, hash, _context, output, _expansion)
+        value = output[@key] = hash ? object.fetch(@symbol) { object.fetch(@string) } : object.public_send(@symbol)
+        if @recheck && !Ractor.shareable?(value)
+          InlineValidation.recheck_later(@check, value)
+        else
+          # The rescue covers the check only: a check that raises, or defers (UncaughtThrowError outside Root), fails
+          ok = begin
+            @check.valid?(value)
+          rescue
+            false
+          end
+          InlineValidation.failed! unless ok
+        end
+      end
+    end
+  end
+end

data/lib/versponse/steps/checked_read_formatted.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Steps
+    # A formatted read that checks the formatted value it writes
+    #
+    # @api private
+    class CheckedReadFormatted < CheckedRead
+      # @param object [Object] source
+      # @param hash [Boolean] whether the source is a Hash
+      # @param _context [Hash] unused
+      # @param output [Hash] Hash being built
+      # @param _expansion [Versponse::Expansion] unused
+      # @return [void]
+      def call(object, hash, _context, output, _expansion)
+        value = hash ? object.fetch(@symbol) { object.fetch(@string) } : object.public_send(@symbol)
+        value = output[@key] = value.nil? ? nil : @formatter.call(value)
+        if @recheck && !Ractor.shareable?(value)
+          InlineValidation.recheck_later(@check, value)
+        else
+          # The rescue covers the check only: a check that raises, or defers (UncaughtThrowError outside Root), fails
+          ok = begin
+            @check.valid?(value)
+          rescue
+            false
+          end
+          InlineValidation.failed! unless ok
+        end
+      end
+    end
+  end
+end

data/lib/versponse/steps/checked_value.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Steps
+    # A value step that checks the value it writes
+    #
+    # @api private
+    class CheckedValue < Value
+      # @param key [String] output key
+      # @param extractor [#call] value reader
+      # @param condition [Versponse::Condition, nil] if:/unless:
+      # @param formatter [#call, nil] applied to non-nil values
+      # @param check [#valid?] checker of the property's schema
+      # @param recheck [Boolean] a change in place can break the schema, so a value not frozen all the way down is
+      #   checked after the render (see InlineValidation.check)
+      def initialize(key:, extractor:, condition:, formatter:, check:, recheck:)
+        @check = check
+        @recheck = recheck
+        super(key:, extractor:, condition:, formatter:)
+      end
+
+      # @param object [Object] source
+      # @param hash [Boolean] whether the source is a Hash
+      # @param context [Hash] serialize context
+      # @param output [Hash] Hash being built
+      # @param _expansion [Versponse::Expansion] unused
+      # @return [void]
+      def call(object, hash, context, output, _expansion)
+        return if @condition && !@condition.call(object, context)
+
+        value = @extractor.call(object, hash, context)
+        value = @formatter.call(value) if @formatter && !value.nil?
+        output[@key] = value
+        if @recheck && !Ractor.shareable?(value)
+          InlineValidation.recheck_later(@check, value)
+        else
+          # The rescue covers the check only: a check that raises, or defers (UncaughtThrowError outside Root), fails
+          ok = begin
+            @check.valid?(value)
+          rescue
+            false
+          end
+          InlineValidation.failed! unless ok
+        end
+      end
+    end
+  end
+end

data/lib/versponse/steps/const.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Steps
+    # Writes a constant value
+    #
+    # @api private
+    class Const
+      # @return [String] output key
+      attr_reader :key
+      # @return [Object] the frozen constant value (each render copies a Hash or Array)
+      attr_reader :value
+
+      # @param key [String] output key
+      # @param value [Object] constant value
+      # @param condition [Versponse::Condition, nil] if:/unless:
+      def initialize(key:, value:, condition:)
+        @key = key
+        @value = value
+        # A Hash or Array is the caller's to change, so each render gets its own copy
+        @copy = DeepCopy.container?(value)
+        @condition = condition
+        freeze
+      end
+
+      # @return [Boolean] true with if:/unless:
+      def conditional?
+        !@condition.nil?
+      end
+
+      # @param object [Object] source
+      # @param _hash [Boolean] unused
+      # @param context [Hash] serialize context
+      # @param output [Hash] Hash being built
+      # @param _expansion [Versponse::Expansion] unused
+      # @return [void]
+      def call(object, _hash, context, output, _expansion)
+        return if @condition && !@condition.call(object, context)
+
+        output[@key] = @copy ? DeepCopy.call(@value) : @value
+      end
+    end
+  end
+end