jsonstructure 0.5.1

data/lib/jsonstructure/instance_validator.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module JsonStructure
+  # Validates JSON instances against JSON Structure schemas
+  #
+  # This class is thread-safe. Multiple threads can call validate concurrently.
+  class InstanceValidator
+    # Validate an instance against a schema
+    #
+    # This method is thread-safe and can be called from multiple threads concurrently.
+    #
+    # @param instance_json [String] JSON string containing the instance to validate
+    # @param schema_json [String] JSON string containing the schema
+    # @return [ValidationResult] validation result
+    #
+    # @example
+    #   schema = '{"type": "string", "minLength": 1}'
+    #   instance = '"hello"'
+    #   result = JsonStructure::InstanceValidator.validate(instance, schema)
+    #   if result.valid?
+    #     puts "Instance is valid!"
+    #   else
+    #     result.errors.each { |e| puts e.message }
+    #   end
+    def self.validate(instance_json, schema_json)
+      raise ArgumentError, 'instance_json must be a String' unless instance_json.is_a?(String)
+      raise ArgumentError, 'schema_json must be a String' unless schema_json.is_a?(String)
+
+      JsonStructure.validation_started
+      begin
+        result_ptr = ::FFI::MemoryPointer.new(FFI::JSResult.size)
+        FFI.js_result_init(result_ptr)
+
+        FFI.js_validate_instance(instance_json, schema_json, result_ptr)
+        ValidationResult.from_ffi(result_ptr)
+      ensure
+        JsonStructure.validation_completed
+      end
+    end
+
+    # Validate an instance against a schema, raising an exception on failure
+    #
+    # @param instance_json [String] JSON string containing the instance to validate
+    # @param schema_json [String] JSON string containing the schema
+    # @return [ValidationResult] validation result (only if valid)
+    # @raise [InstanceValidationError] if validation fails
+    #
+    # @example
+    #   begin
+    #     result = JsonStructure::InstanceValidator.validate!(instance, schema)
+    #     puts "Instance is valid!"
+    #   rescue JsonStructure::InstanceValidationError => e
+    #     puts "Validation failed: #{e.message}"
+    #   end
+    def self.validate!(instance_json, schema_json)
+      result = validate(instance_json, schema_json)
+      raise InstanceValidationError.new(result) unless result.valid?
+
+      result
+    end
+  end
+
+  # Exception raised when instance validation fails
+  class InstanceValidationError < StandardError
+    attr_reader :result
+
+    def initialize(result)
+      @result = result
+      super(result.to_s)
+    end
+
+    def errors
+      @result.errors
+    end
+  end
+end

data/lib/jsonstructure/schema_validator.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module JsonStructure
+  # Validates JSON Structure schema documents
+  #
+  # This class is thread-safe. Multiple threads can call validate concurrently.
+  class SchemaValidator
+    # Validate a schema string
+    #
+    # This method is thread-safe and can be called from multiple threads concurrently.
+    #
+    # @param schema_json [String] JSON string containing the schema
+    # @return [ValidationResult] validation result
+    #
+    # @example
+    #   schema = '{"type": "string", "minLength": 1}'
+    #   result = JsonStructure::SchemaValidator.validate(schema)
+    #   if result.valid?
+    #     puts "Schema is valid!"
+    #   else
+    #     result.errors.each { |e| puts e.message }
+    #   end
+    def self.validate(schema_json)
+      raise ArgumentError, 'schema_json must be a String' unless schema_json.is_a?(String)
+
+      JsonStructure.validation_started
+      begin
+        result_ptr = ::FFI::MemoryPointer.new(FFI::JSResult.size)
+        FFI.js_result_init(result_ptr)
+
+        FFI.js_validate_schema(schema_json, result_ptr)
+        ValidationResult.from_ffi(result_ptr)
+      ensure
+        JsonStructure.validation_completed
+      end
+    end
+
+    # Validate a schema string, raising an exception on failure
+    #
+    # @param schema_json [String] JSON string containing the schema
+    # @return [ValidationResult] validation result (only if valid)
+    # @raise [SchemaValidationError] if validation fails
+    #
+    # @example
+    #   begin
+    #     JsonStructure::SchemaValidator.validate!(schema)
+    #     puts "Schema is valid!"
+    #   rescue JsonStructure::SchemaValidationError => e
+    #     puts "Validation failed: #{e.message}"
+    #   end
+    def self.validate!(schema_json)
+      result = validate(schema_json)
+      raise SchemaValidationError.new(result) unless result.valid?
+
+      result
+    end
+  end
+
+  # Exception raised when schema validation fails
+  class SchemaValidationError < StandardError
+    attr_reader :result
+
+    def initialize(result)
+      @result = result
+      super(result.to_s)
+    end
+
+    def errors
+      @result.errors
+    end
+  end
+end

