diff options
Diffstat (limited to '')
-rw-r--r-- | js/public/SavedFrameAPI.h | 159 |
1 files changed, 159 insertions, 0 deletions
diff --git a/js/public/SavedFrameAPI.h b/js/public/SavedFrameAPI.h new file mode 100644 index 0000000000..02bc65a0ea --- /dev/null +++ b/js/public/SavedFrameAPI.h @@ -0,0 +1,159 @@ +/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ + +/* + * Functions and types related to SavedFrame objects created by the Debugger + * API. + */ + +#ifndef js_SavedFrameAPI_h +#define js_SavedFrameAPI_h + +#include "jstypes.h" // JS_PUBLIC_API + +#include "js/ColumnNumber.h" // JS::TaggedColumnNumberOneOrigin +#include "js/TypeDecls.h" + +struct JSPrincipals; + +namespace JS { + +/* + * Accessors for working with SavedFrame JSObjects + * + * Each of these functions assert that if their `HandleObject savedFrame` + * argument is non-null, its JSClass is the SavedFrame class (or it is a + * cross-compartment or Xray wrapper around an object with the SavedFrame class) + * and the object is not the SavedFrame.prototype object. + * + * Each of these functions will find the first SavedFrame object in the chain + * whose underlying stack frame principals are subsumed by the given + * |principals|, and operate on that SavedFrame object. This prevents leaking + * information about privileged frames to un-privileged callers + * + * The SavedFrame in parameters do _NOT_ need to be in the same compartment as + * the cx, and the various out parameters are _NOT_ guaranteed to be in the same + * compartment as cx. + * + * You may consider or skip over self-hosted frames by passing + * `SavedFrameSelfHosted::Include` or `SavedFrameSelfHosted::Exclude` + * respectively. + * + * Additionally, it may be the case that there is no such SavedFrame object + * whose captured frame's principals are subsumed by |principals|! If the + * `HandleObject savedFrame` argument is null, or the |principals| do not + * subsume any of the chained SavedFrame object's principals, + * `SavedFrameResult::AccessDenied` is returned and a (hopefully) sane default + * value is chosen for the out param. + * + * See also `js/src/doc/SavedFrame/SavedFrame.md`. + */ + +enum class SavedFrameResult { Ok, AccessDenied }; + +enum class SavedFrameSelfHosted { Include, Exclude }; + +/** + * Given a SavedFrame JSObject, get its source property. Defaults to the empty + * string. + */ +extern JS_PUBLIC_API SavedFrameResult GetSavedFrameSource( + JSContext* cx, JSPrincipals* principals, Handle<JSObject*> savedFrame, + MutableHandle<JSString*> sourcep, + SavedFrameSelfHosted selfHosted = SavedFrameSelfHosted::Include); + +/** + * Given a SavedFrame JSObject, get an ID identifying its ScriptSource. + * Defaults to 0. + */ +extern JS_PUBLIC_API SavedFrameResult GetSavedFrameSourceId( + JSContext* cx, JSPrincipals* principals, Handle<JSObject*> savedFrame, + uint32_t* sourceIdp, + SavedFrameSelfHosted selfHosted = SavedFrameSelfHosted::Include); + +/** + * Given a SavedFrame JSObject, get its line property (1-origin). + * Defaults to 0. + */ +extern JS_PUBLIC_API SavedFrameResult GetSavedFrameLine( + JSContext* cx, JSPrincipals* principals, Handle<JSObject*> savedFrame, + uint32_t* linep, + SavedFrameSelfHosted selfHosted = SavedFrameSelfHosted::Include); + +/** + * Given a SavedFrame JSObject, get its column property. Defaults to 0. + */ +extern JS_PUBLIC_API SavedFrameResult GetSavedFrameColumn( + JSContext* cx, JSPrincipals* principals, Handle<JSObject*> savedFrame, + JS::TaggedColumnNumberOneOrigin* columnp, + SavedFrameSelfHosted selfHosted = SavedFrameSelfHosted::Include); + +/** + * Given a SavedFrame JSObject, get its functionDisplayName string, or nullptr + * if SpiderMonkey was unable to infer a name for the captured frame's + * function. Defaults to nullptr. + */ +extern JS_PUBLIC_API SavedFrameResult GetSavedFrameFunctionDisplayName( + JSContext* cx, JSPrincipals* principals, Handle<JSObject*> savedFrame, + MutableHandle<JSString*> namep, + SavedFrameSelfHosted selfHosted = SavedFrameSelfHosted::Include); + +/** + * Given a SavedFrame JSObject, get its asyncCause string. Defaults to nullptr. + */ +extern JS_PUBLIC_API SavedFrameResult GetSavedFrameAsyncCause( + JSContext* cx, JSPrincipals* principals, Handle<JSObject*> savedFrame, + MutableHandle<JSString*> asyncCausep, + SavedFrameSelfHosted selfHosted = SavedFrameSelfHosted::Include); + +/** + * Given a SavedFrame JSObject, get its asyncParent SavedFrame object or nullptr + * if there is no asyncParent. The `asyncParentp` out parameter is _NOT_ + * guaranteed to be in the cx's compartment. Defaults to nullptr. + */ +extern JS_PUBLIC_API SavedFrameResult GetSavedFrameAsyncParent( + JSContext* cx, JSPrincipals* principals, Handle<JSObject*> savedFrame, + MutableHandle<JSObject*> asyncParentp, + SavedFrameSelfHosted selfHosted = SavedFrameSelfHosted::Include); + +/** + * Given a SavedFrame JSObject, get its parent SavedFrame object or nullptr if + * it is the oldest frame in the stack. The `parentp` out parameter is _NOT_ + * guaranteed to be in the cx's compartment. Defaults to nullptr. + */ +extern JS_PUBLIC_API SavedFrameResult GetSavedFrameParent( + JSContext* cx, JSPrincipals* principals, Handle<JSObject*> savedFrame, + MutableHandle<JSObject*> parentp, + SavedFrameSelfHosted selfHosted = SavedFrameSelfHosted::Include); + +/** + * Given a SavedFrame object, convert it and its transitive parents to plain + * objects. Because SavedFrame objects store their properties on the prototype, + * they cannot be usefully stringified to JSON. Assigning their properties to + * plain objects allow those objects to be stringified and the saved frame stack + * can be encoded as a string. + */ +JS_PUBLIC_API JSObject* ConvertSavedFrameToPlainObject( + JSContext* cx, JS::HandleObject savedFrame, + JS::SavedFrameSelfHosted selfHosted); + +} // namespace JS + +namespace js { + +/** + * Get the first SavedFrame object in this SavedFrame stack whose principals are + * subsumed by the given |principals|. If there is no such frame, return + * nullptr. + * + * Do NOT pass a non-SavedFrame object here. + */ +extern JS_PUBLIC_API JSObject* GetFirstSubsumedSavedFrame( + JSContext* cx, JSPrincipals* principals, JS::Handle<JSObject*> savedFrame, + JS::SavedFrameSelfHosted selfHosted); + +} // namespace js + +#endif /* js_SavedFrameAPI_h */ |