yeptris 0.6.18.2-arm-linux-eabihf

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d861d71fda8e06d38693a273a8c3eea7cbe96325af1eb0e4d2fdcc4bf7f08e46
+  data.tar.gz: 1120adc922c754da05873a318e2406206606ca966d22b79a686e08192b4a0e4d
+SHA512:
+  metadata.gz: a68230754f4f90049a59ea30d8d8abb903c8fdef3f5e26abf5b110fd966d4da973c811d8e4c55750034aaa2207289f9fed60ed50f5065125b7b6854b44c5bce4
+  data.tar.gz: eb0d85052b73579c0809a9b1aef3f6be57ee5aff43406b9569f7f77189d23af3471d4bd29b5d9f4815a50bd661e20007a7c93fc6b3a2bac8d842a1a7001da921

data/README.adoc

@@ -0,0 +1,141 @@
+= yeptris — YAML for Ruby at libleptris speed
+
+An FFI-based (no C extension) Ruby YAML library over
+https://github.com/leptris/yeptris[libyeptris] — the YAML counterpart
+of libleptris. Psych-compatible semantics, one shared library, zero
+compilation at install.
+
+== Install (development)
+
+The gem loads a shared `libyeptris` — from `YEPTRIS_LIB_PATH`, a
+vendored `lib/platform/<tag>/` copy, or the system paths. For
+development against a local build:
+
+....
+# the sibling C checkout: ~/src/leptris/yeptris
+cmake -B build -S . -DCMAKE_BUILD_TYPE=Release -DYEPTRIS_BUILD_SHARED=ON
+cmake --build build
+
+cd ~/src/leptris/yeptris-ruby
+YEPTRIS_LIB_PATH=../yeptris/build/src/libyeptris.dylib bundle exec rspec
+....
+
+Without `YEPTRIS_LIB_PATH` the spec helper falls back to a vendored
+`lib/platform/<tag>/` copy, then to the sibling checkout's
+`build-validate` — any `libyeptris.{so,dylib,dll}` path works.
+
+== Usage
+
+[source,ruby]
+----
+require "yeptris"
+
+Yeptris::YAML.load("name: yeptris\nrating: 10\n")
+# => {"name" => "yeptris", "rating" => 10}
+
+# brace mixed hashes on Ruby 3.x: a trailing symbol key otherwise
+# splits the literal into keywords
+Yeptris::YAML.dump({"name" => "yeptris", "tags" => [:yaml, :fast]})
+
+doc = Yeptris::Document.parse(config_yaml)
+doc.root["server"]["port"].to_i
+doc.serialize
+----
+
+`Yeptris::YAML.load` defaults to Psych's YAML 1.1 implicit typing
+(`yes` is `true`, `017` is octal); pass `schema: :core_12` for YAML
+1.2 core semantics. Dump builds through the library's DOM mutation
+API, so the writer's sizing/escape machinery applies to synthesized
+trees unchanged.
+
+Handles are document-scoped: `Document#free` releases everything
+(one C call), a GC finalizer backs it up, and any use after free
+raises `Yeptris::FreedError` — never a segfault.
+
+== Two load surfaces: YAML and strict JSON
+
+`Yeptris::YAML.load` keeps the Psych contract for EVERY input —
+including JSON-shaped ones. `{"a": [1,]}` is legal flow YAML (spec
+production [141] allows the trailing comma); `"1e3"` is a Psych
+String. These semantics never flip because input happens to look
+like JSON.
+
+`Yeptris::JSON.load` is the STRICT RFC 8259 surface — exact
+`JSON.parse` semantics by construction (spec-pinned in
+`spec/json_parity_spec.rb`: every value and every error case,
+Bignum integers, exponent-only floats, duplicate keys). Engines,
+fastest first:
+
+1. **Native materializer** (opt-in build; see below): a fused C scan
+   → `VALUE` parser. Order-alternating interleaved profile, 152 KB /
+   ~29k-value corpus, Ruby 3.4:
++
+....
+CI referee (gated at 1.05 on both platforms, order-alternating
+interleave, N=200; prefix-hashed token cache):
+  ubuntu (x86_64)   mean 0.745x  vs JSON.parse, 200/200 head-to-head
+  macos  (arm64)    mean 0.759x  vs JSON.parse, 169/200 head-to-head
+....
+
+The parse-window GC strategy is per-arch and runtime-switchable:
+`Yeptris::Native.gc_mode` / `YEPTRIS_NATIVE_GC` = `:none`
+(steady-state: +0 heap pages, the stdlib's own GC cadence — the
+default on arm64) or `:disable` (no GC during the parse — the
+default on x86_64, faster where pages are free). On a LOADED x86_64
+box prefer `:none`: `:disable` grows ~478 heap pages per 50 parses,
+and page growth under contention is exactly the loaded-box
+regression. `:start` (in-window collection) measured 8x — dead.
+2. **Record-drain fallback** (always available): the strict-JSON
+   validator gates, then the value records convert without the Psych
+   quirk table — exact parity with engine 1, spec-pinned.
+
+The committed profile (`benchmark/json_profile.rb`) is the fair
+benchmark of record — any performance claim runs through it.
+
+=== Building the native materializer (opt-in)
+
+....
+cd ext/yeptris_native
+YEPTRIS_LIB_PATH=/path/to/libyeptris.dylib ruby extconf.rb && make
+cp native.bundle ../../lib/yeptris/   # or .so on Linux
+....
+
+`require "yeptris"` picks it up automatically (`Yeptris::JSON` then
+uses it; missing builds silently use the fallback — the gem installs
+without compiling).
+
+== Shipped beyond the original plan
+
+* The columnar value drain (bulk, pre-converted typed columns — the
+  load fast path) and the bulk DOM builder (one `document_build`
+  call per dump).
+* **Ruby Marshal 4.8 emission** (libyeptris >= 0.1.11): the C side
+  converts value records into Marshal bytes; one `Marshal.load`
+  materializes the whole graph. ~10× faster than the columnar walk
+  on JSON-shaped input, ~5× on YAML, ~50× on the per-node DOM walk
+  (`Node#to_ruby` becomes bulk). Alias identity preserved through
+  object links; merge keys and timestamps return UNSUPPORTED for the
+  record-walk fallback.
+* `Yeptris::Psych` — the Psych-compatible namespace with the ported
+  Psych suite (143 specs), `.tml` corpora conformance, and the
+  Encodable object protocol (`include Yeptris::Psych::Encodable` +
+  `encode_with`/`init_with` — no `respond_to?`, no ivar reflection;
+  the library never reaches into an object's internals).
+** CO-EXISTENCE (issue #69): `require "yeptris/psych"` loads the
+   namespace WITHOUT touching the top-level `Psych` constant — it
+   coexists with stdlib psych in ANY load order. The process-
+   exclusive drop-in rebind (`::Psych = Yeptris::Psych`) is now
+   OPT-IN: `require "yeptris/psych/drop_in"`. Once the drop-in runs,
+   stdlib psych must NOT be loaded afterwards (its require re-opens
+   the rebound module and clobbers constants). Bundles that cannot
+   control the load order (activesupport et al.) should use
+   `Yeptris::Psych` / `Yeptris::YAML` directly.
+** `Yeptris::YAML.safe_load(yaml, permitted_classes: [], aliases:
+   false)` — Psych's safe_load semantics on the native surface:
+   plain data by default; a leaf that would materialize to a
+   non-permitted class (a compat_11 date) raises
+   `Yeptris::Psych::DisallowedClass`; alias use without `aliases:
+   true` raises `Yeptris::Psych::AliasesError`.
+* Lockstep versioning with the C library
+  (`{c-semver}.{gem-patch}`); releases published from the C repo's
+  workflow through the RubyGems trusted publisher.

data/ext/build_windows_native.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Builds the native materializer DLL for the CURRENT Ruby and
+# installs it under its minor-versioned name
+# (lib/yeptris/native-<major.minor>.so).
+#
+# The leptris-ruby Windows lesson (#207/#227): a PE DLL cannot
+# resolve Ruby imports lazily — it must bind the build Ruby's
+# x64-ucrt-rubyNNN.dll. One DLL per supported minor therefore ships
+# in the Windows platform gems, and the loader in lib/yeptris.rb
+# picks by RUBY_VERSION at require. Ruby 3.3 has no arm64 build:
+# that cell ships no artifact and falls back loudly to the FFI
+# ladder.
+#
+# Standalone by design: the release workflow runs this under each
+# Ruby minor (3.3/3.4/4.0) with no bundler context.
+
+require "rbconfig"
+require "fileutils"
+
+root = File.expand_path("..", __dir__)
+ext_dir = File.join(root, "ext", "yeptris_native")
+minor = RUBY_VERSION[/\A\d+\.\d+/]
+
+Dir.chdir(ext_dir) do
+  system(RbConfig.ruby, "extconf.rb") or abort "extconf failed under #{RUBY_VERSION}"
+  # mkmf's link binds the CURRENT Ruby's runtime DLL — exactly
+  # what the versioned naming is for.
+  success = system("make")
+  abort "make failed under #{RUBY_VERSION}" unless success
+  so = Dir.glob("native.{so,dll}").first
+  abort "native bundle not produced under #{RUBY_VERSION}" unless so
+  dest = File.join(root, "lib", "yeptris", "native-#{minor}.so")
+  # The artifact must reference only this minor's Ruby DLL.
+  imported = `strings #{so} 2>/dev/null`[/[a-z0-9-]*ruby\d{3,}\.dll/i]
+  if imported && !imported.include?("ruby#{minor.delete('.')}")
+    abort "#{so} imports #{imported} but was built under #{RUBY_VERSION} — refuse to mis-name it"
+  end
+  FileUtils.cp(so, dest)
+  puts "Installed native materializer for Ruby #{minor} -> #{dest} (#{imported || 'no ruby dll string found'})"
+end

data/ext/libyeptris/extconf.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# Builds the vendored libyeptris at gem-install time so EVERY install
+# carries the engine (the pure `ruby`-platform gem has no prebuilt
+# binary). Platform gems vendor the prebuilt lib at the gem root —
+# when one is present this extension no-ops.
+
+require "mkmf"
+require "fileutils"
+
+gem_root = File.expand_path("../..", __dir__)
+vendored = File.join(gem_root, "vendor", "libyeptris")
+
+prebuilt = ["libyeptris.so", "libyeptris.dylib", "libyeptris.dll",
+            "yeptris.dll"].any? { |n| File.exist?(File.join(gem_root, n)) }
+
+def write_dummy_makefile(reason)
+  File.write("Makefile", <<~MAKE)
+    all:
+    \t@echo "#{reason}"
+    install:
+    clean:
+  MAKE
+end
+
+if prebuilt
+  write_dummy_makefile("yeptris: prebuilt libyeptris ships in this gem; source build skipped")
+elsif !File.directory?(vendored)
+  write_dummy_makefile("yeptris: no vendored libyeptris sources; set YEPTRIS_LIB_PATH at require time")
+elsif find_executable("cmake").nil?
+  write_dummy_makefile("yeptris: cmake not found; set YEPTRIS_LIB_PATH at require time")
+else
+  # Out-of-source into the ext workdir; the shared lib then moves to
+  # the GEM ROOT, where ffi.rb's ladder probes it.
+  build = File.join(Dir.pwd, "libyeptris-build")
+  # BUILD_TESTING (the CMake standard) gates test/ — the vendored
+  # tree ships no test dir; the static target must build because the
+  # unconditional install(TARGETS yeptris_static) expects it
+  args = [
+    "-DCMAKE_BUILD_TYPE=Release",
+    "-DBUILD_TESTING=OFF",
+    "-DYEPTRIS_BUILD_CLI=OFF",
+    "-DYEPTRIS_BUILD_BENCHMARKS=OFF",
+    "-DYEPTRIS_BUILD_SHARED=ON",
+  ]
+  ok = system("cmake", "-S", vendored, "-B", build, *args) &&
+       system("cmake", "--build", build, "--config", "Release")
+  lib = Dir.glob(File.join(build, "**", "libyeptris.{so,dylib}")).first
+  if ok && lib
+    FileUtils.cp(lib, File.join(gem_root, File.basename(lib)))
+    write_dummy_makefile("yeptris: built vendored libyeptris at gem install")
+  else
+    # a failed build must not abort the install — require-time raises
+    # the informative ladder error instead
+    write_dummy_makefile("yeptris: libyeptris source build failed; set YEPTRIS_LIB_PATH at require time")
+  end
+end

data/ext/yeptris_native/cbor_ruby.c

@@ -0,0 +1,193 @@
+/* cbor_ruby.c — CBOR decode → Ruby VALUE in one C pass (#157).
+ *
+ * The FFI ladder's CBOR.load pays decode + a Marshal emit/load round
+ * trip; this walks the decoded DOM directly, building the same VALUEs
+ * the materializer builds (tag-driven scalar semantics, insertion-
+ * order mappings), with no intermediate representation.
+ */
+#include <ruby.h>
+/* rb_hash_new_capa is Ruby 3.2+; older Rubies grow dynamically (the
+ * json_ruby.c guard, verbatim). */
+#if RUBY_API_VERSION_MAJOR > 3 || (RUBY_API_VERSION_MAJOR == 3 && RUBY_API_VERSION_MINOR >= 2)
+#define HASH_NEW_CAPA(n) rb_hash_new_capa(n)
+#else
+#define HASH_NEW_CAPA(n) rb_hash_new()
+#endif
+#include <ruby/encoding.h>
+#include <stdlib.h>
+#include <string.h>
+
+static rb_encoding* cr_utf8_enc;
+
+/* Map keys repeat across records in CBOR corpora; interning shares one
+ * VALUE per distinct key (the json_ruby.c on_key pattern, #157). */
+static VALUE cr_key_str(const char* p, size_t len) {
+    return rb_enc_interned_str(p, (long)len, cr_utf8_enc);
+}
+
+#include "cbor/sink.h"
+#include "dom/dom.h"
+#include "doc.h" /* the public YeptrisDocument wrapper: ->dom */
+#include <yeptris/cbor.h>
+#include <yeptris/dom.h>
+#include <yeptris/resolve.h>
+
+/* ---- the VALUE sink (#157): bytes -> VALUE in ONE pass ----
+ *
+ * The decode grammar drives; these callbacks build the same VALUEs
+ * the old DOM + cr_walk pair produced (verified by the binding's
+ * differential suite): nil/true/false by tag, ints via LL2NUM (the
+ * INT64_MIN text parity wart kept), floats via DBL2NUM (no
+ * text round trip), strings copied utf8 (byte strings today ride the
+ * same utf8 String), map keys interned (values never are).
+ *
+ * GC: the container stack is a Ruby array (every VALUE reachable);
+ * the input buffer is read directly, so decode runs with GC disabled
+ * (the caller's String may move otherwise — the #160 bus error). */
+
+struct rv_ctx {
+    VALUE stack; /* [.., container, (pending-key)?] */
+    VALUE root;  /* Qnil until the top item closes */
+};
+
+static VALUE rv_top(const struct rv_ctx* c) {
+    long n = RARRAY_LEN(c->stack);
+    return n > 0 ? rb_ary_entry(c->stack, n - 1) : Qnil;
+}
+
+static VALUE rv_attach(struct rv_ctx* c, VALUE v) {
+    VALUE top = rv_top(c);
+    if (RB_TYPE_P(top, T_ARRAY)) {
+        rb_ary_push(top, v);
+        return v;
+    }
+    if (RB_TYPE_P(top, T_HASH)) {
+        rb_ary_push(c->stack, v); /* becomes the pending key */
+        return v;
+    }
+    /* a pending key: pop it, land v in the map */
+    VALUE k = rb_ary_pop(c->stack);
+    VALUE map = rv_top(c);
+    if (RB_TYPE_P(map, T_HASH)) {
+        rb_hash_aset(map, k, v);
+        return v;
+    }
+    /* the stack emptied: v is the root */
+    c->root = v;
+    return v;
+}
+
+static int rv_text(void* ctx, const char* s, uint32_t n, uint8_t tag_id, int is_key,
+                   const char* tag, uint32_t tag_len) {
+    (void)tag;
+    (void)tag_len;
+    struct rv_ctx* c = ctx;
+    VALUE v;
+    switch (tag_id) {
+    case YEPTRIS_TAG_NULL:
+        v = Qnil;
+        break;
+    case YEPTRIS_TAG_BOOL:
+        v = (n == 4 && memcmp(s, "true", 4) == 0) ? Qtrue : Qfalse;
+        break;
+    default: /* rendered text (diagnostics, simple(N), key ints) */
+        v = rb_utf8_str_new(s, (long)n);
+        break;
+    }
+    (void)is_key;
+    rv_attach(c, v);
+    return 1;
+}
+
+static int rv_int(void* ctx, int negative, uint64_t mag, int is_key, const char* tag,
+                  uint32_t tag_len) {
+    (void)tag;
+    (void)tag_len;
+    struct rv_ctx* c = ctx;
+    VALUE v;
+    if (negative && mag == (uint64_t)1 << 63) {
+        /* parity: the DOM path's strtoll guard renders INT64_MIN a
+         * String today; the differential suite pins it */
+        v = rb_utf8_str_new("-9223372036854775808", 20);
+    } else {
+        v = LL2NUM(negative ? -(int64_t)mag : (int64_t)mag);
+    }
+    rv_attach(c, v);
+    return 1;
+}
+
+static int rv_float(void* ctx, double dv, int is_key, const char* tag, uint32_t tag_len) {
+    (void)is_key;
+    (void)tag;
+    (void)tag_len;
+    rv_attach(ctx, DBL2NUM(dv));
+    return 1;
+}
+
+static int rv_str(void* ctx, const unsigned char* p, uint32_t n, int borrowed, int is_key,
+                  const char* tag, uint32_t tag_len) {
+    (void)borrowed;
+    (void)tag;
+    (void)tag_len;
+    struct rv_ctx* c = ctx;
+    VALUE v = is_key ? rb_enc_interned_str((const char*)p, (long)n, cr_utf8_enc)
+                     : rb_utf8_str_new((const char*)p, (long)n);
+    rv_attach(c, v);
+    return 1;
+}
+
+static int rv_bytes(void* ctx, const unsigned char* p, uint32_t n, int borrowed, int is_key,
+                    const char* tag, uint32_t tag_len) {
+    /* parity: byte strings ride the same utf8 String today */
+    return rv_str(ctx, p, n, borrowed, is_key, tag, tag_len);
+}
+
+static int rv_open(void* ctx, int is_map, uint64_t cap, const char* tag, uint32_t tag_len) {
+    (void)tag;
+    (void)tag_len;
+    struct rv_ctx* c = ctx;
+    VALUE v;
+    if (is_map) {
+        v = (cap != UINT64_MAX && cap / 2 <= 4096) ? HASH_NEW_CAPA((long)(cap / 2))
+                                                   : rb_hash_new();
+    } else {
+        v = (cap != UINT64_MAX && cap <= 8192) ? rb_ary_new_capa((long)cap) : rb_ary_new();
+    }
+    rb_ary_push(c->stack, v);
+    return 1;
+}
+
+static int rv_close(void* ctx, int is_map) {
+    (void)is_map;
+    struct rv_ctx* c = ctx;
+    VALUE v = rb_ary_pop(c->stack);
+    rv_attach(c, v);
+    return 1;
+}
+
+VALUE yep_rb_cbor_load(const char* p, size_t len, int strict) {
+    if (cr_utf8_enc == NULL) {
+        cr_utf8_enc = rb_utf8_encoding();
+    }
+    YeptrisStatus st = YEPTRIS_OK;
+    /* the decoder reads the caller's buffer directly; GC off across
+     * the pass (a compaction would move the String under p — the
+     * #160 bus error) */
+    VALUE gc_on = rb_gc_disable();
+    struct rv_ctx ctx;
+    ctx.stack = rb_ary_new();
+    ctx.root = Qnil;
+    static const yep_cbor_sink RV_SINK = {
+        NULL, rv_text, rv_int, rv_float, rv_str, rv_bytes, rv_open, rv_close,
+    };
+    yep_cbor_sink sink = RV_SINK;
+    sink.ctx = &ctx;
+    st = yep_cbor_decode_gen((const unsigned char*)p, len, strict, NULL, &sink);
+    if (RTEST(gc_on)) {
+        rb_gc_enable();
+    }
+    if (st != YEPTRIS_OK) {
+        return Qundef;
+    }
+    return ctx.root;
+}

data/ext/yeptris_native/extconf.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "mkmf"
+
+# libyeptris location: YEPTRIS_LIB_PATH (file or dir), then sibling
+# checkouts. CI sets YEPTRIS_LIB_PATH (the built shared library) and
+# YEPTRIS_SRC (the C checkout) explicitly.
+lib_path = ENV["YEPTRIS_LIB_PATH"]
+candidates = []
+if lib_path
+  candidates << File.dirname(lib_path)
+  candidates << lib_path if File.directory?(lib_path)
+end
+candidates << File.expand_path("../../../../yeptris/build-validate/src", __dir__)
+candidates << File.expand_path("../../../../yeptris/build/src", __dir__)
+candidates << File.expand_path("../../../yeptris/build-validate/src", __dir__)
+candidates << File.expand_path("../../../yeptris/build/src", __dir__)
+
+# Source root: YEPTRIS_SRC (CI / explicit), then sibling checkouts.
+src_roots = [ENV["YEPTRIS_SRC"]].compact
+src_roots << File.expand_path("../../../../yeptris/src", __dir__)
+src_roots << File.expand_path("../../../yeptris/src", __dir__)
+src_root = src_roots.find { |d| d && File.directory?(File.join(d, "include")) }
+abort "yeptris sources not found (set YEPTRIS_SRC)" unless src_root
+
+$INCFLAGS << " -I#{src_root}/include -I#{src_root}/yeptris"
+%w[build-validate/generated build/generated].each do |g|
+  d = File.join(File.dirname(src_root), g)
+  $INCFLAGS << " -I#{d}" if File.directory?(d)
+end
+
+libdir = candidates.find do |d|
+  d && File.directory?(d) && Dir[File.join(d, "libyeptris*.{dylib,so,dll}")].any?
+end
+abort "libyeptris not found (set YEPTRIS_LIB_PATH)" unless libdir
+
+$LIBPATH << libdir
+# Platform gems bake a RELATIVE rpath so the bundle finds the
+  # vendored libyeptris next to itself; absolute build-time paths
+  # would dangle on user machines.
+  rpath = ENV["YEPTRIS_RPATH"] || libdir
+  $LDFLAGS << " -Wl,-rpath,#{rpath}" if RUBY_PLATFORM =~ /linux|darwin/
+have_library("yeptris", "yep_json_string") or abort "yep_json_string not exported — rebuild libyeptris"
+have_library("yeptris", "yeptris_visit_json") or abort "yeptris_visit_json missing"
+
+$CFLAGS << " -O3 -fvisibility=hidden" unless RUBY_PLATFORM =~ /mswin|mingw/
+create_makefile("yeptris/native")