Backtrace API Proposal

[AlbertMarashi]

Research Summary

Every engine exposes the same core per-frame info:

• Function name
• File/path
• Line number (1-start-based)
• Column number (1-start-based)

V8 goes further with its CallSite API (16 methods) including isNative(), isEval(), isConstructor(), isAsync(), getThis(), getFunction(), etc.

SpiderMonkey & JSC only expose a formatted string - no structured API at all.

TC39 has proposals for structured stack frames but nothing past Stage 1-2 yet.

Proposal

For Boa's Rust-side API, the sensible minimum that matches what ShadowEntry already has is basically:

┌───────────────┬────────────────────────┐
│     Field     │ Already in ShadowEntry │
├───────────────┼────────────────────────┤
│ Function name │ Yes                    │
├───────────────┼────────────────────────┤
│ File path     │ Yes                    │
├───────────────┼────────────────────────┤
│ Line number   │ Yes                    │
├───────────────┼────────────────────────┤
│ Column number │ Yes                    │
├───────────────┼────────────────────────┤
│ Is native     │ Yes (variant)          │
└───────────────┴────────────────────────┘

That's the universal common denominator across all engines. Boa's ShadowEntry already has all of this - it just needs to be made public (or wrapped in a clean public type). There's really nothing to bikeshed here - the shape is obvious and matches the industry standard.

[jedel1043]

What about the fact that ShadowEntry is an enum? Does it make sense to leave it like that or should we add something like #[non_exhaustive] or make it a private enum with methods to access their variants?

[AlbertMarashi]

Yes, I believe a method-based approach would be suited here, as it keeps the internals private. Those core essential API methods are unlikely to ever change.

[jedel1043]

If they're unlikely to change, then the enum itself would be unlikely to change, right? Then, wouldn't it be better to just add #[non_exhaustive] to it? I don't see us adding more types of functions other than non-native and native ones

[AlbertMarashi]

Maybe there could be WASM, Web Workers, error causes, custom user stack frames(?) - or maybe we want to expose some state about async tasks, or perhaps we want to represent anonymous functions a bit differently in the future...

It's possible that we may want to change things internally, But I believe that the core functionality revolving getting basic stack trace info (resource, location) will remain stable over time, adding new methods down the line won't break anything.

[jedel1043]

Hmmm true, being able to transparently provide WASM strack traces would be really useful. Additionally, it's easier to go from an opaque type to an enum type than the inverse, so it should be easy to backpedal if in the future we determine that an enum is better.

Yeah, we can go with an opaque ShadowEntry

[AlbertMarashi]

another thing worth considering is potential cases for sourcemaps that may be provided for bundled, or transpiled JS code, or WASM modules down the line.

most likely, we'd want the source mapped code locations to appear in our backtraces as opposed to bundled code - in many cases, some JS modules may even be entirely virtual (e.g. produced by a module resolver at runtime for transpilation purposes) - in this case, most users would want or expect the source locations to be representative of their source code.