script_bindings/
callback.rs

1/* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
4
5//! Base classes to work with IDL callbacks.
6
7use std::default::Default;
8use std::ffi::CStr;
9use std::rc::Rc;
10
11use js::context::JSContext;
12use js::jsapi::{Heap, IsCallable, JSObject};
13use js::jsval::{JSVal, NullValue, ObjectValue, UndefinedValue};
14use js::rust::wrappers2::{EnterRealm, JS_WrapObject, LeaveRealm};
15use js::rust::{HandleObject, MutableHandleValue};
16
17use crate::codegen::GenericBindings::WindowBinding::Window_Binding::WindowMethods;
18use crate::error::{Error, Fallible};
19use crate::interfaces::{DocumentHelpers, DomHelpers, GlobalScopeHelpers};
20use crate::js::JS_GetProperty;
21use crate::permanent_root::PermanentRoot;
22use crate::realms::enter_auto_realm;
23use crate::reflector::DomObject;
24use crate::root::Dom;
25use crate::settings_stack::{run_a_callback, run_a_script};
26use crate::{DomTypes, cformat};
27
28pub trait ThisReflector {
29    fn jsobject(&self) -> *mut JSObject;
30}
31
32/// Try to obtain a Window object from a callback target.
33/// This Window may be different than the callback's associated global if the
34/// owner has been adopted into a different realm than it was created in.
35/// As such, the default implementation should be used for any callback target
36/// that cannot be adopted (i.e. is not a descendant of Node).
37pub trait OwnerWindow<D: DomTypes> {
38    fn owner_window(&self) -> Option<crate::root::DomRoot<D::Window>> {
39        None
40    }
41}
42
43impl<T: DomObject> ThisReflector for T {
44    fn jsobject(&self) -> *mut JSObject {
45        self.reflector().get_jsobject().get()
46    }
47}
48
49impl ThisReflector for HandleObject<'_> {
50    fn jsobject(&self) -> *mut JSObject {
51        self.get()
52    }
53}
54
55impl<D: DomTypes> OwnerWindow<D> for HandleObject<'_> {}
56
57/// The exception handling used for a call.
58#[derive(Clone, Copy, PartialEq)]
59pub enum ExceptionHandling {
60    /// Report any exception and don't throw it to the caller code.
61    Report,
62    /// Throw any exception to the caller code.
63    Rethrow,
64}
65
66/// A WebIDL callback that is treated as a GC root.
67pub struct RootedCallback<T>(Rc<(T, PermanentRoot)>);
68
69impl<D: DomTypes, T: HasCallbackHolder<D = D>> RootedCallback<T> {
70    /// Create a new [TracedCallback] value from this rooted callback.
71    pub fn to_traced(&self) -> TracedCallback<T>
72    where
73        T: for<'a> From<&'a CallbackObject<D>>,
74    {
75        let mut duplicate = Rc::new(T::from(self.callback_holder()));
76        // Note: callback cannot be moved after calling init.
77        match Rc::get_mut(&mut duplicate) {
78            Some(ref mut callback) => unsafe {
79                callback
80                    .callback_holder_mut()
81                    .init_callback(self.callback())
82            },
83            None => unreachable!(),
84        };
85        TracedCallback(duplicate)
86    }
87}
88
89impl<T> Clone for RootedCallback<T> {
90    fn clone(&self) -> Self {
91        Self(self.0.clone())
92    }
93}
94
95impl<T> std::ops::Deref for RootedCallback<T> {
96    type Target = T;
97    fn deref(&self) -> &Self::Target {
98        &self.0.0
99    }
100}
101
102impl<T: js::conversions::ToJSValConvertible> js::conversions::ToJSValConvertible
103    for RootedCallback<T>
104{
105    fn to_jsval(&self, cx: &mut JSContext, rval: MutableHandleValue<'_>) {
106        self.0.0.to_jsval(cx, rval)
107    }
108}
109
110#[cfg_attr(crown, crown::unrooted_must_root_lint::must_root)]
111#[derive(JSTraceable, MallocSizeOf, PartialEq)]
112/// A WebIDL callback value that can only be stored in locations that are
113/// traced by the GC.
114pub struct TracedCallback<T>(#[conditional_malloc_size_of] Rc<T>);
115
116impl<T: crate::JSTraceable> js::gc::Rootable for TracedCallback<T> {}
117
118impl<T> Clone for TracedCallback<T> {
119    fn clone(&self) -> Self {
120        Self(self.0.clone())
121    }
122}
123
124impl<T> std::ops::Deref for TracedCallback<T> {
125    type Target = T;
126    fn deref(&self) -> &Self::Target {
127        &self.0
128    }
129}
130
131#[expect(unsafe_code)]
132pub(crate) unsafe fn create_callback_rooted<D: DomTypes, T: HasCallbackHolder<D = D>>(
133    cx: &JSContext,
134    obj: T,
135    callback: *mut JSObject,
136) -> RootedCallback<T> {
137    let mut ret = Rc::new((obj, PermanentRoot::default()));
138    let (callback2, permanent_root) = Rc::get_mut(&mut ret).unwrap();
139    unsafe {
140        callback2.callback_holder_mut().init_callback(callback);
141        permanent_root.init(cx, callback2.callback(), c"Callback::root");
142    };
143    RootedCallback(ret)
144}
145
146impl<T: CallbackContainer + HasCallbackHolder> TracedCallback<T> {
147    pub fn root(&self, cx: &JSContext) -> RootedCallback<T> {
148        // Safety: the callback pointer is valid at this point.
149        unsafe { T::new(cx, self.callback()) }
150    }
151}
152
153/// A common base class for representing IDL callback function and
154/// callback interface types.
155#[derive(JSTraceable, MallocSizeOf)]
156#[cfg_attr(crown, crown::unrooted_must_root_lint::must_root)]
157pub struct CallbackObject<D: DomTypes> {
158    /// The underlying `JSObject`.
159    #[ignore_malloc_size_of = "measured by mozjs"]
160    callback: Heap<*mut JSObject>,
161    /// The ["callback context"], that is, the global to use as incumbent
162    /// global when calling the callback.
163    ///
164    /// Looking at the WebIDL standard, it appears as though there would always
165    /// be a value here, but [sometimes] callback functions are created by
166    /// hand-waving without defining the value of the callback context, and
167    /// without any JavaScript code on the stack to grab an incumbent global
168    /// from.
169    ///
170    /// ["callback context"]: https://heycam.github.io/webidl/#dfn-callback-context
171    /// [sometimes]: https://github.com/whatwg/html/issues/2248
172    incumbent: Option<Dom<D::GlobalScope>>,
173}
174
175impl<D: DomTypes> CallbackObject<D> {
176    fn new_from_existing(other: &CallbackObject<D>) -> Self {
177        Self {
178            callback: Heap::default(),
179            incumbent: other.incumbent.clone(),
180        }
181    }
182
183    fn new_with_exterior_root() -> Self {
184        Self {
185            callback: Heap::default(),
186            incumbent: D::GlobalScope::incumbent().map(|i| Dom::from_ref(&*i)),
187        }
188    }
189
190    pub fn get(&self) -> *mut JSObject {
191        self.callback.get()
192    }
193
194    #[expect(unsafe_code)]
195    unsafe fn init_callback(&mut self, callback: *mut JSObject) {
196        self.callback.set(callback);
197    }
198}
199
200impl<D: DomTypes> PartialEq for CallbackObject<D> {
201    fn eq(&self, other: &CallbackObject<D>) -> bool {
202        self.callback.get() == other.callback.get()
203    }
204}
205
206/// A type which can obtain a reference to a CallbackObject member.
207pub trait HasCallbackHolder {
208    type D: DomTypes;
209
210    /// Returns the underlying `CallbackObject`.
211    fn callback_holder(&self) -> &CallbackObject<Self::D>;
212    /// Returns the underlying `CallbackObject`.
213    fn callback_holder_mut(&mut self) -> &mut CallbackObject<Self::D>;
214
215    /// Returns the underlying `JSObject`.
216    fn callback(&self) -> *mut JSObject {
217        self.callback_holder().get()
218    }
219}
220
221/// A trait to be implemented by concrete IDL callback function and
222/// callback interface types.
223pub trait CallbackContainer {
224    /// Create a new rooted CallbackContainer object for the given `JSObject`.
225    ///
226    /// # Safety
227    /// `callback` must point to a valid, non-null JSObject.
228    unsafe fn new(cx: &JSContext, callback: *mut JSObject) -> RootedCallback<Self>
229    where
230        Self: Sized;
231}
232
233/// A common base class for representing IDL callback function types.
234#[derive(JSTraceable, MallocSizeOf, PartialEq)]
235#[cfg_attr(crown, crown::unrooted_must_root_lint::must_root)]
236pub struct CallbackFunction<D: DomTypes> {
237    object: CallbackObject<D>,
238}
239
240impl<'a, D: DomTypes> From<&'a CallbackObject<D>> for CallbackFunction<D> {
241    fn from(object: &'a CallbackObject<D>) -> Self {
242        Self {
243            object: CallbackObject::new_from_existing(object),
244        }
245    }
246}
247
248impl<D: DomTypes> CallbackFunction<D> {
249    /// Create a new `CallbackFunction` for this object, with rooting provided
250    /// by the caller.
251    pub(crate) fn new_with_exterior_root() -> Self {
252        Self {
253            object: CallbackObject::new_with_exterior_root(),
254        }
255    }
256}
257
258impl<D: DomTypes> HasCallbackHolder for CallbackFunction<D> {
259    type D = D;
260    /// Returns the underlying `CallbackObject`.
261    fn callback_holder(&self) -> &CallbackObject<D> {
262        &self.object
263    }
264
265    fn callback_holder_mut(&mut self) -> &mut CallbackObject<D> {
266        &mut self.object
267    }
268}
269
270/// A common base class for representing IDL callback interface types.
271#[derive(JSTraceable, MallocSizeOf, PartialEq)]
272#[cfg_attr(crown, crown::unrooted_must_root_lint::must_root)]
273pub struct CallbackInterface<D: DomTypes> {
274    object: CallbackObject<D>,
275}
276
277impl<'a, D: DomTypes> From<&'a CallbackObject<D>> for CallbackInterface<D> {
278    fn from(object: &'a CallbackObject<D>) -> Self {
279        Self {
280            object: CallbackObject::new_from_existing(object),
281        }
282    }
283}
284
285impl<D: DomTypes> HasCallbackHolder for CallbackInterface<D> {
286    type D = D;
287    /// Returns the underlying `CallbackObject`.
288    fn callback_holder(&self) -> &CallbackObject<D> {
289        &self.object
290    }
291
292    fn callback_holder_mut(&mut self) -> &mut CallbackObject<D> {
293        &mut self.object
294    }
295}
296
297impl<D: DomTypes> CallbackInterface<D> {
298    /// Create a new CallbackInterface object with rooting provided by the caller.
299    pub(crate) fn new_with_exterior_root() -> Self {
300        Self {
301            object: CallbackObject::new_with_exterior_root(),
302        }
303    }
304
305    /// Returns the property with the given `name`, if it is a callable object,
306    /// or an error otherwise.
307    pub fn get_callable_property(&self, cx: &mut JSContext, name: &CStr) -> Fallible<JSVal> {
308        rooted!(&in(cx) let mut callable = UndefinedValue());
309        rooted!(&in(cx) let obj = self.callback_holder().get());
310        unsafe {
311            if !JS_GetProperty(cx, obj.handle(), name, callable.handle_mut()) {
312                return Err(Error::JSFailed);
313            }
314
315            if !callable.is_object() || !IsCallable(callable.to_object()) {
316                return Err(Error::Type(cformat!(
317                    "The value of the {} property is not callable",
318                    name.to_string_lossy()
319                )));
320            }
321        }
322        Ok(callable.get())
323    }
324}
325
326/// Wraps the reflector for `p` into the realm of `cx`.
327pub(crate) fn wrap_call_this_value<T: ThisReflector>(
328    cx: &mut JSContext,
329    p: &T,
330    mut rval: MutableHandleValue,
331) -> bool {
332    rooted!(&in(cx) let mut obj = p.jsobject());
333
334    if obj.is_null() {
335        rval.set(NullValue());
336        return true;
337    }
338
339    unsafe {
340        if !JS_WrapObject(cx, obj.handle_mut()) {
341            return false;
342        }
343    }
344
345    rval.set(ObjectValue(*obj));
346    true
347}
348
349/// A function wrapper that performs whatever setup we need to safely make a call.
350///
351/// <https://webidl.spec.whatwg.org/#es-invoking-callback-functions>
352pub(crate) fn call_setup<D: DomTypes, T: HasCallbackHolder<D = D>, R>(
353    cx: &mut JSContext,
354    callback: &T,
355    owner_window: Option<&D::Window>,
356    handling: ExceptionHandling,
357    f: impl FnOnce(&mut JSContext) -> R,
358) -> R {
359    if let Some(window) = owner_window {
360        window.Document().ensure_safe_to_run_script_or_layout();
361    }
362
363    // The global for reporting exceptions. This is the global object of the
364    // (possibly wrapped) callback object.
365    let global = unsafe { D::GlobalScope::from_object(callback.callback()) };
366    let global = &global;
367
368    // Step 8: Prepare to run script with relevant settings.
369    run_a_script::<D, R, _>(cx, global, move |cx| {
370        let actual_callback = || {
371            let old_realm = unsafe { EnterRealm(cx, callback.callback()) };
372            let result = f(cx);
373            unsafe {
374                LeaveRealm(cx, old_realm);
375            }
376            if handling == ExceptionHandling::Report {
377                let mut realm = enter_auto_realm::<D>(cx, &**global);
378                let cx = &mut realm.current_realm();
379                <D as DomHelpers<D>>::report_pending_exception(cx);
380            }
381            result
382        };
383        if let Some(incumbent_global) = callback.callback_holder().incumbent.as_deref() {
384            // Step 9: Prepare to run a callback with stored settings.
385            run_a_callback::<D, R>(incumbent_global, actual_callback)
386        } else {
387            actual_callback()
388        }
389    }) // Step 14.2: Clean up after running script with relevant settings.
390}
script_bindings/callback.rs

script_bindings/
callback.rs
