nautilus-plugin 0.64.0

// -------------------------------------------------------------------------------------------------
//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
//  https://nautechsystems.io
//
//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
//  You may not use this file except in compliance with the License.
//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
//
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.
// -------------------------------------------------------------------------------------------------

//! Catch-unwind wrapper used by every plug-in `extern "C"` thunk.
//!
//! Unwinding across an FFI boundary is undefined behavior, so every host-bound
//! call from a plug-in must be wrapped to convert a panic into a returned
//! [`PluginError`] with code [`PluginErrorCode::Panic`].

use std::panic::{AssertUnwindSafe, catch_unwind};

use crate::boundary::{PluginError, PluginErrorCode, PluginResult};

/// Wraps a closure in `catch_unwind` and maps a panic to a `PluginError`.
///
/// Macro-generated thunks call this so plug-in panics surface as errors instead
/// of unwinding through the FFI.
pub fn guard<T>(f: impl FnOnce() -> Result<T, PluginError>) -> PluginResult<T> {
    let result = catch_unwind(AssertUnwindSafe(f));
    match result {
        Ok(Ok(t)) => PluginResult::Ok(t),
        Ok(Err(e)) => PluginResult::Err(e),
        Err(payload) => {
            let message = panic_message(payload.as_ref());
            drop_payload(payload);
            PluginResult::Err(PluginError::new(PluginErrorCode::Panic, message))
        }
    }
}

/// Runs a closure under `catch_unwind` for thunks whose return type cannot
/// carry a `PluginError` (e.g. `extern "C" fn(...) -> u64`).
///
/// On panic, logs the message and aborts the process. Aborting is the only
/// sound option once a panic reaches this point: returning a sentinel would
/// silently corrupt downstream computation, and unwinding across the FFI
/// boundary is undefined behavior.
pub fn guard_infallible<T>(thunk_name: &str, f: impl FnOnce() -> T) -> T {
    match catch_unwind(AssertUnwindSafe(f)) {
        Ok(t) => t,
        Err(payload) => {
            let msg = panic_message(payload.as_ref());
            drop_payload(payload);
            log::error!(
                target: "nautilus_plugin",
                "plug-in panicked in `{thunk_name}` thunk; aborting process: {msg}",
            );
            std::process::abort();
        }
    }
}

/// Runs a closure under `catch_unwind` for thunks that return a raw pointer
/// where null already signals failure (`create`, `clone_handle`).
///
/// On panic, logs the message and returns null so the host can surface a
/// recoverable error instead of the process aborting.
pub fn guard_or_null<T>(thunk_name: &str, f: impl FnOnce() -> *mut T) -> *mut T {
    match catch_unwind(AssertUnwindSafe(f)) {
        Ok(ptr) => ptr,
        Err(payload) => {
            let msg = panic_message(payload.as_ref());
            drop_payload(payload);
            // A panicking logger must not unwind out of the thunk; the
            // null-return contract holds even when reporting fails.
            catch_unwind(AssertUnwindSafe(|| {
                log::error!(
                    target: "nautilus_plugin",
                    "plug-in panicked in `{thunk_name}` thunk; returning null: {msg}",
                );
            }))
            .unwrap_or_else(drop_payload);
            std::ptr::null_mut()
        }
    }
}

/// Runs a destructor closure under `catch_unwind` for `drop_handle` thunks.
///
/// On panic, logs the message and returns normally, leaking whatever the
/// destructor failed to release. A leaked value is recoverable; unwinding
/// across the FFI boundary or aborting the process is not.
pub fn guard_drop(thunk_name: &str, f: impl FnOnce()) {
    if let Err(payload) = catch_unwind(AssertUnwindSafe(f)) {
        let msg = panic_message(payload.as_ref());
        drop_payload(payload);
        // A panicking logger must not unwind out of the thunk; the
        // swallow-and-leak contract holds even when reporting fails.
        catch_unwind(AssertUnwindSafe(|| {
            log::error!(
                target: "nautilus_plugin",
                "plug-in panicked in `{thunk_name}` thunk; value leaked: {msg}",
            );
        }))
        .unwrap_or_else(drop_payload);
    }
}

