@react-native-quickjs/quickjs 1.0.0-alpha.0

package/modules/cdp/quickjs-cdp.h

@@ -0,0 +1,122 @@
+/*
+ * Copyright (c) Ammar Ahmed.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * The Chrome DevTools Protocol, for QuickJS.
+ *
+ * This is plain C over <quickjs.h> and nothing else, with no generated
+ * marshalling code: protocol messages are JSON, and
+ * the engine already has a JSON parser, so they are handled as JSValues on a
+ * private context of the agent's own.
+ *
+ * THREADS
+ *   Every protocol message is handled on the JS thread. qjs_cdp_send_message()
+ *   may be called from any thread; it copies the message and queues it. The
+ *   queue is drained by qjs_cdp_poll(), which the embedder calls on the JS
+ *   thread, and by the pause loop, which is the only reason the queue exists:
+ *   while execution is stopped at a breakpoint the JS thread is inside the
+ *   engine, and the frontend still has to be answered.
+ *
+ * PARSE-TIME INSTRUMENTATION
+ *   The engine emits statement traps only into code parsed while a trace
+ *   handler is installed, so qjs_cdp_new() must be called before any script is
+ *   evaluated. A runtime that started without one cannot be attached to later.
+ */
+
+#ifndef QUICKJS_CDP_H
+#define QUICKJS_CDP_H
+
+#include <quickjs.h>
+#include <stdbool.h>
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct QJSCDPAgent QJSCDPAgent;
+
+/* Receives one complete CDP message to deliver to the frontend. Called on the
+   JS thread. `json` is owned by the agent and is not valid after the call.
+
+   `session` is the token that came with the request being answered, or NULL for
+   an event, which belongs to every session at once. A reply must reach only the
+   frontend that asked: two frontends can be attached, and answering both makes
+   each of them see a response to something it never sent. */
+typedef void QJSCDPSendFunc(
+    void *opaque, void *session, const char *json, size_t len);
+
+/* Creates the agent and installs the engine's trace handler on `ctx`.
+   `execution_context_id` is the id reported in Runtime.executionContextCreated
+   and echoed back in every remote object. */
+QJSCDPAgent *qjs_cdp_new(
+    JSContext *ctx, int execution_context_id, QJSCDPSendFunc *send,
+    void *send_opaque);
+
+void qjs_cdp_free(QJSCDPAgent *agent);
+
+/* True when this agent implements `method`.
+   A request it does not implement must be left to whoever else is listening
+   rather than answered with an error: the frontend talks to several agents at
+   once, and refusing on behalf of all of them is not ours to do. */
+bool qjs_cdp_handles(const char *method);
+
+/* Tells the agent which execution context it is speaking for. The embedder
+   assigns the id, and a Runtime.evaluate naming any other context is refused
+   rather than run in this one. */
+void qjs_cdp_set_execution_context(QJSCDPAgent *agent, int id);
+
+/* Queues one CDP message from `session`. Any thread. */
+void qjs_cdp_send_message(
+    QJSCDPAgent *agent, void *session, const char *json, size_t len);
+
+/* Handles every queued message. JS thread only. */
+void qjs_cdp_poll(QJSCDPAgent *agent);
+
+/* Reports a console call to the frontend as Runtime.consoleAPICalled. `type` is
+   the protocol's name for it ("log", "warning", ...). The values are borrowed
+   for the duration of the call. JS thread only. */
+void qjs_cdp_console_message(
+    QJSCDPAgent *agent, const char *type, const JSValue *args, int count);
+
+/* Tells the agent a script was loaded, so it can answer Debugger.scriptParsed
+   and resolve breakpoints set against `url`. Call after evaluating each script.
+   JS thread only. */
+void qjs_cdp_script_loaded(
+    QJSCDPAgent *agent, const char *url, const char *source);
+
+/* Everything a replacement agent needs to carry on where this one left off:
+   whether the debugger was enabled and which breakpoints the frontend has set.
+   React Native destroys and recreates the runtime on a reload, and the frontend
+   is not told -- from its side the breakpoints it set are still set.
+
+   Export returns a string the caller frees with free(); import takes one back. */
+char *qjs_cdp_export_state(QJSCDPAgent *agent);
+void qjs_cdp_import_state(QJSCDPAgent *agent, const char *json);
+
+/* Whether the debugger is switched on for the runtime.
+
+   Debugger.enable turns it on by itself, so a lone embedder needs none of this.
+   Turning it OFF is different: enabling is per session and two frontends can
+   disagree, so Debugger.disable from one of them is not the whole story. An
+   embedder that supports several sessions calls the setter with the union.
+   After an import this is whatever it was before the reload. */
+bool qjs_cdp_debugger_enabled(QJSCDPAgent *agent);
+void qjs_cdp_set_debugger_enabled(QJSCDPAgent *agent, bool enabled);
+
+/* The call stack right now, as a Runtime.StackTrace JSON object. Returns a
+   string the caller frees with free(), or NULL when nothing is running.
+   `frames_to_skip` drops that many innermost frames, which is how a native
+   function leaves itself out of the trace it is capturing. JS thread only. */
+char *qjs_cdp_capture_stack_trace(QJSCDPAgent *agent, int frames_to_skip);
+
+/* Asks the running program to stop at the next statement. Any thread. */
+void qjs_cdp_pause(QJSCDPAgent *agent);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* QUICKJS_CDP_H */

