teptris 0.2.52 → 0.2.54

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2537428f82b791a55389c0be4bb2eaa2115f118238839705a913e51da11e6af1
-  data.tar.gz: a95d1d2b3f582803ef44c0bacbc1ec9172a9cf044c30cf56a488963f575c4007
+  metadata.gz: d87bfa72c18905691d707f6025a6a38c50145e3b3fbdd852ae684a23b02cf5de
+  data.tar.gz: da1577dbc5917511ea6013c686b1ae9e33cdc8e344af69bbd73f884d9e658814
 SHA512:
-  metadata.gz: 2a8d04664b9cb79842b466a7bc4e877e167ff61aaa58258c2e2419363d601d75ad759913f439c3f722c0b3ceccee603548414dcbcf828aa169acd00793fad92c
-  data.tar.gz: 27633d7ecf115edbb86be8b669552b8bdd4ccc427aacd1c775dea017a4a143aa7df267a4dfb0ffa59de3f1e827f0056f6e6989f16e022ee808d277ee2e32bcc8
+  metadata.gz: 3207652a5292daeafb0f790cb91da4497f9f83d860dc13cdbef03c0fe8d728daa69fd5e012cfd529b6a678e14298c9af1e6e9c5fd36715a74590922ccb336e02
+  data.tar.gz: 0e193983d8e3913b8b23c4d337fd6f1874cb8992fd7d28a82f7dddceba96d93a1038ec1cff203ac437281ab2b9c44a853092b54caefb669cb8bbfbcfeab896d0

data/Steepfile

@@ -0,0 +1,10 @@
+target :lib do
+  signature "sig"
+  library "date"
+
+  check "lib"
+
+  configure_code_diagnostics do |hash|
+    # keep the lane green while signatures evolve
+  end
+end

data/ext/teptris_ext/materialize.c

@@ -256,28 +256,6 @@ static void *parse_without_gvl(void *p)
     return NULL;
 }
 
-static teptris_document *parse_or_raise(VALUE str) {
-    teptris_document *doc = NULL;
-    /* frozen strings cannot take the tmp lock (ruby 4.0 raises
-     * FrozenError - chilled literals); a dup is movable-page-safe the
-     * same way, at one input copy for frozen callers only */
-    volatile VALUE pin = OBJ_FROZEN(str) ? rb_str_dup(str) : str;
-    rb_str_locktmp(pin);
-    struct gvl_parse_arg arg = {RSTRING_PTR(pin), (size_t)RSTRING_LEN(pin),
-                                &doc, TEPTRIS_OK};
-    rb_thread_call_without_gvl(parse_without_gvl, &arg, RUBY_UBF_IO, NULL);
-    rb_str_unlocktmp(pin);
-    teptris_status st = arg.st;
-    if (st != TEPTRIS_OK) {
-        const teptris_error *e = teptris_document_error(doc);
-        VALUE ex = rb_exc_new(eParseError, e->message, (long)strlen(e->message));
-        rb_iv_set(ex, "@line", SIZET2NUM(e->line));
-        rb_iv_set(ex, "@column", SIZET2NUM(e->column));
-        teptris_document_free(doc);
-        rb_exc_raise(ex);
-    }
-    return doc;
-}
 
 static VALUE ext_load(int argc, VALUE *argv, VALUE self) {
     VALUE str, opts;
@@ -292,11 +270,29 @@ static VALUE ext_load(int argc, VALUE *argv, VALUE self) {
         if (RTEST(ft)) flags |= FMT_FORBID_TIME;
         if (RTEST(fd)) flags |= FMT_FORBID_DATE;
     }
-    teptris_document *doc = parse_or_raise(str);
+    /* the parse is pure C over a private copy, GVL-free; the copy
+     * must outlive materialization - the document's strings are
+     * zero-copy views into it (a real UAF on glibc when freed early) */
+    long len = RSTRING_LEN(str);
+    char *cbuf = ALLOC_N(char, (size_t)len + 1);
+    memcpy(cbuf, RSTRING_PTR(str), (size_t)len);
+    teptris_document *doc = NULL;
+    struct gvl_parse_arg arg = {cbuf, (size_t)len, &doc, TEPTRIS_OK};
+    rb_thread_call_without_gvl(parse_without_gvl, &arg, RUBY_UBF_IO, NULL);
+    if (arg.st != TEPTRIS_OK) {
+        const teptris_error *e = teptris_document_error(doc);
+        VALUE ex = rb_exc_new(eParseError, e->message, (long)strlen(e->message));
+        rb_iv_set(ex, "@line", SIZET2NUM(e->line));
+        rb_iv_set(ex, "@column", SIZET2NUM(e->column));
+        xfree(cbuf);
+        teptris_document_free(doc);
+        rb_exc_raise(ex);
+    }
     keycache kc;
     kc_init(&kc);
     VALUE out = obj_from_node(teptris_document_root(doc), flags, &kc);
     kc_free(&kc);
+    xfree(cbuf);
     teptris_document_free(doc);
     return out;
 }