/// Drops a panic payload while suppressing any unwind from its `Drop` impl.
///
/// `std::panic::catch_unwind` catches the original panic, but if the payload
/// itself panics on drop the second panic unwinds the caller. For an
/// `extern "C"` thunk that is undefined behavior. Wrapping the drop in
/// another `catch_unwind` keeps the surface around the FFI boundary
/// unwind-free even with adversarial payloads (e.g. `panic_any(T)` where
/// `T: Drop` panics). If disposal panics, its new payload is deliberately leaked.
pub fn drop_payload(payload: Box<dyn std::any::Any + Send>) {
    if let Err(nested) = catch_unwind(AssertUnwindSafe(move || drop(payload))) {
        // Its destructor is also untrusted; attempting another drop can unwind again
        #[allow(
            clippy::mem_forget,
            reason = "the replacement payload can also panic on drop"
        )]
        std::mem::forget(nested);
    }
}

pub(crate) fn panic_message(payload: &(dyn std::any::Any + Send)) -> String {
    if let Some(s) = payload.downcast_ref::<&'static str>() {
        (*s).to_string()
    } else if let Some(s) = payload.downcast_ref::<String>() {
        s.clone()
    } else {
        "plug-in panicked with non-string payload".to_string()
    }
}

#[cfg(test)]
mod tests {
    use std::sync::atomic::{AtomicUsize, Ordering};

    use rstest::rstest;

    use super::*;

    #[rstest]
    fn returns_ok_on_success() {
        let r = guard(|| Ok::<u32, PluginError>(7));
        assert_eq!(r.into_result().unwrap(), 7);
    }

    #[rstest]
    fn returns_err_on_returned_error() {
        let r = guard(|| Err::<u32, _>(PluginError::generic("boom")));
        let e = r.into_result().unwrap_err();
        assert_eq!(e.code, PluginErrorCode::Generic);
        assert_eq!(e.message_string(), "boom");
    }

    #[rstest]
    fn returns_err_on_string_panic() {
        let r = guard(|| -> Result<u32, PluginError> { panic!("oops") });
        let e = r.into_result().unwrap_err();
        assert_eq!(e.code, PluginErrorCode::Panic);
        assert!(e.message_string().contains("oops"));
    }

    #[rstest]
    fn returns_err_on_non_string_panic() {
        let r = guard(|| -> Result<u32, PluginError> {
            std::panic::panic_any(42_u32);
        });
        let e = r.into_result().unwrap_err();
        assert_eq!(e.code, PluginErrorCode::Panic);
        assert!(e.message_string().contains("non-string"));
    }

    #[rstest]
    fn guard_infallible_returns_inner_on_success() {
        let v = guard_infallible("test", || 42u64);
        assert_eq!(v, 42);
    }

    #[rstest]
    fn guard_or_null_returns_inner_on_success() {
        let boxed = Box::into_raw(Box::new(7u32));
        let v = guard_or_null("test", || boxed);
        assert_eq!(v, boxed);
        // SAFETY: pointer originates from Box::into_raw above.
        unsafe { drop(Box::from_raw(boxed)) };
    }

    #[rstest]
    fn guard_or_null_returns_null_on_panic() {
        let v: *mut u32 = guard_or_null("test", || panic!("create panic"));
        assert!(v.is_null());
    }

    #[rstest]
    fn guard_drop_runs_inner_on_success() {
        let mut ran = false;
        guard_drop("test", || ran = true);
        assert!(ran);
    }

    #[rstest]
    fn guard_drop_swallows_panic() {
        guard_drop("test", || panic!("drop panic"));
    }

    #[rstest]
    fn drop_payload_swallows_panicking_drop() {
        // `drop_payload` runs the payload Drop inside an inner `catch_unwind`
        // so a panicking Drop does not propagate out of the function. This
        // test asserts the call returns normally even when the payload
        // panics on drop.
        use std::{
            any::Any,
            sync::atomic::{AtomicUsize, Ordering},
        };

        static DROPS_OBSERVED: AtomicUsize = AtomicUsize::new(0);
        struct Bomb;
        impl Drop for Bomb {
            fn drop(&mut self) {
                DROPS_OBSERVED.fetch_add(1, Ordering::SeqCst);
                panic!("drop panic");
            }
        }
        DROPS_OBSERVED.store(0, Ordering::SeqCst);

        let payload: Box<dyn Any + Send> = Box::new(Bomb);
        drop_payload(payload);
        assert_eq!(DROPS_OBSERVED.load(Ordering::SeqCst), 1);
    }

