schemurai 3.1.0-aarch64-linux-gnu

data/lib/schemurai.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+require_relative "schemurai/version"
+require_relative "schemurai/backend"
+require_relative "schemurai/formats"
+require_relative "schemurai/schema_graph"
+require_relative "schemurai/evaluator"
+
+# Public API for compiling and evaluating JSON Schemas.
+module Schemurai
+  # Base class for errors raised by Schemurai.
+  class Error < StandardError; end
+
+  require_relative "schemurai/limited_evaluator"
+
+  # Raised when a schema or URI cannot be resolved from a registry.
+  class ResolutionError < Error; end
+
+  # Raised when a schema requires a format assertion Schemurai does not support.
+  class UnsupportedFormatError < Error; end
+
+  # Raised when a schema does not conform to its declared meta-schema.
+  class InvalidSchemaError < Error
+    # The detailed meta-schema validation result.
+    attr_reader :result
+
+    def initialize(result)
+      @result = result
+      first_error = result.errors.first
+      message = if first_error
+        "invalid schema at #{first_error.instance_path.inspect}: #{first_error.message}"
+      else
+        "invalid schema"
+      end
+      super(message)
+    end
+  end
+
+  # Public value type describing one failed JSON Schema assertion.
+  #
+  # +keyword+ identifies the failed keyword. +instance_path+ and +schema_path+
+  # are JSON Pointers; an empty string points to the root instance or schema.
+  # +message+ is a human-readable String. Its presence and type are public API,
+  # but its exact wording is not. Use +keyword+ and the paths for programmatic
+  # error handling.
+  class ValidationError < Data.define(:keyword, :instance_path, :schema_path, :message)
+    # Returns the error fields as a Hash.
+    def to_h
+      {keyword: keyword, instance_path: instance_path, schema_path: schema_path, message: message}
+    end
+  end
+
+  # The detailed result of validating one instance.
+  class Result
+    # The frozen array of ValidationError objects. It is empty when validation
+    # succeeds.
+    attr_reader :errors
+
+    # Creates a result from an array of ValidationError objects.
+    def initialize(errors)
+      @errors = errors.freeze
+    end
+
+    # Returns whether the instance passed validation.
+    def valid?
+      errors.empty?
+    end
+
+    alias_method :success?, :valid?
+  end
+
+  # Compiles schemas that share registered external schemas and backend state.
+  #
+  # Register every external schema with +schemas:+ before compiling. A registry
+  # can be made shareable once registration and compilation are complete.
+  class SchemaRegistry
+    # The selected backend, +:ruby+, +:vm+, or +:native+.
+    attr_reader :backend
+
+    # Creates a registry.
+    #
+    # +schemas+ maps absolute URI strings to JSON-shaped Ruby schemas. Pass
+    # +validate_schema: true+ to validate every registered and compiled schema
+    # against its meta-schema. +backend+ accepts +:ruby+, +:vm+, +:native+, or +:default+.
+    def initialize(schemas: {}, validate_schema: false, backend: Backend.requested)
+      @backend = Backend.resolve(backend)
+      @validate_schema = validate_schema
+      @graph = Internal::SchemaGraph.new(schemas: schemas)
+      @compiler = VM::Compiler.new(@graph) if %i[vm native].include?(@backend)
+      schemas.each_value { |schema| validate_schema!(schema) } if validate_schema?
+    end
+
+    # Returns whether this registry validates every schema against its meta-schema.
+    def validate_schema?
+      @validate_schema
+    end
+
+    # Compiles +schema+ and returns a Validator.
+    #
+    # +base_uri+ supplies the schema's base URI. Pass +content: true+ or
+    # +format: true+ to enable the corresponding optional assertions. +max_errors:+ and +timeout:+
+    # configure per-call validation caps; schema compilation is not bounded.
+    def compile(schema, base_uri: nil, content: false, format: false, max_errors: nil, timeout: nil)
+      raise Error, "cannot compile schemas after the registry is made shareable" if shareable?
+
+      validate_schema!(schema) if validate_schema?
+      root = @graph.compile(schema, base_uri: base_uri)
+      build_validator(root, content: content, format: format, max_errors: max_errors, timeout: timeout)
+    end
+
+    # Validates +schema+ against its declared meta-schema and returns a Result.
+    # Schemas without +$schema+ are validated as Draft 7.
+    def validate_schema(schema, max_errors: nil, timeout: nil)
+      raise Error, "cannot validate schemas after the registry is made shareable" if shareable?
+
+      root = @graph.meta_schema_root(schema)
+      build_validator(root, content: false, format: false, max_errors: max_errors, timeout: timeout).validate(schema)
+    end
+
+    # Returns whether +schema+ conforms to its declared meta-schema.
+    def valid_schema?(schema, max_errors: nil, timeout: nil)
+      raise Error, "cannot validate schemas after the registry is made shareable" if shareable?
+
+      root = @graph.meta_schema_root(schema)
+      build_validator(root, content: false, format: false, max_errors: max_errors, timeout: timeout).valid?(schema)
+    end
+
+    # Resolves and freezes registered schemas, then makes the registry Ractor-shareable.
+    #
+    # Returns +self+. No more schemas can be compiled after this transition.
+    def make_shareable
+      return self if shareable?
+
+      @graph.make_shareable
+      @compiler&.compile_all
+      if @backend == :native
+        programs = @graph.nodes.map { |node| @compiler.compile(node) }
+        # Build every option variant before the registry becomes immutable.
+        @native_programs = [false, true].product([false, true]).to_h do |format, content|
+          [[format, content], Native::Program.new(programs, @compiler, format, content).make_shareable]
+        end
+      end
+      Ractor.make_shareable(self)
+    end
+
+    # Returns whether this registry is Ractor-shareable.
+    def shareable?
+      Ractor.shareable?(self)
+    end
+
+    # Returns a Validator for the registered resource at +uri+.
+    #
+    # The registry must first be made shareable with #make_shareable.
+    def validator_for(uri, content: false, format: false, max_errors: nil, timeout: nil)
+      raise Error, "make_shareable must be called before retrieving validators by URI" unless shareable?
+
+      root = @graph.node_at(uri)
+      raise ResolutionError, "unregistered schema URI #{uri.inspect}" unless root
+
+      build_validator(root, content: content, format: format, max_errors: max_errors, timeout: timeout)
+    end
+
+    private def build_validator(root, content:, format:, max_errors: nil, timeout: nil)
+      evaluator = if @compiler
+        program = @compiler.compile(root)
+        evaluator_class = (@backend == :native) ? Native::Evaluator : VM::Evaluator
+        if @native_programs
+          compiled = @native_programs.fetch([!!format, !!content])
+          Native::Evaluator.new(@graph, @compiler, program, content: content, format: format, compiled: compiled)
+        else
+          evaluator_class.new(@graph, @compiler, program, content: content, format: format)
+        end
+      else
+        Internal::Evaluator.new(@graph, root, content: content, format: format)
+      end
+      bounded_evaluator = lambda do
+        case @backend
+        when :native then evaluator
+        when :vm then VM::LimitedEvaluator.new(@graph, @compiler, program, content: content, format: format)
+        else Internal::LimitedEvaluator.new(@graph, root, content: content, format: format)
+        end
+      end
+      Validator.new(evaluator, max_errors: max_errors, timeout: timeout, bounded_evaluator: bounded_evaluator)
+    end
+
+    private def validate_schema!(schema)
+      result = validate_schema(schema)
+      raise InvalidSchemaError, result unless result.valid?
+    end
+  end
+
+  # A reusable compiled JSON Schema validator.
+  #
+  # Create validators through Schemurai.compile or SchemaRegistry#compile.
+  # Validator instances contain mutable evaluation state and must not be used
+  # concurrently or shared between Ractors.
+  class Validator
+    # Wraps an evaluator implementation.
+    #
+    # Applications should normally create validators through Schemurai.compile
+    # or SchemaRegistry#compile.
+    def initialize(evaluator, max_errors: nil, timeout: nil, bounded_evaluator: nil)
+      @evaluator = evaluator
+      Internal::LimitBudget.validate_options!(max_errors, timeout)
+      @max_errors = max_errors
+      @timeout = timeout
+      @bounded_evaluator = bounded_evaluator
+    end
+
+    # The backend reported by the evaluator, +:ruby+, +:vm+, or +:native+.
+    def backend
+      @evaluator.backend
+    end
+
+    # Validates +instance+ and returns a Result containing all reported errors.
+    # +max_errors:+ and +timeout:+ override compiled defaults. Raises LimitExceeded when evaluation
+    # cannot complete; no partial Result is returned.
+    def validate(instance, max_errors: @max_errors, timeout: @timeout)
+      Internal::LimitBudget.validate_options!(max_errors, timeout)
+      return @evaluator.validate(instance) if max_errors.nil? && timeout.nil?
+
+      limited_evaluator.validate(instance, max_errors: max_errors, timeout: timeout)
+    end
+
+    # Returns whether +instance+ is valid without building a detailed error list.
+    # The timeout applies; the diagnostic count limit is ignored.
+    def valid?(instance, max_errors: @max_errors, timeout: @timeout)
+      Internal::LimitBudget.validate_options!(max_errors, timeout)
+      return @evaluator.valid?(instance) if timeout.nil?
+
+      limited_evaluator.valid?(instance, timeout: timeout)
+    end
+
+    private def limited_evaluator
+      raise ArgumentError, "this manually constructed Validator has no bounded evaluator" unless @bounded_evaluator
+
+      @bounded_evaluator.call
+    end
+  end
+
+  # Returns the backend selected by SCHEMURAI_BACKEND, +:ruby+, +:vm+, or +:native+.
+  module_function def backend
+    Backend.resolve
+  end
+
+  # Compiles +schema+ and returns a reusable Validator.
+  #
+  # +schemas+ maps external URI strings to schemas. +base_uri+ supplies the
+  # schema's base URI. Optional content and format assertions are disabled by
+  # default. +backend+ accepts +:ruby+, +:vm+, +:native+, or +:default+.
+  module_function def compile(schema, schemas: {}, base_uri: nil, content: false, format: false, validate_schema: false, backend: Backend.requested, max_errors: nil, timeout: nil)
+    SchemaRegistry.new(schemas: schemas, validate_schema: validate_schema, backend: backend).compile(
+      schema,
+      base_uri: base_uri,
+      content: content,
+      format: format,
+      max_errors: max_errors, timeout: timeout
+    )
+  end
+
+  # Validates +schema+ against its declared meta-schema and returns a Result.
+  # Schemas without +$schema+ are validated as Draft 7.
+  module_function def validate_schema(schema, schemas: {}, backend: Backend.requested, max_errors: nil, timeout: nil)
+    SchemaRegistry.new(schemas: schemas, backend: backend).validate_schema(schema, max_errors: max_errors, timeout: timeout)
+  end
+
+  # Returns whether +schema+ conforms to its declared meta-schema.
+  module_function def valid_schema?(schema, schemas: {}, backend: Backend.requested, max_errors: nil, timeout: nil)
+    SchemaRegistry.new(schemas: schemas, backend: backend).valid_schema?(schema, max_errors: max_errors, timeout: timeout)
+  end
+
+  # Validates +instance+ against +schema+ and returns a Result.
+  #
+  # This convenience method compiles the schema for each call. Use .compile
+  # when validating multiple instances against the same schema.
+  module_function def validate(schema, instance, schemas: {}, base_uri: nil, content: false, format: false, validate_schema: false, backend: Backend.requested, max_errors: nil, timeout: nil)
+    compile(
+      schema,
+      schemas: schemas,
+      base_uri: base_uri,
+      content: content,
+      format: format,
+      validate_schema: validate_schema,
+      backend: backend,
+      max_errors: max_errors, timeout: timeout
+    ).validate(instance)
+  end
+
+  # Returns whether +instance+ is valid against +schema+.
+  #
+  # This convenience method compiles the schema for each call. Use .compile
+  # when validating multiple instances against the same schema.
+  module_function def valid?(schema, instance, schemas: {}, base_uri: nil, content: false, format: false, validate_schema: false, backend: Backend.requested, max_errors: nil, timeout: nil)
+    compile(
+      schema,
+      schemas: schemas,
+      base_uri: base_uri,
+      content: content,
+      format: format,
+      validate_schema: validate_schema,
+      backend: backend,
+      max_errors: max_errors, timeout: timeout
+    ).valid?(instance)
+  end
+
+  private_constant :Backend
+end

