lib.rs

//! Minor conveniences on top of the backtrace crate
//!
//! See [`short_frames_strict`][] for details.
use backtrace::*;
use std::ops::Range;

#[cfg(test)]
mod test;

/// Gets an iterator over the frames that are part of Rust's "short backtrace" range.
/// If no such range is found, the full stack is yielded.
///
/// Rust generally tries to include special frames on the stack called `rust_end_short_backtrace`
/// and `rust_begin_short_backtrace` which delimit the "real" stackframes from "gunk" stackframes
/// like setting up main and invoking the panic runtime. This yields all the "real" frames between
/// those two (which theoretically can be nothing with enough optimization, although that's unlikely
/// for any non-trivial program).
///
/// If only one of the special frames is present we will only clamp one side of the stack
/// (similar to `a..` or `..a`). If the special frames are in the wrong order we will discard
/// them and produce the full stack. If multiple versions of a special frame are found
/// (I've seen it in the wild), we will pick the "innermost" ones, producing the smallest
/// possible backtrace (and excluding all special frames from the output).
///
/// Each element of the iterator includes a Range which you should use to slice
/// the frame's `symbols()` array. This handles the theoretical situation where "real" frames
/// got inlined together with the special marker frames. I want to believe this can't happen
/// but you can never trust backtraces to be reasonable! We will never yield a Frame to you
/// with an empty Range.
///
/// Note that some "gunk" frames may still be found within the short backtrace, as there is still some
/// platform-specific and optimization-specific glue around the edges because compilers are
/// complicated and nothing's perfect. This can include:
///
/// * `core::ops::function::FnOnce::call_once`
/// * `std::panicking::begin_panic_handler`
/// * `core::panicking::panic_fmt`
/// * `rust_begin_unwind`
///
/// In the future we may introduce a non-strict short_frames which heuristically filters
/// those frames out too. Until then, the strict approach is safe.
///
/// # Example
///
/// Here's an example simple "short backtrace" implementation.
/// Note the use of `sub_frames` for the inner loop to restrict `symbols`!
///
/// This example is based off of code found in `miette` (Apache-2.0), which itself
/// copied the logic from `human-panic` (MIT/Apache-2.0).
///
/// FIXME: it would be nice if this example consulted `RUST_BACKTRACE=full`,
/// and maybe other vars used by rust's builtin panic handler..?
///
/// ```
/// fn backtrace() -> String {
///     use std::fmt::Write;
///     if let Ok(var) = std::env::var("RUST_BACKTRACE") {
///         if !var.is_empty() && var != "0" {
///             const HEX_WIDTH: usize = std::mem::size_of::<usize>() + 2;
///             // Padding for next lines after frame's address
///             const NEXT_SYMBOL_PADDING: usize = HEX_WIDTH + 6;
///             let mut backtrace = String::new();
///             let trace = backtrace::Backtrace::new();
///             let frames = backtrace_ext::short_frames_strict(&trace).enumerate();
///             for (idx, (frame, subframes)) in frames {
///                 let ip = frame.ip();
///                 let _ = write!(backtrace, "\n{:4}: {:2$?}", idx, ip, HEX_WIDTH);
///     
///                 let symbols = frame.symbols();
///                 if symbols.is_empty() {
///                     let _ = write!(backtrace, " - <unresolved>");
///                     continue;
///                 }
///     
///                 for (idx, symbol) in symbols[subframes].iter().enumerate() {
///                     // Print symbols from this address,
///                     // if there are several addresses
///                     // we need to put it on next line
///                     if idx != 0 {
///                         let _ = write!(backtrace, "\n{:1$}", "", NEXT_SYMBOL_PADDING);
///                     }
///     
///                     if let Some(name) = symbol.name() {
///                         let _ = write!(backtrace, " - {}", name);
///                     } else {
///                         let _ = write!(backtrace, " - <unknown>");
///                     }
///     
///                     // See if there is debug information with file name and line
///                     if let (Some(file), Some(line)) = (symbol.filename(), symbol.lineno()) {
///                         let _ = write!(
///                             backtrace,
///                             "\n{:3$}at {}:{}",
///                             "",
///                             file.display(),
///                             line,
///                             NEXT_SYMBOL_PADDING
///                         );
///                     }
///                 }
///             }
///             return backtrace;
///         }
///     }
///     "".into()
/// }
/// ```
pub fn short_frames_strict(
    backtrace: &Backtrace,
) -> impl Iterator<Item = (&BacktraceFrame, Range<usize>)> {
    short_frames_strict_impl(backtrace)
}

