schemurai 2.2.3 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4620544f45920ada46eda1beff7cbb6461fb1633031f78d2964c4e963716d82
-  data.tar.gz: b0a66f4e369181d9182a10715d1622924ebac68cfe32a1169b844714a7b6a038
+  metadata.gz: 8fde4b5a2e6ccf979c4948fd13476c8250acf053346de28c4d62b32ed0c92e4f
+  data.tar.gz: 7e3a5fb2dfa17195b1a45cde045f7256a1c5f3687f19f8d2c7b821980ffe2ab1
 SHA512:
-  metadata.gz: b6dd9a631fa90e9600e0a60ba4e2ecfca492497a69376a11801cf1a4bfb799fb71eea3546f417b394279b7c3795ace0d2ff8422c8fa8c0b9c9cf6e7530ca8f86
-  data.tar.gz: b8b2e1bdaccdfc420b1aa2cec9fc2bef856157d450ccb547dcf230693b4b959baa77f9901b9df920c5c73bd6ef982b468249655397c0160e55c3b57772b1c2c5
+  metadata.gz: 42c0e94ce30932d09c9f1617592338f2386076eca4d176f1e1a9461557ea723abf512f94d7c68fb52a392021e9b45cba4ab329ee3669754b6d0a996f0319a07f
+  data.tar.gz: 68b8c4e585cd40e11d4d7fbae8d9345f52a4bfca437704b86999eab79f219cf52e276b623faf0271cd49c4044c596f544399be77ba8a8fd36946f20524708cc2

data/README.md