@@ -741,7 +737,8 @@ static VALUE cLazyOwner, cLazyValue;
 
 typedef struct {
     teptris_document *doc;
-    VALUE input; /* the borrowed views' buffer */
+    VALUE input; /* single-doc path: owned frozen copy (GC-marked) */
+    char *buf;   /* batch path: owned input copy the doc's views use */
 } lazy_owner;
 
 typedef struct {
@@ -752,12 +749,18 @@ typedef struct {
 static void lazy_owner_free(void *p) {
     lazy_owner *o = (lazy_owner *)p;
     if (o->doc != NULL) teptris_document_free(o->doc);
+    if (o->buf != NULL) xfree(o->buf);
     xfree(o);
 }
 static size_t lazy_owner_size(const void *p) { return sizeof(lazy_owner); }
+static void lazy_owner_mark(void *p)
+{
+    lazy_owner *o = (lazy_owner *)p;
+    if (o->input) rb_gc_mark(o->input); /* roots the single-path copy */
+}
 static const rb_data_type_t lazy_owner_type = {
     "TeptrisExt/LazyOwner",
-    {NULL, lazy_owner_free, lazy_owner_size, NULL, 0},
+    {lazy_owner_mark, lazy_owner_free, lazy_owner_size, NULL, 0},
     NULL, NULL, RUBY_TYPED_FREE_IMMEDIATELY};
 
 static void lazy_value_mark(void *p) {
@@ -792,7 +795,7 @@ static VALUE ext_load_lazy(VALUE self, VALUE toml) {
     VALUE owner = TypedData_Make_Struct(cLazyOwner, lazy_owner,
                                         &lazy_owner_type, o);
     o->doc = NULL;
-    o->input = rb_str_new_frozen(toml); /* borrowed views: own a copy */
+    o->input = rb_str_new_frozen(toml); /* owned frozen copy */
     teptris_status st = teptris_parse(RSTRING_PTR(o->input),
                                       (size_t)RSTRING_LEN(o->input),
                                       NULL, &o->doc);
@@ -973,25 +976,53 @@ static unsigned flags_from_opts(VALUE opts) {
 /* Parse-only batch (returns an Array of Lazy wrappers, one per doc):
  * eager parse, deferred materialization. Same per-doc error semantics
  * as ext_load_lazy. */
+struct batch_parse_arg {
+    const char **data;
+    size_t *lens;
+    size_t n;
+    teptris_document **docs;
+    teptris_status *statuses;
+    teptris_status batch;
+};
+
+static void *batch_parse_without_gvl(void *p)
+{
+    struct batch_parse_arg *a = (struct batch_parse_arg *)p;
+    a->batch = teptris_parse_batch(a->data, a->lens, a->n, NULL,
+                                   a->docs, a->statuses);
+    return NULL;
+}
+
 static VALUE ext_load_lazy_batch(VALUE self, VALUE strings) {
     Check_Type(strings, T_ARRAY);
     long n = RARRAY_LEN(strings);
     if (n == 0) return rb_ary_new();
     batch_scratch *s = batch_scratch_alloc(n);
     if (s == NULL) rb_raise(eError, "out of memory batching %ld documents", n);
+    /* the batch parse is pure C: pin every input (one tmp lock per
+     * string - repeated objects dup; frozen strings cannot take the
+     * lock, yet compaction can move them) and release the GVL for the
+     * whole parse */
+    /* the batch parse is pure C over private copies: a Ruby-string
+     * buffer can move under a concurrent compacting GC, and locktmp
+     * does not pin on every platform - copies are C memory, immovable
+     * by construction. Each LazyOwner owns its copy (freed with the
+     * owner): the lazy nodes view these buffers until materialized. */
+    char **bufs = ALLOC_N(char *, n);
     for (long i = 0; i < n; i++) {
         VALUE str = rb_ary_entry(strings, i);
         StringValue(str); /* raises TypeError if not coercible */
-        s->data[i] = RSTRING_PTR(str);
-        s->lens[i] = (size_t)RSTRING_LEN(str);
-    }
-    teptris_status batch =
-        teptris_parse_batch(s->data, s->lens, (size_t)n, NULL,
-                            s->docs, s->statuses);
-    if (batch != TEPTRIS_OK) {
-        batch_scratch_free(s);
-        rb_raise(eError, "batch parse failed (status %d)", (int)batch);
+        long len = RSTRING_LEN(str);
+        bufs[i] = ALLOC_N(char, (size_t)len + 1);
+        memcpy(bufs[i], RSTRING_PTR(str), (size_t)len);
+        s->data[i] = bufs[i];
+        s->lens[i] = (size_t)len;
     }
+    struct batch_parse_arg arg = {s->data, s->lens, (size_t)n,
+                                  s->docs, s->statuses, TEPTRIS_OK};
+    rb_thread_call_without_gvl(batch_parse_without_gvl, &arg,
+                               RUBY_UBF_IO, NULL);
+    teptris_status batch = arg.batch;
     long first_fail = -1;
     for (long i = 0; i < n; i++) {
         if (s->statuses[i] != TEPTRIS_OK && first_fail == -1) first_fail = i;
@@ -1012,7 +1043,7 @@ static VALUE ext_load_lazy_batch(VALUE self, VALUE strings) {
         VALUE owner = TypedData_Make_Struct(cLazyOwner, lazy_owner,
                                             &lazy_owner_type, o);
         o->doc = s->docs[i];
-        o->input = rb_ary_entry(strings, i);
+        o->buf = bufs[i]; /* the owner owns this copy */
         rb_ary_push(out, lazy_wrap(owner, teptris_document_root(s->docs[i])));
     }
     batch_scratch_free(s);
@@ -1053,35 +1084,29 @@ static VALUE ext_load_slice(int argc, VALUE *argv, VALUE self) {
     if (n == 0) return rb_ary_new();
     unsigned flags = flags_from_opts(opts);
 
-    volatile VALUE *pins = ALLOC_N(VALUE, n);
+    /* the GVL-free parse reads private copies: a Ruby-string buffer
+     * can move under a concurrent compacting GC, and locktmp does not
+     * pin on every platform (windows ruby 3.3 parsed garbage). Copies
+     * are C memory - immovable by construction. Freed after
+     * materialization (the docs view them until then). */
     const char **data = ALLOC_N(const char *, n);
     size_t *lens = ALLOC_N(size_t, n);
     teptris_document **docs = ALLOC_N(teptris_document *, n);
     teptris_status *stats = ALLOC_N(teptris_status, n);
-    /* the tmp lock is one-per-string: repeated objects in the slice
-     * get a dup before pinning (frozen inputs dup for the same reason
-     * - they cannot take the lock, yet compaction can move them) */
-    VALUE seen = rb_hash_new();
+    char **bufs = ALLOC_N(char *, n);
     long i;
     for (i = 0; i < n; i++) {
         VALUE str = rb_ary_entry(strs, i);
         StringValue(str);
-        VALUE id = rb_obj_id(str);
-        if (!NIL_P(rb_hash_aref(seen, id))) {
-            str = rb_str_dup(str);
-        } else {
-            rb_hash_aset(seen, id, Qtrue);
-            if (OBJ_FROZEN(str)) str = rb_str_dup(str);
-        }
-        pins[i] = str;
-        rb_str_locktmp(pins[i]);
-        data[i] = RSTRING_PTR(pins[i]);
-        lens[i] = (size_t)RSTRING_LEN(pins[i]);
+        long len = RSTRING_LEN(str);
+        bufs[i] = ALLOC_N(char, (size_t)len + 1);
+        memcpy(bufs[i], RSTRING_PTR(str), (size_t)len);
+        data[i] = bufs[i];
+        lens[i] = (size_t)len;
     }
     struct slice_parse_arg arg = {n, data, lens, docs, stats};
     rb_thread_call_without_gvl(slice_parse_without_gvl, &arg,
                                RUBY_UBF_IO, NULL);
-    for (i = 0; i < n; i++) rb_str_unlocktmp(pins[i]);
 
     VALUE out = rb_ary_new_capa(n);
     keycache kc;
@@ -1091,7 +1116,7 @@ static VALUE ext_load_slice(int argc, VALUE *argv, VALUE self) {
             const char *msg = "parse failed (out of memory)";
             VALUE ex = rb_exc_new(eParseError, msg, (long)strlen(msg));
             kc_free(&kc);
-            xfree(pins); xfree(data); xfree(lens); xfree(docs); xfree(stats);
+            xfree(data); xfree(lens); xfree(docs); xfree(stats);
             rb_exc_raise(ex);
         }
         const teptris_error *e = teptris_document_error(docs[i]);
@@ -1103,7 +1128,7 @@ static VALUE ext_load_slice(int argc, VALUE *argv, VALUE self) {
             long j;
             for (j = i; j < n; j++) teptris_document_free(docs[j]);
             kc_free(&kc);
-            xfree(pins); xfree(data); xfree(lens); xfree(docs); xfree(stats);
+            xfree(data); xfree(lens); xfree(docs); xfree(stats);
             rb_exc_raise(ex);
         }
     }
@@ -1113,7 +1138,7 @@ static VALUE ext_load_slice(int argc, VALUE *argv, VALUE self) {
         teptris_document_free(docs[i]);
     }
     kc_free(&kc);
-    xfree(pins); xfree(data); xfree(lens); xfree(docs); xfree(stats);
+    xfree(data); xfree(lens); xfree(docs); xfree(stats);
     return out;
 }
 

data/lib/teptris/descriptor.rb

@@ -32,7 +32,9 @@ class Teptris::Descriptor
     # siblings that follow a :nested child into the sub-plan's range —
     # the 0.2.29 bug (every array-of-tables element grew stray nil
     # rows).
+    # @type var plans: Array[Hash[Symbol, untyped]]
     plans = []
+    # @type var index_of: Hash[Integer, Integer]
     index_of = {}
     collect = lambda do |t|
       unless index_of.key?(t.object_id)

data/lib/teptris/toml.rb

@@ -25,6 +25,7 @@ module Teptris
         unless %i[native string].include?(datetime_policy)
           raise ArgumentError, "datetime_policy must be :native or :string"
         end
+        # @type var opts: Hash[Symbol, untyped]
         opts = {}
         opts[:string_datetimes] = true if datetime_policy == :string
         if permitted_classes && datetime_policy == :native
@@ -69,6 +70,7 @@ module Teptris
         # Repeated objects are dup'd once each HERE: a repeat landing in
         # two slices would double-lock across threads (the slice-level
         # guard cannot see across slices); frozen dup'ing is C-side.
+        # @type var seen: Hash[Integer, bool]
         seen = {}
         tomls = tomls.map do |s|
           next s.dup if seen[s.object_id]
@@ -77,6 +79,7 @@ module Teptris
         end
         per = (n.to_f / threads).ceil
         results = Array.new(n)
+        # @type var first_error: [Integer, untyped]?
         first_error = nil
         mutex = Mutex.new
         threads.times.map do |ti|
@@ -157,6 +160,7 @@ module Teptris
       end
 
       def _safe_load_opts(safe_load, datetime_policy)
+        # @type var opts: Hash[Symbol, untyped]
         opts = {}
         opts[:string_datetimes] = true if datetime_policy == :string
         if safe_load && datetime_policy == :native

data/lib/teptris/version.rb

@@ -1,3 +1,3 @@
 module Teptris
-  VERSION = "0.2.52"
+  VERSION = "0.2.54"
 end

data/sig/teptris.rbs

@@ -0,0 +1,131 @@
+module Teptris
+  VERSION: String
+
+  # mirrored from the engine's teptris_status (lib/teptris.rb)
+  TEPTRIS_OK: Integer
+
+  class Error < StandardError
+  end
+
+  class ParseError < Error
+    attr_reader line: Integer
+    attr_reader column: Integer
+
+    def initialize: (String message, ?Integer line, ?Integer column) -> void
+  end
+
+  module TOML
+    VERSION: String
+
+    # Eager load: String -> Hash with String keys. Datetime contract
+    # (the tomlib shape): Time with zone for offset datetimes, local
+    # Time for local datetimes, Date for dates, "HH:MM:SS" String for
+    # local times.
+    def self.load: (String toml) -> Hash[String, untyped]
+
+    def self.load_file: (String path) -> Hash[String, untyped]
+
+    def self.safe_load: (String toml, ?permitted_classes: Array[Class]?,
+                         ?datetime_policy: :native | :string)
+                       -> Hash[String, untyped]
+
+    # One parse; host objects materialize only along accessed paths.
+    def self.load_lazy: (String toml) -> TeptrisExt::LazyValue
+
+    def self.load_batch: (Array[String] tomls, ?safe_load: Array[Class]?,
+                          ?datetime_policy: :native | :string,
+                          ?threads: Integer)
+                        -> Array[Hash[String, untyped]]
+
+    def self.load_lazy_batch: (Array[String] tomls)
+                            -> Array[TeptrisExt::LazyValue]
+
+    def self.load_files: (Array[String] paths, ?safe_load: Array[Class]?,
+                          ?datetime_policy: :native | :string)
+                        -> Array[Hash[String, untyped]]
+
+    def self.load_schema: (String toml, Descriptor descriptor)
+                         -> Hash[String, untyped]
+
+    def self.dump: (untyped obj) -> String
+
+    def self.engine_version: () -> String
+
+    def self._validate_batch!: (untyped input, untyped safe_load,
+                                :native | :string datetime_policy,
+                                ?kind: Symbol) -> void
+
+    def self._safe_load_opts: (untyped safe_load,
+                               :native | :string datetime_policy)
+                             -> Hash[Symbol, untyped]?
+  end
+
+  # Tree-shaped schema descriptor: compile once with .build, then
+  # materialize documents against it with #walk — unplanned keys are
+  # never materialized (the py twin is teptris.Descriptor).
+  class Descriptor
+    KINDS: Hash[Symbol, Integer]
+
+    def self.build: (Hash[Symbol, untyped] tree) -> Descriptor
+
+    attr_reader rows: Array[[String, Integer, Integer]]
+    attr_reader first_row: Array[Integer]
+
+    def walk: (String toml) -> Hash[String, untyped]
+  end
+end
+
+# The C extension's surface (defined in ext/teptris_ext). The gem's
+# public API is Teptris::TOML; these module functions are the binding
+# layer underneath it.
+module TeptrisExt
+  # Lazy wrapper: one parse, scalars materialize on access, to_h/to_a
+  # flatten to the eager shapes.
+  class LazyValue
+    def []: (String key) -> (LazyValue | untyped)
+           | (Integer index) -> (LazyValue | untyped)
+
+    def at: (Integer index) -> (LazyValue | untyped)
+
+    def dig: (*String keys) -> (LazyValue | untyped)
+
+    def kind: () -> String
+
+    def size: () -> Integer
+
+    def each: () { (LazyValue | untyped) -> void } -> LazyValue
+             | () -> Enumerator[LazyValue | untyped, LazyValue]
+
+    def value: () -> untyped
+
+    def to_h: () -> Hash[String, untyped]
+
+    def to_a: () -> Array[untyped]
+
+    def ==: (untyped other) -> bool
+
+    include Enumerable[LazyValue | untyped]
+  end
+
+  def self.load: (String toml, ?Hash[Symbol, untyped]? opts)
+               -> Hash[String, untyped]
+
+  def self.load_lazy: (String toml) -> LazyValue
+
+  def self.load_batch: (Array[String] tomls, Hash[Symbol, untyped]? opts)
+                     -> Array[Hash[String, untyped]]
+
+  def self.load_slice: (Array[String] tomls, Hash[Symbol, untyped]? opts)
+                     -> Array[Hash[String, untyped]]
+
+  def self.load_lazy_batch: (Array[String] tomls) -> Array[LazyValue]
+
+  def self.dump: (untyped obj) -> String
+
+  def self.engine_version: () -> String
+
+  def self.plan_build: (Array[[String, Integer, Integer]] rows,
+                        Array[Integer] first_row) -> untyped
+
+  def self.plan_emit: (untyped handle, String toml) -> Hash[String, untyped]
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: teptris
 version: !ruby/object:Gem::Version
-  version: 0.2.52
+  version: 0.2.54
 platform: ruby
 authors:
 - teptris contributors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-01 00:00:00.000000000 Z
+date: 2026-10-04 00:00:00.000000000 Z
 dependencies: []
 description: A native C extension over libteptris, a C99 TOML 1.1 parser/emitter.
   API shape mirrors the tomlib gem.
@@ -18,6 +18,7 @@ extensions:
 - ext/teptris_ext/extconf.rb
 extra_rdoc_files: []
 files:
+- Steepfile
 - ext/teptris_ext/engine/LICENSE.md
 - ext/teptris_ext/engine/README.md
 - ext/teptris_ext/engine/src/include/teptris/plan.h
@@ -56,6 +57,7 @@ files:
 - lib/teptris/error.rb
 - lib/teptris/toml.rb
 - lib/teptris/version.rb
+- sig/teptris.rbs
 homepage: https://github.com/leptris/teptris-ruby
 licenses:
 - MIT