data/lib/jsonstructure/validation_result.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module JsonStructure
+  # Represents a validation error
+  class ValidationError
+    attr_reader :code, :severity, :path, :message, :location
+
+    def initialize(code:, severity:, path:, message:, location:)
+      @code = code
+      @severity = severity
+      @path = path
+      @message = message
+      @location = location
+    end
+
+    def error?
+      @severity == FFI::JS_SEVERITY_ERROR
+    end
+
+    def warning?
+      @severity == FFI::JS_SEVERITY_WARNING
+    end
+
+    def info?
+      @severity == FFI::JS_SEVERITY_INFO
+    end
+
+    def to_s
+      if @path && !@path.empty?
+        "#{@message} (at #{@path})"
+      else
+        @message
+      end
+    end
+
+    def inspect
+      "#<#{self.class.name} @severity=#{@severity} @code=#{@code} @message=#{@message.inspect} @path=#{@path.inspect}>"
+    end
+  end
+
+  # Represents the result of a validation operation
+  class ValidationResult
+    attr_reader :errors
+
+    def initialize(valid, errors = [])
+      @valid = valid
+      @errors = errors
+    end
+
+    def valid?
+      @valid
+    end
+
+    def invalid?
+      !@valid
+    end
+
+    def error_messages
+      @errors.select(&:error?).map(&:message)
+    end
+
+    def warning_messages
+      @errors.select(&:warning?).map(&:message)
+    end
+
+    def to_s
+      if valid?
+        'Validation succeeded'
+      else
+        "Validation failed with #{@errors.count} error(s):\n" +
+          @errors.map { |e| "  - #{e}" }.join("\n")
+      end
+    end
+
+    # Creates a ValidationResult from an FFI JSResult struct
+    # @api private
+    def self.from_ffi(result_ptr)
+      result = FFI::JSResult.new(result_ptr)
+      valid = result[:valid]
+
+      errors = result.errors_array.map do |ffi_error|
+        ValidationError.new(
+          code: ffi_error[:code],
+          severity: ffi_error[:severity],
+          path: ffi_error.path_str,
+          message: ffi_error.message_str,
+          location: ffi_error.location_hash
+        )
+      end
+
+      new(valid, errors)
+    ensure
+      FFI.js_result_cleanup(result_ptr) if result_ptr
+    end
+  end
+end

data/lib/jsonstructure/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module JsonStructure
+  # Version of the JSON Structure Ruby SDK
+  VERSION = '0.5.1'
+end

