jsonstructure 0.5.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: db9b0251a2324184e370f6adc96d369922448d7aea9b25f5635667a49bfe48f4
+  data.tar.gz: 4eb4c28ec727433e9b7d6f9e255d805c34ec68d7cfa2c01409bb856bf29386a1
+SHA512:
+  metadata.gz: 043a453dbb8f2b6fad129f4201001718c9a85b9c9d4268aa573bb7d04a675c6958750778eb9aa80b53c9b631c0f627ef915251144ab9f984225e6ac6d422eb5a
+  data.tar.gz: dce72087731cb806299e9bb4dd9f958a035e47c6eb996b50a10f470e87e091504d7f536195ef8b61f27ee66958fdec0a08b5f3d36819868d29bad557fec5c427

data/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in jsonstructure.gemspec
+gemspec
+
+group :development, :test do
+  gem 'rake', '~> 13.0'
+  gem 'rspec', '~> 3.0'
+  gem 'rubocop', '~> 1.50'
+end

data/README.md

@@ -0,0 +1,252 @@
+# JSON Structure Ruby SDK
+
+Ruby SDK for JSON Structure schema validation using FFI bindings to the C library.
+
+## Features
+
+- **Schema validation** - Validate JSON Structure schema documents
+- **Instance validation** - Validate JSON instances against schemas
+- **High performance** - FFI bindings to native C library
+- **Idiomatic Ruby API** - Wrapped in clean, Ruby-friendly classes
+- **Cross-platform** - Works on Linux, macOS, and Windows
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'jsonstructure'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install jsonstructure
+```
+
+### Binary Distribution
+
+**The gem automatically downloads pre-built C library binaries from GitHub releases.** No compilation is required during installation.
+
+Supported platforms:
+- Linux (x86_64, arm64)
+- macOS (x86_64, arm64)
+- Windows (x86_64)
+
+If you're developing the gem itself or contributing, see the Development section below for building from source.
+
+## Usage
+
+### Schema Validation
+
+```ruby
+require 'jsonstructure'
+
+schema = '{"type": "string", "minLength": 1}'
+result = JsonStructure::SchemaValidator.validate(schema)
+
+if result.valid?
+  puts "Schema is valid!"
+else
+  result.errors.each do |error|
+    puts "Error: #{error.message}"
+  end
+end
+```
+
+### Instance Validation
+
+```ruby
+require 'jsonstructure'
+
+schema = '{"type": "string", "minLength": 1}'
+instance = '"hello"'
+
+result = JsonStructure::InstanceValidator.validate(instance, schema)
+
+if result.valid?
+  puts "Instance is valid!"
+else
+  result.errors.each do |error|
+    puts "Error: #{error.message}"
+    puts "  Path: #{error.path}" if error.path
+  end
+end
+```
+
+### Using Exceptions
+
+Both validators provide a `validate!` method that raises an exception on validation failure:
+
+```ruby
+require 'jsonstructure'
+
+begin
+  schema = '{"type": "string"}'
+  JsonStructure::SchemaValidator.validate!(schema)
+  puts "Schema is valid!"
+rescue JsonStructure::SchemaValidationError => e
+  puts "Schema validation failed: #{e.message}"
+  e.errors.each { |err| puts "  - #{err.message}" }
+end
+
+begin
+  instance = '123'
+  schema = '{"type": "string"}'
+  JsonStructure::InstanceValidator.validate!(instance, schema)
+  puts "Instance is valid!"
+rescue JsonStructure::InstanceValidationError => e
+  puts "Instance validation failed: #{e.message}"
+  e.errors.each { |err| puts "  - #{err.message}" }
+end
+```
+
+### Working with Validation Results
+
+```ruby
+result = JsonStructure::InstanceValidator.validate(instance, schema)
+
+# Check validity
+puts result.valid?    # => true or false
+puts result.invalid?  # => opposite of valid?
+
+# Access errors
+result.errors.each do |error|
+  puts error.code      # Error code
+  puts error.severity  # Severity level
+  puts error.message   # Human-readable message
+  puts error.path      # JSON Pointer path to error location
+  puts error.location  # Hash with :line, :column, :offset
+
+  # Check error type
+  puts error.error?    # true if severity is ERROR
+  puts error.warning?  # true if severity is WARNING
+  puts error.info?     # true if severity is INFO
+end
+
+# Get error/warning messages
+error_msgs = result.error_messages    # Array of error messages
+warning_msgs = result.warning_messages # Array of warning messages
+```
+
+## API Reference
+
+### `JsonStructure::SchemaValidator`
+
+- `validate(schema_json)` - Validate a schema, returns `ValidationResult`
+- `validate!(schema_json)` - Validate a schema, raises `SchemaValidationError` on failure
+
+### `JsonStructure::InstanceValidator`
+
+- `validate(instance_json, schema_json)` - Validate an instance against a schema, returns `ValidationResult`
+- `validate!(instance_json, schema_json)` - Validate an instance, raises `InstanceValidationError` on failure
+
+### `JsonStructure::ValidationResult`
+
+- `valid?` - Returns true if validation passed
+- `invalid?` - Returns true if validation failed
+- `errors` - Array of `ValidationError` objects
+- `error_messages` - Array of error message strings
+- `warning_messages` - Array of warning message strings
+
+### `JsonStructure::ValidationError`
+
+- `code` - Error code (integer)
+- `severity` - Severity level (ERROR, WARNING, or INFO)
+- `message` - Human-readable error message
+- `path` - JSON Pointer path to error location (may be nil)
+- `location` - Hash with `:line`, `:column`, `:offset` keys
+- `error?`, `warning?`, `info?` - Check severity level
+
+## Thread Safety
+
+This library is **thread-safe**. Multiple threads can perform validations concurrently without any external synchronization.
+
+### Concurrent Validation
+
+```ruby
+require 'jsonstructure'
+
+schema = '{"type": "object", "properties": {"name": {"type": "string"}}}'
+
+# Safe to validate from multiple threads simultaneously
+threads = 10.times.map do |i|
+  Thread.new do
+    instance = %Q({"name": "Thread #{i}"})
+    result = JsonStructure::InstanceValidator.validate(instance, schema)
+    puts "Thread #{i}: #{result.valid? ? 'valid' : 'invalid'}"
+  end
+end
+threads.each(&:join)
+```
+
+### Implementation Details
+
+- The underlying C library uses proper synchronization primitives (SRWLOCK on Windows, pthread_mutex on Unix) to protect shared state
+- Each validation call is independent and does not share mutable state with other calls
+- The `at_exit` cleanup hook coordinates with active validations to avoid races during process shutdown
+
+### Best Practices
+
+1. **Prefer stateless validation**: Each `validate` call is independent. There's no need to create validator instances or manage state.
+
+2. **Thread-local results**: ValidationResult objects returned by `validate` are thread-local and can be safely used without synchronization.
+
+3. **Exception safety**: If a validation raises an exception (e.g., ArgumentError for invalid input), the library state remains consistent.
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies.
+
+### For Local Development (Building from Source)
+
+When developing the gem with the C library in the same repository:
+
+```bash
+# Build the C library locally
+rake build_c_lib_local
+
+# Run the tests
+rake test
+```
+
+The `rake test` task will attempt to download a pre-built binary first. If that fails (e.g., during development), it will fall back to building the C library from source if available.
+
+### For Production Use
+
+Production installations automatically download pre-built binaries from GitHub releases. No local build is required:
+
+```bash
+# Just install and use
+gem install jsonstructure
+# The binary will be downloaded automatically on first require
+```
+
+## Architecture
+
+This Ruby SDK treats the JSON Structure C library as an external dependency, downloading pre-built binaries from GitHub releases. The architecture consists of:
+
+1. **C Library Binaries** - Pre-built shared libraries (`.so`, `.dylib`, `.dll`) distributed via GitHub releases
+2. **Binary Installer** (`lib/jsonstructure/binary_installer.rb`) - Downloads and installs platform-specific binaries
+3. **FFI Bindings** (`lib/jsonstructure/ffi.rb`) - Low-level FFI mappings to C functions
+4. **Ruby Wrappers** - Idiomatic Ruby classes that wrap the FFI calls
+   - `SchemaValidator` - Schema validation
+   - `InstanceValidator` - Instance validation
+   - `ValidationResult` - Result container
+   - `ValidationError` - Error information
+
+This design allows the Ruby SDK to be distributed independently of the C library source code, treating it as a foreign SDK dependency.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/json-structure/sdk.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'fileutils'
+
+begin
+  require 'rspec/core/rake_task'
+  RSpec::Core::RakeTask.new(:spec)
+rescue LoadError
+  # RSpec not available, skip test tasks
+  desc 'Run tests (requires rspec gem)'
+  task :spec do
+    puts 'RSpec not available. Install with: gem install rspec'
+  end
+end
+
+desc 'Download pre-built C library binary from GitHub releases'
+task :download_binary do
+  require_relative 'lib/jsonstructure/binary_installer'
+  installer = JsonStructure::BinaryInstaller.new
+  installer.install
+end
+
+desc 'Build the C library locally (for development only)'
+task :build_c_lib_local do
+  puts 'Building C library locally...'
+  c_dir = File.expand_path('../c', __dir__)
+  
+  unless Dir.exist?(c_dir)
+    puts 'C library source not found. Skipping local build.'
+    puts 'This is normal when installing from a gem.'
+    next
+  end
+  
+  build_dir = File.join(c_dir, 'build')
+  Dir.mkdir(build_dir) unless Dir.exist?(build_dir)
+
+  Dir.chdir(build_dir) do
+    system('cmake', '..', '-DCMAKE_BUILD_TYPE=Release', '-DJS_BUILD_SHARED=ON', '-DJS_BUILD_TESTS=OFF', '-DJS_BUILD_EXAMPLES=OFF') || raise('CMake configuration failed')
+    system('cmake', '--build', '.') || raise('Build failed')
+  end
+
+  # Copy to ext directory
+  ext_dir = File.expand_path('ext', __dir__)
+  FileUtils.mkdir_p(ext_dir)
+  
+  lib_name = case RbConfig::CONFIG['host_os']
+             when /darwin|mac os/
+               'libjson_structure.dylib'
+             when /mswin|msys|mingw|cygwin|bccwin|wince|emc/
+               'json_structure.dll'
+             else
+               'libjson_structure.so'
+             end
+  
+  src = File.join(build_dir, lib_name)
+  dst = File.join(ext_dir, lib_name)
+  FileUtils.cp(src, dst) if File.exist?(src)
+  
+  puts 'C library built successfully!'
+end
+
+desc 'Run tests (downloads binary first if needed, falls back to local build for development)'
+task :test do
+  # Try to download binary first
+  begin
+    Rake::Task[:download_binary].invoke
+  rescue StandardError => e
+    puts "Binary download failed: #{e.message}"
+    puts "Attempting local build for development..."
+    begin
+      Rake::Task[:build_c_lib_local].invoke
+    rescue StandardError => build_error
+      puts "Local build also failed: #{build_error.message}"
+      raise "Cannot obtain C library binary. Please check the error messages above."
+    end
+  end
+  
+  Rake::Task[:spec].invoke
+end
+
+task default: :test

data/lib/jsonstructure/binary_installer.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'net/http'
+require 'uri'
+require 'rbconfig'
+
+module JsonStructure
+  # Downloads and installs pre-built C library binaries from GitHub releases
+  class BinaryInstaller
+    REPO = 'json-structure/sdk'
+    DEFAULT_VERSION = 'v0.1.0'
+
+    attr_reader :version, :platform, :lib_dir
+
+    def initialize(version: nil)
+      @version = version || DEFAULT_VERSION
+      @platform = detect_platform
+      @lib_dir = File.expand_path('../../ext', __dir__)
+    end
+
+    def install
+      FileUtils.mkdir_p(lib_dir)
+
+      if binary_exists?
+        puts "Binary already installed at #{binary_path}"
+        return true
+      end
+
+      puts "Downloading C library binary for #{platform}..."
+      download_binary
+      puts "Binary installed successfully at #{binary_path}"
+      true
+    rescue StandardError => e
+      warn "Failed to download binary: #{e.message}"
+      warn "You may need to build the C library manually."
+      false
+    end
+
+    def binary_exists?
+      File.exist?(binary_path)
+    end
+
+    def binary_path
+      File.join(lib_dir, binary_name)
+    end
+
+    private
+
+    def detect_platform
+      os = RbConfig::CONFIG['host_os']
+      arch = RbConfig::CONFIG['host_cpu']
+
+      case os
+      when /darwin|mac os/
+        "macos-#{normalize_arch(arch)}"
+      when /linux/
+        "linux-#{normalize_arch(arch)}"
+      when /mswin|msys|mingw|cygwin|bccwin|wince|emc/
+        "windows-#{normalize_arch(arch)}"
+      else
+        raise "Unsupported platform: #{os}"
+      end
+    end
+
+    def normalize_arch(arch)
+      case arch
+      when /x86_64|x64|amd64/
+        'x86_64'
+      when /aarch64|arm64/
+        'arm64'
+      when /arm/
+        'arm'
+      else
+        arch
+      end
+    end
+
+    def binary_name
+      case RbConfig::CONFIG['host_os']
+      when /darwin|mac os/
+        'libjson_structure.dylib'
+      when /mswin|msys|mingw|cygwin|bccwin|wince|emc/
+        'json_structure.dll'
+      else
+        'libjson_structure.so'
+      end
+    end
+
+    def download_url
+      # Try to get from GitHub releases
+      # Format: https://github.com/json-structure/sdk/releases/download/v0.1.0/json_structure-macos-x86_64.tar.gz
+      "https://github.com/#{REPO}/releases/download/#{version}/json_structure-#{platform}.tar.gz"
+    end
+
+    def download_binary
+      uri = URI(download_url)
+      response = fetch_with_redirects(uri)
+
+      unless response.is_a?(Net::HTTPSuccess)
+        raise "Failed to download binary from #{download_url}: HTTP #{response.code}"
+      end
+
+      # Save and extract tarball
+      tarball_path = File.join(lib_dir, 'binary.tar.gz')
+      File.binwrite(tarball_path, response.body)
+
+      # Extract tarball
+      Dir.chdir(lib_dir) do
+        system('tar', '-xzf', 'binary.tar.gz') || raise('Failed to extract tarball')
+        FileUtils.rm('binary.tar.gz')
+      end
+
+      # Verify the binary was extracted
+      raise "Binary not found after extraction: #{binary_path}" unless File.exist?(binary_path)
+    end
+
+    def fetch_with_redirects(uri, limit = 10)
+      raise 'Too many HTTP redirects' if limit.zero?
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == 'https')
+      request = Net::HTTP::Get.new(uri.request_uri)
+      response = http.request(request)
+
+      case response
+      when Net::HTTPRedirection
+        fetch_with_redirects(URI(response['location']), limit - 1)
+      else
+        response
+      end
+    end
+  end
+end

data/lib/jsonstructure/ffi.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require 'ffi'
+
+module JsonStructure
+  # Low-level FFI bindings to the C library
+  module FFI
+    extend ::FFI::Library
+
+    # Determine library name based on platform
+    lib_name = case RbConfig::CONFIG['host_os']
+               when /darwin|mac os/
+                 'libjson_structure.dylib'
+               when /mswin|msys|mingw|cygwin|bccwin|wince|emc/
+                 'json_structure.dll'
+               else
+                 'libjson_structure.so'
+               end
+
+    # Try to load from several possible locations
+    # Priority: downloaded binaries (ext/), system paths, then local build (fallback for development)
+    lib_paths = [
+      ::File.expand_path("../../../ext/#{lib_name}", __FILE__),
+      lib_name, # Let FFI search in standard library paths
+      ::File.expand_path("../../../../c/build/#{lib_name}", __FILE__) # Fallback for local development
+    ]
+
+    loaded = false
+    lib_paths.each do |path|
+      begin
+        ffi_lib path
+        loaded = true
+        break
+      rescue LoadError
+        next
+      end
+    end
+
+    raise LoadError, "Could not load json_structure library from: #{lib_paths.join(', ')}" unless loaded
+
+    # Enums
+    typedef :int, :js_type_t
+    typedef :int, :js_error_code_t
+    typedef :int, :js_severity_t
+
+    # js_severity_t enum values
+    JS_SEVERITY_ERROR = 0
+    JS_SEVERITY_WARNING = 1
+    JS_SEVERITY_INFO = 2
+
+    # Structs
+    class JSLocation < ::FFI::Struct
+      layout :line, :int,
+             :column, :int,
+             :offset, :size_t
+    end
+
+    class JSError < ::FFI::Struct
+      layout :code, :js_error_code_t,
+             :severity, :js_severity_t,
+             :location, JSLocation,
+             :path, :pointer,
+             :message, :pointer
+
+      def path_str
+        ptr = self[:path]
+        ptr.null? ? nil : ptr.read_string
+      end
+
+      def message_str
+        ptr = self[:message]
+        ptr.null? ? '' : ptr.read_string
+      end
+
+      def location_hash
+        loc = self[:location]
+        {
+          line: loc[:line],
+          column: loc[:column],
+          offset: loc[:offset]
+        }
+      end
+    end
+
+    class JSResult < ::FFI::Struct
+      layout :valid, :bool,
+             :errors, :pointer,
+             :error_count, :size_t,
+             :error_capacity, :size_t
+
+      def errors_array
+        return [] if self[:error_count].zero?
+
+        errors_ptr = self[:errors]
+        (0...self[:error_count]).map do |i|
+          JSError.new(errors_ptr + i * JSError.size)
+        end
+      end
+    end
+
+    class JSSchemaValidator < ::FFI::Struct
+      layout :allow_import, :bool,
+             :warnings_enabled, :bool,
+             :import_registry, :pointer
+    end
+
+    class JSInstanceValidator < ::FFI::Struct
+      layout :check_refs, :bool,
+             :warnings_enabled, :bool,
+             :import_registry, :pointer
+    end
+
+    # Library functions
+    attach_function :js_init, [], :void
+    attach_function :js_cleanup, [], :void
+
+    # Result functions
+    attach_function :js_result_init, [:pointer], :void
+    attach_function :js_result_cleanup, [:pointer], :void
+    attach_function :js_result_to_string, [:pointer], :pointer
+
+    # Schema validator functions
+    attach_function :js_schema_validator_init, [:pointer], :void
+    attach_function :js_schema_validate_string, [:pointer, :string, :pointer], :bool
+
+    # Instance validator functions
+    attach_function :js_instance_validator_init, [:pointer], :void
+    attach_function :js_instance_validate_strings, [:pointer, :string, :string, :pointer], :bool
+
+    # Error message function
+    attach_function :js_error_message, [:js_error_code_t], :string
+
+    # Memory management
+    attach_function :js_free, [:pointer], :void
+
+    # Convenience wrappers (since the C inline functions aren't exported)
+    def self.js_validate_schema(schema_json, result_ptr)
+      validator_ptr = ::FFI::MemoryPointer.new(JSSchemaValidator.size)
+      js_schema_validator_init(validator_ptr)
+      js_schema_validate_string(validator_ptr, schema_json, result_ptr)
+    end
+
+    def self.js_validate_instance(instance_json, schema_json, result_ptr)
+      validator_ptr = ::FFI::MemoryPointer.new(JSInstanceValidator.size)
+      js_instance_validator_init(validator_ptr)
+      js_instance_validate_strings(validator_ptr, instance_json, schema_json, result_ptr)
+    end
+  end
+end