package/modules/cdp/react/QuickJSInspector.cpp

@@ -0,0 +1,322 @@
+/*
+ * Copyright (c) Ammar Ahmed.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#include "QuickJSInspector.h"
+
+#include <folly/json.h>
+
+#include <algorithm>
+#include <cstdlib>
+#include <utility>
+
+#include "QuickJSRuntime.h"
+
+using namespace facebook::react;
+using namespace facebook::react::jsinspector_modern;
+
+namespace qjs {
+
+/// One debugging session. Requests arrive on the inspector thread and are
+/// queued; the agent handles them on the JS thread, or from inside the pause
+/// loop when execution is stopped.
+class InspectorSession : public RuntimeAgentDelegate {
+ public:
+  InspectorSession(
+      QuickJSInspectorDelegate &owner, QJSCDPAgent *agent,
+      FrontendChannel channel, RuntimeExecutor executor, bool debuggerEnabled)
+      : owner_(owner),
+        agent_(agent),
+        channel_(std::move(channel)),
+        executor_(std::move(executor)),
+        debuggerEnabled_(debuggerEnabled) {}
+
+  ~InspectorSession() override {
+    owner_.forget(this);
+  }
+
+  bool handleRequest(const cdp::PreparsedRequest &req) override {
+    if (!qjs_cdp_handles(req.method.c_str())) {
+      return false;
+    }
+    // Enabling a domain is per session, not per runtime: one frontend can be
+    // watching the debugger while another is not, and sending Debugger events
+    // to the second is a message it never asked for.
+    if (req.method == "Debugger.enable") {
+      debuggerEnabled_ = true;
+      owner_.debuggerEnabledChanged();
+    } else if (req.method == "Debugger.disable") {
+      debuggerEnabled_ = false;
+      owner_.debuggerEnabledChanged();
+    }
+    const std::string json = req.toJson();
+    qjs_cdp_send_message(agent_, this, json.c_str(), json.size());
+    // Nothing happens until someone runs the queue on the JS thread. While
+    // paused this task will not run at all, which is correct: the pause loop is
+    // draining the same queue.
+    executor_(
+        [agent = agent_](facebook::jsi::Runtime &) { qjs_cdp_poll(agent); });
+    return true;
+  }
+
+  /// Handed to the agent that replaces this one when the runtime is reloaded.
+  std::unique_ptr<ExportedState> getExportedState() override;
+
+  bool debuggerEnabled() const {
+    return debuggerEnabled_;
+  }
+
+  void deliver(std::string_view message) const {
+    if (!debuggerEnabled_ &&
+        message.find("\"method\":\"Debugger.") != std::string_view::npos) {
+      return;
+    }
+    channel_(message);
+  }
+
+ private:
+  QuickJSInspectorDelegate &owner_;
+  QJSCDPAgent *agent_;
+  FrontendChannel channel_;
+  RuntimeExecutor executor_;
+  bool debuggerEnabled_;
+};
+
+namespace {
+
+/// The debugger state that outlives one runtime: whether it was enabled, and
+/// the breakpoints the frontend believes it has set.
+class CarriedState : public RuntimeAgentDelegate::ExportedState {
+ public:
+  explicit CarriedState(std::string json) : json_(std::move(json)) {}
+
+  const std::string &json() const {
+    return json_;
+  }
+
+ private:
+  std::string json_;
+};
+
+/// A captured stack, kept as the JSON the frontend will eventually be given.
+/// Capture happens on the JS thread while the frames are alive; serialization
+/// can happen later, and by then they are gone.
+class CapturedStack : public StackTrace {
+ public:
+  explicit CapturedStack(std::string json) : json_(std::move(json)) {}
+
+  const std::string &json() const {
+    return json_;
+  }
+
+ private:
+  std::string json_;
+};
+
+}  // namespace
+
+namespace {
+
+const char *consoleTypeName(ConsoleAPIType type) {
+  switch (type) {
+    case ConsoleAPIType::kLog:
+      return "log";
+    case ConsoleAPIType::kDebug:
+      return "debug";
+    case ConsoleAPIType::kInfo:
+      return "info";
+    case ConsoleAPIType::kError:
+      return "error";
+    case ConsoleAPIType::kWarning:
+      return "warning";
+    case ConsoleAPIType::kDir:
+      return "dir";
+    case ConsoleAPIType::kDirXML:
+      return "dirxml";
+    case ConsoleAPIType::kTable:
+      return "table";
+    case ConsoleAPIType::kTrace:
+      return "trace";
+    case ConsoleAPIType::kStartGroup:
+      return "startGroup";
+    case ConsoleAPIType::kStartGroupCollapsed:
+      return "startGroupCollapsed";
+    case ConsoleAPIType::kEndGroup:
+      return "endGroup";
+    case ConsoleAPIType::kClear:
+      return "clear";
+    case ConsoleAPIType::kAssert:
+      return "assert";
+    case ConsoleAPIType::kTimeEnd:
+      return "timeEnd";
+    case ConsoleAPIType::kCount:
+      return "count";
+    default:
+      return "log";
+  }
+}
+
+}  // namespace
+
+bool QuickJSInspectorDelegate::supportsConsole() const {
+  // True, and that is the switch: with it React Native stops using its own
+  // string-only fallback and routes console calls through here, where each
+  // argument becomes a real remote object the frontend can expand.
+  return true;
+}
+
+void QuickJSInspectorDelegate::addConsoleMessage(
+    facebook::jsi::Runtime &runtime, ConsoleMessage message) {
+  auto &quickjs = dynamic_cast<QuickJSRuntime &>(runtime);
+
+  // toJSValue borrows -- the jsi::Value still owns the reference -- which is
+  // what the agent wants, since it only reads each argument to describe it.
+  std::vector<JSValue> args;
+  args.reserve(message.args.size());
+  for (const facebook::jsi::Value &arg : message.args) {
+    args.push_back(quickjs.toJSValue(arg));
+  }
+
+  qjs_cdp_console_message(
+      agent_, consoleTypeName(message.type), args.data(), (int)args.size());
+}
+
+std::unique_ptr<RuntimeAgentDelegate::ExportedState>
+InspectorSession::getExportedState() {
+  char *json = qjs_cdp_export_state(agent_);
+  if (!json) {
+    return std::make_unique<ExportedState>();
+  }
+  auto carried = std::make_unique<CarriedState>(std::string(json));
+  free(json);
+  return carried;
+}
+
+std::unique_ptr<StackTrace> QuickJSInspectorDelegate::captureStackTrace(
+    facebook::jsi::Runtime &runtime, size_t framesToSkip) {
+  (void)runtime;
+  char *json = qjs_cdp_capture_stack_trace(agent_, (int)framesToSkip);
+  if (!json) {
+    return StackTrace::empty();
+  }
+  auto captured = std::make_unique<CapturedStack>(std::string(json));
+  free(json);
+  return captured;
+}
+
+std::optional<folly::dynamic> QuickJSInspectorDelegate::serializeStackTrace(
+    const StackTrace &stackTrace) {
+  const auto *captured = dynamic_cast<const CapturedStack *>(&stackTrace);
+  if (!captured) {
+    return std::nullopt;
+  }
+  return folly::parseJson(captured->json());
+}
+
+QuickJSInspectorDelegate::QuickJSInspectorDelegate(JSContext *ctx)
+    : FallbackRuntimeTargetDelegate("QuickJS") {
+  agent_ = qjs_cdp_new(ctx, 1, &QuickJSInspectorDelegate::deliver, this);
+}
+
+QuickJSInspectorDelegate::~QuickJSInspectorDelegate() {
+  qjs_cdp_free(agent_);
+}
+
+void QuickJSInspectorDelegate::deliver(
+    void *opaque, void *session, const char *json, size_t len) {
+  auto *self = static_cast<QuickJSInspectorDelegate *>(opaque);
+  const std::string_view message(json, len);
+  std::lock_guard<std::mutex> guard(self->lock_);
+
+  // A reply belongs to the session that asked and to no other; an event has no
+  // session and belongs to all of them.
+  for (auto *live : self->sessions_) {
+    if (session == nullptr || live == session) {
+      live->deliver(message);
+    }
+  }
+}
+
+std::unique_ptr<RuntimeAgentDelegate>
+QuickJSInspectorDelegate::createAgentDelegate(
+    FrontendChannel channel, SessionState &sessionState,
+    std::unique_ptr<RuntimeAgentDelegate::ExportedState>
+        previouslyExportedState,
+    const ExecutionContextDescription &executionContextDescription,
+    RuntimeExecutor runtimeExecutor) {
+  (void)sessionState;
+
+  // A reload replaces the runtime without telling the frontend, so the
+  // breakpoints it set have to be carried over to the agent that takes over.
+  if (auto *carried =
+          dynamic_cast<CarriedState *>(previouslyExportedState.get())) {
+    qjs_cdp_import_state(agent_, carried->json().c_str());
+  }
+
+  // React Native assigns the execution context id, and the frontend addresses
+  // requests to it by number.
+  qjs_cdp_set_execution_context(agent_, executionContextDescription.id);
+
+  // A reload replaces the agent but not the frontend, so a session that had
+  // the debugger enabled before still has it enabled after.
+  auto session = std::make_unique<InspectorSession>(
+      *this, agent_, std::move(channel), std::move(runtimeExecutor),
+      qjs_cdp_debugger_enabled(agent_));
+  {
+    std::lock_guard<std::mutex> guard(lock_);
+    sessions_.push_back(session.get());
+  }
+  return session;
+}
+
+void QuickJSInspectorDelegate::forget(InspectorSession *session) {
+  {
+    std::lock_guard<std::mutex> guard(lock_);
+    sessions_.erase(
+        std::remove(sessions_.begin(), sessions_.end(), session),
+        sessions_.end());
+  }
+  debuggerEnabledChanged();
+}
+
+/// The debugger is on for the runtime when it is on for anybody. One frontend
+/// turning it off must not stop the statement traps another is relying on.
+void QuickJSInspectorDelegate::debuggerEnabledChanged() {
+  bool any = false;
+  {
+    std::lock_guard<std::mutex> guard(lock_);
+    for (const auto *session : sessions_) {
+      any = any || session->debuggerEnabled();
+    }
+  }
+  qjs_cdp_set_debugger_enabled(agent_, any);
+}
+
+void QuickJSInspectorDelegate::scriptLoaded(
+    const std::string &url, const std::string &source) {
+  qjs_cdp_script_loaded(agent_, url.c_str(), source.c_str());
+}
+
+QuickJSInspectorRuntime::QuickJSInspectorRuntime(
+    std::unique_ptr<facebook::jsi::Runtime> runtime)
+    : runtime_(std::move(runtime)) {
+  auto &quickjs = dynamic_cast<QuickJSRuntime &>(*runtime_);
+  delegate_ = std::make_unique<QuickJSInspectorDelegate>(quickjs.context());
+  quickjs.setScriptEvaluatedHook(
+      [this](const std::string &url, const std::string &source) {
+        delegate_->scriptLoaded(url, source);
+      });
+}
+
+facebook::jsi::Runtime &QuickJSInspectorRuntime::getRuntime() noexcept {
+  return *runtime_;
+}
+
+RuntimeTargetDelegate &QuickJSInspectorRuntime::getRuntimeTargetDelegate() {
+  return *delegate_;
+}
+
+}  // namespace qjs

package/modules/cdp/react/QuickJSInspector.h

@@ -0,0 +1,114 @@
+/*
+ * Copyright (c) Ammar Ahmed.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * Plugs the CDP layer into React Native's inspector.
+ *
+ * React Native owns the WebSocket, the page target and the session; all this
+ * has to do is hand CDP messages to the agent and hand its replies back. The
+ * protocol work is all in modules/cdp, which knows nothing about any of this.
+ */
+
+#pragma once
+
+#include <jsinspector-modern/ReactCdp.h>
+#include <react/runtime/JSRuntimeFactory.h>
+
+#include <memory>
+#include <mutex>
+#include <string>
+#include <vector>
+
+extern "C" {
+#include "quickjs-cdp.h"
+}
+
+namespace qjs {
+
+class InspectorSession;
+
+/**
+ * Owns the agent for one runtime.
+ *
+ * Constructed with the runtime, not when a frontend connects: the engine emits
+ * statement traps at parse time, so a runtime that was not instrumented before
+ * its first script ran cannot be debugged afterwards.
+ */
+class QuickJSInspectorDelegate : public facebook::react::jsinspector_modern::
+                                     FallbackRuntimeTargetDelegate {
+ public:
+  explicit QuickJSInspectorDelegate(JSContext *ctx);
+  ~QuickJSInspectorDelegate() override;
+
+  std::unique_ptr<facebook::react::jsinspector_modern::RuntimeAgentDelegate>
+  createAgentDelegate(
+      facebook::react::jsinspector_modern::FrontendChannel channel,
+      facebook::react::jsinspector_modern::SessionState &sessionState,
+      std::unique_ptr<facebook::react::jsinspector_modern::
+                          RuntimeAgentDelegate::ExportedState>
+          previouslyExportedState,
+      const facebook::react::jsinspector_modern::ExecutionContextDescription
+          &executionContextDescription,
+      facebook::react::RuntimeExecutor runtimeExecutor) override;
+
+  void addConsoleMessage(
+      facebook::jsi::Runtime &runtime,
+      facebook::react::jsinspector_modern::ConsoleMessage message) override;
+
+  bool supportsConsole() const override;
+
+  std::unique_ptr<facebook::react::jsinspector_modern::StackTrace>
+  captureStackTrace(
+      facebook::jsi::Runtime &runtime, size_t framesToSkip) override;
+
+  std::optional<folly::dynamic> serializeStackTrace(
+      const facebook::react::jsinspector_modern::StackTrace &stackTrace)
+      override;
+
+  /// Tells the frontend a script exists, and resolves breakpoints set against
+  /// its URL. JS thread only.
+  void scriptLoaded(const std::string &url, const std::string &source);
+
+  /// Called by a session as it goes away, so that a reply can never be routed
+  /// to a frontend that has disconnected.
+  void forget(InspectorSession *session);
+
+  /// Recomputes whether any session still wants the debugger, and tells the
+  /// agent. Called whenever a session enables, disables, or goes away.
+  void debuggerEnabledChanged();
+
+ private:
+  static void deliver(
+      void *opaque, void *session, const char *json, size_t len);
+
+  QJSCDPAgent *agent_;
+  std::mutex lock_;
+  std::vector<InspectorSession *> sessions_;  // not owned
+};
+
+/**
+ * The JSRuntime React Native asks for, with the debugger attached.
+ *
+ * The delegate is built here, immediately after the runtime and before any
+ * script has been evaluated, rather than when a frontend connects. React
+ * Native calls getRuntimeTargetDelegate() lazily, long after the bundle has
+ * run, and by then it is far too late to instrument anything.
+ */
+class QuickJSInspectorRuntime : public facebook::react::JSRuntime {
+ public:
+  explicit QuickJSInspectorRuntime(
+      std::unique_ptr<facebook::jsi::Runtime> runtime);
+
+  facebook::jsi::Runtime &getRuntime() noexcept override;
+
+  facebook::react::jsinspector_modern::RuntimeTargetDelegate &
+  getRuntimeTargetDelegate() override;
+
+ private:
+  std::unique_ptr<facebook::jsi::Runtime> runtime_;
+  std::unique_ptr<QuickJSInspectorDelegate> delegate_;
+};
+
+}  // namespace qjs

