servus 0.7.0 → 1.0.0

data/lib/servus/schema/compiler.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module Servus
+  module Schema
+    # Resolves +$ref+ pointers in a schema against the {Servus::Schema} registry,
+    # producing a self-contained schema with no refs left in it.
+    #
+    # One instance per compile. The instance carries the cycle-detection state
+    # and the context label used in error messages; the memo it consults is
+    # process-wide and lives on {Servus::Schema}.
+    #
+    # == Sibling properties
+    #
+    # Keys alongside a +$ref+ override the resolved target:
+    #
+    #   { '$ref' => '#/core/$defs/amount', 'description' => 'Fee charged' }
+    #
+    # This is a template-and-override reading, which is what makes shared
+    # fragments usable in practice — you take the shape and re-describe it for
+    # the site that uses it. Note that it *differs* from JSON Schema 2019-09 and
+    # later, where properties beside a +$ref+ are an additional subschema
+    # applied as an intersection rather than an override.
+    #
+    # Siblings are compiled independently and merged *onto* an already-resolved
+    # target, rather than merged first and resolved after. That ordering is what
+    # makes the target cacheable: the memo holds a value that does not depend on
+    # the call site.
+    #
+    # @see Servus::Schema
+    # @see Servus::Schema::Ref
+    class Compiler
+      # Maximum structural nesting depth before {DepthExceededError} is raised.
+      #
+      # This is a runaway guard for pathological input, not a cycle check —
+      # cycles are caught exactly by {#resolve_ref}'s visited set, however deep
+      # or shallow they are. Keeping the two separate means a legitimately deep
+      # acyclic schema compiles instead of being misreported as circular.
+      MAX_DEPTH = 100
+
+      # Keys stripped from a fragment when it is spliced into another schema.
+      #
+      # +json-schema+ resolves a nested +$schema+ against its registered
+      # validators and raises +JSON::Schema::SchemaError+ when it does not
+      # recognize the URI — at any position in the document, not just the root.
+      # Fragments authored as standalone documents routinely carry these, so
+      # they are dropped on splice rather than left to blow up at validation time.
+      #
+      # @see https://github.com/voxpupuli/json-schema
+      METADATA_KEYS = %w[$schema $id id].freeze
+
+      # @param context [String, nil] label for the schema being compiled, used
+      #   in error messages, e.g. "Treasury::TransferGold::Service arguments schema"
+      def initialize(context: nil)
+        @context = context
+        @path = []
+      end
+
+      # Compiles a schema, replacing every +$ref+ with the fragment it names.
+      #
+      # @param schema [Object] the authored schema
+      # @return [Object] the compiled schema
+      # @raise [Error] if any ref cannot be resolved
+      def compile(schema)
+        resolve(schema, 0)
+      end
+
+      private
+
+      # Recursively resolves a node.
+      #
+      # @param node [Object]
+      # @param depth [Integer] current structural nesting depth
+      # @return [Object]
+      # @api private
+      def resolve(node, depth)
+        raise DepthExceededError, contextualize(depth_message) if depth > MAX_DEPTH
+
+        case node
+        when Hash  then resolve_hash(node, depth)
+        when Array then node.map { |item| resolve(item, depth + 1) }
+        else node
+        end
+      end
+
+      # @param node [Hash]
+      # @param depth [Integer]
+      # @return [Hash]
+      # @api private
+      def resolve_hash(node, depth)
+        return resolve_ref_node(node, depth) if node.key?('$ref') || node.key?(:$ref)
+
+        node.transform_values { |value| resolve(value, depth + 1) }
+      end
+
+      # Resolves a node carrying a +$ref+, merging sibling keys over the target.
+      #
+      # @param node [Hash]
+      # @param depth [Integer]
+      # @return [Hash]
+      # @api private
+      def resolve_ref_node(node, depth)
+        target = resolve_ref(node['$ref'] || node[:$ref])
+        siblings = node.reject { |key, _| key.to_s == '$ref' }
+
+        siblings.empty? ? target : target.merge(resolve_hash(siblings, depth))
+      end
+
+      # Resolves a single ref to its target, guarding against cycles.
+      #
+      # @param value [Object] the raw +$ref+ value
+      # @return [Object] the resolved target
+      # @raise [Error]
+      # @api private
+      def resolve_ref(value)
+        ref = with_context { Ref.parse(value) }
+
+        raise CircularReferenceError, contextualize(circular_message(ref)) if @path.include?(ref.value)
+
+        @path.push(ref.value)
+        begin
+          Schema.cache.resolve(ref.value) { expand(ref) }
+        ensure
+          @path.pop
+        end
+      end
+
+      # Looks a ref's target up in the registry and resolves it in turn.
+      #
+      # @param ref [Ref]
+      # @return [Object]
+      # @api private
+      def expand(ref)
+        target = with_context { Schema.fetch(ref.key, *ref.segments) }
+
+        strip_metadata(resolve(target, 0))
+      end
+
+      # Removes document-level metadata from a spliced fragment.
+      #
+      # @param node [Object]
+      # @return [Object]
+      # @api private
+      def strip_metadata(node)
+        return node unless node.is_a?(Hash)
+        return node unless node.keys.map(&:to_s).intersect?(METADATA_KEYS)
+
+        node.reject { |key, _| METADATA_KEYS.include?(key.to_s) }
+      end
+
+      # Runs a block, re-raising any schema error with this compile's context.
+      #
+      # {Ref} and {Servus::Schema} raise where the problem is detected and know
+      # nothing about which schema or ref chain led there. This attaches that.
+      #
+      # Both call sites wrap a single foreign call rather than the recursion
+      # around it, so an error is decorated exactly once on its way out.
+      #
+      # @yield the work that might raise
+      # @return [Object] the block's value
+      # @api private
+      def with_context
+        yield
+      rescue Error => e
+        raise e.class, contextualize(e.message)
+      end
+
+      # Appends the schema being compiled and the ref chain that led here.
+      #
+      # @param message [String]
+      # @return [String]
+      # @api private
+      def contextualize(message)
+        parts = [message]
+        parts << "while compiling #{@context}" if @context
+        parts << "(resolution path: #{@path.join(' -> ')})" if @path.length > 1
+
+        parts.join("
+  ")
+      end
+
+      # @param ref [Ref]
+      # @return [String]
+      # @api private
+      def circular_message(ref)
+        "circular $ref detected: #{(@path + [ref.value]).join(' -> ')}"
+      end
+
+      # @return [String]
+      # @api private
+      def depth_message
+        "schema nests more than #{MAX_DEPTH} levels deep. This is a runaway guard — " \
+          'if the schema is legitimately this deep, flatten it into registered fragments.'
+      end
+    end
+  end
+end

data/lib/servus/schema/declaration.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Servus
+  module Schema
+    # Provides the +schema+ DSL to a class.
+    #
+    # Extend a class with this and call {#declare_schemas} with the schema
+    # kinds it supports. {Servus::Base} declares +arguments+, +result+, and
+    # +failure+; {Servus::Event} declares +payload+. Each kind gets:
+    #
+    # * a keyword on the generated +schema+ class method
+    # * a reader returning the compiled schema, e.g. +arguments_schema+
+    #
+    # == Compiled on read
+    #
+    # The plain reader compiles, so every consumer — validation, the test
+    # example builders, the +have_schema+ matcher, application code reading a
+    # service's contract — sees resolved +$ref+s without having to know that
+    # compilation exists. Results are memoized per class against
+    # {Servus::Schema.generation}, so registering a changed fragment rebuilds
+    # dependent schemas with no dependency tracking.
+    #
+    # == Inheritance
+    #
+    # Readers walk the ancestor chain, so a subclass of a schema-bearing class
+    # inherits its contract. Without this a subclass silently validates nothing,
+    # which is the failure mode this whole subsystem is built to prevent.
+    #
+    # @see Servus::Base.schema
+    # @see Servus::Event.schema
+    module Declaration
+      # Defines the +schema+ DSL and its readers for the given kinds.
+      #
+      # @param types [Array<Symbol>] the schema kinds this class supports
+      # @return [void]
+      #
+      # @example
+      #   class Servus::Event
+      #     extend Servus::Schema::Declaration
+      #     declare_schemas :payload
+      #   end
+      def declare_schemas(*types)
+        @schema_types = types.freeze
+
+        types.each do |type|
+          define_singleton_method(:"#{type}_schema") { compiled_schema(type) }
+        end
+      end
+
+      # The schema kinds this class supports.
+      #
+      # @return [Array<Symbol>]
+      # @api private
+      def schema_types
+        @schema_types || superclass.schema_types
+      end
+
+      # Declares schemas for this class.
+      #
+      # Omitting a keyword leaves any previously declared schema of that kind
+      # in place. Passing one explicitly as +nil+ raises, rather than quietly
+      # leaving the class unvalidated — a lookup that returns nil is a bug at
+      # the call site, and swallowing it is how contracts silently disappear.
+      #
+      # @param schemas [Hash{Symbol => Hash}] schema kind to JSON Schema
+      # @return [void]
+      # @raise [ArgumentError] on an unknown kind or an explicit nil
+      #
+      # @example
+      #   schema arguments: { type: 'object', required: ['user_id'] }
+      def schema(**schemas)
+        validate_schema_kinds!(schemas.keys)
+
+        schemas.each do |type, value|
+          raise ArgumentError, nil_schema_message(type) if value.nil?
+
+          instance_variable_set(:"@raw_#{type}_schema", value.with_indifferent_access)
+        end
+
+        @compiled_schemas = nil
+      end
+
+      private
+
+      # @param types [Array<Symbol>]
+      # @return [void]
+      # @raise [ArgumentError]
+      # @api private
+      def validate_schema_kinds!(types)
+        unknown = types - schema_types
+        return if unknown.empty?
+
+        raise ArgumentError,
+              "unknown schema #{'kind'.pluralize(unknown.size)} #{unknown.map(&:inspect).join(', ')} " \
+              "for #{name}. Valid: #{schema_types.map(&:inspect).join(', ')}."
+      end
+
+      # @param type [Symbol]
+      # @return [String]
+      # @api private
+      def nil_schema_message(type)
+        "#{name} declared a nil #{type} schema. Pass a Hash, or omit the keyword entirely — " \
+          'an explicit nil is usually a lookup that failed, and accepting it would leave this ' \
+          'class silently unvalidated.'
+      end
+
+      # The schema as authored, from this class or the nearest ancestor.
+      #
+      # @param type [Symbol]
+      # @return [Hash, nil]
+      # @api private
+      def raw_schema(type)
+        klass = self
+
+        while klass.respond_to?(:raw_schema, true)
+          declared = klass.instance_variable_get(:"@raw_#{type}_schema")
+          return declared if declared
+
+          klass = klass.superclass
+        end
+
+        nil
+      end
+
+      # The compiled schema, memoized against the registry generation.
+      #
+      # @param type [Symbol]
+      # @return [Hash, nil]
+      # @raise [Servus::Schema::Error] if a ref cannot be resolved
+      # @api private
+      def compiled_schema(type)
+        generation = Schema.generation
+        @compiled_schemas = nil unless @compiled_generation == generation
+        @compiled_generation = generation
+        @compiled_schemas ||= {}
+
+        return @compiled_schemas[type] if @compiled_schemas.key?(type)
+
+        compiled = Schema.compile(raw_schema(type), context: "#{name} #{type} schema")
+
+        # Compilation rebuilds hashes as it walks, so the indifferent access
+        # applied at declaration does not survive it. Readers are public API;
+        # restore it rather than making callers know which keys are strings.
+        @compiled_schemas[type] = compiled&.with_indifferent_access
+      end
+    end
+  end
+end

data/lib/servus/schema/errors.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Servus
+  module Schema
+    # Base class for every schema registry and compilation error.
+    #
+    # These deliberately do *not* inherit from {Servus::Support::Errors::ServiceError}.
+    # Everything in that hierarchy carries an +#http_status+ and an +#api_error+
+    # because it describes a business outcome a caller might render. A malformed
+    # +$ref+ or an unregistered fragment key is a programming error in the schema
+    # itself — there is no sensible HTTP status for it, and rescuing it would
+    # reintroduce exactly the silent non-validation this design exists to prevent.
+    #
+    # @see Servus::Schema
+    # @see Servus::Schema::Compiler
+    class Error < StandardError; end
+
+    # Raised when a +$ref+ names a fragment key that is not registered.
+    #
+    # This is the error the whole registry design exists to produce. A lookup
+    # that returned nil instead would let a service that appears to declare a
+    # contract run with no validation at all, indefinitely and silently.
+    class UnknownKeyError < Error
+      # Builds the error for a missed lookup, suggesting the nearest key.
+      #
+      # @param key [String] the key that was not found
+      # @param available [Array<String>] currently registered keys
+      # @return [UnknownKeyError]
+      def self.for(key, available:)
+        return new(nothing_registered(key)) if available.empty?
+
+        new("unknown schema key #{key.inspect}.#{suggestion(key, available)}")
+      end
+
+      # @param key [String]
+      # @return [String]
+      # @api private
+      def self.nothing_registered(key)
+        "unknown schema key #{key.inspect}: no schema fragments are registered. " \
+          'Register one with Servus::Schema.register(key, fragment).'
+      end
+
+      # @param key [String]
+      # @param available [Array<String>]
+      # @return [String] a " Did you mean: ..." clause, or an empty string
+      # @api private
+      def self.suggestion(key, available)
+        matches = DidYouMean::SpellChecker.new(dictionary: available).correct(key)
+        return '' if matches.empty?
+
+        " Did you mean: #{matches.map(&:inspect).join(', ')}?"
+      end
+
+      private_class_method :nothing_registered, :suggestion
+    end
+
+    # Raised when a +$ref+ names a registered key but the path within it is absent.
+    class RefNotFoundError < Error; end
+
+    # Raised when a +$ref+ value is not a supported ref form.
+    class InvalidRefError < Error; end
+
+    # Raised when a key passed to {Servus::Schema.register} cannot be referenced.
+    class InvalidKeyError < Error; end
+
+    # Raised when refs form a cycle.
+    class CircularReferenceError < Error; end
+
+    # Raised when a schema nests more deeply than {Servus::Schema::Compiler::MAX_DEPTH}.
+    #
+    # Distinct from {CircularReferenceError} on purpose: a deep but acyclic
+    # schema is a different problem from a cycle, and conflating them is what
+    # makes depth-counter-only implementations reject valid schemas.
+    class DepthExceededError < Error; end
+  end
+end

data/lib/servus/schema/path.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Servus
+  module Schema
+    # Walks a path of literal keys into a registered schema fragment.
+    #
+    # This is the single addressing implementation behind both
+    # {Servus::Schema.fetch} and +$ref+ resolution, so a path that misses reads
+    # the same whether application code asked for it directly or a ref led there.
+    #
+    # Segments are literal hash keys, not JSON Pointer tokens — there is no
+    # +~0+/+~1+ unescaping and no array indexing.
+    #
+    # @see Servus::Schema.fetch
+    # @see Servus::Schema::Ref
+    # @api private
+    module Path
+      class << self
+        # Walks +path+ into +fragment+.
+        #
+        # @param fragment [Hash] the registered fragment
+        # @param key [String] the fragment key, for the error message
+        # @param path [Array<String>] segments to walk
+        # @return [Object] the value at the path, or the fragment if path is empty
+        # @raise [RefNotFoundError] if a segment is not present
+        def walk(fragment, key, path)
+          path.reduce(fragment) do |current, segment|
+            unless current.is_a?(Hash) && current.key?(segment)
+              raise RefNotFoundError, message_for(key, path, segment, current)
+            end
+
+            current[segment]
+          end
+        end
+
+        private
+
+        # @param key [String] the fragment key
+        # @param path [Array<String>] the full path being walked
+        # @param segment [String] the segment that was not found
+        # @param current [Object] the node the walk failed at
+        # @return [String]
+        # @api private
+        def message_for(key, path, segment, current)
+          "#{path.join('/').inspect} could not be resolved in schema fragment #{key.inspect}: " \
+            "#{segment.inspect} is not present.#{available_in(current)}"
+        end
+
+        # @param current [Object] the node the walk failed at
+        # @return [String] a clause describing what was there instead
+        # @api private
+        def available_in(current)
+          return " #{current.class} is not a Hash, so it has no keys to walk into." unless current.is_a?(Hash)
+
+          " Available keys: #{current.keys.map(&:to_s).sort.map(&:inspect).join(', ')}."
+        end
+      end
+    end
+  end
+end

data/lib/servus/schema/ref.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Servus
+  module Schema
+    # A parsed +$ref+ pointing at a registered schema fragment.
+    #
+    # Servus supports exactly two ref forms:
+    #
+    #   #/core                  # the whole fragment registered as "core"
+    #   #/core/$defs/amount     # a path walked within it
+    #
+    # Segments are literal hash keys, not JSON Pointer tokens — there is no
+    # +~0+/+~1+ unescaping and no array indexing. +$defs+ carries no special
+    # meaning; it is a conventional place to put definitions, and any key works.
+    #
+    # Everything else is rejected by {parse} with a message that names what was
+    # wrong. That matters most for local refs: +#/$defs/amount+ would otherwise
+    # parse as a request for a fragment registered under the key +$defs+ and
+    # fail as a confusing lookup miss rather than as the unsupported form it is.
+    #
+    # @see Servus::Schema::Compiler
+    class Ref
+      # Ref forms Servus does not implement, paired with the reason.
+      #
+      # Checked in order; the first match raises {InvalidRefError}.
+      #
+      # @api private
+      REJECTIONS = [
+        [
+          ->(value) { !value.start_with?('#/') },
+          'Servus resolves refs against registered schema fragments, which always take the form ' \
+          '"#/<key>" or "#/<key>/<path>". Remote and file refs are not supported.'
+        ],
+        [
+          ->(value) { value == '#/' },
+          'it names no schema fragment key.'
+        ],
+        [
+          ->(value) { value.delete_prefix('#/').start_with?('$') },
+          'it looks like a local ref. Refs resolve against registered fragments, not against the ' \
+          'enclosing document. Register the shared definition as a fragment and reference it as ' \
+          '"#/<key>/...".'
+        ]
+      ].freeze
+
+      # The original ref string.
+      #
+      # @return [String]
+      attr_reader :value
+
+      # The registry key the ref names.
+      #
+      # @return [String]
+      attr_reader :key
+
+      # Path segments to walk within the fragment. Empty for a whole-fragment ref.
+      #
+      # @return [Array<String>]
+      attr_reader :segments
+
+      # Parses a +$ref+ value.
+      #
+      # @param value [Object] the raw +$ref+ value from a schema
+      # @return [Ref]
+      # @raise [InvalidRefError] if the value is not a supported ref form
+      #
+      # @example
+      #   Servus::Schema::Ref.parse('#/core/$defs/amount').key  # => "core"
+      def self.parse(value)
+        raise InvalidRefError, "$ref must be a String, got #{value.class}: #{value.inspect}" unless value.is_a?(String)
+
+        _, explanation = REJECTIONS.find { |rejects, _| rejects.call(value) }
+
+        raise InvalidRefError, "#{value.inspect} is not a supported $ref — #{explanation}" if explanation
+
+        new(value)
+      end
+
+      # @param value [String] a ref string already known to be well-formed
+      # @api private
+      def initialize(value)
+        @value = value
+        @key, *@segments = value.delete_prefix('#/').split('/')
+      end
+    end
+  end
+end