bao-servo-script-bindings 0.5.22

/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at https://mozilla.org/MPL/2.0/. */

//! Base classes to work with IDL callbacks.

use std::default::Default;
use std::ffi::CStr;
use std::rc::Rc;

use malloc_size_of::MallocConditionalSizeOf;
use malloc_size_of::MallocSizeOfOps;
use js::context::JSContext;
use js::jsapi::{Heap, IsCallable, JSObject, RemoveRawValueRoot};
use js::jsval::{JSVal, NullValue, ObjectValue, UndefinedValue};
use js::rust::wrappers2::{AddRawValueRoot, EnterRealm, JS_GetProperty, JS_WrapObject, LeaveRealm};
use js::rust::{HandleObject, MutableHandleValue, Runtime};

use crate::codegen::GenericBindings::WindowBinding::Window_Binding::WindowMethods;
use crate::error::{Error, Fallible};
use crate::interfaces::{DocumentHelpers, DomHelpers, GlobalScopeHelpers};
use crate::realms::enter_auto_realm;
use crate::reflector::DomObject;
use crate::root::Dom;
use crate::settings_stack::{run_a_callback, run_a_script};
use crate::{DomTypes, cformat};

pub trait ThisReflector {
    fn jsobject(&self) -> *mut JSObject;
}

/// Try to obtain a Window object from a callback target.
/// This Window may be different than the callback's associated global if the
/// owner has been adopted into a different realm than it was created in.
/// As such, the default implementation should be used for any callback target
/// that cannot be adopted (i.e. is not a descendant of Node).
pub trait OwnerWindow<D: DomTypes> {
    fn owner_window(&self) -> Option<crate::root::DomRoot<D::Window>> {
        None
    }
}

impl<T: DomObject> ThisReflector for T {
    fn jsobject(&self) -> *mut JSObject {
        self.reflector().get_jsobject().get()
    }
}

impl ThisReflector for HandleObject<'_> {
    fn jsobject(&self) -> *mut JSObject {
        self.get()
    }
}

impl<D: DomTypes> OwnerWindow<D> for HandleObject<'_> {}

/// The exception handling used for a call.
#[derive(Clone, Copy, PartialEq)]
pub enum ExceptionHandling {
    /// Report any exception and don't throw it to the caller code.
    Report,
    /// Throw any exception to the caller code.
    Rethrow,
}

// BAO patch (fork-maintained, 2026-09-27): GC root safety series replay —
// `RootedCallback`/`TracedCallback` from upstream (pre-window baseline delta,
// b820a9679 state), verbatim. Required by the rooted/traced callback
// conversions replayed in this wave (REQ-BRW-047 absorption wave ①).
#[derive(JSTraceable)]
pub struct RootedCallback<T>(Rc<T>);

impl<T> RootedCallback<T> {
    pub fn to_traced(&self) -> TracedCallback<T> {
        TracedCallback(self.0.clone())
    }

    // BAO patch (fork-maintained, 2026-09-28): ③c transitional accessor —
    // exposes the underlying `Rc<T>` for not-yet-flipped consumers until the
    // coordinated wave flips the callback decision globally.
    pub fn native(&self) -> Rc<T> {
        self.0.clone()
    }
}

impl<T> Clone for RootedCallback<T> {
    fn clone(&self) -> Self {
        Self(self.0.clone())
    }
}

impl<T> std::ops::Deref for RootedCallback<T> {
    type Target = T;
    fn deref(&self) -> &Self::Target {
        &self.0
    }
}

impl<T> From<Rc<T>> for RootedCallback<T> {
    fn from(callback: Rc<T>) -> Self {
        Self(callback)
    }
}

impl<T: js::conversions::ToJSValConvertible> js::conversions::ToJSValConvertible
    for RootedCallback<T>
{
    // BAO patch (fork-maintained, 2026-09-27): this fork's conversions trait
    // uses the `safe_to_jsval` form (no unsafe to_jsval), unlike the
    // pre-window upstream baseline this type is replayed from.
    fn safe_to_jsval(&self, cx: &mut JSContext, rval: MutableHandleValue) {
        self.0.safe_to_jsval(cx, rval)
    }
}

