LibDevTools: Introduce a Firefox DevTools server library

To aid with debugging web page issues in Ladybird without needing to implement a fully fledged inspector, we can implement the Firefox DevTools protocol and use their DevTools. The protocol is described here: https://firefox-source-docs.mozilla.org/devtools/backend/protocol.html This commit contains just enough to connect to Ladybird from a DevTools client.
Author: https://github.com/trflynn89 Commit: 58bc44ba2a Pull-request: https://github.com/LadybirdBrowser/ladybird/pull/3589 Reviewed-by: https://github.com/ADKaster
2025-09-11 12:06:07 +00:00 · 2025-02-15 07:35:58 -05:00 · 2025-02-15 07:35:58 -05:00 · 58bc44ba2a · 2025-02-19 13:47:24 +00:00
commit 58bc44ba2a
parent 49c93d01db
20 changed files with 947 additions and 0 deletions
--- a/Libraries/LibDevTools/Actors/DeviceActor.cpp
+++ b/Libraries/LibDevTools/Actors/DeviceActor.cpp
@ -0,0 +1,56 @@
+/*
+ * Copyright (c) 2025, Tim Flynn <trflynn89@ladybird.org>
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ */
+
+#include <AK/JsonObject.h>
+#include <AK/String.h>
+#include <LibCore/Version.h>
+#include <LibDevTools/Actors/DeviceActor.h>
+#include <LibWeb/Loader/UserAgent.h>
+
+namespace DevTools {
+
+NonnullRefPtr<DeviceActor> DeviceActor::create(DevToolsServer& devtools, ByteString name)
+{
+    return adopt_ref(*new DeviceActor(devtools, move(name)));
+}
+
+DeviceActor::DeviceActor(DevToolsServer& devtools, ByteString name)
+    : Actor(devtools, move(name))
+{
+}
+
+DeviceActor::~DeviceActor() = default;
+
+void DeviceActor::handle_message(StringView type, JsonObject const&)
+{
+    if (type == "getDescription"sv) {
+        auto build_id = Core::Version::read_long_version_string().to_byte_string();
+
+        // https://github.com/mozilla/gecko-dev/blob/master/devtools/shared/system.js
+        JsonObject value;
+        value.set("apptype"sv, "ladybird"sv);
+        value.set("name"sv, BROWSER_NAME);
+        value.set("brandName"sv, BROWSER_NAME);
+        value.set("version"sv, BROWSER_VERSION);
+        value.set("appbuildid"sv, build_id);
+        value.set("platformbuildid"sv, build_id);
+        value.set("platformversion"sv, "135.0"sv);
+        value.set("useragent"sv, Web::default_user_agent);
+        value.set("os"sv, OS_STRING);
+        value.set("arch"sv, CPU_STRING);
+
+        JsonObject response;
+        response.set("from"sv, name());
+        response.set("value"sv, move(value));
+
+        send_message(move(response));
+        return;
+    }
+
+    send_unrecognized_packet_type_error(type);
+}
+
+}
--- a/Libraries/LibDevTools/Actors/DeviceActor.h
+++ b/Libraries/LibDevTools/Actors/DeviceActor.h
@ -0,0 +1,27 @@
+/*
+ * Copyright (c) 2025, Tim Flynn <trflynn89@ladybird.org>
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ */
+
+#pragma once
+
+#include <AK/NonnullRefPtr.h>
+#include <LibDevTools/Actor.h>
+
+namespace DevTools {
+
+class DeviceActor final : public Actor {
+public:
+    static constexpr auto base_name = "device"sv;
+
+    static NonnullRefPtr<DeviceActor> create(DevToolsServer&, ByteString name);
+    virtual ~DeviceActor() override;
+
+    virtual void handle_message(StringView type, JsonObject const&) override;
+
+private:
+    DeviceActor(DevToolsServer&, ByteString name);
+};
+
+}
--- a/Libraries/LibDevTools/Actors/PreferenceActor.cpp
+++ b/Libraries/LibDevTools/Actors/PreferenceActor.cpp
@ -0,0 +1,42 @@
+/*
+ * Copyright (c) 2025, Tim Flynn <trflynn89@ladybird.org>
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ */
+
+#include <AK/JsonObject.h>
+#include <LibDevTools/Actors/PreferenceActor.h>
+
+namespace DevTools {
+
+NonnullRefPtr<PreferenceActor> PreferenceActor::create(DevToolsServer& devtools, ByteString name)
+{
+    return adopt_ref(*new PreferenceActor(devtools, move(name)));
+}
+
+PreferenceActor::PreferenceActor(DevToolsServer& devtools, ByteString name)
+    : Actor(devtools, move(name))
+{
+}
+
+PreferenceActor::~PreferenceActor() = default;
+
+void PreferenceActor::handle_message(StringView type, JsonObject const&)
+{
+    // FIXME: During session initialization, Firefox DevTools asks for the following boolean configurations:
+    //            browser.privatebrowsing.autostart
+    //            devtools.debugger.prompt-connection
+    //            dom.serviceWorkers.enabled
+    //        We just blindly return `false` for these, but we will eventually want a real configuration manager.
+    if (type == "getBoolPref"sv) {
+        JsonObject response;
+        response.set("from"sv, name());
+        response.set("value"sv, false);
+        send_message(move(response));
+        return;
+    }
+
+    send_unrecognized_packet_type_error(type);
+}
+
+}
--- a/Libraries/LibDevTools/Actors/PreferenceActor.h
+++ b/Libraries/LibDevTools/Actors/PreferenceActor.h
@ -0,0 +1,27 @@
+/*
+ * Copyright (c) 2025, Tim Flynn <trflynn89@ladybird.org>
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ */
+
+#pragma once
+
+#include <AK/NonnullRefPtr.h>
+#include <LibDevTools/Actor.h>
+
+namespace DevTools {
+
+class PreferenceActor final : public Actor {
+public:
+    static constexpr auto base_name = "preference"sv;
+
+    static NonnullRefPtr<PreferenceActor> create(DevToolsServer&, ByteString name);
+    virtual ~PreferenceActor() override;
+
+    virtual void handle_message(StringView type, JsonObject const&) override;
+
+private:
+    PreferenceActor(DevToolsServer&, ByteString name);
+};
+
+}
--- a/Libraries/LibDevTools/Actors/ProcessActor.cpp
+++ b/Libraries/LibDevTools/Actors/ProcessActor.cpp
@ -0,0 +1,45 @@
+/*
+ * Copyright (c) 2025, Tim Flynn <trflynn89@ladybird.org>
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ */
+
+#include <AK/JsonObject.h>
+#include <LibDevTools/Actors/ProcessActor.h>
+
+namespace DevTools {
+
+NonnullRefPtr<ProcessActor> ProcessActor::create(DevToolsServer& devtools, ByteString name, ProcessDescription description)
+{
+    return adopt_ref(*new ProcessActor(devtools, move(name), move(description)));
+}
+
+ProcessActor::ProcessActor(DevToolsServer& devtools, ByteString name, ProcessDescription description)
+    : Actor(devtools, move(name))
+    , m_description(move(description))
+{
+}
+
+ProcessActor::~ProcessActor() = default;
+
+void ProcessActor::handle_message(StringView type, JsonObject const&)
+{
+    send_unrecognized_packet_type_error(type);
+}
+
+JsonObject ProcessActor::serialize_description() const
+{
+    JsonObject traits;
+    traits.set("watcher"sv, m_description.is_parent);
+    traits.set("supportsReloadDescriptor"sv, true);
+
+    JsonObject description;
+    description.set("actor"sv, name());
+    description.set("id"sv, m_description.id);
+    description.set("isParent"sv, m_description.is_parent);
+    description.set("isWindowlessParent"sv, m_description.is_windowless_parent);
+    description.set("traits"sv, move(traits));
+    return description;
+}
+
+}
--- a/Libraries/LibDevTools/Actors/ProcessActor.h
+++ b/Libraries/LibDevTools/Actors/ProcessActor.h
@ -0,0 +1,38 @@
+/*
+ * Copyright (c) 2025, Tim Flynn <trflynn89@ladybird.org>
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ */
+
+#pragma once
+
+#include <AK/NonnullRefPtr.h>
+#include <LibDevTools/Actor.h>
+
+namespace DevTools {
+
+struct ProcessDescription {
+    u64 id { 0 };
+    bool is_parent { false };
+    bool is_windowless_parent { false };
+};
+
+class ProcessActor final : public Actor {
+public:
+    static constexpr auto base_name = "process"sv;
+
+    static NonnullRefPtr<ProcessActor> create(DevToolsServer&, ByteString name, ProcessDescription);
+    virtual ~ProcessActor() override;
+
+    virtual void handle_message(StringView type, JsonObject const&) override;
+
+    ProcessDescription const& description() const { return m_description; }
+    JsonObject serialize_description() const;
+
+private:
+    ProcessActor(DevToolsServer&, ByteString name, ProcessDescription);
+
+    ProcessDescription m_description;
+};
+
+}
--- a/Libraries/LibDevTools/Actors/RootActor.cpp
+++ b/Libraries/LibDevTools/Actors/RootActor.cpp
@ -0,0 +1,136 @@
+/*
+ * Copyright (c) 2025, Tim Flynn <trflynn89@ladybird.org>
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ */
+
+#include <AK/JsonObject.h>
+#include <LibDevTools/Actors/DeviceActor.h>
+#include <LibDevTools/Actors/PreferenceActor.h>
+#include <LibDevTools/Actors/ProcessActor.h>
+#include <LibDevTools/Actors/RootActor.h>
+#include <LibDevTools/DevToolsDelegate.h>
+#include <LibDevTools/DevToolsServer.h>
+
+namespace DevTools {
+
+// https://firefox-source-docs.mozilla.org/devtools/backend/protocol.html#the-root-actor
+NonnullRefPtr<RootActor> RootActor::create(DevToolsServer& devtools, ByteString name)
+{
+    auto actor = adopt_ref(*new RootActor(devtools, move(name)));
+
+    JsonObject traits;
+    traits.set("sources"sv, false);
+    traits.set("highlightable"sv, true);
+    traits.set("customHighlighters"sv, true);
+    traits.set("networkMonitor"sv, false);
+
+    JsonObject message;
+    message.set("from"sv, actor->name());
+    message.set("applicationType"sv, "browser"sv);
+    message.set("traits"sv, move(traits));
+    actor->send_message(move(message));
+
+    return actor;
+}
+
+RootActor::RootActor(DevToolsServer& devtools, ByteString name)
+    : Actor(devtools, move(name))
+{
+}
+
+RootActor::~RootActor() = default;
+
+void RootActor::handle_message(StringView type, JsonObject const& message)
+{
+    JsonObject response;
+    response.set("from"sv, name());
+
+    if (type == "connect") {
+        send_message(move(response));
+        return;
+    }
+
+    if (type == "getRoot"sv) {
+        response.set("selected"sv, 0);
+
+        for (auto const& actor : devtools().actor_registry()) {
+            if (is<DeviceActor>(*actor.value))
+                response.set("deviceActor"sv, actor.key);
+            else if (is<PreferenceActor>(*actor.value))
+                response.set("preferenceActor"sv, actor.key);
+        }
+
+        send_message(move(response));
+        return;
+    }
+
+    if (type == "getProcess"sv) {
+        auto id = message.get_integer<u64>("id"sv);
+        if (!id.has_value()) {
+            send_missing_parameter_error("id"sv);
+            return;
+        }
+
+        for (auto const& actor : devtools().actor_registry()) {
+            auto const* process_actor = as_if<ProcessActor>(*actor.value);
+            if (!process_actor)
+                continue;
+            if (process_actor->description().id != *id)
+                continue;
+
+            response.set("processDescriptor"sv, process_actor->serialize_description());
+            break;
+        }
+
+        send_message(move(response));
+        return;
+    }
+
+    if (type == "getTab"sv) {
+        response.set("tab"sv, JsonObject {});
+        send_message(move(response));
+        return;
+    }
+
+    if (type == "listAddons"sv) {
+        response.set("addons"sv, JsonArray {});
+        send_message(move(response));
+        return;
+    }
+
+    if (type == "listProcesses"sv) {
+        JsonArray processes;
+
+        for (auto const& actor : devtools().actor_registry()) {
+            if (auto const* process_actor = as_if<ProcessActor>(*actor.value))
+                processes.must_append(process_actor->serialize_description());
+        }
+
+        response.set("processes"sv, move(processes));
+        send_message(move(response));
+        return;
+    }
+
+    if (type == "listServiceWorkerRegistrations"sv) {
+        response.set("registrations"sv, JsonArray {});
+        send_message(move(response));
+        return;
+    }
+
+    if (type == "listTabs"sv) {
+        response.set("tabs"sv, JsonArray {});
+        send_message(move(response));
+        return;
+    }
+
+    if (type == "listWorkers"sv) {
+        response.set("workers"sv, JsonArray {});
+        send_message(move(response));
+        return;
+    }
+
+    send_unrecognized_packet_type_error(type);
+}
+
+}
--- a/Libraries/LibDevTools/Actors/RootActor.h
+++ b/Libraries/LibDevTools/Actors/RootActor.h
@ -0,0 +1,27 @@
+/*
+ * Copyright (c) 2025, Tim Flynn <trflynn89@ladybird.org>
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ */
+
+#pragma once
+
+#include <AK/NonnullRefPtr.h>
+#include <LibDevTools/Actor.h>
+
+namespace DevTools {
+
+class RootActor final : public Actor {
+public:
+    static constexpr auto base_name = "root"sv;
+
+    static NonnullRefPtr<RootActor> create(DevToolsServer&, ByteString name);
+    virtual ~RootActor() override;
+
+    virtual void handle_message(StringView type, JsonObject const&) override;
+
+private:
+    RootActor(DevToolsServer&, ByteString name);
+};
+
+}