data/lib/schemurai_native.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Installed as lib/schemurai_native.rb in binary gems only.
+require_relative "schemurai/native/#{RUBY_VERSION.split(".").first(2).join(".")}/schemurai_native"

data/sig/schemurai.rbs

@@ -0,0 +1,108 @@
+module Schemurai
+  # A JSON-shaped Ruby value accepted as a schema value or validation instance.
+  type json_value = nil | bool | Integer | Float | String | Array[json_value] | Hash[String, json_value]
+
+  # A JSON Schema root.
+  type schema = bool | Hash[String, json_value]
+
+  # External schemas indexed by their absolute URI.
+  type schemas = Hash[String, schema]
+
+  # A resolved evaluator backend.
+  type backend = :ruby | :vm | :native
+
+  # A backend accepted when configuring a validator.
+  type backend_selection = backend | :default
+
+  VERSION: String
+
+  class Error < StandardError
+  end
+
+  class LimitExceeded < Error
+    attr_reader limit: Symbol
+    attr_reader maximum: Integer | Float
+    attr_reader attempted: Integer | Float
+
+    def initialize: (Symbol limit, Integer | Float maximum, Integer | Float attempted) -> void
+  end
+
+  class ResolutionError < Error
+  end
+
+  class UnsupportedFormatError < Error
+  end
+
+  class InvalidSchemaError < Error
+    attr_reader result: Result
+
+    def initialize: (Result result) -> void
+  end
+
+  class ValidationError < Data
+    attr_reader keyword: String
+    attr_reader instance_path: String
+    attr_reader schema_path: String
+    attr_reader message: String
+
+    def self.new: (String keyword, String instance_path, String schema_path, String message) -> ValidationError
+                | (keyword: String, instance_path: String, schema_path: String, message: String) -> ValidationError
+
+    def self.[]: (String keyword, String instance_path, String schema_path, String message) -> ValidationError
+               | (keyword: String, instance_path: String, schema_path: String, message: String) -> ValidationError
+
+    def to_h: () -> { keyword: String, instance_path: String, schema_path: String, message: String }
+  end
+
+  class Result
+    attr_reader errors: Array[ValidationError]
+
+    def initialize: (Array[ValidationError] errors) -> void
+    def valid?: () -> bool
+    alias success? valid?
+  end
+
+  interface _Evaluator
+    def backend: () -> backend
+
+    def validate: (json_value instance) -> Result
+
+    def valid?: (json_value instance) -> bool
+  end
+
+  class Validator
+    def initialize: (_Evaluator evaluator, ?max_errors: Integer?, ?timeout: (Integer | Float)?, ?bounded_evaluator: (^() -> untyped)?) -> void
+    def backend: () -> backend
+    def validate: (json_value instance, ?max_errors: Integer?, ?timeout: (Integer | Float)?) -> Result
+    def valid?: (json_value instance, ?max_errors: Integer?, ?timeout: (Integer | Float)?) -> bool
+  end
+
+  class SchemaRegistry
+    attr_reader backend: backend
+
+    def initialize: (?schemas: schemas, ?validate_schema: bool, ?backend: backend_selection) -> void
+
+    def validate_schema?: () -> bool
+
+    def compile: (schema schema, ?base_uri: String?, ?content: bool, ?format: bool, ?max_errors: Integer?, ?timeout: (Integer | Float)?) -> Validator
+
+    def validate_schema: (schema schema, ?max_errors: Integer?, ?timeout: (Integer | Float)?) -> Result
+    def valid_schema?: (schema schema, ?max_errors: Integer?, ?timeout: (Integer | Float)?) -> bool
+    def make_shareable: () -> self
+    def shareable?: () -> bool
+
+    def validator_for: (String uri, ?content: bool, ?format: bool, ?max_errors: Integer?, ?timeout: (Integer | Float)?) -> Validator
+  end
+
+  def self.backend: () -> backend
+
+  def self.compile: (schema schema, ?schemas: schemas, ?base_uri: String?, ?content: bool, ?format: bool, ?validate_schema: bool, ?backend: backend_selection, ?max_errors: Integer?, ?timeout: (Integer | Float)?) -> Validator
+
+  def self.validate_schema: (schema schema, ?schemas: schemas, ?backend: backend_selection, ?max_errors: Integer?, ?timeout: (Integer | Float)?) -> Result
+
+  def self.valid_schema?: (schema schema, ?schemas: schemas, ?backend: backend_selection, ?max_errors: Integer?, ?timeout: (Integer | Float)?) -> bool
+
+  def self.validate: (schema schema, json_value instance, ?schemas: schemas, ?base_uri: String?, ?content: bool, ?format: bool, ?validate_schema: bool, ?backend: backend_selection, ?max_errors: Integer?, ?timeout: (Integer | Float)?) -> Result
+
+  def self.valid?: (schema schema, json_value instance, ?schemas: schemas, ?base_uri: String?, ?content: bool, ?format: bool, ?validate_schema: bool, ?backend: backend_selection, ?max_errors: Integer?, ?timeout: (Integer | Float)?) -> bool
+end

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification
+name: schemurai
+version: !ruby/object:Gem::Version
+  version: 3.1.0
+platform: aarch64-linux-gnu
+authors:
+- Kuya KOHARA (oakcask)
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Validates Ruby values against JSON Schema Draft 7, 2019-09, and 2020-12
+  schemas.
+email:
+- kuya.kohara@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE
+- README.md
+files:
+- LICENSE
+- README.md
+- lib/schemurai.rb
+- lib/schemurai/backend.rb
+- lib/schemurai/container_checks.rb
+- lib/schemurai/container_checks/array_diagnostics.rb
+- lib/schemurai/container_checks/object_diagnostics.rb
+- lib/schemurai/decimal.rb
+- lib/schemurai/dialect.rb
+- lib/schemurai/dialect_keywords.rb
+- lib/schemurai/dialects/draft2019_09.rb
+- lib/schemurai/dialects/draft2020_12.rb
+- lib/schemurai/dialects/draft7.rb
+- lib/schemurai/ecma_regexp.rb
+- lib/schemurai/error_message.rb
+- lib/schemurai/evaluation.rb
+- lib/schemurai/evaluation_limits.rb
+- lib/schemurai/evaluation_pool.rb
+- lib/schemurai/evaluator.rb
+- lib/schemurai/formats.rb
+- lib/schemurai/json_pointer.rb
+- lib/schemurai/limit_budget.rb
+- lib/schemurai/limit_exceeded.rb
+- lib/schemurai/limited_evaluator.rb
+- lib/schemurai/meta_schemas.rb
+- lib/schemurai/meta_schemas/draft2019_09.rb
+- lib/schemurai/meta_schemas/draft2020_12.rb
+- lib/schemurai/meta_schemas/draft7.rb
+- lib/schemurai/native/4.0/schemurai_native.so
+- lib/schemurai/native/diagnostics.rb
+- lib/schemurai/native/evaluator.rb
+- lib/schemurai/native/null_numeric.rb
+- lib/schemurai/number_checks.rb
+- lib/schemurai/schema_domain.rb
+- lib/schemurai/schema_graph.rb
+- lib/schemurai/schema_node.rb
+- lib/schemurai/string_checks.rb
+- lib/schemurai/type_checks.rb
+- lib/schemurai/unique_items.rb
+- lib/schemurai/value_equality.rb
+- lib/schemurai/version.rb
+- lib/schemurai/vm/compiler.rb
+- lib/schemurai/vm/evaluator.rb
+- lib/schemurai/vm/limited_evaluator.rb
+- lib/schemurai_native.rb
+- sig/schemurai.rbs
+homepage: https://github.com/oakcask/schemurai
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/oakcask/schemurai
+  source_code_uri: https://github.com/oakcask/schemurai/tree/main
+  documentation_uri: https://rubydoc.info/gems/schemurai/3.1.0
+  rubygems_mfa_required: 'true'
+rdoc_options:
+- "--main"
+- README.md
+- "--title"
+- Schemurai API Documentation
+- "--visibility"
+- public
+- "--exclude"
+- lib/schemurai/(?!(?:version|limit_exceeded)\.rb)
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: A fast, Ractor-safe JSON Schema Draft 7+ validator
+test_files: []