package/modules/hermes-compat/include/hermes/DebuggerAPI.h

@@ -0,0 +1,20 @@
+/*
+ * Copyright (c) Ammar Ahmed.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+namespace facebook::hermes::debugger {
+
+// Named so that IHermes::getDebugger has a complete return type. Hermes's
+// debugger is expressed in bytecode offsets and has no QuickJS meaning;
+// debugging here goes through jsinspector-modern and modules/cdp instead.
+class Debugger {
+ public:
+  Debugger() = default;
+};
+
+}  // namespace facebook::hermes::debugger

package/modules/hermes-compat/include/hermes/Public/CrashManager.h

@@ -0,0 +1,47 @@
+/*
+ * Copyright (c) Ammar Ahmed.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <cstdint>
+#include <memory>
+#include <string>
+
+namespace hermes::vm {
+
+/// Named so that code passing a crash manager compiles. QuickJS installs no
+/// crash handlers, so a registered callback is never invoked.
+class CrashManager {
+ public:
+  using CallbackKey = int;
+  using CallbackFunc = void (*)(int fd);
+
+  /// Out of line, and so this class's key function: it is what places the
+  /// vtable in this library. react-native-worklets references the base class
+  /// vtable directly, not only NopCrashManager's, and with every virtual
+  /// defined inline no translation unit here emits it -- the shim then loads
+  /// on its own but fails dlopen the moment worklets links against it.
+  virtual ~CrashManager();
+
+  virtual void registerMemory(void *, size_t) {}
+  virtual void unregisterMemory(void *) {}
+  virtual void setCustomData(const char *, const char *) {}
+  virtual void removeCustomData(const char *) {}
+  virtual CallbackKey registerCallback(CallbackFunc) {
+    return 0;
+  }
+  virtual void unregisterCallback(CallbackKey) {}
+};
+
+/// react-native-worklets constructs one of these, so this class needs its own
+/// vtable here too, by the same rule.
+class NopCrashManager : public CrashManager {
+ public:
+  ~NopCrashManager() override;
+};
+
+}  // namespace hermes::vm