mini_racer 0.19.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5923ad9b3aa9cdea7785f0f2eb3fa27357217d0feb5ed439dad46b5ea7eaea8f
-  data.tar.gz: ffac8a1b740c74467f40e0200730a3fe25892d63105022f8775fe8aaffdcdd20
+  metadata.gz: 5aa16bf587a6e12df562d7a946ce3a965a8444debd9769b376075cafd10a3b5c
+  data.tar.gz: 5aaf6a08ae90f05bc554bae0a06e93efce5318d00aacdfe959f36513533caac4
 SHA512:
-  metadata.gz: 0f8ab9852328121e3d55119fb1a2a8a875806b0a256d2c79ab09846fe2ed7df174beb68949213057fe8186376b73993b21dc21fe22ce82632f26e0a4354c982e
-  data.tar.gz: 88c0a37a5a26ab746312c76499a202578a0604098a1ec3fcf7b98110aace6facd95490b19bd0f6abb8afba136b9ae94f5f1367d55050d6abdcf62bd628d6b8f2
+  metadata.gz: 2b2641ceb0fd1770efd32cfb9e37aee92ca857ad6acbe2129157a58be9ed6bbef4a355c5af133f5749f229d578e10a452ef77a62eadbe436993f005146d242cd
+  data.tar.gz: 3264e95d4951aa52ba080a94b847c5080705e1de0e3dd5fefae0786342ccece850b00db4f151220e65068e9e5d62fb0eebae0fda65e79647196903fae70d8012

data/CHANGELOG

@@ -1,3 +1,14 @@
+- 0.20.0 - 24-02-2026
+  - Add Snapshot.load to restore snapshots from binary data, enabling disk persistence
+
+- 0.19.2 - 24-12-2025
+  - upgrade to node 24.12.0
+
+- 0.19.1 - 20-10-2025
+  - JS code can now catch ruby exceptions - Ben Noordhuis
+  - Retain string encoding when raising exceptions - Ben Noordhuis
+  - Fix object identity bug with Ruby to JS conversion - Benjamin Wood
+
 - 0.19.0 - 24-06-2025
   - upgrade to node 24.1.0 
 

data/README.md