    #[rstest]
    fn guard_survives_panic_any_with_panicking_drop() {
        // Regression: a panic payload whose Drop also panics must not unwind
        // past `catch_unwind`. `drop_payload` wraps the payload drop in a
        // second `catch_unwind`; without it the second panic aborts the host
        // or causes UB in the `extern "C"` thunk.
        static DROPS_OBSERVED: AtomicUsize = AtomicUsize::new(0);
        struct Bomb;
        impl Drop for Bomb {
            fn drop(&mut self) {
                DROPS_OBSERVED.fetch_add(1, Ordering::SeqCst);
                panic!("drop panic");
            }
        }

        DROPS_OBSERVED.store(0, Ordering::SeqCst);
        let r = guard(|| -> Result<u32, PluginError> {
            std::panic::panic_any(Bomb);
        });
        let e = r.into_result().unwrap_err();
        assert_eq!(e.code, PluginErrorCode::Panic);

        // Drop ran inside the inner catch_unwind; observed exactly once
        assert_eq!(DROPS_OBSERVED.load(Ordering::SeqCst), 1);
    }

    #[rstest]
    fn guard_contains_successive_panicking_payload_destructors() {
        use std::sync::Arc;

        struct Payload {
            drops: Arc<AtomicUsize>,
        }

        impl Drop for Payload {
            fn drop(&mut self) {
                self.drops.fetch_add(1, Ordering::SeqCst);
                std::panic::panic_any(Self {
                    drops: Arc::clone(&self.drops),
                });
            }
        }

        let drops = Arc::new(AtomicUsize::new(0));
        let result = catch_unwind(AssertUnwindSafe(|| {
            guard(|| -> Result<(), PluginError> {
                std::panic::panic_any(Payload {
                    drops: Arc::clone(&drops),
                });
            })
        }));
        let result = match result {
            Ok(result) => Some(result.into_result().unwrap_err()),
            Err(payload) => {
                // Disposing of this escaped payload would panic again in the failing test
                #[allow(
                    clippy::mem_forget,
                    reason = "preserve the assertion failure without another panic"
                )]
                std::mem::forget(payload);
                None
            }
        };

        assert_eq!(drops.load(Ordering::SeqCst), 1);
        let error = result.expect("panic cleanup must not unwind out of the guard");
        assert_eq!(error.code, PluginErrorCode::Panic);
        assert_eq!(
            error.message_string(),
            "plug-in panicked with non-string payload"
        );
    }

    #[rstest]
    fn guards_contain_panicking_logger_payloads() {
        const CHILD: &str = "NAUTILUS_TEST_PANIC_LOGGER_CHILD";
        static DROPS: AtomicUsize = AtomicUsize::new(0);
        struct Payload;
        impl Drop for Payload {
            fn drop(&mut self) {
                DROPS.fetch_add(1, Ordering::SeqCst);
                std::panic::panic_any(Self);
            }
        }
        struct Logger;
        impl log::Log for Logger {
            fn enabled(&self, _: &log::Metadata<'_>) -> bool {
                true
            }
            fn log(&self, _: &log::Record<'_>) {
                std::panic::panic_any(Payload);
            }
            fn flush(&self) {}
        }
        static LOGGER: Logger = Logger;
        extern "C" fn exercise() {
            let pointer = guard_or_null::<u8>("logger", || panic!("constructor panic"));
            assert!(pointer.is_null());
            guard_drop("logger", || panic!("destructor panic"));
        }

        if std::env::var_os(CHILD).is_none() {
            let current = std::thread::current();
            let name = current.name().expect("the test harness names its thread");
            let output = std::process::Command::new(std::env::current_exe().unwrap())
                .args(["--exact", name])
                .env(CHILD, "1")
                .output()
                .unwrap();
            assert!(
                output.status.success(),
                "{}",
                String::from_utf8_lossy(&output.stderr)
            );
            return;
        }

        log::set_logger(&LOGGER).unwrap();
        log::set_max_level(log::LevelFilter::Error);

        exercise();

        assert_eq!(DROPS.load(Ordering::SeqCst), 2);
    }
}