mini_racer 0.19.2 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2730baed1d90aa6181def75b81766dca2481c2ce7406f430436ba524e0dc70d6
-  data.tar.gz: d1aa0298af002dfe183acee282718a3e2702c9bfb98cb3b80bc6fc93e5a711b3
+  metadata.gz: 7cd44fe0925a58e264712d933d805af54b517d31cdbefc26455e7e139e234279
+  data.tar.gz: 17190bc083b885c838b0dfc3424c3fc08fb02df354972a3007a292ddf70afc22
 SHA512:
-  metadata.gz: 8050de8f1506ed9a85f0e5109089dae8e7413b6eee5902636ab922a7ccd819a3ae3a7aea8b4f0465f3c795afab03e4c3e2c9dccc77325b848304008d6bad4091
-  data.tar.gz: 3c1e532d346b607278235f837eb5bc35d88c82d3e2e088fc3b833344293c94f02dc5b0303edd7d59b4ee8aa86ccfb20497ef86a777e10892f02f2bd10bd710a6
+  metadata.gz: 9cdd4cdf20f9be0e3ceb34daa48f7f1eeb93c4c11eada10c23e2c3e3dbd82cf7a13c8102e67140cc15c028c51a468c6e74ac518c76050cadceb33aa99fd71b7d
+  data.tar.gz: c7110aabb771e18bccd85283696e8f811970cf8d03bb0ef1f573a84f2fa7da2ef1014b5138513b09d80825de96ddebe7e6316f79efbe8adecbd1ff202b14e4d5

data/CHANGELOG

@@ -1,3 +1,9 @@
+- 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
+
 - 0.19.2 - 24-12-2025
   - upgrade to node 24.12.0
 

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:
@@ -193,6 +212,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

@@ -193,6 +193,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 +689,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;
@@ -1111,6 +1119,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;
@@ -1690,6 +1703,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;
@@ -1742,11 +1769,13 @@ 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);
     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

@@ -102,7 +102,7 @@ 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
+      @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, @js_new_uint8array_func = eval_in_context <<-CODE
         [
           (x) => { return (x instanceof Object || x instanceof Array) && !(x instanceof Date) && !(x instanceof Function) },
           (x) => { return x instanceof Map },
@@ -113,6 +113,7 @@ module MiniRacer
           (x) => { var r = x.description; return r === undefined ? 'undefined' : r },
           (x) => { return new Date(x) },
           (x) => { return new Array(x) },
+          (x) => { return new Uint8Array(x) },
         ]
       CODE
     end
@@ -329,6 +330,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.19.2"
+  VERSION = "0.21.0"
   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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mini_racer
 version: !ruby/object:Gem::Version
-  version: 0.19.2
+  version: 0.21.0
 platform: ruby
 authors:
 - Sam Saffron
@@ -136,9 +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.19.2/CHANGELOG
-  documentation_uri: https://www.rubydoc.info/gems/mini_racer/0.19.2
-  source_code_uri: https://github.com/discourse/mini_racer/tree/v0.19.2
+  changelog_uri: https://github.com/discourse/mini_racer/blob/v0.21.0/CHANGELOG
+  documentation_uri: https://www.rubydoc.info/gems/mini_racer/0.21.0
+  source_code_uri: https://github.com/discourse/mini_racer/tree/v0.21.0
 rdoc_options: []
 require_paths:
 - lib
@@ -154,7 +154,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Minimal embedded v8 for Ruby
 test_files: []