js/public/SavedFrameAPI.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 /*
   7  * Functions and types related to SavedFrame objects created by the Debugger
   8  * API.
   9  */
  10
  11 #ifndef js_SavedFrameAPI_h
  12 #define js_SavedFrameAPI_h
  13
  14 #include "jstypes.h"  // JS_PUBLIC_API
  15
  16 #include "js/ColumnNumber.h"  // JS::TaggedColumnNumberOneOrigin
  17 #include "js/TypeDecls.h"
  18
  19 struct JSPrincipals;
  20
  21 namespace JS {
  22
  23 /*
  24  * Accessors for working with SavedFrame JSObjects
  25  *
  26  * Each of these functions assert that if their `HandleObject savedFrame`
  27  * argument is non-null, its JSClass is the SavedFrame class (or it is a
  28  * cross-compartment or Xray wrapper around an object with the SavedFrame class)
  29  * and the object is not the SavedFrame.prototype object.
  30  *
  31  * Each of these functions will find the first SavedFrame object in the chain
  32  * whose underlying stack frame principals are subsumed by the given
  33  * |principals|, and operate on that SavedFrame object. This prevents leaking
  34  * information about privileged frames to un-privileged callers
  35  *
  36  * The SavedFrame in parameters do _NOT_ need to be in the same compartment as
  37  * the cx, and the various out parameters are _NOT_ guaranteed to be in the same
  38  * compartment as cx.
  39  *
  40  * You may consider or skip over self-hosted frames by passing
  41  * `SavedFrameSelfHosted::Include` or `SavedFrameSelfHosted::Exclude`
  42  * respectively.
  43  *
  44  * Additionally, it may be the case that there is no such SavedFrame object
  45  * whose captured frame's principals are subsumed by |principals|! If the
  46  * `HandleObject savedFrame` argument is null, or the |principals| do not
  47  * subsume any of the chained SavedFrame object's principals,
  48  * `SavedFrameResult::AccessDenied` is returned and a (hopefully) sane default
  49  * value is chosen for the out param.
  50  *
  51  * See also `js/src/doc/SavedFrame/SavedFrame.md`.
  52  */
  53
  54 enum class SavedFrameResult { Ok, AccessDenied };
  55
  56 enum class SavedFrameSelfHosted { Include, Exclude };
  57
  58 /**
  59  * Given a SavedFrame JSObject, get its source property. Defaults to the empty
  60  * string.
  61  */
  62 extern JS_PUBLIC_API SavedFrameResult GetSavedFrameSource(
  63     JSContext* cx, JSPrincipals* principals, Handle<JSObject*> savedFrame,
  64     MutableHandle<JSString*> sourcep,
  65     SavedFrameSelfHosted selfHosted = SavedFrameSelfHosted::Include);
  66
  67 /**
  68  * Given a SavedFrame JSObject, get an ID identifying its ScriptSource.
  69  * Defaults to 0.
  70  */
  71 extern JS_PUBLIC_API SavedFrameResult GetSavedFrameSourceId(
  72     JSContext* cx, JSPrincipals* principals, Handle<JSObject*> savedFrame,
  73     uint32_t* sourceIdp,
  74     SavedFrameSelfHosted selfHosted = SavedFrameSelfHosted::Include);
  75
  76 /**
  77  * Given a SavedFrame JSObject, get its line property (1-origin).
  78  * Defaults to 0.
  79  */
  80 extern JS_PUBLIC_API SavedFrameResult GetSavedFrameLine(
  81     JSContext* cx, JSPrincipals* principals, Handle<JSObject*> savedFrame,
  82     uint32_t* linep,
  83     SavedFrameSelfHosted selfHosted = SavedFrameSelfHosted::Include);
  84
  85 /**
  86  * Given a SavedFrame JSObject, get its column property. Defaults to 0.
  87  */
  88 extern JS_PUBLIC_API SavedFrameResult GetSavedFrameColumn(
  89     JSContext* cx, JSPrincipals* principals, Handle<JSObject*> savedFrame,
  90     JS::TaggedColumnNumberOneOrigin* columnp,
  91     SavedFrameSelfHosted selfHosted = SavedFrameSelfHosted::Include);
  92
  93 /**
  94  * Given a SavedFrame JSObject, get its functionDisplayName string, or nullptr
  95  * if SpiderMonkey was unable to infer a name for the captured frame's
  96  * function. Defaults to nullptr.
  97  */
  98 extern JS_PUBLIC_API SavedFrameResult GetSavedFrameFunctionDisplayName(
  99     JSContext* cx, JSPrincipals* principals, Handle<JSObject*> savedFrame,
 100     MutableHandle<JSString*> namep,
 101     SavedFrameSelfHosted selfHosted = SavedFrameSelfHosted::Include);
 102
 103 /**
 104  * Given a SavedFrame JSObject, get its asyncCause string. Defaults to nullptr.
 105  */
 106 extern JS_PUBLIC_API SavedFrameResult GetSavedFrameAsyncCause(
 107     JSContext* cx, JSPrincipals* principals, Handle<JSObject*> savedFrame,
 108     MutableHandle<JSString*> asyncCausep,
 109     SavedFrameSelfHosted selfHosted = SavedFrameSelfHosted::Include);
 110
 111 /**
 112  * Given a SavedFrame JSObject, get its asyncParent SavedFrame object or nullptr
 113  * if there is no asyncParent. The `asyncParentp` out parameter is _NOT_
 114  * guaranteed to be in the cx's compartment. Defaults to nullptr.
 115  */
 116 extern JS_PUBLIC_API SavedFrameResult GetSavedFrameAsyncParent(
 117     JSContext* cx, JSPrincipals* principals, Handle<JSObject*> savedFrame,
 118     MutableHandle<JSObject*> asyncParentp,
 119     SavedFrameSelfHosted selfHosted = SavedFrameSelfHosted::Include);
 120
 121 /**
 122  * Given a SavedFrame JSObject, get its parent SavedFrame object or nullptr if
 123  * it is the oldest frame in the stack. The `parentp` out parameter is _NOT_
 124  * guaranteed to be in the cx's compartment. Defaults to nullptr.
 125  */
 126 extern JS_PUBLIC_API SavedFrameResult GetSavedFrameParent(
 127     JSContext* cx, JSPrincipals* principals, Handle<JSObject*> savedFrame,
 128     MutableHandle<JSObject*> parentp,
 129     SavedFrameSelfHosted selfHosted = SavedFrameSelfHosted::Include);
 130
 131 /**
 132  * Given a SavedFrame object, convert it and its transitive parents to plain
 133  * objects. Because SavedFrame objects store their properties on the prototype,
 134  * they cannot be usefully stringified to JSON. Assigning their properties to
 135  * plain objects allow those objects to be stringified and the saved frame stack
 136  * can be encoded as a string.
 137  */
 138 JS_PUBLIC_API JSObject* ConvertSavedFrameToPlainObject(
 139     JSContext* cx, JS::HandleObject savedFrame,
 140     JS::SavedFrameSelfHosted selfHosted);
 141
 142 }  // namespace JS
 143
 144 namespace js {
 145
 146 /**
 147  * Get the first SavedFrame object in this SavedFrame stack whose principals are
 148  * subsumed by the given |principals|. If there is no such frame, return
 149  * nullptr.
 150  *
 151  * Do NOT pass a non-SavedFrame object here.
 152  */
 153 extern JS_PUBLIC_API JSObject* GetFirstSubsumedSavedFrame(
 154     JSContext* cx, JSPrincipals* principals, JS::Handle<JSObject*> savedFrame,
 155     JS::SavedFrameSelfHosted selfHosted);
 156
 157 }  // namespace js
 158
 159 #endif /* js_SavedFrameAPI_h */