mini_racer 0.20.0 → 0.21.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5aa16bf587a6e12df562d7a946ce3a965a8444debd9769b376075cafd10a3b5c
-  data.tar.gz: 5aaf6a08ae90f05bc554bae0a06e93efce5318d00aacdfe959f36513533caac4
+  metadata.gz: 6c838b1bc35ed1adb0156f0e01d699afc180c174718f197a6afc1356fe9e4815
+  data.tar.gz: 7a4b00c4bcd4572bf7fdcce3df6455ded628706975fa8540946faee17e53617d
 SHA512:
-  metadata.gz: 2b2641ceb0fd1770efd32cfb9e37aee92ca857ad6acbe2129157a58be9ed6bbef4a355c5af133f5749f229d578e10a452ef77a62eadbe436993f005146d242cd
-  data.tar.gz: 3264e95d4951aa52ba080a94b847c5080705e1de0e3dd5fefae0786342ccece850b00db4f151220e65068e9e5d62fb0eebae0fda65e79647196903fae70d8012
+  metadata.gz: d826ca742dbe6580f92faebf11c827795536c55596c279fa070dd38836d03b7dcecc0b43fe254b6d95590bea1a24d8ec168f9d5008b668ba488a5aff7b6e3aea
+  data.tar.gz: 985effeb709d8dfc1481c679dfdc86a3930a0d84de6d3b6d9d154d6801a6766af76ffecd468e22d8b20b68952e02b756ab0ec11b1bc3c93736b078d046719798

data/CHANGELOG

@@ -1,3 +1,11 @@
+- 0.21.1 - 25-05-2026
+  - Run `:single_threaded` V8 dispatches on a reusable mini_racer-owned native thread so V8 does not execute on Ruby-owned threads
+  - Stop and join the reusable `:single_threaded` runner when contexts are disposed
+  - Document `:single_threaded` fork-safety requirements for pre-fork contexts
+
+- 0.21.0 - 16-04-2026
+  - Add MiniRacer::Binary for returning Uint8Array to JavaScript from attached Ruby callbacks
+
 - 0.20.0 - 24-02-2026
   - Add Snapshot.load to restore snapshots from binary data, enabling disk persistence
 

data/README.md

@@ -60,6 +60,25 @@ puts context.eval("array_and_hash()")
 # => {"a" => 1, "b" => [1, {"a" => 1}]}
 ```
 
+### Return binary data from Ruby to JavaScript
+
+Attached Ruby functions can return binary data as `Uint8Array` using `MiniRacer::Binary`:
+
+```ruby
+require "digest"
+
+context = MiniRacer::Context.new
+context.attach("sha256_raw", ->(data) {
+  MiniRacer::Binary.new(Digest::SHA256.digest(data))
+})
+
+# Inside JavaScript the return value is a Uint8Array
+context.eval("sha256_raw('hello') instanceof Uint8Array") # => true
+context.eval("sha256_raw('hello').length")                 # => 32
+```
+
+This is useful when you need to pass raw bytes (e.g., cryptographic digests, compressed data, binary file contents) from Ruby to JavaScript. The `MiniRacer::Binary` wrapper tells the bridge to serialize the data as a `Uint8Array` on the JavaScript side rather than a string.
+
 ### GIL free JavaScript execution
 
 The Ruby Global interpreter lock is released when scripts are executing:
@@ -120,6 +139,15 @@ Since 0.6.1 mini_racer does support V8 single threaded platform mode which shoul
 MiniRacer::Platform.set_flags!(:single_threaded)
 ```
 
+When using pre-fork `MiniRacer::Context` objects in `:single_threaded` mode,
+ensure the process only forks while MiniRacer is quiescent: no thread may be
+evaluating JavaScript, calling into a context, disposing/freeing a context,
+running a Ruby callback from JavaScript, or otherwise using MiniRacer at the
+instant of `fork`. In multi-threaded applications, guard all MiniRacer context
+operations and the `fork` itself with the same application-level lock. Forking
+while a MiniRacer operation is in progress can leave inherited pthread mutexes
+in an unusable state in the child process.
+
 If you want to ensure your application does not leak memory after fork either:
 
 1. Ensure no `MiniRacer::Context` objects are created in the master process; or