data/lib/jsonstructure.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require 'rbconfig'
+require 'ffi'
+
+require_relative 'jsonstructure/version'
+require_relative 'jsonstructure/binary_installer'
+require_relative 'jsonstructure/ffi'
+require_relative 'jsonstructure/validation_result'
+require_relative 'jsonstructure/schema_validator'
+require_relative 'jsonstructure/instance_validator'
+
+# JSON Structure SDK for Ruby
+#
+# This gem provides Ruby bindings to the JSON Structure C library
+# via FFI (Foreign Function Interface). It allows you to validate
+# JSON Structure schemas and validate JSON instances against schemas.
+#
+# ## Thread Safety
+#
+# This library is thread-safe. Multiple threads can perform validations
+# concurrently without synchronization. The underlying C library uses
+# proper synchronization primitives to protect shared state.
+#
+# @example Schema Validation
+#   schema = '{"type": "string", "minLength": 1}'
+#   result = JsonStructure::SchemaValidator.validate(schema)
+#   puts "Valid!" if result.valid?
+#
+# @example Instance Validation
+#   schema = '{"type": "string"}'
+#   instance = '"hello"'
+#   result = JsonStructure::InstanceValidator.validate(instance, schema)
+#   puts "Valid!" if result.valid?
+#
+# @example Concurrent Validation
+#   threads = 10.times.map do |i|
+#     Thread.new do
+#       result = JsonStructure::SchemaValidator.validate('{"type": "string"}')
+#       puts "Thread #{i}: #{result.valid?}"
+#     end
+#   end
+#   threads.each(&:join)
+#
+# @see SchemaValidator
+# @see InstanceValidator
+# @see ValidationResult
+module JsonStructure
+  class Error < StandardError; end
+
+  # Mutex for protecting cleanup coordination
+  @cleanup_mutex = Mutex.new
+  # Count of active validations (for safe cleanup)
+  @active_validations = 0
+  # Flag to prevent new validations during shutdown
+  @shutting_down = false
+
+  class << self
+    # Track when a validation starts
+    # @api private
+    def validation_started
+      @cleanup_mutex.synchronize do
+        raise Error, 'Library is shutting down' if @shutting_down
+
+        @active_validations += 1
+      end
+    end
+
+    # Track when a validation completes
+    # @api private
+    def validation_completed
+      @cleanup_mutex.synchronize do
+        @active_validations -= 1
+      end
+    end
+
+    # Check if any validations are currently active
+    # @api private
+    def validations_active?
+      @cleanup_mutex.synchronize do
+        @active_validations > 0
+      end
+    end
+
+    # Safely clean up the library, waiting for active validations
+    # @api private
+    def safe_cleanup
+      @cleanup_mutex.synchronize do
+        @shutting_down = true
+      end
+
+      # Wait briefly for active validations to complete (up to 1 second)
+      10.times do
+        break unless validations_active?
+
+        sleep 0.1
+      end
+
+      # Perform cleanup - the C library is thread-safe, so this is safe
+      # even if a validation is somehow still running
+      FFI.js_cleanup
+    end
+  end
+
+  # Initialize the JSON Structure library
+  # This is called automatically when the module is loaded
+  FFI.js_init
+
+  # Clean up the JSON Structure library when Ruby exits
+  # Uses safe_cleanup to coordinate with active validations
+  at_exit do
+    JsonStructure.safe_cleanup
+  end
+end

data/spec/instance_validator_spec.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe JsonStructure::InstanceValidator do
+  describe '.validate' do
+    context 'with valid instance' do
+      it 'validates string against string schema' do
+        schema = '{"type": "string"}'
+        instance = '"hello"'
+        result = described_class.validate(instance, schema)
+
+        expect(result).to be_valid
+        expect(result.errors).to be_empty
+      end
+
+      it 'validates integer against integer schema' do
+        schema = '{"type": "integer"}'
+        instance = '42'
+        result = described_class.validate(instance, schema)
+
+        expect(result).to be_valid
+        expect(result.errors).to be_empty
+      end
+
+      it 'validates object against object schema' do
+        schema = '{"type": "object", "properties": {"name": {"type": "string"}}}'
+        instance = '{"name": "Alice"}'
+        result = described_class.validate(instance, schema)
+
+        expect(result).to be_valid
+        expect(result.errors).to be_empty
+      end
+
+      it 'validates array against array schema' do
+        schema = '{"type": "array", "items": {"type": "integer"}}'
+        instance = '[1, 2, 3]'
+        result = described_class.validate(instance, schema)
+
+        expect(result).to be_valid
+        expect(result.errors).to be_empty
+      end
+    end
+
+    context 'with invalid instance' do
+      it 'rejects wrong type' do
+        schema = '{"type": "string"}'
+        instance = '123'
+        result = described_class.validate(instance, schema)
+
+        expect(result).to be_invalid
+        expect(result.errors).not_to be_empty
+      end
+
+      it 'rejects string too short' do
+        schema = '{"type": "string", "minLength": 5}'
+        instance = '"hi"'
+        result = described_class.validate(instance, schema)
+
+        expect(result).to be_invalid
+        expect(result.errors).not_to be_empty
+      end
+
+      it 'rejects number out of range' do
+        schema = '{"type": "integer", "minimum": 10}'
+        instance = '5'
+        result = described_class.validate(instance, schema)
+
+        expect(result).to be_invalid
+        expect(result.errors).not_to be_empty
+      end
+    end
+
+    context 'error handling' do
+      it 'raises ArgumentError for non-string instance' do
+        schema = '{"type": "string"}'
+
+        expect { described_class.validate(nil, schema) }.to raise_error(ArgumentError)
+        expect { described_class.validate(123, schema) }.to raise_error(ArgumentError)
+      end
+
+      it 'raises ArgumentError for non-string schema' do
+        instance = '"hello"'
+
+        expect { described_class.validate(instance, nil) }.to raise_error(ArgumentError)
+        expect { described_class.validate(instance, 123) }.to raise_error(ArgumentError)
+      end
+    end
+  end
+
+  describe '.validate!' do
+    context 'with valid instance' do
+      it 'returns result without raising' do
+        schema = '{"type": "string"}'
+        instance = '"hello"'
+        result = described_class.validate!(instance, schema)
+
+        expect(result).to be_valid
+      end
+    end
+
+    context 'with invalid instance' do
+      it 'raises InstanceValidationError' do
+        schema = '{"type": "string"}'
+        instance = '123'
+
+        expect { described_class.validate!(instance, schema) }.to raise_error(JsonStructure::InstanceValidationError)
+      end
+
+      it 'includes validation errors in exception' do
+        schema = '{"type": "string"}'
+        instance = '123'
+
+        begin
+          described_class.validate!(instance, schema)
+          raise 'Expected InstanceValidationError to be raised'
+        rescue JsonStructure::InstanceValidationError => e
+          expect(e.errors).not_to be_empty
+          expect(e.result).to be_invalid
+        end
+      end
+    end
+  end
+end

