neon/sys/
no_panic.rs

1//! Utilities that _will_ not panic for use in contexts where unwinding would be
2//! undefined behavior.
3//!
4//! The following helpers do not panic and instead use `napi_fatal_error`
5//! to crash the process in a controlled way, making them safe for use in FFI
6//! callbacks.
7//!
8//! `#[track_caller]` is used on these helpers to ensure `fatal_error` reports
9//! the calling location instead of the helpers defined here.
10
11use std::{
12    any::Any,
13    ffi::c_void,
14    mem::MaybeUninit,
15    panic::{catch_unwind, AssertUnwindSafe},
16    ptr,
17};
18
19use super::{
20    bindings as napi,
21    debug_send_wrapper::DebugSendWrapper,
22    error::fatal_error,
23    raw::{Env, Local},
24};
25
26type Panic = Box<dyn Any + Send + 'static>;
27
28const UNKNOWN_PANIC_MESSAGE: &str = "Unknown panic";
29
30/// `FailureBoundary`] acts as boundary between Rust and FFI code, protecting
31/// a critical section of code from unhandled failure. It will catch both Rust
32/// panics and JavaScript exceptions. Attempts to handle failures are executed
33/// in order of ascending severity:
34///
35/// 1. Reject a `Promise` if a `Deferred` was provided
36/// 2. Emit a fatal exception
37/// 3. Abort the process with a message and location
38///
39/// This process will be aborted if any step unrecoverably fails. For example,
40/// if a `napi::Env` is unavailable, it is impossible to reject a `Promise` or
41/// emit a fatal exception.
42pub struct FailureBoundary {
43    pub both: &'static str,
44    pub exception: &'static str,
45    pub panic: &'static str,
46}
47
48impl FailureBoundary {
49    #[track_caller]
50    pub unsafe fn catch_failure<F>(&self, env: Env, deferred: Option<napi::Deferred>, f: F)
51    where
52        F: FnOnce(Option<Env>) -> Local,
53    {
54        // Make `env = None` if unable to call into JS
55        #[allow(clippy::unnecessary_lazy_evaluations)]
56        let env = can_call_into_js(env).then(|| env);
57
58        // Run the user supplied callback, catching panics
59        // This is unwind safe because control is never yielded back to the caller
60        let panic = catch_unwind(AssertUnwindSafe(move || f(env)));
61
62        // Unwrap the `Env`
63        let env = if let Some(env) = env {
64            env
65        } else {
66            // If there was a panic and we don't have an `Env`, crash the process
67            if let Err(panic) = panic {
68                let msg = panic_msg(&panic).unwrap_or(UNKNOWN_PANIC_MESSAGE);
69
70                fatal_error(msg);
71            }
72
73            // If we don't have an `Env`, we can't catch an exception, nothing more to try
74            return;
75        };
76
77        // Check and catch a thrown exception
78        let exception = catch_exception(env);
79
80        // Create an error message or return if there wasn't a panic or exception
81        let msg = match (exception, panic.as_ref()) {
82            // Exception and a panic
83            (Some(_), Err(_)) => self.both,
84
85            // Exception, but not a panic
86            (Some(err), Ok(_)) => {
87                // Reject the promise without wrapping
88                if let Some(deferred) = deferred {
89                    reject_deferred(env, deferred, err);
90
91                    return;
92                }
93
94                self.exception
95            }
96
97            // Panic, but not an exception
98            (None, Err(_)) => self.panic,
99
100            // No errors occurred! We're done!
101            (None, Ok(value)) => {
102                if let Some(deferred) = deferred {
103                    resolve_deferred(env, deferred, *value);
104                }
105
106                return;
107            }
108        };
109
110        // Reject the promise
111        if let Some(deferred) = deferred {
112            let error = create_error(env, msg, exception, panic.err());
113
114            reject_deferred(env, deferred, error);
115
116            return;
117        }
118
119        let error = create_error(env, msg, exception, panic.err());
120
121        // Trigger a fatal exception
122        fatal_exception(env, error);
123    }
124}
125
126// HACK: Force `NAPI_PREAMBLE` to run without executing any JavaScript to tell if it's
127// possible to call into JS.
128//
129// `NAPI_PREAMBLE` is a macro that checks if it is possible to call into JS.
130// https://github.com/nodejs/node/blob/5fad0b93667ffc6e4def52996b9529ac99b26319/src/js_native_api_v8.h#L211-L218
131//
132//  `napi_throw` starts by using `NAPI_PREAMBLE` and then a `CHECK_ARGS` on the `napi_value`. Since
133// we already know `env` is non-null, we expect the `null` value to cause a `napi_invalid_arg` error.
134// https://github.com/nodejs/node/blob/5fad0b93667ffc6e4def52996b9529ac99b26319/src/js_native_api_v8.cc#L1925-L1926
135fn can_call_into_js(env: Env) -> bool {
136    !env.is_null() && unsafe { napi::throw(env, ptr::null_mut()) == Err(napi::Status::InvalidArg) }
137}
138
139// We cannot use `napi_fatal_exception` because of this bug; instead, cause an
140// unhandled rejection which has similar behavior on recent versions of Node.
141// https://github.com/nodejs/node/issues/33771
142unsafe fn fatal_exception(env: Env, error: Local) {
143    let mut deferred = MaybeUninit::uninit();
144    let mut promise = MaybeUninit::uninit();
145
146    let deferred = match napi::create_promise(env, deferred.as_mut_ptr(), promise.as_mut_ptr()) {
147        Ok(()) => deferred.assume_init(),
148        _ => fatal_error("Failed to create a promise"),
149    };
150
151    if napi::reject_deferred(env, deferred, error) != Ok(()) {
152        fatal_error("Failed to reject a promise");
153    }
154}
155
156#[track_caller]
157unsafe fn create_error(
158    env: Env,
159    msg: &str,
160    exception: Option<Local>,
161    panic: Option<Panic>,
162) -> Local {
163    // Construct the `uncaughtException` Error object
164    let error = error_from_message(env, msg);
165
166    // Add the exception to the error
167    if let Some(exception) = exception {
168        set_property(env, error, "cause", exception);
169    };
170
171    // Add the panic to the error
172    if let Some(panic) = panic {
173        set_property(env, error, "panic", error_from_panic(env, panic));
174    }
175
176    error
177}
178
179#[track_caller]
180unsafe fn resolve_deferred(env: Env, deferred: napi::Deferred, value: Local) {
181    if napi::resolve_deferred(env, deferred, value) != Ok(()) {
182        fatal_error("Failed to resolve promise");
183    }
184}
185
186#[track_caller]
187unsafe fn reject_deferred(env: Env, deferred: napi::Deferred, value: Local) {
188    if napi::reject_deferred(env, deferred, value) != Ok(()) {
189        fatal_error("Failed to reject promise");
190    }
191}
192
193#[track_caller]
194unsafe fn catch_exception(env: Env) -> Option<Local> {
195    if !is_exception_pending(env) {
196        return None;
197    }
198
199    let mut error = MaybeUninit::uninit();
200
201    if napi::get_and_clear_last_exception(env, error.as_mut_ptr()) != Ok(()) {
202        fatal_error("Failed to get and clear the last exception");
203    }
204
205    Some(error.assume_init())
206}
207
208#[track_caller]
209unsafe fn error_from_message(env: Env, msg: &str) -> Local {
210    let msg = create_string(env, msg);
211    let mut err = MaybeUninit::uninit();
212
213    let status = napi::create_error(env, ptr::null_mut(), msg, err.as_mut_ptr());
214
215    match status {
216        Ok(()) => err.assume_init(),
217        Err(_) => fatal_error("Failed to create an Error"),
218    }
219}
220
221#[track_caller]
222unsafe fn error_from_panic(env: Env, panic: Panic) -> Local {
223    if let Some(msg) = panic_msg(&panic) {
224        error_from_message(env, msg)
225    } else {
226        let error = error_from_message(env, UNKNOWN_PANIC_MESSAGE);
227        let panic = external_from_panic(env, panic);
228
229        set_property(env, error, "cause", panic);
230        error
231    }
232}
233
234#[track_caller]
235unsafe fn set_property(env: Env, object: Local, key: &str, value: Local) {
236    let key = create_string(env, key);
237
238    if napi::set_property(env, object, key, value).is_err() {
239        fatal_error("Failed to set an object property");
240    }
241}
242
243#[track_caller]
244unsafe fn panic_msg(panic: &Panic) -> Option<&str> {
245    if let Some(msg) = panic.downcast_ref::<&str>() {
246        Some(msg)
247    } else if let Some(msg) = panic.downcast_ref::<String>() {
248        Some(msg)
249    } else {
250        None
251    }
252}
253
254unsafe fn external_from_panic(env: Env, panic: Panic) -> Local {
255    let fail = || fatal_error("Failed to create a neon::types::JsBox from a panic");
256    let mut result = MaybeUninit::uninit();
257
258    if napi::create_external(
259        env,
260        Box::into_raw(Box::new(DebugSendWrapper::new(panic))).cast(),
261        Some(finalize_panic),
262        ptr::null_mut(),
263        result.as_mut_ptr(),
264    )
265    .is_err()
266    {
267        fail();
268    }
269
270    let external = result.assume_init();
271
272    #[cfg(feature = "napi-8")]
273    if napi::type_tag_object(env, external, &*crate::MODULE_TAG).is_err() {
274        fail();
275    }
276
277    external
278}
279
280extern "C" fn finalize_panic(_env: Env, data: *mut c_void, _hint: *mut c_void) {
281    unsafe {
282        drop(Box::from_raw(data.cast::<Panic>()));
283    }
284}
285
286#[track_caller]
287unsafe fn create_string(env: Env, msg: &str) -> Local {
288    let mut string = MaybeUninit::uninit();
289
290    if napi::create_string_utf8(env, msg.as_ptr().cast(), msg.len(), string.as_mut_ptr()).is_err() {
291        fatal_error("Failed to create a String");
292    }
293
294    string.assume_init()
295}
296
297unsafe fn is_exception_pending(env: Env) -> bool {
298    let mut throwing = false;
299
300    if napi::is_exception_pending(env, &mut throwing).is_err() {
301        fatal_error("Failed to check if an exception is pending");
302    }
303
304    throwing
305}
neon/sys/no_panic.rs

neon/sys/
no_panic.rs