data/ext/mini_racer_extension/mini_racer_extension.c

@@ -4,6 +4,7 @@
 #include <stdlib.h>
 #include <string.h>
 #include <pthread.h>
+#include <unistd.h>
 #include <math.h>
 
 #if defined(__linux__) && !defined(__GLIBC__)
@@ -136,6 +137,9 @@ typedef struct Context
     VALUE exception;   // pending exception or Qnil
     Buf req, res;      // ruby->v8 request/response, mediated by |mtx| and |cv|
     Buf snapshot;
+    pthread_t single_threaded_thr;
+    pid_t single_threaded_pid;
+    int single_threaded_thr_started;
     // |rr_mtx| stands for "recursive ruby mutex"; it's used to exclude
     // other ruby threads but allow reentrancy from the same ruby thread
     // (think ruby->js->ruby->js calls)
@@ -193,6 +197,7 @@ static VALUE terminated_error;
 static VALUE context_class;
 static VALUE snapshot_class;
 static VALUE date_time_class;
+static VALUE binary_class;
 static VALUE js_function_class;
 
 static pthread_mutex_t flags_mtx = PTHREAD_MUTEX_INITIALIZER;
@@ -688,10 +693,17 @@ static int serialize1(Ser *s, VALUE refs, VALUE v)
         // entirely new objects
         if (rb_respond_to(v, rb_intern("to_time"))) {
             v = rb_funcall(v, rb_intern("to_time"), 0);
-        }
-        if (rb_obj_is_kind_of(v, rb_cTime)) {
-            struct timeval tv = rb_time_timeval(v);
-            ser_date(s, tv.tv_sec*1e3 + tv.tv_usec/1e3);
+            if (rb_obj_is_kind_of(v, rb_cTime)) {
+                struct timeval tv = rb_time_timeval(v);
+                ser_date(s, tv.tv_sec*1e3 + tv.tv_usec/1e3);
+            } else {
+                snprintf(s->err, sizeof(s->err), "unsupported type %s", rb_class2name(CLASS_OF(v)));
+                return -1;
+            }
+        } else if (!NIL_P(binary_class) && rb_obj_is_kind_of(v, binary_class)) {
+            t = rb_ivar_get(v, rb_intern("@data"));
+            Check_Type(t, T_STRING);
+            ser_uint8array(s, RSTRING_PTR(t), RSTRING_LEN(t));
         } else {
             snprintf(s->err, sizeof(s->err), "unsupported type %s", rb_class2name(CLASS_OF(v)));
             return -1;
@@ -860,18 +872,10 @@ void v8_dispatch(Context *c)
 // only called when inside v8_call, v8_eval, or v8_pump_message_loop
 void v8_roundtrip(Context *c, const uint8_t **p, size_t *n)
 {
-    struct rendezvous_nogvl *args;
-
     buf_reset(&c->req);
-    if (single_threaded) {
-        assert(*c->res.buf == 'c'); // js -> ruby callback
-        args = &(struct rendezvous_nogvl){c, &c->req, &c->res};
-        rb_thread_call_with_gvl(rendezvous_callback, args);
-    } else {
-        pthread_cond_signal(&c->cv);
-        while (!c->req.len)
-            pthread_cond_wait(&c->cv, &c->mtx);
-    }
+    pthread_cond_signal(&c->cv);
+    while (!c->req.len)
+        pthread_cond_wait(&c->cv, &c->mtx);
     buf_reset(&c->res);
     *p = c->req.buf;
     *n = c->req.len;
@@ -983,10 +987,45 @@ fail:
     goto out;
 }
 
+static void *single_threaded_runner(void *arg)
+{
+    Context *c;
+
+    c = arg;
+    pthread_mutex_lock(&c->mtx);
+    for (;;) {
+        while (!c->req.len && atomic_load(&c->quit) < 1)
+            pthread_cond_wait(&c->cv, &c->mtx);
+        if (atomic_load(&c->quit) >= 1)
+            break;
+        v8_single_threaded_enter(c->pst, c, dispatch);
+        pthread_cond_signal(&c->cv);
+    }
+    pthread_mutex_unlock(&c->mtx);
+    return NULL;
+}
+
+static int single_threaded_runner_start(Context *c)
+{
+    pid_t pid;
+    int r;
+
+    pid = getpid();
+    if (c->single_threaded_thr_started && c->single_threaded_pid == pid)
+        return 0;
+    c->single_threaded_thr_started = 0;
+    c->single_threaded_pid = pid;
+    r = pthread_create(&c->single_threaded_thr, NULL, single_threaded_runner, c);
+    if (!r)
+        c->single_threaded_thr_started = 1;
+    return r;
+}
+
 static inline void *rendezvous_nogvl(void *arg)
 {
     struct rendezvous_nogvl *a;
     Context *c;
+    int r;
 
     a = arg;
     c = a->context;
@@ -1002,7 +1041,16 @@ next:
     assert(c->res.len == 0);
     buf_move(a->req, &c->req); // v8 thread takes ownership of req
     if (single_threaded) {
-        v8_single_threaded_enter(c->pst, c, dispatch);
+        r = single_threaded_runner_start(c);
+        if (r) {
+            buf_move(&c->req, a->req);
+            pthread_mutex_unlock(&c->mtx);
+            c->depth--;
+            pthread_mutex_unlock(&c->rr_mtx);
+            return (void *)(intptr_t)r;
+        }
+        pthread_cond_signal(&c->cv);
+        do pthread_cond_wait(&c->cv, &c->mtx); while (!c->res.len);
     } else {
         pthread_cond_signal(&c->cv);
         do pthread_cond_wait(&c->cv, &c->mtx); while (!c->res.len);
@@ -1011,6 +1059,7 @@ next:
     pthread_mutex_unlock(&c->mtx);
     if (*a->res->buf == 'c') { // js -> ruby callback?
         rb_thread_call_with_gvl(rendezvous_callback, a);
+        buf_reset(a->res);
         goto next;
     }
     c->depth--;
@@ -1020,12 +1069,16 @@ next:
 
 static void rendezvous_no_des(Context *c, Buf *req, Buf *res)
 {
+    void *r;
+
     if (atomic_load(&c->quit)) {
         buf_reset(req);
         rb_raise(context_disposed_error, "disposed context");
     }
-    rb_nogvl(rendezvous_nogvl, &(struct rendezvous_nogvl){c, req, res},
-             NULL, NULL, 0);
+    r = rb_nogvl(rendezvous_nogvl, &(struct rendezvous_nogvl){c, req, res},
+                 NULL, NULL, 0);
+    if (r)
+        rb_raise(runtime_error, "pthread_create: %s", strerror((int)(intptr_t)r));
 }
 
 // send request to & receive reply from v8 thread; takes ownership of |req|
@@ -1111,6 +1164,11 @@ static VALUE context_alloc(VALUE klass)
         if (Qtrue == rb_funcall(rb_cObject, f, 1, a))
             date_time_class = rb_const_get(rb_cObject, rb_intern("DateTime"));
     }
+    if (NIL_P(binary_class)) {
+        VALUE m = rb_const_get(rb_cObject, rb_intern("MiniRacer"));
+        if (Qtrue == rb_funcall(m, rb_intern("const_defined?"), 1, rb_str_new_cstr("Binary")))
+            binary_class = rb_const_get(m, rb_intern("Binary"));
+    }
     c = ruby_xmalloc(sizeof(*c));
     memset(c, 0, sizeof(*c));
     c->exception = Qnil;
@@ -1177,7 +1235,16 @@ static void *context_free_thread_do(void *arg)
     Context *c;
 
     c = arg;
-    v8_single_threaded_dispose(c->pst);
+    if (single_threaded && c->single_threaded_thr_started && c->single_threaded_pid == getpid()) {
+        pthread_mutex_lock(&c->mtx);
+        atomic_store(&c->quit, 2);
+        pthread_cond_signal(&c->cv);
+        pthread_mutex_unlock(&c->mtx);
+        pthread_join(c->single_threaded_thr, NULL);
+    }
+    if (c->pst)
+        v8_single_threaded_dispose(c->pst);
+    pthread_mutex_lock(&c->mtx);
     context_destroy(c);
     return NULL;
 }
@@ -1271,8 +1338,18 @@ static void *context_dispose_do(void *arg)
 
     c = arg;
     if (single_threaded) {
+        pthread_mutex_lock(&c->mtx);
+        while (c->req.len || c->res.len)
+            pthread_cond_wait(&c->cv, &c->mtx);
         atomic_store(&c->quit, 1);   // disposed
-        // intentionally a no-op for now
+        if (c->single_threaded_thr_started && c->single_threaded_pid == getpid()) {
+            pthread_cond_signal(&c->cv);
+            pthread_mutex_unlock(&c->mtx);
+            pthread_join(c->single_threaded_thr, NULL);
+            pthread_mutex_lock(&c->mtx);
+            c->single_threaded_thr_started = 0;
+        }
+        pthread_mutex_unlock(&c->mtx);
     } else {
         pthread_mutex_lock(&c->mtx);
         while (c->req.len || c->res.len)
@@ -1763,5 +1840,6 @@ void Init_mini_racer_extension(void)
     rb_define_singleton_method(c, "set_flags!", platform_set_flags, -1);
 
     date_time_class = Qnil; // lazy init
+    binary_class = Qnil; // lazy init
     js_function_class = rb_define_class_under(m, "JavaScriptFunction", rb_cObject);
 }

data/ext/mini_racer_extension/serde.c

@@ -322,6 +322,19 @@ static void ser_string16(Ser *s, const void *p, size_t n)
     w(s, p, n);
 }
 