@@ -5,13 +5,18 @@
 [![lint / rubocop](https://github.com/oakcask/schemurai/actions/workflows/lint--rubocop.yaml/badge.svg)](https://github.com/oakcask/schemurai/actions/workflows/lint--rubocop.yaml)
 [![lint / rbs](https://github.com/oakcask/schemurai/actions/workflows/lint--rbs.yaml/badge.svg)](https://github.com/oakcask/schemurai/actions/workflows/lint--rbs.yaml)
 
-A small, light-weight-dependency JSON Schema validator for Ruby supporting Draft 7,
-Draft 2019-09, and Draft 2020-12. It covers the required cases in the official
-JSON-Schema-Test-Suite, as well as the applicable optional tests for numeric
+A JSON Schema validator for Ruby with reusable compiled schemas and detailed
+validation errors. It supports Draft 7, Draft 2019-09, and Draft 2020-12 and
+covers the required cases in the official JSON-Schema-Test-Suite, as well as
+the applicable optional tests for numeric
 precision, ECMA-262 regular expressions, content validation, anchors, and dynamic
 references. The dialect is selected from the schema's `$schema` URI; schemas that
 omit `$schema` use Draft 7 for compatibility.
 
+Choose the default Ruby evaluator, the Ruby VM backend, or the optional
+experimental Rust native backend. See [backend selection](#backend-selection)
+for setup and requirements.
+
 Schemurai ships RBS declarations for its public API in `sig/schemurai.rbs`.
 
 ```ruby
@@ -180,9 +185,12 @@ validator = registry.validator_for("https://example.test/value")
 `ResolutionError` if a reference cannot be resolved. After it returns,
 `validator_for` is read-only and may be called concurrently, while `compile` is
 no longer available. A `Validator` contains per-validation mutable state and
-must not be shared between threads or Ractors. With the VM backend, the registry
-compiles and shares its bytecode before this transition, so those validators do
-not compile separate instruction streams in each Ractor.
+must not be shared between threads or Ractors. With the VM and native backends,
+the registry compiles and shares its bytecode before this transition. The native
+backend also prepares shared native instruction tables for all four combinations
+of `content` and `format`; `validator_for` does not recompile them in each Ractor.
+Native regex search caches and VM fallback evaluation state belong to each
+validator. Preparing these tables adds time and memory to `make_shareable`.
 
 ### Meta-schema validation
 
@@ -213,11 +221,77 @@ regardless of the registry option and reuse meta-schema graph data within that
 registry. The stateful validator used for a check is temporary; no global
 validator is retained.
 
+### Opt-in validation limits (experimental)
+
+`max_errors:` and `timeout:` are optional kwargs. Both default to `nil`
+(unlimited) and apply independently to each validation call. `max_errors` must
+be a nonnegative Integer; `timeout` must be finite nonnegative Integer or Float
+seconds. No settings object is needed.
+
+```ruby
+validator = Schemurai.compile(schema, max_errors: 100, timeout: 0.1)
+begin
+  result = validator.validate(order)
+rescue Schemurai::LimitExceeded => error
+  # Evaluation is incomplete; no partial result is returned.
+  warn "Validation stopped at #{error.limit}"
+end
+
+validator.validate(order, max_errors: 10) # retains the compiled timeout
+validator.validate(order, timeout: nil)  # retains the compiled error cap
+validator.validate(order, max_errors: nil, timeout: nil) # disables both
+validator.valid?(order) # applies the timeout, ignores max_errors
+```
+
+`SchemaRegistry#compile`, `#validator_for`, the convenience `validate` / `valid?`
+methods and explicit meta-schema checks also accept these kwargs. Overrides
+replace only the specified option. Settings belong to each compiled validator;
+a shareable registry retains no mutable invocation counters.
+
+The error cap checks before constructing the next emitted diagnostic. Exactly
+`max_errors` errors may be returned; attempting another raises `LimitExceeded`
+with `limit == :max_errors`, `maximum` and `attempted` counts. Suppressed
+applicator trials do not consume the cap. Boolean checks ignore the error cap
+and use the ordinary evaluator when no timeout is set.
+
+The timeout uses a monotonic elapsed-time deadline, including diagnostic
+rendering and native-to-VM fallback. It checks at entry, before returning and
+every 256 checkpoints in evaluation, container scans and structural traversal.
+Ruby string/content operations also check before and after expensive calls.
+Zero seconds stops even a trivial call. Expiry raises `LimitExceeded` with
+`limit == :timeout`; `maximum` and `attempted` are configured and elapsed seconds.
+Native returns an exhaustion status and releases Rust resources before Ruby
+raises. A limit hit is terminal and does not trigger fallback.
+
+This implementation never uses Ruby `Timeout`, timer threads, signals or
+asynchronous exception injection. It is cooperative: one regexp search, scalar
+operation, JSON decode, allocation or custom format callback may overrun until
+the next checkpoint. GC and descheduling count toward elapsed time; the polling
+interval bounds skipped checkpoints, not elapsed overrun. Compilation,
+registration and automatic compile-time meta-schema validation are outside the
+timeout. Explicit meta-schema checks can set their own timeout.
+
+Use the error cap to bound diagnostic count and the timeout to bound prolonged
+traversal. They protect different resources: a deadline does not bound the
+number of diagnostics, and an error cap cannot stop a long successful check.
+Input byte size and nesting depth belong at the parsing boundary. An error cap
+does not bound the size of an individual message. Preempting individual scalar
+operations requires operation-specific limits or a supervised worker process.
+The backends retain their respective Ruby, VM and native execution paths and
+native memoization. Timed native bulk pattern/format/content and Fixnum contains
+scans use per-item evaluation so successful scans can poll.
+
 ### Backend selection
 
 `Schemurai.backend`, `SchemaRegistry#backend`, and `Validator#backend` expose
-the actual backend. Pass `backend: :ruby` to force the Ruby oracle or
+the selected backend. Pass `backend: :ruby` to force the Ruby oracle or
 `backend: :vm` to ahead-of-time compile schemas for the validator virtual machine.
+Pass `backend: :native` to use the experimental Rust VM extension. Building the
+native extension requires a C toolchain, Ruby development headers, and Rust
+1.93 or newer. If cargo is absent, gem installation skips the optional native
+extension and Ruby/VM remain available; explicitly selecting `:native` then
+raises `LoadError`. Native execution borrows Ruby values directly; its current coverage and
+remaining VM delegation are documented below.
 Schema graph construction remains shared Ruby infrastructure. Environment-based selection
 is documented in [`docs/backend-selection.md`](docs/backend-selection.md).
 

data/ext/schemurai_native/Cargo.lock

@@ -0,0 +1,99 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "aho-corasick"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "base64-simd"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "339abbe78e73178762e23bea9dfd08e697eb3f3301cd4be981c0f78ba5859195"
+dependencies = [
+ "outref",
+ "vsimd",
+]
+
+[[package]]
+name = "base64-turbo"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "865a269d8d8fc97f16122eae7a74e7e9dffa2df68d5f067cb1f494e9984528db"
+dependencies = [
+ "cpufeatures",
+]
+
+[[package]]
+name = "cpufeatures"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5ca28b0ae3115b884660db4118d803791fd6756b6e88f39c0f3f7859060d7566"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.190"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce5d3ddc6d3fa000eb1536d85e147bfe31aacaba692ed6a876f95cb7c855be78"
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "outref"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1a80800c0488c3a21695ea981a54918fbb37abf04f4d0720c453632255e2ff0e"
+
+[[package]]
+name = "regex-automata"
+version = "0.4.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-syntax"
+version = "0.8.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
+
+[[package]]
+name = "ryu"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f"
+
+[[package]]
+name = "schemurai-native"
+version = "3.0.0"
+dependencies = [
+ "base64-simd",
+ "base64-turbo",
+ "memchr",
+ "regex-automata",
+ "regex-syntax",
+ "ryu",
+]
+
+[[package]]
+name = "vsimd"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c3082ca00d5a5ef149bb8b555a72ae84c9c59f7250f013ac822ac2e49b19c64"

data/ext/schemurai_native/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "schemurai-native"
+version = "3.0.0"
+edition = "2024"
+rust-version = "1.93"
+publish = false
+
+[dependencies]
+base64-simd = "0.8.0"
+base64-turbo = "0.5.0"
+memchr = "2.8.3"
+regex-automata = "0.4.18"
+regex-syntax = "0.8.11"
+ryu = "1.0.23"
+
+[lib]
+crate-type = ["staticlib"]
+
+[profile.release]
+lto = true
+codegen-units = 1

data/ext/schemurai_native/build.rs

@@ -0,0 +1,35 @@
+use std::{env, fs, path::PathBuf};
+
+fn main() {
+    println!("cargo:rerun-if-changed=protocol.def");
+    let definitions = fs::read_to_string("protocol.def").expect("read native protocol");
+    let mut output = String::new();
+    for line in definitions.lines() {
+        let (fields, opcode) = if let Some(fields) = line.strip_prefix("SN_OPCODE(") {
+            (fields, true)
+        } else if let Some(fields) = line.strip_prefix("SN_CONSTANT(") {
+            (fields, false)
+        } else {
+            continue;
+        };
+        let fields: Vec<_> = fields
+            .strip_suffix(')')
+            .expect("protocol closing parenthesis")
+            .split(',')
+            .map(str::trim)
+            .collect();
+        assert_eq!(fields.len(), if opcode { 3 } else { 2 });
+        let name = fields[0];
+        assert!(
+            name.bytes()
+                .all(|c| c.is_ascii_uppercase() || c.is_ascii_digit() || c == b'_')
+        );
+        let value: i32 = fields[if opcode { 2 } else { 1 }]
+            .parse()
+            .expect("protocol integer value");
+        let prefix = if opcode { "OP_" } else { "" };
+        output.push_str(&format!("pub const {prefix}{name}: i32 = {value};\n"));
+    }
+    let directory = PathBuf::from(env::var_os("OUT_DIR").expect("Cargo output directory"));
+    fs::write(directory.join("protocol.rs"), output).expect("write native protocol constants");
+}

data/ext/schemurai_native/extconf.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "mkmf"
+
+unless find_executable("cargo")
+  warn "cargo was not found; skipping the optional native backend (Ruby and VM remain available)"
+  File.write("Makefile", dummy_makefile(".").join)
+  exit
+end
+unless enable_config("portable-hash-walk", false)
+  if have_func("rb_hash_stlike_foreach", ["ruby.h", "ruby/st.h"])
+    # CRuby 3.4/4.0 identity Hashes always use ST storage. Check the private
+    # storage flag against a fresh interpreter before enabling the read hint.
+    ar_proof = !CROSS_COMPILING && try_run(<<~C)
+      #include <ruby.h>
+      #include <ruby/version.h>
+      #if (RUBY_API_VERSION_MAJOR == 3 && RUBY_API_VERSION_MINOR == 4) || \
+          (RUBY_API_VERSION_MAJOR == 4 && RUBY_API_VERSION_MINOR == 0)
+      int main(int argc, char **argv) {
+          ruby_sysinit(&argc, &argv);
+          RUBY_INIT_STACK;
+          ruby_init();
+          int status = 0;
+          ID identity = rb_intern_const("compare_by_identity");
+          for (int n = 0; n <= 8; n++) {
+              VALUE h = rb_hash_new();
+              VALUE id = rb_funcall(rb_hash_new(), identity, 0);
+              for (int i = 0; i < n; i++) {
+                  rb_hash_aset(h, INT2FIX(i), INT2FIX(i));
+                  rb_hash_aset(id, INT2FIX(i), INT2FIX(i));
+              }
+              VALUE hashes[] = {h, rb_obj_freeze(rb_hash_dup(h)),
+                  rb_funcall(rb_hash_dup(h), identity, 0), id};
+              for (int i = 0; i < 4; i++) {
+                  int st = RB_FL_TEST_RAW(hashes[i], RUBY_FL_USER3) != 0;
+                  if (st != (i >= 2)) status = 1;
+              }
+              RB_GC_GUARD(h);
+              RB_GC_GUARD(id);
+          }
+          return ruby_cleanup(status);
+      }
+      #else
+      int main(void) { return 1; }
+      #endif
+    C
+    $defs << "-DSCHEMURAI_AR_HASH_PROOF" if ar_proof # rubocop:disable Style/GlobalVars -- mkmf build configuration.
+  end
+end
+$LOCAL_LIBS << " $(srcdir)/target/release/libschemurai_native.a" # rubocop:disable Style/GlobalVars -- mkmf build configuration.
+$LOCAL_LIBS << " -lpthread -ldl -lm" unless /mswin|mingw/ =~ RUBY_PLATFORM # rubocop:disable Style/GlobalVars -- mkmf build configuration.
+create_makefile("schemurai_native")
+File.open("Makefile", "a") do |file|
+  file.puts <<~MAKE
+
+    $(TARGET_SO): $(srcdir)/target/release/libschemurai_native.a
+
+    glue.o: $(srcdir)/protocol.h $(srcdir)/protocol.def
+
+    $(srcdir)/target/release/libschemurai_native.a: $(srcdir)/Cargo.toml $(srcdir)/Cargo.lock $(srcdir)/build.rs $(srcdir)/protocol.def $(wildcard $(srcdir)/src/*.rs)
+    \tcargo build --manifest-path $(srcdir)/Cargo.toml --release --locked
+  MAKE
+end