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: StringView()38 StringView() : m_is8Bit(true), m_length(0), m_characters8(nullptr) {} 39 StringView(const uint8_t * characters,size_t length)40 StringView(const uint8_t* characters, size_t length) 41 : m_is8Bit(true), m_length(length), m_characters8(characters) {} 42 StringView(const uint16_t * characters,size_t length)43 StringView(const uint16_t* characters, size_t length) 44 : m_is8Bit(false), m_length(length), m_characters16(characters) {} 45 is8Bit()46 bool is8Bit() const { return m_is8Bit; } length()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. characters8()51 const uint8_t* characters8() const { return m_characters8; } characters16()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: ~StringBuffer()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: V8ContextInfo(v8::Local<v8::Context> context,int contextGroupId,const StringView & humanReadableName)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 ~V8StackTrace()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: ~V8InspectorSession()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; ~Inspectable()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: ~V8InspectorClient()163 virtual ~V8InspectorClient() {} 164 runMessageLoopOnPause(int contextGroupId)165 virtual void runMessageLoopOnPause(int contextGroupId) {} quitMessageLoopOnPause()166 virtual void quitMessageLoopOnPause() {} runIfWaitingForDebugger(int contextGroupId)167 virtual void runIfWaitingForDebugger(int contextGroupId) {} 168 muteMetrics(int contextGroupId)169 virtual void muteMetrics(int contextGroupId) {} unmuteMetrics(int contextGroupId)170 virtual void unmuteMetrics(int contextGroupId) {} 171 beginUserGesture()172 virtual void beginUserGesture() {} endUserGesture()173 virtual void endUserGesture() {} 174 valueSubtype(v8::Local<v8::Value>)175 virtual std::unique_ptr<StringBuffer> valueSubtype(v8::Local<v8::Value>) { 176 return nullptr; 177 } formatAccessorsAsProperties(v8::Local<v8::Value>)178 virtual bool formatAccessorsAsProperties(v8::Local<v8::Value>) { 179 return false; 180 } isInspectableHeapObject(v8::Local<v8::Object>)181 virtual bool isInspectableHeapObject(v8::Local<v8::Object>) { return true; } 182 ensureDefaultContextInGroup(int contextGroupId)183 virtual v8::Local<v8::Context> ensureDefaultContextInGroup( 184 int contextGroupId) { 185 return v8::Local<v8::Context>(); 186 } beginEnsureAllContextsInGroup(int contextGroupId)187 virtual void beginEnsureAllContextsInGroup(int contextGroupId) {} endEnsureAllContextsInGroup(int contextGroupId)188 virtual void endEnsureAllContextsInGroup(int contextGroupId) {} 189 installAdditionalCommandLineAPI(v8::Local<v8::Context>,v8::Local<v8::Object>)190 virtual void installAdditionalCommandLineAPI(v8::Local<v8::Context>, 191 v8::Local<v8::Object>) {} consoleAPIMessage(int contextGroupId,v8::Isolate::MessageErrorLevel level,const StringView & message,const StringView & url,unsigned lineNumber,unsigned columnNumber,V8StackTrace *)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*) {} memoryInfo(v8::Isolate *,v8::Local<v8::Context>)197 virtual v8::MaybeLocal<v8::Value> memoryInfo(v8::Isolate*, 198 v8::Local<v8::Context>) { 199 return v8::MaybeLocal<v8::Value>(); 200 } 201 consoleTime(const StringView & title)202 virtual void consoleTime(const StringView& title) {} consoleTimeEnd(const StringView & title)203 virtual void consoleTimeEnd(const StringView& title) {} consoleTimeStamp(const StringView & title)204 virtual void consoleTimeStamp(const StringView& title) {} consoleClear(int contextGroupId)205 virtual void consoleClear(int contextGroupId) {} currentTimeMS()206 virtual double currentTimeMS() { return 0; } 207 typedef void (*TimerCallback)(void*); startRepeatingTimer(double,TimerCallback,void * data)208 virtual void startRepeatingTimer(double, TimerCallback, void* data) {} cancelTimer(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. canExecuteScripts(int contextGroupId)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*); ~V8Inspector()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: ~Channel()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