Home | History | Annotate | Download | only in include 
      1 // Copyright 2016 the V8 project authors. All rights reserved.
      2 // Use of this source code is governed by a BSD-style license that can be
      3 // found in the LICENSE file.
      4 
      5 #ifndef V8_V8_INSPECTOR_H_
      6 #define V8_V8_INSPECTOR_H_
      7 
      8 #include <stdint.h>
      9 #include <cctype>
     10 
     11 #include <memory>
     12 
     13 #include "v8.h"  // NOLINT(build/include)
     14 
     15 namespace v8_inspector {
     16 
     17 namespace protocol {
     18 namespace Debugger {
     19 namespace API {
     20 class SearchMatch;
     21 }
     22 }
     23 namespace Runtime {
     24 namespace API {
     25 class RemoteObject;
     26 class StackTrace;
     27 }
     28 }
     29 namespace Schema {
     30 namespace API {
     31 class Domain;
     32 }
     33 }
     34 }  // namespace protocol
     35 
     36 class V8_EXPORT StringView {
     37  public:
     38   StringView() : m_is8Bit(true), m_length(0), m_characters8(nullptr) {}
     39 
     40   StringView(const uint8_t* characters, size_t length)
     41       : m_is8Bit(true), m_length(length), m_characters8(characters) {}
     42 
     43   StringView(const uint16_t* characters, size_t length)
     44       : m_is8Bit(false), m_length(length), m_characters16(characters) {}
     45 
     46   bool is8Bit() const { return m_is8Bit; }
     47   size_t length() const { return m_length; }
     48 
     49   // TODO(dgozman): add DCHECK(m_is8Bit) to accessors once platform can be used
     50   // here.
     51   const uint8_t* characters8() const { return m_characters8; }
     52   const uint16_t* characters16() const { return m_characters16; }
     53 
     54  private:
     55   bool m_is8Bit;
     56   size_t m_length;
     57   union {
     58     const uint8_t* m_characters8;
     59     const uint16_t* m_characters16;
     60   };
     61 };
     62 
     63 class V8_EXPORT StringBuffer {
     64  public:
     65   virtual ~StringBuffer() {}
     66   virtual const StringView& string() = 0;
     67   // This method copies contents.
     68   static std::unique_ptr<StringBuffer> create(const StringView&);
     69 };
     70 
     71 class V8_EXPORT V8ContextInfo {
     72  public:
     73   V8ContextInfo(v8::Local<v8::Context> context, int contextGroupId,
     74                 const StringView& humanReadableName)
     75       : context(context),
     76         contextGroupId(contextGroupId),
     77         humanReadableName(humanReadableName),
     78         hasMemoryOnConsole(false) {}
     79 
     80   v8::Local<v8::Context> context;
     81   // Each v8::Context is a part of a group. The group id must be non-zero.
     82   int contextGroupId;
     83   StringView humanReadableName;
     84   StringView origin;
     85   StringView auxData;
     86   bool hasMemoryOnConsole;
     87 
     88   static int executionContextId(v8::Local<v8::Context> context);
     89 
     90  private:
     91   // Disallow copying and allocating this one.
     92   enum NotNullTagEnum { NotNullLiteral };
     93   void* operator new(size_t) = delete;
     94   void* operator new(size_t, NotNullTagEnum, void*) = delete;
     95   void* operator new(size_t, void*) = delete;
     96   V8ContextInfo(const V8ContextInfo&) = delete;
     97   V8ContextInfo& operator=(const V8ContextInfo&) = delete;
     98 };
     99 
    100 class V8_EXPORT V8StackTrace {
    101  public:
    102   virtual bool isEmpty() const = 0;
    103   virtual StringView topSourceURL() const = 0;
    104   virtual int topLineNumber() const = 0;
    105   virtual int topColumnNumber() const = 0;
    106   virtual StringView topScriptId() const = 0;
    107   virtual StringView topFunctionName() const = 0;
    108 
    109   virtual ~V8StackTrace() {}
    110   virtual std::unique_ptr<protocol::Runtime::API::StackTrace>
    111   buildInspectorObject() const = 0;
    112   virtual std::unique_ptr<StringBuffer> toString() const = 0;
    113 
    114   // Safe to pass between threads, drops async chain.
    115   virtual std::unique_ptr<V8StackTrace> clone() = 0;
    116 };
    117 
    118 class V8_EXPORT V8InspectorSession {
    119  public:
    120   virtual ~V8InspectorSession() {}
    121 
    122   // Cross-context inspectable values (DOM nodes in different worlds, etc.).
    123   class V8_EXPORT Inspectable {
    124    public:
    125     virtual v8::Local<v8::Value> get(v8::Local<v8::Context>) = 0;
    126     virtual ~Inspectable() {}
    127   };
    128   virtual void addInspectedObject(std::unique_ptr<Inspectable>) = 0;
    129 
    130   // Dispatching protocol messages.
    131   static bool canDispatchMethod(const StringView& method);
    132   virtual void dispatchProtocolMessage(const StringView& message) = 0;
    133   virtual std::unique_ptr<StringBuffer> stateJSON() = 0;
    134   virtual std::vector<std::unique_ptr<protocol::Schema::API::Domain>>
    135   supportedDomains() = 0;
    136 
    137   // Debugger actions.
    138   virtual void schedulePauseOnNextStatement(const StringView& breakReason,
    139                                             const StringView& breakDetails) = 0;
    140   virtual void cancelPauseOnNextStatement() = 0;
    141   virtual void breakProgram(const StringView& breakReason,
    142                             const StringView& breakDetails) = 0;
    143   virtual void setSkipAllPauses(bool) = 0;
    144   virtual void resume() = 0;
    145   virtual void stepOver() = 0;
    146   virtual std::vector<std::unique_ptr<protocol::Debugger::API::SearchMatch>>
    147   searchInTextByLines(const StringView& text, const StringView& query,
    148                       bool caseSensitive, bool isRegex) = 0;
    149 
    150   // Remote objects.
    151   virtual std::unique_ptr<protocol::Runtime::API::RemoteObject> wrapObject(
    152       v8::Local<v8::Context>, v8::Local<v8::Value>,
    153       const StringView& groupName) = 0;
    154   virtual bool unwrapObject(std::unique_ptr<StringBuffer>* error,
    155                             const StringView& objectId, v8::Local<v8::Value>*,
    156                             v8::Local<v8::Context>*,
    157                             std::unique_ptr<StringBuffer>* objectGroup) = 0;
    158   virtual void releaseObjectGroup(const StringView&) = 0;
    159 };
    160 
    161 class V8_EXPORT V8InspectorClient {
    162  public:
    163   virtual ~V8InspectorClient() {}
    164 
    165   virtual void runMessageLoopOnPause(int contextGroupId) {}
    166   virtual void quitMessageLoopOnPause() {}
    167   virtual void runIfWaitingForDebugger(int contextGroupId) {}
    168 
    169   virtual void muteMetrics(int contextGroupId) {}
    170   virtual void unmuteMetrics(int contextGroupId) {}
    171 
    172   virtual void beginUserGesture() {}
    173   virtual void endUserGesture() {}
    174 
    175   virtual std::unique_ptr<StringBuffer> valueSubtype(v8::Local<v8::Value>) {
    176     return nullptr;
    177   }
    178   virtual bool formatAccessorsAsProperties(v8::Local<v8::Value>) {
    179     return false;
    180   }
    181   virtual bool isInspectableHeapObject(v8::Local<v8::Object>) { return true; }
    182 
    183   virtual v8::Local<v8::Context> ensureDefaultContextInGroup(
    184       int contextGroupId) {
    185     return v8::Local<v8::Context>();
    186   }
    187   virtual void beginEnsureAllContextsInGroup(int contextGroupId) {}
    188   virtual void endEnsureAllContextsInGroup(int contextGroupId) {}
    189 
    190   virtual void installAdditionalCommandLineAPI(v8::Local<v8::Context>,
    191                                                v8::Local<v8::Object>) {}
    192   virtual void consoleAPIMessage(int contextGroupId,
    193                                  v8::Isolate::MessageErrorLevel level,
    194                                  const StringView& message,
    195                                  const StringView& url, unsigned lineNumber,
    196                                  unsigned columnNumber, V8StackTrace*) {}
    197   virtual v8::MaybeLocal<v8::Value> memoryInfo(v8::Isolate*,
    198                                                v8::Local<v8::Context>) {
    199     return v8::MaybeLocal<v8::Value>();
    200   }
    201 
    202   virtual void consoleTime(const StringView& title) {}
    203   virtual void consoleTimeEnd(const StringView& title) {}
    204   virtual void consoleTimeStamp(const StringView& title) {}
    205   virtual void consoleClear(int contextGroupId) {}
    206   virtual double currentTimeMS() { return 0; }
    207   typedef void (*TimerCallback)(void*);
    208   virtual void startRepeatingTimer(double, TimerCallback, void* data) {}
    209   virtual void cancelTimer(void* data) {}
    210 
    211   // TODO(dgozman): this was added to support service worker shadow page. We
    212   // should not connect at all.
    213   virtual bool canExecuteScripts(int contextGroupId) { return true; }
    214 };
    215 
    216 class V8_EXPORT V8Inspector {
    217  public:
    218   static std::unique_ptr<V8Inspector> create(v8::Isolate*, V8InspectorClient*);
    219   virtual ~V8Inspector() {}
    220 
    221   // Contexts instrumentation.
    222   virtual void contextCreated(const V8ContextInfo&) = 0;
    223   virtual void contextDestroyed(v8::Local<v8::Context>) = 0;
    224   virtual void resetContextGroup(int contextGroupId) = 0;
    225 
    226   // Various instrumentation.
    227   virtual void willExecuteScript(v8::Local<v8::Context>, int scriptId) = 0;
    228   virtual void didExecuteScript(v8::Local<v8::Context>) = 0;
    229   virtual void idleStarted() = 0;
    230   virtual void idleFinished() = 0;
    231 
    232   // Async stack traces instrumentation.
    233   virtual void asyncTaskScheduled(const StringView& taskName, void* task,
    234                                   bool recurring) = 0;
    235   virtual void asyncTaskCanceled(void* task) = 0;
    236   virtual void asyncTaskStarted(void* task) = 0;
    237   virtual void asyncTaskFinished(void* task) = 0;
    238   virtual void allAsyncTasksCanceled() = 0;
    239 
    240   // Exceptions instrumentation.
    241   virtual unsigned exceptionThrown(
    242       v8::Local<v8::Context>, const StringView& message,
    243       v8::Local<v8::Value> exception, const StringView& detailedMessage,
    244       const StringView& url, unsigned lineNumber, unsigned columnNumber,
    245       std::unique_ptr<V8StackTrace>, int scriptId) = 0;
    246   virtual void exceptionRevoked(v8::Local<v8::Context>, unsigned exceptionId,
    247                                 const StringView& message) = 0;
    248 
    249   // Connection.
    250   class V8_EXPORT Channel {
    251    public:
    252     virtual ~Channel() {}
    253     virtual void sendResponse(int callId,
    254                               std::unique_ptr<StringBuffer> message) = 0;
    255     virtual void sendNotification(std::unique_ptr<StringBuffer> message) = 0;
    256     virtual void flushProtocolNotifications() = 0;
    257   };
    258   virtual std::unique_ptr<V8InspectorSession> connect(
    259       int contextGroupId, Channel*, const StringView& state) = 0;
    260 
    261   // API methods.
    262   virtual std::unique_ptr<V8StackTrace> createStackTrace(
    263       v8::Local<v8::StackTrace>) = 0;
    264   virtual std::unique_ptr<V8StackTrace> captureStackTrace(bool fullStack) = 0;
    265 };
    266 
    267 }  // namespace v8_inspector
    268 
    269 #endif  // V8_V8_INSPECTOR_H_
    270