#[cfg_attr(crown, crown::unrooted_must_root_lint::must_root)]
#[derive(JSTraceable, MallocSizeOf, PartialEq)]
pub struct TracedCallback<T>(#[conditional_malloc_size_of] Rc<T>);

impl<T> From<Rc<T>> for TracedCallback<T> {
    fn from(callback: Rc<T>) -> Self {
        Self(callback)
    }
}

impl<T: crate::JSTraceable> js::gc::Rootable for TracedCallback<T> {}

impl<T> Clone for TracedCallback<T> {
    fn clone(&self) -> Self {
        Self(self.0.clone())
    }
}

impl<T> std::ops::Deref for TracedCallback<T> {
    type Target = T;
    fn deref(&self) -> &Self::Target {
        &self.0
    }
}

impl<T> TracedCallback<T> {
    pub fn root(&self) -> RootedCallback<T> {
        RootedCallback(self.0.clone())
    }
}

// BAO patch (fork-maintained, 2026-09-28): foundation ③a' — TracedCallback's
// ToJSValConvertible, completing the conversion surface for the decision-port
// needTraced form (dictionaries carrying callback members converted back to
// JS). Upstream (b820a9679 / origin/main) ships no such impl; this fork adds
// it in the same safe_to_jsval form as RootedCallback above (crown-era
// conversions trait — the pre-window to_jsval form does not exist here).
impl<T: js::conversions::ToJSValConvertible> js::conversions::ToJSValConvertible
    for TracedCallback<T>
{
    fn safe_to_jsval(&self, cx: &mut JSContext, rval: MutableHandleValue) {
        self.0.safe_to_jsval(cx, rval)
    }
}

/// A common base class for representing IDL callback function and
/// callback interface types.
#[derive(JSTraceable, MallocSizeOf)]
#[cfg_attr(crown, crown::unrooted_must_root_lint::must_root)]
pub struct CallbackObject<D: DomTypes> {
    /// The underlying `JSObject`.
    #[ignore_malloc_size_of = "measured by mozjs"]
    callback: Heap<*mut JSObject>,
    #[ignore_malloc_size_of = "measured by mozjs"]
    permanent_js_root: Heap<JSVal>,

    /// The ["callback context"], that is, the global to use as incumbent
    /// global when calling the callback.
    ///
    /// Looking at the WebIDL standard, it appears as though there would always
    /// be a value here, but [sometimes] callback functions are created by
    /// hand-waving without defining the value of the callback context, and
    /// without any JavaScript code on the stack to grab an incumbent global
    /// from.
    ///
    /// ["callback context"]: https://heycam.github.io/webidl/#dfn-callback-context
    /// [sometimes]: https://github.com/whatwg/html/issues/2248
    incumbent: Option<Dom<D::GlobalScope>>,
}

impl<D: DomTypes> CallbackObject<D> {
    // These are used by the bindings and do not need `default()` functions.
    #[allow(clippy::new_without_default)]
    fn new() -> Self {
        Self {
            callback: Heap::default(),
            permanent_js_root: Heap::default(),
            incumbent: D::GlobalScope::incumbent().map(|i| Dom::from_ref(&*i)),
        }
    }

    pub fn get(&self) -> *mut JSObject {
        self.callback.get()
    }

    #[expect(unsafe_code)]
    unsafe fn init(&mut self, cx: &JSContext, callback: *mut JSObject) {
        self.callback.set(callback);
        self.permanent_js_root.set(ObjectValue(callback));
        unsafe {
            assert!(AddRawValueRoot(
                cx,
                self.permanent_js_root.get_unsafe(),
                c"CallbackObject::root".as_ptr()
            ));
        }
    }
}

impl<D: DomTypes> Drop for CallbackObject<D> {
    #[expect(unsafe_code)]
    fn drop(&mut self) {
        unsafe {
            if let Some(cx) = Runtime::get() {
                RemoveRawValueRoot(cx.as_ptr(), self.permanent_js_root.get_unsafe());
            }
        }
    }
}

impl<D: DomTypes> PartialEq for CallbackObject<D> {
    fn eq(&self, other: &CallbackObject<D>) -> bool {
        self.callback.get() == other.callback.get()
    }
}

/// A trait to be implemented by concrete IDL callback function and
/// callback interface types.
pub trait CallbackContainer<D: DomTypes> {
    /// Create a new CallbackContainer object for the given `JSObject`.
    ///
    /// # Safety
    /// `callback` must point to a valid, non-null JSObject.
    unsafe fn new(cx: &JSContext, callback: *mut JSObject) -> Rc<Self>;
    /// Returns the underlying `CallbackObject`.
    fn callback_holder(&self) -> &CallbackObject<D>;
    /// Returns the underlying `JSObject`.
    fn callback(&self) -> *mut JSObject {
        self.callback_holder().get()
    }
    /// Returns the ["callback context"], that is, the global to use as
    /// incumbent global when calling the callback.
    ///
    /// ["callback context"]: https://heycam.github.io/webidl/#dfn-callback-context
    fn incumbent(&self) -> Option<&D::GlobalScope> {
        self.callback_holder().incumbent.as_deref()
    }
}

/// A common base class for representing IDL callback function types.
#[derive(JSTraceable, MallocSizeOf, PartialEq)]
#[cfg_attr(crown, crown::unrooted_must_root_lint::must_root)]
pub struct CallbackFunction<D: DomTypes> {
    object: CallbackObject<D>,
}

impl<D: DomTypes> CallbackFunction<D> {
    /// Create a new `CallbackFunction` for this object.
    // These are used by the bindings and do not need `default()` functions.
    #[expect(clippy::new_without_default)]
    pub fn new() -> Self {
        Self {
            object: CallbackObject::new(),
        }
    }

    /// Returns the underlying `CallbackObject`.
    pub fn callback_holder(&self) -> &CallbackObject<D> {
        &self.object
    }

    /// Initialize the callback function with a value.
    /// Should be called once this object is done moving.
    ///
    /// # Safety
    /// `callback` must point to a valid, non-null JSObject.
    pub unsafe fn init(&mut self, cx: &JSContext, callback: *mut JSObject) {
        unsafe { self.object.init(cx, callback) };
    }
}

/// A common base class for representing IDL callback interface types.
#[derive(JSTraceable, MallocSizeOf, PartialEq)]
#[cfg_attr(crown, crown::unrooted_must_root_lint::must_root)]
pub struct CallbackInterface<D: DomTypes> {
    object: CallbackObject<D>,
}

impl<D: DomTypes> CallbackInterface<D> {
    /// Create a new CallbackInterface object for the given `JSObject`.
    // These are used by the bindings and do not need `default()` functions.
    #[expect(clippy::new_without_default)]
    pub fn new() -> Self {
        Self {
            object: CallbackObject::new(),
        }
    }

    /// Returns the underlying `CallbackObject`.
    pub fn callback_holder(&self) -> &CallbackObject<D> {
        &self.object
    }

    /// Initialize the callback function with a value.
    /// Should be called once this object is done moving.
    ///
    /// # Safety
    /// `callback` must point to a valid, non-null JSObject.
    pub unsafe fn init(&mut self, cx: &JSContext, callback: *mut JSObject) {
        unsafe { self.object.init(cx, callback) };
    }

    /// Returns the property with the given `name`, if it is a callable object,
    /// or an error otherwise.
    pub fn get_callable_property(&self, cx: &mut JSContext, name: &CStr) -> Fallible<JSVal> {
        rooted!(&in(cx) let mut callable = UndefinedValue());
        rooted!(&in(cx) let obj = self.callback_holder().get());
        unsafe {
            if !JS_GetProperty(cx, obj.handle(), name.as_ptr(), callable.handle_mut()) {
                return Err(Error::JSFailed);
            }

            if !callable.is_object() || !IsCallable(callable.to_object()) {
                return Err(Error::Type(cformat!(
                    "The value of the {} property is not callable",
                    name.to_string_lossy()
                )));
            }
        }
        Ok(callable.get())
    }
}

/// Wraps the reflector for `p` into the realm of `cx`.
pub(crate) fn wrap_call_this_value<T: ThisReflector>(
    cx: &mut JSContext,
    p: &T,
    mut rval: MutableHandleValue,
) -> bool {
    rooted!(&in(cx) let mut obj = p.jsobject());

    if obj.is_null() {
        rval.set(NullValue());
        return true;
    }

    unsafe {
        if !JS_WrapObject(cx, obj.handle_mut()) {
            return false;
        }
    }

    rval.set(ObjectValue(*obj));
    true
}

/// A function wrapper that performs whatever setup we need to safely make a call.
///
/// <https://webidl.spec.whatwg.org/#es-invoking-callback-functions>
pub(crate) fn call_setup<D: DomTypes, T: CallbackContainer<D>, R>(
    cx: &mut JSContext,
    callback: &T,
    owner_window: Option<&D::Window>,
    handling: ExceptionHandling,
    f: impl FnOnce(&mut JSContext) -> R,
) -> R {
    if let Some(window) = owner_window {
        window.Document().ensure_safe_to_run_script_or_layout();
    }

    // The global for reporting exceptions. This is the global object of the
    // (possibly wrapped) callback object.
    let global = unsafe { D::GlobalScope::from_object(callback.callback()) };
    let global = &global;

    // Step 8: Prepare to run script with relevant settings.
    run_a_script::<D, R, _>(cx, global, move |cx| {
        let actual_callback = || {
            let old_realm = unsafe { EnterRealm(cx, callback.callback()) };
            let result = f(cx);
            unsafe {
                LeaveRealm(cx, old_realm);
            }
            if handling == ExceptionHandling::Report {
                let mut realm = enter_auto_realm::<D>(cx, &**global);
                let cx = &mut realm.current_realm();
                <D as DomHelpers<D>>::report_pending_exception(cx);
            }
            result
        };
        if let Some(incumbent_global) = callback.incumbent() {
            // Step 9: Prepare to run a callback with stored settings.
            run_a_callback::<D, R>(incumbent_global, actual_callback)
        } else {
            actual_callback()
        }
    }) // Step 14.2: Clean up after running script with relevant settings.
}

// BAO patch (fork-maintained, 2026-09-28): conditional malloc size for the
// callback wrappers (dom_struct derive with #[conditional_malloc_size_of]).
impl<T: malloc_size_of::MallocSizeOf> MallocConditionalSizeOf for RootedCallback<T> {
    fn conditional_size_of(&self, ops: &mut MallocSizeOfOps) -> usize {
        // Rc's conditional impl dedups shared allocations.
        self.0.conditional_size_of(ops)
    }
}

impl<T: malloc_size_of::MallocSizeOf> MallocConditionalSizeOf for TracedCallback<T> {
    fn conditional_size_of(&self, ops: &mut MallocSizeOfOps) -> usize {
        self.0.conditional_size_of(ops)
    }
}

// BAO patch (fork-maintained, 2026-09-28): JS-backed callback wrapper — the
// payload is GC-owned and measured by the JS heap, so the malloc-conditional
// contribution is nil (mirrors the Heap<T> convention).
impl<D: crate::DomTypes> MallocConditionalSizeOf for crate::codegen::GenericBindings::AnimationFrameProviderBinding::FrameRequestCallback<D> {
    fn conditional_size_of(&self, _ops: &mut MallocSizeOfOps) -> usize {
        0
    }
}