+// Uint8Array: ArrayBuffer header + data + typed array view descriptor
+static void ser_uint8array(Ser *s, const void *p, size_t n)
+{
+    w_byte(s, 'B');     // ArrayBuffer tag
+    w_varint(s, n);     // byte length
+    w(s, p, n);         // raw bytes
+    w_byte(s, 'V');     // typed array view tag
+    w_byte(s, 'B');     // Uint8Array type
+    w_varint(s, 0);     // byteOffset
+    w_varint(s, n);     // byteLength
+    w_varint(s, 0);     // flags
+}
+
 static void ser_object_begin(Ser *s)
 {
     w_byte(s, 'o');

data/lib/mini_racer/truffleruby.rb

@@ -77,9 +77,13 @@ module MiniRacer
         raise "TruffleRuby #{RUBY_ENGINE_VERSION} does not have support for inner contexts, use a more recent version"
       end
 
+
+      if TruffleRuby.native?
+        raise "You need the TruffleRuby JVM Standalone for mini_racer because it is not possible to install the js component in the the Native standalone"
+      end
+
       unless Polyglot.languages.include? "js"
-        raise "The language 'js' is not available, you likely need to `export TRUFFLERUBYOPT='--jvm --polyglot'`\n" \
-          "You also need to install the 'js' component, see https://github.com/oracle/truffleruby/blob/master/doc/user/polyglot.md#installing-other-languages"
+        raise "The language 'js' is not available, you need to install the 'js' component.\nSee https://github.com/oracle/truffleruby/blob/master/doc/user/polyglot.md#installing-other-languages"
       end
 
       @context = Polyglot::InnerContext.new(on_cancelled: -> { 
@@ -102,19 +106,19 @@ module MiniRacer
       else
         @snapshot = nil
       end
-      @is_object_or_array_func, @is_map_func, @is_map_iterator_func, @is_time_func, @js_date_to_time_func, @is_symbol_func, @js_symbol_to_symbol_func, @js_new_date_func, @js_new_array_func = eval_in_context <<-CODE
-        [
-          (x) => { return (x instanceof Object || x instanceof Array) && !(x instanceof Date) && !(x instanceof Function) },
-          (x) => { return x instanceof Map },
-          (x) => { return x[Symbol.toStringTag] === 'Map Iterator' },
-          (x) => { return x instanceof Date },
-          (x) => { return x.getTime(x) },
-          (x) => { return typeof x === 'symbol' },
-          (x) => { var r = x.description; return r === undefined ? 'undefined' : r },
-          (x) => { return new Date(x) },
-          (x) => { return new Array(x) },
-        ]
-      CODE
+
+      @is_object_or_array_func = eval_in_context "(x) => { return (x instanceof Object || x instanceof Array) && !(x instanceof Date) && !(x instanceof Function) }"
+      @is_map_func = eval_in_context "(x) => { return x instanceof Map }"
+      @is_map_iterator_func = eval_in_context "(x) => { return x[Symbol.toStringTag] === 'Map Iterator' }"
+      @is_time_func = eval_in_context "(x) => { return x instanceof Date }"
+      @is_symbol_func = eval_in_context "(x) => { return typeof x === 'symbol' }"
+      @is_uint8_array_func = eval_in_context "(x) => { return x instanceof Uint8Array }"
+
+      @js_date_to_time_func = eval_in_context "(x) => { return x.getTime(x) }"
+      @js_symbol_to_symbol_func = eval_in_context "(x) => { var r = x.description; return r === undefined ? 'undefined' : r }"
+      @js_new_date_func = eval_in_context "(x) => { return new Date(x) }"
+      @js_new_array_func = eval_in_context "(x) => { return new Array(x) }"
+      @js_new_uint8array_func = eval_in_context "(x) => { return new Uint8Array(x) }"
     end
 
     def dispose_unsafe
@@ -231,6 +235,10 @@ module MiniRacer
         elsif value.respond_to?(:to_str)
           value.to_str.dup
         elsif value.respond_to?(:to_ary)
+          if uint8_array?(value)
+            return value.to_a.pack('C*')
+          end
+
           value.to_ary.map do |e|
             if e.respond_to?(:call)
               nil
@@ -280,15 +288,19 @@ module MiniRacer
       @is_time_func.call(value)
     end
 
+    def symbol?(value)
+      @is_symbol_func.call(value)
+    end
+
+    def uint8_array?(value)
+      @is_uint8_array_func.call(value)
+    end
+
     def js_date_to_time(value)
       millis = @js_date_to_time_func.call(value)
       Time.at(Rational(millis, 1000))
     end
 
-    def symbol?(value)
-      @is_symbol_func.call(value)
-    end
-
     def js_symbol_to_symbol(value)
       @js_symbol_to_symbol_func.call(value).to_s.to_sym
     end
@@ -329,6 +341,8 @@ module MiniRacer
         js_new_date(value.to_f * 1000)
       when DateTime
         js_new_date(value.to_time.to_f * 1000)
+      when MiniRacer::Binary
+        @js_new_uint8array_func.call(value.data.bytes)
       else
         "Undefined Conversion"
       end

data/lib/mini_racer/version.rb

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

data/lib/mini_racer.rb

@@ -1,6 +1,17 @@
 require "mini_racer/version"
 require "pathname"
 
+module MiniRacer
+  class Binary
+    attr_reader :data
+
+    def initialize(data)
+      raise TypeError, "wrong argument type #{data.class} (expected String)" unless data.is_a?(String)
+      @data = data
+    end
+  end
+end
+
 if RUBY_ENGINE == "truffleruby"
   require "mini_racer/truffleruby"
 else

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: mini_racer
 version: !ruby/object:Gem::Version
-  version: 0.20.0
+  version: 0.21.1
 platform: ruby
 authors:
 - Sam Saffron
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-24 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -113,8 +112,8 @@ email:
 - sam.saffron@gmail.com
 executables: []
 extensions:
-- ext/mini_racer_loader/extconf.rb
 - ext/mini_racer_extension/extconf.rb
+- ext/mini_racer_loader/extconf.rb
 extra_rdoc_files: []
 files:
 - CHANGELOG
@@ -137,10 +136,9 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/discourse/mini_racer/issues
-  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:
+  changelog_uri: https://github.com/discourse/mini_racer/blob/v0.21.1/CHANGELOG
+  documentation_uri: https://www.rubydoc.info/gems/mini_racer/0.21.1
+  source_code_uri: https://github.com/discourse/mini_racer/tree/v0.21.1
 rdoc_options: []
 require_paths:
 - lib
@@ -156,8 +154,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Minimal embedded v8 for Ruby
 test_files: []