pub(crate) fn short_frames_strict_impl<B: Backtraceish>(
    backtrace: &B,
) -> impl Iterator<Item = (&B::Frame, Range<usize>)> {
    // Search for the special frames
    let mut short_start = None;
    let mut short_end = None;
    let frames = backtrace.frames();
    for (frame_idx, frame) in frames.iter().enumerate() {
        let symbols = frame.symbols();
        for (subframe_idx, frame) in symbols.iter().enumerate() {
            if let Some(name) = frame.name().and_then(|n| n.as_str()) {
                // Yes these ARE backwards, and that's intentional! We want to print the frames from
                // "newest to oldest" (show what panicked first), and that's the order that Backtrace
                // gives us, but these magic labels view the stack in the opposite order. So we just
                // swap it once here and forget about that weirdness.
                //
                // Note that due to platform/optimization wobblyness you can end up with multiple frames
                // that contain these names in sequence. If that happens we just want to pick the two
                // that are closest together. For the start that means just using the last one we found,
                // and for the end that means taking the first one we find.
                if name.contains("rust_end_short_backtrace") {
                    short_start = Some((frame_idx, subframe_idx));
                }
                if name.contains("rust_begin_short_backtrace") && short_end.is_none() {
                    short_end = Some((frame_idx, subframe_idx));
                }
            }
        }
    }

    // Check if these are in the right order, if they aren't, discard them
    // This also handles the mega-cursed case of "someone made a symbol with both names
    // so actually they're the exact same subframe".
    if let (Some(start), Some(end)) = (short_start, short_end) {
        if start >= end {
            short_start = None;
            short_end = None;
        }
    }

    // By default we want to produce a full stack trace and now we'll try to clamp it.
    let mut first_frame = 0usize;
    let mut first_subframe = 0usize;
    // NOTE: this is INCLUSIVE
    let mut last_frame = frames.len().saturating_sub(1);
    // NOTE: this is EXCLUSIVE
    let mut last_subframe_excl = backtrace
        .frames()
        .last()
        .map(|frame| frame.symbols().len())
        .unwrap_or(0);

    // This code tries to be really paranoid about boundary conditions although in practice
    // most of them are impossible because there's always going to be gunk on either side
    // of the short backtrace to smooth out the boundaries, and panic_fmt is basically
    // impossible to optimize out. Still, don't trust backtracers!!!
    //
    // This library has a fuckton of tests to try to catch all the little corner cases here.

    // If we found the start bound...
    if let Some((idx, sub_idx)) = short_start {
        if frames[idx].symbols().len() == sub_idx + 1 {
            // If it was the last subframe of this frame, we want to just
            // use the whole next frame! It's ok if this takes us to `first_frame = len`,
            // that will be properly handled as an empty output
            first_frame = idx + 1;
            first_subframe = 0;
        } else {
            // Otherwise use this frame, and all the subframes after it
            first_frame = idx;
            first_subframe = sub_idx + 1;
        }
    }

    // If we found the end bound...
    if let Some((idx, sub_idx)) = short_end {
        if sub_idx == 0 {
            // If it was the first subframe of this frame, we want to just
            // use the whole previous frame!
            if idx == 0 {
                // If we were *also* on the first frame, set subframe_excl
                // to 0, indicating an empty output
                last_frame = 0;
                last_subframe_excl = 0;
            } else {
                last_frame = idx - 1;
                last_subframe_excl = frames[last_frame].symbols().len();
            }
        } else {
            // Otherwise use this frame (no need subframe math, exclusive bound!)
            last_frame = idx;
            last_subframe_excl = sub_idx;
        }
    }

    // If the two subframes managed to perfectly line up with eachother, just
    // throw everything out and yield an empty range. We don't need to fix any
    // other values at this point as they won't be used for anything with an
    // empty iterator
    let final_frames = {
        let start = (first_frame, first_subframe);
        let end = (last_frame, last_subframe_excl);
        if start == end {
            &frames[0..0]
        } else {
            &frames[first_frame..=last_frame]
        }
    };

    // Get the index of the last frame when starting from the first frame
    let adjusted_last_frame = last_frame.saturating_sub(first_frame);

    // finally do the iteration
    final_frames.iter().enumerate().map(move |(idx, frame)| {
        // Default to all subframes being yielded
        let mut sub_start = 0;
        let mut sub_end_excl = frame.symbols().len();
        // If we're on first frame, apply its subframe clamp
        if idx == 0 {
            sub_start = first_subframe;
        }
        // If we're on the last frame, apply its subframe clamp
        if idx == adjusted_last_frame {
            sub_end_excl = last_subframe_excl;
        }
        (frame, sub_start..sub_end_excl)
    })
}

pub(crate) trait Backtraceish {
    type Frame: Frameish;
    fn frames(&self) -> &[Self::Frame];
}

pub(crate) trait Frameish {
    type Symbol: Symbolish;
    fn symbols(&self) -> &[Self::Symbol];
}

pub(crate) trait Symbolish {
    type Name<'a>: SymbolNameish<'a>
    where
        Self: 'a;
    fn name(&self) -> Option<Self::Name<'_>>;
}

pub(crate) trait SymbolNameish<'a> {
    fn as_str(&self) -> Option<&'a str>;
}

impl Backtraceish for Backtrace {
    type Frame = BacktraceFrame;
    fn frames(&self) -> &[Self::Frame] {
        self.frames()
    }
}

impl Frameish for BacktraceFrame {
    type Symbol = BacktraceSymbol;
    fn symbols(&self) -> &[Self::Symbol] {
        self.symbols()
    }
}

impl Symbolish for BacktraceSymbol {
    type Name<'a> = SymbolName<'a>;
    fn name(&self) -> Option<Self::Name<'_>> {
        self.name()
    }
}

impl<'a> SymbolNameish<'a> for SymbolName<'a> {
    fn as_str(&self) -> Option<&'a str> {
        self.as_str()
    }
}