data/spec/schema_validator_spec.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe JsonStructure::SchemaValidator do
+  describe '.validate' do
+    context 'with valid schema' do
+      it 'returns valid result for simple string schema' do
+        schema = '{"type": "string"}'
+        result = described_class.validate(schema)
+
+        expect(result).to be_valid
+        expect(result.error_messages).to be_empty # Only check errors, not warnings
+      end
+
+      it 'returns valid result for object schema' do
+        schema = '{"type": "object", "properties": {"name": {"type": "string"}}}'
+        result = described_class.validate(schema)
+
+        expect(result).to be_valid
+        expect(result.error_messages).to be_empty # Only check errors, not warnings
+      end
+
+      it 'returns valid result for array schema' do
+        schema = '{"type": "array", "items": {"type": "integer"}}'
+        result = described_class.validate(schema)
+
+        expect(result).to be_valid
+        expect(result.error_messages).to be_empty # Only check errors, not warnings
+      end
+    end
+
+    context 'with invalid schema' do
+      it 'returns invalid result for malformed JSON' do
+        schema = '{invalid json}'
+        result = described_class.validate(schema)
+
+        expect(result).to be_invalid
+        expect(result.errors).not_to be_empty
+      end
+
+      it 'returns invalid result for invalid type' do
+        schema = '{"type": "not_a_type"}'
+        result = described_class.validate(schema)
+
+        expect(result).to be_invalid
+        expect(result.errors).not_to be_empty
+      end
+    end
+
+    context 'error handling' do
+      it 'raises ArgumentError for non-string input' do
+        expect { described_class.validate(nil) }.to raise_error(ArgumentError)
+        expect { described_class.validate(123) }.to raise_error(ArgumentError)
+        expect { described_class.validate({}) }.to raise_error(ArgumentError)
+      end
+    end
+  end
+
+  describe '.validate!' do
+    context 'with valid schema' do
+      it 'returns result without raising' do
+        schema = '{"type": "string"}'
+        result = described_class.validate!(schema)
+
+        expect(result).to be_valid
+      end
+    end
+
+    context 'with invalid schema' do
+      it 'raises SchemaValidationError' do
+        schema = '{invalid json}'
+
+        expect { described_class.validate!(schema) }.to raise_error(JsonStructure::SchemaValidationError)
+      end
+
+      it 'includes validation errors in exception' do
+        schema = '{invalid json}'
+
+        begin
+          described_class.validate!(schema)
+          raise 'Expected SchemaValidationError to be raised'
+        rescue JsonStructure::SchemaValidationError => e
+          expect(e.errors).not_to be_empty
+          expect(e.result).to be_invalid
+        end
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'jsonstructure'
+
+RSpec.configure do |config|
+  # Enable flags like --only-failures and --next-failure
+  config.example_status_persistence_file_path = '.rspec_status'
+
+  # Disable RSpec exposing methods globally on `Module` and `main`
+  config.disable_monkey_patching!
+
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+end