mini_racer_rs 1.0.0

data/crates/mini_racer_wire/src/lib.rs

@@ -0,0 +1,67 @@
+#![forbid(unsafe_code)]
+#![deny(
+    clippy::arithmetic_side_effects,
+    clippy::cast_possible_truncation,
+    clippy::indexing_slicing
+)]
+
+mod decode;
+pub mod marker;
+pub mod text;
+mod write;
+
+use std::ops::RangeInclusive;
+
+pub use decode::{
+    Begun, Container, DecodeError, Limits, Scalar, Text, Visitor, decode_value, decode_values,
+};
+pub use write::{WriteError, Writer};
+
+pub const READ_VERSIONS: RangeInclusive<u32> = 13..=16;
+pub const WRITE_VERSION: u32 = 15;
+
+mod tag {
+    pub const HEADER: u8 = 0xFF;
+    pub const PADDING: u8 = 0x00;
+    pub const VERIFY_OBJECT_COUNT: u8 = b'?';
+    pub const THE_HOLE: u8 = b'-';
+    pub const UNDEFINED: u8 = b'_';
+    pub const NULL: u8 = b'0';
+    pub const TRUE: u8 = b'T';
+    pub const FALSE: u8 = b'F';
+    pub const INT32: u8 = b'I';
+    pub const UINT32: u8 = b'U';
+    pub const DOUBLE: u8 = b'N';
+    pub const BIGINT: u8 = b'Z';
+    pub const UTF8_STRING: u8 = b'S';
+    pub const ONE_BYTE_STRING: u8 = b'"';
+    pub const TWO_BYTE_STRING: u8 = b'c';
+    pub const OBJECT_REFERENCE: u8 = b'^';
+    pub const BEGIN_OBJECT: u8 = b'o';
+    pub const END_OBJECT: u8 = b'{';
+    pub const BEGIN_SPARSE_ARRAY: u8 = b'a';
+    pub const END_SPARSE_ARRAY: u8 = b'@';
+    pub const BEGIN_DENSE_ARRAY: u8 = b'A';
+    pub const END_DENSE_ARRAY: u8 = b'$';
+    pub const DATE: u8 = b'D';
+    pub const TRUE_OBJECT: u8 = b'y';
+    pub const FALSE_OBJECT: u8 = b'x';
+    pub const NUMBER_OBJECT: u8 = b'n';
+    pub const BIGINT_OBJECT: u8 = b'z';
+    pub const STRING_OBJECT: u8 = b's';
+    pub const REGEXP: u8 = b'R';
+    pub const BEGIN_MAP: u8 = b';';
+    pub const END_MAP: u8 = b':';
+    pub const BEGIN_SET: u8 = b'\'';
+    pub const END_SET: u8 = b',';
+    pub const ARRAY_BUFFER: u8 = b'B';
+    pub const IMMUTABLE_ARRAY_BUFFER: u8 = b'C';
+    pub const RESIZABLE_ARRAY_BUFFER: u8 = b'~';
+    pub const ARRAY_BUFFER_VIEW: u8 = b'V';
+    pub const ERROR: u8 = b'r';
+    pub const ERROR_MESSAGE: u8 = b'm';
+    pub const ERROR_STACK: u8 = b's';
+    pub const ERROR_CAUSE: u8 = b'c';
+    pub const ERROR_END: u8 = b'.';
+    pub const UINT8_ARRAY: u8 = b'B';
+}

data/crates/mini_racer_wire/src/marker.rs

@@ -0,0 +1,43 @@
+//! `mini_racer` stands a two-byte string in for a function result, and its
+//! Ruby side turns exactly that string into a `MiniRacer::JavaScriptFunction`.
+
+/// U+0BFF, then `JavaScriptFunction`.
+pub const JAVASCRIPT_FUNCTION: [u16; 19] = [
+    0x0BFF, 0x4A, 0x61, 0x76, 0x61, 0x53, 0x63, 0x72, 0x69, 0x70, 0x74, 0x46, 0x75, 0x6E, 0x63,
+    0x74, 0x69, 0x6F, 0x6E,
+];
+
+/// Whether UTF-16LE `bytes` are the marker and nothing else.
+#[must_use]
+pub fn is_javascript_function(bytes: &[u8]) -> bool {
+    let (pairs, rest) = bytes.as_chunks::<2>();
+    rest.is_empty()
+        && pairs.len() == JAVASCRIPT_FUNCTION.len()
+        && pairs
+            .iter()
+            .zip(JAVASCRIPT_FUNCTION)
+            .all(|(pair, unit)| *pair == unit.to_le_bytes())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn utf16le(text: &str) -> Vec<u8> {
+        text.encode_utf16().flat_map(u16::to_le_bytes).collect()
+    }
+
+    #[test]
+    fn only_the_whole_marker_matches() {
+        assert!(is_javascript_function(&utf16le(
+            "\u{bff}JavaScriptFunction"
+        )));
+        assert!(!is_javascript_function(&utf16le(
+            "\u{bff}JavaScriptFunctio"
+        )));
+        assert!(!is_javascript_function(&utf16le(
+            "\u{bff}JavaScriptFunctions"
+        )));
+        assert!(!is_javascript_function(&utf16le("JavaScriptFunction")));
+    }
+}

data/crates/mini_racer_wire/src/text.rs

@@ -0,0 +1,106 @@
+// Returned HTML is mostly ASCII, which is copied in spans; only blocks holding
+// another byte are converted a byte at a time.
+const LATIN1_BLOCK: usize = 32;
+// Each block's count of non-ASCII bytes is summed in a u8.
+const _: () = assert!(LATIN1_BLOCK <= u8::MAX as usize);
+
+#[expect(clippy::expect_used, reason = "callers pass only spans of ASCII bytes")]
+fn ascii(bytes: &[u8]) -> &str {
+    std::str::from_utf8(bytes).expect("ASCII is UTF-8")
+}
+
+#[must_use]
+pub fn latin1_to_utf8(bytes: &[u8]) -> String {
+    if bytes.len() < LATIN1_BLOCK {
+        return bytes.iter().copied().map(char::from).collect();
+    }
+    let (wide, mixed) =
+        bytes
+            .chunks(LATIN1_BLOCK)
+            .fold((0_usize, 0_usize), |(wide, mixed), block| {
+                let count = block
+                    .iter()
+                    .map(|&byte| u8::from(!byte.is_ascii()))
+                    .sum::<u8>();
+                (
+                    wide.saturating_add(usize::from(count)),
+                    mixed.saturating_add(usize::from(count > 0)),
+                )
+            });
+    let mut out = String::with_capacity(bytes.len().saturating_add(wide));
+    // Text where most blocks need converting anyway, like accented prose, is
+    // faster a byte at a time throughout.
+    if mixed.saturating_mul(LATIN1_BLOCK).saturating_mul(2) > bytes.len() {
+        out.extend(bytes.iter().copied().map(char::from));
+        return out;
+    }
+    let mut span = 0;
+    let mut at: usize = 0;
+    for block in bytes.chunks(LATIN1_BLOCK) {
+        let next = at.saturating_add(block.len());
+        if !block.is_ascii() {
+            if span < at {
+                out.push_str(ascii(bytes.get(span..at).unwrap_or_default()));
+            }
+            for &byte in block {
+                out.push(char::from(byte));
+            }
+            span = next;
+        }
+        at = next;
+    }
+    out.push_str(ascii(bytes.get(span..).unwrap_or_default()));
+    out
+}
+
+#[must_use]
+pub fn utf16le_to_utf8(bytes: &[u8]) -> Option<String> {
+    let (pairs, rest) = bytes.as_chunks::<2>();
+    if !rest.is_empty() {
+        return None;
+    }
+    let units = pairs.iter().copied().map(u16::from_le_bytes);
+    char::decode_utf16(units)
+        .collect::<Result<String, _>>()
+        .ok()
+}
+
+#[cfg(test)]
+mod tests {
+    use proptest::prelude::*;
+
+    use super::*;
+
+    #[test]
+    fn latin1_maps_bytes_to_code_points() {
+        assert_eq!(latin1_to_utf8(b"abc"), "abc");
+        assert_eq!(latin1_to_utf8(&[0x63, 0x61, 0x66, 0xE9]), "café");
+    }
+
+    #[test]
+    fn utf16_rejects_odd_lengths_and_lone_surrogates() {
+        assert_eq!(
+            utf16le_to_utf8(&[0x3D, 0xD8, 0x00, 0xDE]).as_deref(),
+            Some("😀")
+        );
+        assert_eq!(utf16le_to_utf8(&[0x41]), None);
+        assert_eq!(utf16le_to_utf8(&[0x3D, 0xD8]), None);
+    }
+
+    proptest! {
+        // ASCII runs of every length with other bytes between them, so whole
+        // ASCII blocks, mixed blocks and spans across block edges all come up.
+        #[test]
+        fn latin1_matches_mapping_each_byte(segments in proptest::collection::vec(
+            (
+                proptest::collection::vec(0u8..0x80, 0..80),
+                proptest::collection::vec(0x80u8..=0xFF, 0..3),
+            ),
+            0..24,
+        )) {
+            let bytes: Vec<u8> = segments.into_iter().flat_map(|(run, wide)| run.into_iter().chain(wide)).collect();
+            let by_byte: String = bytes.iter().copied().map(char::from).collect();
+            prop_assert_eq!(latin1_to_utf8(&bytes), by_byte);
+        }
+    }
+}

data/crates/mini_racer_wire/src/write.rs

@@ -0,0 +1,187 @@
+use crate::{WRITE_VERSION, tag};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
+pub enum WriteError {
+    #[error("bad bigint")]
+    BigInt,
+}
+
+// The bit pattern mini_racer writes for every NaN.
+const CANONICAL_NAN: f64 = f64::from_bits(0x7FF8_0000_0000_0000);
+
+/// Writes the V8 wire format the way `mini_racer`'s encoder does, into a buffer
+/// the caller owns and can reuse.
+///
+/// Each method that writes an object returns the id V8 gives that object on
+/// reading, for `object_ref`.
+pub struct Writer<'a> {
+    out: &'a mut Vec<u8>,
+    next_id: u32,
+}
+
+impl<'a> Writer<'a> {
+    /// Starts a frame: clears `out` and writes the header.
+    pub fn new(out: &'a mut Vec<u8>) -> Self {
+        out.clear();
+        out.push(tag::HEADER);
+        let mut writer = Self { out, next_id: 0 };
+        writer.varint(WRITE_VERSION.into());
+        writer
+    }
+
+    const fn id(&mut self) -> u32 {
+        let id = self.next_id;
+        self.next_id = id.saturating_add(1);
+        id
+    }
+
+    fn varint(&mut self, mut value: u64) {
+        while value > 0x7F {
+            self.out
+                .push(0x80 | u8::try_from(value & 0x7F).unwrap_or(0));
+            value >>= 7;
+        }
+        self.out.push(u8::try_from(value).unwrap_or(u8::MAX));
+    }
+
+    fn zigzag(&mut self, value: i32) {
+        self.varint(u64::from(((value << 1) ^ (value >> 31)).cast_unsigned()));
+    }
+
+    fn len(&mut self, len: usize) {
+        self.varint(u64::try_from(len).unwrap_or(u64::MAX));
+    }
+
+    pub fn null(&mut self) {
+        self.out.push(tag::NULL);
+    }
+
+    pub fn undefined(&mut self) {
+        self.out.push(tag::UNDEFINED);
+    }
+
+    pub fn bool(&mut self, value: bool) {
+        self.out.push(if value { tag::TRUE } else { tag::FALSE });
+    }
+
+    pub fn number(&mut self, value: f64) {
+        self.out.push(tag::DOUBLE);
+        let value = if value.is_nan() { CANONICAL_NAN } else { value };
+        self.out.extend_from_slice(&value.to_le_bytes());
+    }
+
+    /// An int32 when it fits; otherwise, as `mini_racer` does, a double up to
+    /// `2**63 / 1024` in magnitude, and a `BigInt` beyond.
+    pub fn integer(&mut self, value: i64) {
+        if let Ok(small) = i32::try_from(value) {
+            self.out.push(tag::INT32);
+            self.zigzag(small);
+        } else if value > i64::MIN / 1024 && value <= i64::MAX / 1024 {
+            #[expect(
+                clippy::cast_precision_loss,
+                reason = "mini_racer rounds these to a double too"
+            )]
+            self.number(value as f64);
+        } else {
+            let magnitude = value.unsigned_abs().to_le_bytes();
+            // Eight bytes always form one whole word.
+            let _ = self.bigint(value < 0, &magnitude);
+        }
+    }
+
+    /// `digits` is the magnitude as little-endian 64-bit words.
+    pub fn bigint(&mut self, negative: bool, digits: &[u8]) -> Result<(), WriteError> {
+        if !digits.len().is_multiple_of(8) {
+            return Err(WriteError::BigInt);
+        }
+        let used = digits
+            .iter()
+            .rposition(|&byte| byte != 0)
+            .map_or(0, |last| last.saturating_add(1));
+        self.out.push(tag::BIGINT);
+        if used == 0 {
+            self.out.push(0);
+            return Ok(());
+        }
+        let words = used.div_ceil(8).saturating_mul(8);
+        let bitfield =
+            u64::try_from(words).unwrap_or(u64::MAX).saturating_mul(2) | u64::from(negative);
+        self.varint(bitfield);
+        self.out
+            .extend_from_slice(digits.get(..words).unwrap_or(digits));
+        Ok(())
+    }
+
+    pub fn utf8(&mut self, bytes: &[u8]) {
+        self.out.push(tag::UTF8_STRING);
+        self.len(bytes.len());
+        self.out.extend_from_slice(bytes);
+    }
+
+    pub fn latin1(&mut self, bytes: &[u8]) {
+        self.out.push(tag::ONE_BYTE_STRING);
+        self.len(bytes.len());
+        self.out.extend_from_slice(bytes);
+    }
+
+    /// `bytes` is UTF-16LE; its length is in bytes.
+    pub fn utf16le(&mut self, bytes: &[u8]) {
+        self.out.push(tag::TWO_BYTE_STRING);
+        self.len(bytes.len());
+        self.out.extend_from_slice(bytes);
+    }
+
+    /// Milliseconds since the Unix epoch; non-finite times become NaN.
+    pub fn date(&mut self, millis: f64) -> u32 {
+        self.out.push(tag::DATE);
+        let millis = if millis.is_finite() {
+            millis
+        } else {
+            CANONICAL_NAN
+        };
+        self.out.extend_from_slice(&millis.to_le_bytes());
+        self.id()
+    }
+
+    /// A `Uint8Array` over a fresh buffer holding `bytes`. The id is the
+    /// view's; the buffer takes the one before it.
+    pub fn uint8_array(&mut self, bytes: &[u8]) -> u32 {
+        self.out.push(tag::ARRAY_BUFFER);
+        self.len(bytes.len());
+        self.out.extend_from_slice(bytes);
+        self.out.push(tag::ARRAY_BUFFER_VIEW);
+        self.out.push(tag::UINT8_ARRAY);
+        self.varint(0);
+        self.len(bytes.len());
+        self.varint(0);
+        self.id();
+        self.id()
+    }
+
+    pub fn begin_object(&mut self) -> u32 {
+        self.out.push(tag::BEGIN_OBJECT);
+        self.id()
+    }
+
+    pub fn end_object(&mut self, properties: u32) {
+        self.out.push(tag::END_OBJECT);
+        self.varint(properties.into());
+    }
+
+    pub fn begin_array(&mut self, length: u32) -> u32 {
+        self.out.push(tag::BEGIN_DENSE_ARRAY);
+        self.varint(length.into());
+        self.id()
+    }
+
+    pub fn end_array(&mut self, length: u32) {
+        self.out.push(tag::END_DENSE_ARRAY);
+        self.varint(0);
+        self.varint(length.into());
+    }
+
+    pub fn object_ref(&mut self, id: u32) {
+        self.out.push(tag::OBJECT_REFERENCE);
+        self.varint(id.into());
+    }
+}

data/ext/mini_racer_rs/Cargo.toml

@@ -0,0 +1,26 @@
+[package]
+build = "build.rs"
+description = "Ruby extension for mini_racer_rs"
+edition.workspace = true
+license.workspace = true
+name = "mini_racer_rs"
+publish.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+version.workspace = true
+
+[lib]
+crate-type = ["cdylib"]
+
+[features]
+no-madvise-wrap = ["mini_racer_engine/no-madvise-wrap"]
+
+[dependencies]
+magnus.workspace = true
+mini_racer_engine.workspace = true
+mini_racer_wire.workspace = true
+rb-sys.workspace = true
+thiserror.workspace = true
+
+[lints]
+workspace = true

data/ext/mini_racer_rs/build.rs

@@ -0,0 +1,16 @@
+#![allow(
+    clippy::print_stdout,
+    reason = "cargo reads build script directives from stdout"
+)]
+
+fn main() {
+    println!("cargo::rerun-if-env-changed=DEP_MINI_RACER_MADVISE_WRAP");
+    if std::env::var("DEP_MINI_RACER_MADVISE_WRAP").is_ok_and(|v| v == "madvise") {
+        println!("cargo::rustc-link-arg-cdylib=-Wl,--wrap=madvise");
+    }
+    // Ruby dlopens extensions RTLD_GLOBAL; -Bsymbolic keeps our V8 and rusty_v8
+    // symbols bound to our own copies if another extension exports the same names.
+    if std::env::var("CARGO_CFG_TARGET_OS").is_ok_and(|os| os == "linux") {
+        println!("cargo::rustc-link-arg-cdylib=-Wl,-Bsymbolic");
+    }
+}

data/ext/mini_racer_rs/extconf.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "mkmf"
+
+if RUBY_ENGINE == "truffleruby"
+  File.write("Makefile", dummy_makefile(__dir__).join)
+  return
+end
+
+TARGETS = {
+  %w[x86_64 linux] => "x86_64-unknown-linux-gnu",
+  %w[aarch64 linux] => "aarch64-unknown-linux-gnu",
+  %w[arm64 darwin] => "aarch64-apple-darwin",
+  %w[aarch64 darwin] => "aarch64-apple-darwin",
+  %w[x86_64 darwin] => "x86_64-apple-darwin",
+}.freeze
+MINIMUM_RUST = Gem::Version.new("1.91.0")
+
+host_os = RbConfig::CONFIG["host_os"]
+os = case host_os
+     when /linux-musl/ then nil
+     when /linux/ then "linux"
+     when /darwin/ then "darwin"
+     end
+target = os && TARGETS[[RbConfig::CONFIG["host_cpu"], os]]
+unless target
+  abort "mini_racer_rs supports Linux (glibc) on x86_64 and aarch64 and macOS on arm64 and x86_64; " \
+        "#{RbConfig::CONFIG["host_cpu"]}-#{host_os} is not supported"
+end
+
+rustc_version = `#{ENV.fetch("RUSTC", "rustc")} --version 2>/dev/null`[/\d+\.\d+\.\d+/]
+if rustc_version.nil? || Gem::Version.new(rustc_version) < MINIMUM_RUST
+  abort "mini_racer_rs needs Rust #{MINIMUM_RUST} or newer to build from source " \
+        "(found #{rustc_version || "no rustc"}); install it from https://rustup.rs"
+end
+
+build_env = {}
+unless ENV.key?("LIBCLANG_PATH")
+  begin
+    require "libclang"
+    build_env["LIBCLANG_PATH"] = Libclang.libdir
+    # The libclang gem ships no compiler builtin headers (stdarg.h); borrow GCC's.
+    gcc_include = `gcc -print-file-name=include 2>/dev/null`.strip
+    if os == "linux" && !ENV.key?("BINDGEN_EXTRA_CLANG_ARGS") && File.directory?(gcc_include)
+      build_env["BINDGEN_EXTRA_CLANG_ARGS"] = "-I#{gcc_include}"
+    end
+  rescue LoadError
+    libclang = find_executable("llvm-config") || Dir[
+      "/usr/lib*/libclang*.so*",
+      "/usr/lib*/llvm*/lib/libclang*.so*",
+      "/usr/lib/*-linux-gnu/libclang*.so*",
+      "/usr/lib/llvm-*/lib/libclang*.so*",
+      "/Library/Developer/CommandLineTools/usr/lib/libclang.dylib",
+      "/Applications/Xcode*.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/libclang.dylib",
+      "/opt/homebrew/opt/llvm/lib/libclang.dylib",
+      "/usr/local/opt/llvm/lib/libclang.dylib",
+    ].first
+    unless libclang
+      abort "mini_racer_rs needs libclang to build from source: install clang " \
+            "(for example `apt install libclang-dev`), run `gem install libclang`, or set LIBCLANG_PATH"
+    end
+  end
+end
+
+pinned = File.readlines(File.join(__dir__, "v8-archives.sha256"), chomp: true).to_h do |line|
+  sha, file = line.split(/\s+/, 2)
+  [file, sha]
+end
+unless %w[RUSTY_V8_ARCHIVE RUSTY_V8_MIRROR RUSTY_V8_ARCHIVE_SHA256].any? { ENV.key?(_1) }
+  build_env["RUSTY_V8_ARCHIVE_SHA256"] = pinned.fetch("librusty_v8_release_#{target}.a.gz")
+end
+
+require "rb_sys/mkmf"
+
+create_rust_makefile("mini_racer_rs/mini_racer_rs") do |r|
+  r.extra_cargo_args += ["--locked"]
+  r.env.merge!(build_env)
+end