@@ -193,6 +193,25 @@ context.eval("counter")
 # => 1
 ```
 
+Snapshots can also be persisted to disk for faster startup:
+
+```ruby
+# Save a snapshot to disk
+snapshot = MiniRacer::Snapshot.new('var foo = "bar";')
+File.binwrite("snapshot.bin", snapshot.dump)
+
+# Load it back in a later process
+blob = File.binread("snapshot.bin")
+snapshot = MiniRacer::Snapshot.load(blob)
+context = MiniRacer::Context.new(snapshot: snapshot)
+context.eval("foo")
+# => "bar"
+```
+
+Note that snapshots are architecture and V8-version specific. A snapshot created on one platform (e.g., ARM64 macOS) cannot be loaded on a different platform (e.g., x86_64 Linux). Snapshots are best used for same-machine caching or homogeneous deployment environments.
+
+**Security note:** Only load snapshots from trusted sources. V8 snapshots are not designed to be safely loaded from untrusted input—malformed or malicious snapshot data may cause crashes or memory corruption.
+
 ### Garbage collection
 
 You can make the garbage collector more aggressive by defining the context with `MiniRacer::Context.new(ensure_gc_after_idle: 1000)`. Using this will ensure V8 will run a full GC using `context.low_memory_notification` 1 second after the last eval on the context. Low memory notifications ensure long living contexts use minimal amounts of memory.

data/ext/mini_racer_extension/mini_racer_extension.c

@@ -6,6 +6,30 @@
 #include <pthread.h>
 #include <math.h>
 
+#if defined(__linux__) && !defined(__GLIBC__)
+// musl compatibility for glibc-linked libraries (e.g. libv8-node)
+// some versions of libv8-node are accidentally linked against glibc symbols
+// or compiled with a toolchain that emits these C23 compatibility symbols
+unsigned long long __isoc23_strtoull(const char *nptr, char **endptr, int base) {
+    return strtoull(nptr, endptr, base);
+}
+unsigned long __isoc23_strtoul(const char *nptr, char **endptr, int base) {
+    return strtoul(nptr, endptr, base);
+}
+long long __isoc23_strtoll(const char *nptr, char **endptr, int base) {
+    return strtoll(nptr, endptr, base);
+}
+long __isoc23_strtol(const char *nptr, char **endptr, int base) {
+    return strtol(nptr, endptr, base);
+}
+double __isoc23_strtod(const char *nptr, char **endptr) {
+    return strtod(nptr, endptr);
+}
+float __isoc23_strtof(const char *nptr, char **endptr) {
+    return strtof(nptr, endptr);
+}
+#endif
+
 #include "ruby.h"
 #include "ruby/encoding.h"
 #include "ruby/version.h"
@@ -13,6 +37,13 @@
 #include "serde.c"
 #include "mini_racer_v8.h"
 
+// for debugging
+#define RB_PUTS(v)                                          \
+    do {                                                    \
+        fflush(stdout);                                     \
+        rb_funcall(rb_mKernel, rb_intern("puts"), 1, v);    \
+    } while (0)
+
 #if RUBY_API_VERSION_CODE < 3*10000+4*100 // 3.4.0
 static inline void rb_thread_lock_native_thread(void)
 {
@@ -154,6 +185,7 @@ static VALUE platform_init_error;
 static VALUE context_disposed_error;
 static VALUE parse_error;
 static VALUE memory_error;
+static VALUE script_error;
 static VALUE runtime_error;
 static VALUE internal_error;
 static VALUE snapshot_error;
@@ -482,12 +514,36 @@ static void des_object_ref(void *arg, uint32_t id)
 
 static void des_error_begin(void *arg)
 {
-    push(arg, rb_class_new_instance(0, NULL, rb_eRuntimeError));
+    push(arg, rb_ary_new());
 }
 
 static void des_error_end(void *arg)
 {
-    pop(arg);
+    VALUE *a, h, message, stack, cause, newline;
+    DesCtx *c;
+
+    c = arg;
+    if (*c->err)
+        return;
+    if (c->tos == c->stack) {
+        snprintf(c->err, sizeof(c->err), "stack underflow");
+        return;
+    }
+    a = &c->tos->a;
+    h = rb_ary_pop(*a);
+    message = rb_hash_aref(h, rb_str_new_cstr("message"));
+    stack = rb_hash_aref(h, rb_str_new_cstr("stack"));
+    cause = rb_hash_aref(h, rb_str_new_cstr("cause"));
+    if (NIL_P(message))
+        message = rb_str_new_cstr("JS exception");
+    if (!NIL_P(stack)) {
+        newline = rb_str_new_cstr("\n");
+        message = rb_funcall(message, rb_intern("concat"), 2, newline, stack);
+    }
+    *a = rb_class_new_instance(1, &message, script_error);
+    if (!NIL_P(cause))
+        rb_iv_set(*a, "@cause", cause);
+    pop(c);
 }
 
 static int collect(VALUE k, VALUE v, VALUE a)
@@ -527,52 +583,58 @@ static int serialize1(Ser *s, VALUE refs, VALUE v)
         return -1;
     switch (TYPE(v)) {
     case T_ARRAY:
-        id = rb_hash_lookup(refs, v);
-        if (NIL_P(id)) {
-            n = RARRAY_LENINT(v);
-            i = rb_hash_size_num(refs);
-            rb_hash_aset(refs, v, LONG2FIX(i));
-            ser_array_begin(s, n);
-            for (i = 0; i < n; i++)
-                if (serialize1(s, refs, rb_ary_entry(v, i)))
-                    return -1;
-            ser_array_end(s, n);
-        } else {
-            ser_object_ref(s, FIX2LONG(id));
+        {
+            VALUE obj_id = rb_obj_id(v);
+            id = rb_hash_lookup(refs, obj_id);
+            if (NIL_P(id)) {
+                n = RARRAY_LENINT(v);
+                i = rb_hash_size_num(refs);
+                rb_hash_aset(refs, obj_id, LONG2FIX(i));
+                ser_array_begin(s, n);
+                for (i = 0; i < n; i++)
+                    if (serialize1(s, refs, rb_ary_entry(v, i)))
+                        return -1;
+                ser_array_end(s, n);
+            } else {
+                ser_object_ref(s, FIX2LONG(id));
+            }
         }
         break;
     case T_HASH:
-        id = rb_hash_lookup(refs, v);
-        if (NIL_P(id)) {
-            a = rb_ary_new();
-            i = rb_hash_size_num(refs);
-            n = rb_hash_size_num(v);
-            rb_hash_aset(refs, v, LONG2FIX(i));
-            rb_hash_foreach(v, collect, a);
-            for (i = 0; i < 2*n; i += 2) {
-                t = rb_ary_entry(a, i);
-                switch (TYPE(t)) {
-                case T_FIXNUM:
-                case T_STRING:
-                case T_SYMBOL:
-                    continue;
-                }
-                break;
-            }
-            if (i == 2*n) {
-                ser_object_begin(s);
+        {
+            VALUE obj_id = rb_obj_id(v);
+            id = rb_hash_lookup(refs, obj_id);
+            if (NIL_P(id)) {
+                a = rb_ary_new();
+                i = rb_hash_size_num(refs);
+                n = rb_hash_size_num(v);
+                rb_hash_aset(refs, obj_id, LONG2FIX(i));
+                rb_hash_foreach(v, collect, a);
                 for (i = 0; i < 2*n; i += 2) {
-                    if (serialize1(s, refs, rb_ary_entry(a, i+0)))
-                        return -1;
-                    if (serialize1(s, refs, rb_ary_entry(a, i+1)))
-                        return -1;
+                    t = rb_ary_entry(a, i);
+                    switch (TYPE(t)) {
+                    case T_FIXNUM:
+                    case T_STRING:
+                    case T_SYMBOL:
+                        continue;
+                    }
+                    break;
+                }
+                if (i == 2*n) {
+                    ser_object_begin(s);
+                    for (i = 0; i < 2*n; i += 2) {
+                        if (serialize1(s, refs, rb_ary_entry(a, i+0)))
+                            return -1;
+                        if (serialize1(s, refs, rb_ary_entry(a, i+1)))
+                            return -1;
+                    }
+                    ser_object_end(s, n);
+                } else {
+                    return bail(&s->err, "TODO serialize as Map");
                 }
-                ser_object_end(s, n);
             } else {
-                return bail(&s->err, "TODO serialize as Map");
+                ser_object_ref(s, FIX2LONG(id));
             }
-        } else {
-            ser_object_ref(s, FIX2LONG(id));
         }
         break;
     case T_DATA:
@@ -888,6 +950,7 @@ static VALUE rendezvous_callback_do(VALUE arg)
 static void *rendezvous_callback(void *arg)
 {
     struct rendezvous_nogvl *a;
+    const char *err;
     Context *c;
     int exc;
     VALUE r;
@@ -911,7 +974,12 @@ out:
     buf_move(&s.b, a->req);
     return NULL;
 fail:
-    ser_init1(&s, 'e'); // exception pending
+    ser_init0(&s);   // ruby exception pending
+    w_byte(&s, 'e'); // send ruby error message to v8 thread
+    r = rb_funcall(c->exception, rb_intern("to_s"), 0);
+    err = StringValueCStr(r);
+    if (err)
+        w(&s, err, strlen(err));
     goto out;
 }
 
@@ -969,6 +1037,13 @@ static VALUE rendezvous1(Context *c, Buf *req, DesCtx *d)
     int exc;
 
     rendezvous_no_des(c, req, &res); // takes ownership of |req|
+    r = c->exception;
+    c->exception = Qnil;
+    // if js land didn't handle exception from ruby callback, re-raise it now
+    if (res.len == 1 && *res.buf == 'e') {
+        assert(!NIL_P(r));
+        rb_exc_raise(r);
+    }
     r = rb_protect(deserialize, (VALUE)&(struct rendezvous_des){d, &res}, &exc);
     buf_reset(&res);
     if (exc) {
@@ -976,11 +1051,6 @@ static VALUE rendezvous1(Context *c, Buf *req, DesCtx *d)
         rb_set_errinfo(Qnil);
         rb_exc_raise(r);
     }
-    if (!NIL_P(c->exception)) {
-        r = c->exception;
-        c->exception = Qnil;
-        rb_exc_raise(r);
-    }
     return r;
 }
 
@@ -999,8 +1069,8 @@ static void handle_exception(VALUE e)
 
     if (NIL_P(e))
         return;
-    StringValue(e);
-    s = RSTRING_PTR(e);
+    e = StringValue(e);
+    s = StringValueCStr(e);
     switch (*s) {
     case NO_ERROR:
         return;
@@ -1022,7 +1092,7 @@ static void handle_exception(VALUE e)
     default:
         rb_raise(internal_error, "bad error class %02x", *s);
     }
-    rb_raise(klass, "%s", s+1);
+    rb_enc_raise(rb_enc_get(e), klass, "%s", s+1);
 }
 
 static VALUE context_alloc(VALUE klass)
@@ -1620,6 +1690,20 @@ static VALUE snapshot_dump(VALUE self)
     return ss->blob;
 }
 
+static VALUE snapshot_load(VALUE klass, VALUE blob)
+{
+    Snapshot *ss;
+    VALUE self;
+
+    Check_Type(blob, T_STRING);
+    self = snapshot_alloc(klass);
+    TypedData_Get_Struct(self, Snapshot, &snapshot_type, ss);
+    ss->blob = rb_str_dup(blob);
+    rb_enc_associate(ss->blob, rb_ascii8bit_encoding());
+    ENC_CODERANGE_SET(ss->blob, ENC_CODERANGE_VALID);
+    return self;
+}
+
 static VALUE snapshot_size0(VALUE self)
 {
     Snapshot *ss;
@@ -1628,6 +1712,11 @@ static VALUE snapshot_size0(VALUE self)
     return LONG2FIX(RSTRING_LENINT(ss->blob));
 }
 
+static VALUE script_error_cause(VALUE self)
+{
+    return rb_iv_get(self, "@cause");
+}
+
 __attribute__((visibility("default")))
 void Init_mini_racer_extension(void)
 {
@@ -1642,10 +1731,13 @@ void Init_mini_racer_extension(void)
     c = rb_define_class_under(m, "EvalError", c);
     parse_error = rb_define_class_under(m, "ParseError", c);
     memory_error = rb_define_class_under(m, "V8OutOfMemoryError", c);
+    script_error = rb_define_class_under(m, "ScriptError", c);
     runtime_error = rb_define_class_under(m, "RuntimeError", c);
     internal_error = rb_define_class_under(m, "InternalError", c);
     terminated_error = rb_define_class_under(m, "ScriptTerminatedError", c);
 
+    rb_define_method(script_error, "cause", script_error_cause, 0);
+
     c = context_class = rb_define_class_under(m, "Context", rb_cObject);
     rb_define_method(c, "initialize", context_initialize, -1);
     rb_define_method(c, "attach", context_attach, 2);
@@ -1664,6 +1756,7 @@ void Init_mini_racer_extension(void)
     rb_define_method(c, "warmup!", snapshot_warmup, 1);
     rb_define_method(c, "dump", snapshot_dump, 0);
     rb_define_method(c, "size", snapshot_size0, 0);
+    rb_define_singleton_method(c, "load", snapshot_load, 1);
     rb_define_alloc_func(c, snapshot_alloc);
 
     c = rb_define_class_under(m, "Platform", rb_cObject);

data/ext/mini_racer_extension/mini_racer_v8.cc

@@ -86,6 +86,7 @@ struct State
     v8::Persistent<v8::Context> persistent_context;         // single-thread mode only
     v8::Persistent<v8::Context> persistent_safe_context;    // single-thread mode only
     v8::Persistent<v8::Function> persistent_safe_context_function;  // single-thread mode only
+    v8::Persistent<v8::Value> ruby_exception;
     Context *ruby_context;
     int64_t max_memory;
     int err_reason;
@@ -122,6 +123,20 @@ struct Serialized
     }
 };
 
+bool bubble_up_ruby_exception(State& st, v8::TryCatch *try_catch)
+{
+    auto exception = try_catch->Exception();
+    if (exception.IsEmpty()) return false;
+    auto ruby_exception = v8::Local<v8::Value>::New(st.isolate, st.ruby_exception);
+    if (ruby_exception.IsEmpty()) return false;
+    if (!ruby_exception->SameValue(exception)) return false;
+    // signal that the ruby thread should reraise the exception
+    // that it caught earlier when executing a js->ruby callback
+    uint8_t c = 'e';
+    v8_reply(st.ruby_context, &c, 1);
+    return true;
+}
+
 // throws JS exception on serialization error
 bool reply(State& st, v8::Local<v8::Value> v)
 {
@@ -388,8 +403,17 @@ void v8_api_callback(const v8::FunctionCallbackInfo<v8::Value>& info)
         v8_roundtrip(st.ruby_context, &p, &n);
         if (*p == 'c') // callback reply
             break;
-        if (*p == 'e') // ruby exception pending
-            return st.isolate->TerminateExecution();
+        if (*p == 'e') { // ruby exception pending
+            v8::Local<v8::String> message;
+            auto type = v8::NewStringType::kNormal;
+            if (!v8::String::NewFromOneByte(st.isolate, p+1, type, n-1).ToLocal(&message)) {
+                message = v8::String::NewFromUtf8Literal(st.isolate, "Ruby exception");
+            }
+            auto exception = v8::Exception::Error(message);
+            st.ruby_exception.Reset(st.isolate, exception);
+            st.isolate->ThrowException(exception);
+            return;
+        }
         v8_dispatch(st.ruby_context);
     }
     v8::ValueDeserializer des(st.isolate, p+1, n-1);
@@ -523,6 +547,7 @@ fail:
         cause = st.err_reason ? st.err_reason : TERMINATED_ERROR;
         st.err_reason = NO_ERROR;
     }
+    if (bubble_up_ruby_exception(st, &try_catch)) return;
     if (!cause && try_catch.HasCaught()) cause = RUNTIME_ERROR;
     if (cause) result = v8::Undefined(st.isolate);
     auto err = to_error(st, &try_catch, cause);
@@ -571,6 +596,7 @@ fail:
         cause = st.err_reason ? st.err_reason : TERMINATED_ERROR;
         st.err_reason = NO_ERROR;
     }
+    if (bubble_up_ruby_exception(st, &try_catch)) return;
     if (!cause && try_catch.HasCaught()) cause = RUNTIME_ERROR;
     if (cause) result = v8::Undefined(st.isolate);
     auto err = to_error(st, &try_catch, cause);
@@ -895,6 +921,7 @@ State::~State()
         v8::Isolate::Scope isolate_scope(isolate);
         persistent_safe_context.Reset();
         persistent_context.Reset();
+        ruby_exception.Reset();
     }
     isolate->Dispose();
     for (Callback *cb : callbacks)

data/ext/mini_racer_extension/serde.c

@@ -194,17 +194,21 @@ static inline int r_zigzag(const uint8_t **p, const uint8_t *pe, int64_t *r)
     return 0;
 }
 
-static inline void ser_init(Ser *s)
+static void ser_init0(Ser *s)
 {
     memset(s, 0, sizeof(*s));
     buf_init(&s->b);
+}
+
+static inline void ser_init(Ser *s)
+{
+    ser_init0(s);
     w(s, "\xFF\x0F", 2);
 }
 
 static void ser_init1(Ser *s, uint8_t c)
 {
-    memset(s, 0, sizeof(*s));
-    buf_init(&s->b);
+    ser_init0(s);
     w_byte(s, c);
     w(s, "\xFF\x0F", 2);
 }

data/lib/mini_racer/truffleruby.rb

@@ -246,6 +246,10 @@ module MiniRacer
           js_map_to_hash(value)
         elsif map_iterator?(value)
           value.map { |e| convert_js_to_ruby(e) }
+        elsif Polyglot::ForeignException === value
+          exc = MiniRacer::ScriptError.new(value.message)
+          exc.set_backtrace(value.backtrace)
+          exc
         else
           object = value
           h = {}

data/lib/mini_racer/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module MiniRacer
-  VERSION = "0.19.0"
-  LIBV8_NODE_VERSION = "~> 24.1.0.0"
+  VERSION = "0.20.0"
+  LIBV8_NODE_VERSION = "~> 24.12.0.1"
 end

data/lib/mini_racer.rb

@@ -51,6 +51,19 @@ module MiniRacer
     end
   end
 
+  class ScriptError < EvalError
+    def initialize(message)
+      message, *@frames = message.split("\n")
+      @frames.map! { "JavaScript #{_1.strip}" }
+      super(message)
+    end
+
+    def backtrace
+      frames = super || []
+      @frames + frames
+    end
+  end
+
   class SnapshotError < Error
     def initialize(message)
       message, *@frames = message.split("\n")

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mini_racer
 version: !ruby/object:Gem::Version
-  version: 0.19.0
+  version: 0.20.0
 platform: ruby
 authors:
 - Sam Saffron
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-06-24 00:00:00.000000000 Z
+date: 2026-02-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -100,14 +100,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 24.1.0.0
+        version: 24.12.0.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 24.1.0.0
+        version: 24.12.0.1
 description: Minimal embedded v8 engine for Ruby
 email:
 - sam.saffron@gmail.com
@@ -137,9 +137,9 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/discourse/mini_racer/issues
-  changelog_uri: https://github.com/discourse/mini_racer/blob/v0.19.0/CHANGELOG
-  documentation_uri: https://www.rubydoc.info/gems/mini_racer/0.19.0
-  source_code_uri: https://github.com/discourse/mini_racer/tree/v0.19.0
+  changelog_uri: https://github.com/discourse/mini_racer/blob/v0.20.0/CHANGELOG
+  documentation_uri: https://www.rubydoc.info/gems/mini_racer/0.20.0
+  source_code_uri: https://github.com/discourse/mini_racer/tree/v0.20.0
 post_install_message:
 rdoc_options: []
 require_paths: