miniextendr_api/

r_memory.rs

//! Utilities for recovering R SEXPs from raw data pointers.
//!
//! R stores vector data at a fixed offset after the SEXPREC header. Given a
//! pointer into that data region, we can subtract the header size to recover
//! the SEXP — then verify it by reading raw memory fields (type tag, ALTREP
//! bit, and vecsxp.length) without calling any R functions.
//!
//! This is used by:
//! - Arrow integration: zero-copy IntoR when the buffer is genuinely R-backed
//!   (the value buffer must be unsliced and exactly sized — see #867)
//!
//! It is deliberately *not* used for `Cow<[T]>` IntoR: a bare `&[T]` carries no
//! provenance metadata to prove it points at the start of an R vector, so a
//! borrowed sub-slice would probe off into unrelated memory (the #880 hazard).
//! That path always copies instead.
//!
//! # Initialization
//!
//! [`init_sexprec_data_offset`] must be called during package init (before any
//! recovery attempts). It measures the offset on a real R vector, so it works
//! across R versions and platforms.
//!
//! # R's VECTOR_SEXPREC layout
//!
//! ```text
//! // From R's Defn.h:
//! typedef struct VECTOR_SEXPREC {
//!     SEXPREC_HEADER;           // sxpinfo(8) + attrib(8) + gengc_next(8) + gengc_prev(8)
//!     struct vecsxp_struct {    // length(8) + truelength(8)
//!         R_xlen_t length;
//!         R_xlen_t truelength;
//!     } vecsxp;
//! } VECTOR_SEXPREC;
//!
//! typedef union { VECTOR_SEXPREC s; double align; } SEXPREC_ALIGN;
//! #define STDVEC_DATAPTR(x) ((void *)(((SEXPREC_ALIGN *)(x)) + 1))
//! ```
//!
//! On 64-bit: `sizeof(VECTOR_SEXPREC)` = 48 bytes, `sizeof(SEXPREC_ALIGN)` = 48.
//! Data starts at `sexp + 48`. All vector types (REALSXP, INTSXP, RAWSXP,
//! STRSXP, VECSXP) use the same `VECTOR_SEXPREC` header.
//!
//! # Why not `#[repr(C)]` mirror struct?
//!
//! A Rust `#[repr(C)]` struct mirroring `VECTOR_SEXPREC` would give a
//! compile-time `size_of` instead of runtime measurement. However:
//! - R's layout can vary by version and compile options (32-bit, padding)
//! - The runtime measurement is one allocation at init — negligible
//! - A `repr(C)` mirror struct doesn't help with the real safety issue:
//!   reading from a speculative pointer. `addr_of!` computes field addresses
//!   without dereferencing, but we still need to `read()` the type tag — and
//!   that read is from potentially invalid memory for non-R pointers.
//!
//! The verification (type tag + ALTREP check + XLENGTH) prevents false
//! positives. Only the type tag requires a raw sxpinfo read; ALTREP and
//! XLENGTH use R's public C API.
//!
//! # Safety of speculative reads
//!
//! The candidate pointer is computed from pointer arithmetic on the input
//! data_ptr. For Rust-owned buffers (not R-backed), this points into
//! arbitrary heap memory. We must be careful about which R functions we
//! call on it:
//!
//! - **`ALTREP(x)`** — safe: just reads `x->sxpinfo.alt` (a single bit).
//! - **`XLENGTH(x)`** on non-ALTREP — safe: reads `STDVEC_LENGTH` (struct
//!   field, no dispatch, no error).
//! - **`LENGTH(x)`** — UNSAFE: wraps XLENGTH with `> INT_MAX` check that
//!   calls `R_BadLongVector()` (throws R error on garbage with large length).
//! - **`DATAPTR_RO(x)`** — UNSAFE on ALTREP: dispatches through class vtable
//!   (bogus function pointers on garbage). On non-ALTREP: `STDVEC_DATAPTR`
//!   which also checks for long vectors.
//!
//! The verification sequence is:
//! 1. Raw sxpinfo type tag (bits 0-4) — no public TYPEOF that's safe on garbage
//! 2. `ALTREP(candidate)` — gates step 3 (rejects ALTREP before XLENGTH dispatch)
//! 3. `XLENGTH(candidate)` — safe for non-ALTREP (STDVEC_LENGTH, no errors)

use std::sync::atomic::{AtomicUsize, Ordering};

use crate::sys::{self};
use crate::{SEXP, SEXPREC, SEXPTYPE, SexpExt};

/// Offset in bytes from SEXP address to data pointer for standard (non-ALTREP) vectors.
///
/// `DATAPTR_RO(sexp) == (sexp as *const u8).add(SEXPREC_DATA_OFFSET)`
///
/// Zero means not yet initialized.
static SEXPREC_DATA_OFFSET: AtomicUsize = AtomicUsize::new(0);

/// Get the computed SEXPREC data offset.
///
/// Returns 0 if not yet initialized.
#[inline]
pub fn sexprec_data_offset() -> usize {
    SEXPREC_DATA_OFFSET.load(Ordering::Relaxed)
}

/// Compute and store the SEXPREC data offset by measuring a real R vector.
///
/// Must be called from R's main thread during package init.
///
/// # Safety
///
/// Must be called on R's main thread with R initialized.
pub unsafe fn init_sexprec_data_offset() {
    unsafe {
        // keep raw: bootstrap init probe. Runs before the crate's protect
        // infrastructure is guaranteed set up; a one-shot balanced protect of a
        // throwaway REALSXP is the clearest expression here.
        let test = sys::Rf_protect(sys::Rf_allocVector(SEXPTYPE::REALSXP, 1));
        let sexp_addr = test.0 as usize;
        let data_addr = sys::DATAPTR_RO(test) as usize;
        SEXPREC_DATA_OFFSET.store(data_addr - sexp_addr, Ordering::Relaxed);
        sys::Rf_unprotect(1);
    }
}

/// Try to recover the source R SEXP from a data pointer.
///
/// Given a pointer that may point into an R vector's data area, this
/// subtracts the known SEXPREC header size to get a candidate SEXP, then
/// verifies it:
/// 1. The SEXP type tag (bits 0-4 of sxpinfo) matches `expected_type`
/// 2. `ALTREP(candidate)` is false (only non-ALTREP vectors have fixed-offset data)
/// 3. `XLENGTH(candidate)` matches `expected_len` (safe for non-ALTREP)
///
/// Returns `None` if:
/// - The offset hasn't been initialized yet
/// - The pointer doesn't come from an R vector
/// - The candidate SEXP has the wrong type or length
/// - The candidate is an ALTREP vector (data not at fixed offset from SEXP)
///
/// # Why this is outside Rust's memory model (see #63)
///
/// This is a conservative-GC-style probe, analogous to Boehm GC scanning
/// the heap without allocation provenance. We compute a speculative pointer
/// via `wrapping_byte_sub` (well-defined pointer arithmetic) and read the
/// first 4 bytes (sxpinfo bits) to check whether the address looks like the
/// start of a SEXPREC. For pointers that did not come from an R SEXP, that
/// read has no valid allocation provenance under Rust's Stacked / Tree
/// Borrows model — it's defined behavior at the hardware level (the heap
/// is contiguous mapped memory), but Miri correctly flags it as UB.
///
/// We guard the read with a 4096-byte address floor (below which the
/// candidate would cross into unmapped memory), the ALTREP bit check
/// (prevents calling dispatch fns on garbage), and the length check
/// (filters random garbage with high probability). Callers that cannot
/// tolerate a false positive must not rely on this path alone.
///
/// To keep Miri green, the whole recovery is a no-op under `#[cfg(miri)]`:
/// we always return `None`, and callers fall back to the copy path. This
/// is not a correctness change — the copy path is always a valid alternative.
///
/// # Safety
///
/// Must be called on R's main thread. The data pointer must be valid
/// (i.e., it must point to readable memory for at least `expected_len`
/// elements, which is guaranteed if it came from an Arrow buffer).
pub unsafe fn try_recover_r_sexp(
    data_ptr: *const u8,
    expected_type: SEXPTYPE,
    expected_len: usize,
) -> Option<SEXP> {
    // Speculative sxpinfo read has no provenance for Rust-allocated buffers
    // (see `#63`). Under Miri, skip the probe entirely so the copy path is
    // exercised and the analyzer stays clean. No functional regression.
    #[cfg(miri)]
    {
        let _ = (data_ptr, expected_type, expected_len);
        return None;
    }

    #[cfg_attr(miri, allow(unreachable_code))]
    let offset = SEXPREC_DATA_OFFSET.load(Ordering::Relaxed);
    if offset == 0 {
        return None;
    }

    // Zero-length vectors can't be recovered (R uses sentinel pointer 0x1,
    // and empty Arrow buffers use dangling pointers).
    if expected_len == 0 {
        return None;
    }

    let data_addr = data_ptr as usize;

    // Reject pointers that would wraparound or are in invalid ranges.
    // R's sentinel for empty vectors is 0x1; wrapping_byte_sub on small
    // addresses produces huge values (top of address space) → segfault.
    // The 4096 threshold also guards against speculative reads near page
    // boundaries — for non-R pointers (e.g. Rust-allocated Arrow buffers),
    // subtracting the offset could land before the start of mapped memory.
    if data_addr < offset.saturating_add(4096) {
        return None;
    }

    // Compute candidate SEXP by subtracting header size.
    // wrapping_byte_sub is defined behavior for all pointer arithmetic.
    let candidate_ptr = (data_ptr as *mut SEXPREC).wrapping_byte_sub(offset);

    let candidate = SEXP(candidate_ptr);

    // Quick check: type tag (bits 0-4 of sxpinfo, which is the first field).
    // For Rust-allocated buffers this reads arbitrary heap memory, but
    // wrapping_sub ensures the pointer arithmetic itself is defined.
    // The read is a plain u32 load from mapped heap.
    // No public R API reads TYPEOF without side effects on invalid pointers,
    // so a raw sxpinfo read is unavoidable here.
    let sxpinfo_bits = unsafe { *(candidate.0 as *const u32) };
    let type_bits = sxpinfo_bits & 0x1f;
    if type_bits != expected_type as u32 {
        return None;
    }

    // Reject ALTREP via R's public API (SexpExt::is_altrep → ALTREP(x)).
    // ALTREP vectors store data via indirection — can't recover them.
    // This also gates the xlength() call below: for non-ALTREP, XLENGTH is
    // just STDVEC_LENGTH (a struct field read, no dispatch, no error).
    // For ALTREP, XLENGTH dispatches through the class vtable which would
    // crash on a garbage pointer.
    if candidate.is_altrep() {
        return None;
    }

    // For non-ALTREP, xlength() → Rf_xlength → STDVEC_LENGTH — a direct
    // struct field read with no dispatch and no "long vectors not supported"
    // error. (LENGTH() wraps XLENGTH with an INT_MAX check that can
    // R_BadLongVector; XLENGTH itself never errors for non-ALTREP vectors.)
    if candidate.len() != expected_len {
        return None;
    }

    // No DATAPTR_RO round-trip check needed: for non-ALTREP vectors,
    // STDVEC_DATAPTR(x) == (char*)x + SEXPREC_DATA_OFFSET, and we
    // constructed candidate = data_ptr - offset, so the round-trip
    // is tautologically true. The type + ALTREP + length checks above
    // are the actual discriminators.

    Some(candidate)
}

// Miri-only regression for the `#[cfg(miri)]` gate in `try_recover_r_sexp` (#202).
//
// The whole module is gated `all(test, miri)`: the exercise is inherently a Miri
// exercise, and running the speculative `sxpinfo` read under a normal `cargo test`
// would read arbitrary heap bytes adjacent to a Rust allocation (unsound; the very
// reason the gate exists). Compiled out otherwise, so it neither runs the unsound
// read nor leaves an unused `use super::*` under the standard toolchain.
#[cfg(all(test, miri))]
mod miri_tests {
    use super::*;

    /// Round-trips `try_recover_r_sexp` on a Rust-allocated buffer under Miri.
    ///
    /// A non-zero offset is forced so the function reaches the speculative
    /// `sxpinfo` read rather than bailing at the `offset == 0` guard. With the
    /// `#[cfg(miri)]` no-op branch in place the call returns `None` immediately
    /// and Miri stays clean. If that gate is removed, Miri flags the
    /// `wrapping_byte_sub` read (a load outside the buffer's provenance) as UB
    /// and this test fails — which is exactly what keeps the gate honest.
    #[test]
    fn recover_from_rust_buffer_returns_none() {
        // Force the speculative-read path (skip the `offset == 0` early return).
        // Any plausible SEXPREC header size works; 56 B matches a 64-bit header.
        SEXPREC_DATA_OFFSET.store(56, Ordering::Relaxed);

        // A Rust-owned buffer; a heap address is far above the 4096-byte floor.
        let buf = vec![0u8; 1024];
        let recovered = unsafe { try_recover_r_sexp(buf.as_ptr(), SEXPTYPE::INTSXP, buf.len()) };
        assert!(
            recovered.is_none(),
            "try_recover_r_sexp must return None for a non-R (Rust) buffer under Miri"
        );

        // Don't leak the bogus offset into any other test in this crate.
        SEXPREC_DATA_OFFSET.store(0, Ordering::Relaxed);
    }
}