feat: redesign preload APIs (#45329)

* feat: redesign preload APIs

Co-authored-by: Samuel Maddock <samuel.maddock@gmail.com>

* docs: remove service-worker mentions for now

Co-authored-by: Samuel Maddock <samuel.maddock@gmail.com>

* fix lint

Co-authored-by: Samuel Maddock <samuel.maddock@gmail.com>

* remove service-worker ipc code

Co-authored-by: Samuel Maddock <samuel.maddock@gmail.com>

* add filename

Co-authored-by: Samuel Maddock <samuel.maddock@gmail.com>

* fix: web preferences preload not included

Co-authored-by: Samuel Maddock <samuel.maddock@gmail.com>

* fix: missing common init

Co-authored-by: Samuel Maddock <samuel.maddock@gmail.com>

* fix: preload bundle script error

Co-authored-by: Samuel Maddock <samuel.maddock@gmail.com>

---------

Co-authored-by: trop[bot] <37223003+trop[bot]@users.noreply.github.com>
Co-authored-by: Samuel Maddock <samuel.maddock@gmail.com>

shell/browser/api/electron_api_session.cc

@@ -1065,16 +1065,72 @@ void Session::CreateInterruptedDownload(const gin_helper::Dictionary& options) {
       base::Time::FromSecondsSinceUnixEpoch(start_time)));
 }
 
-void Session::SetPreloads(const std::vector<base::FilePath>& preloads) {
+std::string Session::RegisterPreloadScript(
+    gin_helper::ErrorThrower thrower,
+    const PreloadScript& new_preload_script) {
   auto* prefs = SessionPreferences::FromBrowserContext(browser_context());
   DCHECK(prefs);
-  prefs->set_preloads(preloads);
+
+  auto& preload_scripts = prefs->preload_scripts();
+
+  auto it = std::find_if(preload_scripts.begin(), preload_scripts.end(),
+                         [&new_preload_script](const PreloadScript& script) {
+                           return script.id == new_preload_script.id;
+                         });
+
+  if (it != preload_scripts.end()) {
+    thrower.ThrowError(base::StringPrintf(
+        "Cannot register preload script with existing ID '%s'",
+        new_preload_script.id.c_str()));
+    return "";
+  }
+
+  if (!new_preload_script.file_path.IsAbsolute()) {
+    // Deprecated preload scripts logged error without throwing.
+    if (new_preload_script.deprecated) {
+      LOG(ERROR) << "preload script must have absolute path: "
+                 << new_preload_script.file_path;
+    } else {
+      thrower.ThrowError(
+          base::StringPrintf("Preload script must have absolute path: %s",
+                             new_preload_script.file_path.value().c_str()));
+      return "";
+    }
+  }
+
+  preload_scripts.push_back(new_preload_script);
+  return new_preload_script.id;
 }
 
-std::vector<base::FilePath> Session::GetPreloads() const {
+void Session::UnregisterPreloadScript(gin_helper::ErrorThrower thrower,
+                                      const std::string& script_id) {
   auto* prefs = SessionPreferences::FromBrowserContext(browser_context());
   DCHECK(prefs);
-  return prefs->preloads();
+
+  auto& preload_scripts = prefs->preload_scripts();
+
+  // Find the preload script by its ID
+  auto it = std::find_if(preload_scripts.begin(), preload_scripts.end(),
+                         [&script_id](const PreloadScript& script) {
+                           return script.id == script_id;
+                         });
+
+  // If the script is found, erase it from the vector
+  if (it != preload_scripts.end()) {
+    preload_scripts.erase(it);
+    return;
+  }
+
+  // If the script is not found, throw an error
+  thrower.ThrowError(base::StringPrintf(
+      "Cannot unregister preload script with non-existing ID '%s'",
+      script_id.c_str()));
+}
+
+std::vector<PreloadScript> Session::GetPreloadScripts() const {
+  auto* prefs = SessionPreferences::FromBrowserContext(browser_context());
+  DCHECK(prefs);
+  return prefs->preload_scripts();
 }
 
 /**
@@ -1800,8 +1856,9 @@ void Session::FillObjectTemplate(v8::Isolate* isolate,
       .SetMethod("downloadURL", &Session::DownloadURL)
       .SetMethod("createInterruptedDownload",
                  &Session::CreateInterruptedDownload)
-      .SetMethod("setPreloads", &Session::SetPreloads)
-      .SetMethod("getPreloads", &Session::GetPreloads)
+      .SetMethod("registerPreloadScript", &Session::RegisterPreloadScript)
+      .SetMethod("unregisterPreloadScript", &Session::UnregisterPreloadScript)
+      .SetMethod("getPreloadScripts", &Session::GetPreloadScripts)
       .SetMethod("getSharedDictionaryUsageInfo",
                  &Session::GetSharedDictionaryUsageInfo)
       .SetMethod("getSharedDictionaryInfo", &Session::GetSharedDictionaryInfo)

shell/browser/api/electron_api_session.h

@@ -57,6 +57,7 @@ class ProxyConfig;
 namespace electron {
 
 class ElectronBrowserContext;
+struct PreloadScript;
 
 namespace api {
 
@@ -141,8 +142,11 @@ class Session final : public gin::Wrappable<Session>,
                                      const std::string& uuid);
   void DownloadURL(const GURL& url, gin::Arguments* args);
   void CreateInterruptedDownload(const gin_helper::Dictionary& options);
-  void SetPreloads(const std::vector<base::FilePath>& preloads);
-  std::vector<base::FilePath> GetPreloads() const;
+  std::string RegisterPreloadScript(gin_helper::ErrorThrower thrower,
+                                    const PreloadScript& new_preload_script);
+  void UnregisterPreloadScript(gin_helper::ErrorThrower thrower,
+                               const std::string& script_id);
+  std::vector<PreloadScript> GetPreloadScripts() const;
   v8::Local<v8::Promise> GetSharedDictionaryInfo(
       const gin_helper::Dictionary& options);
   v8::Local<v8::Promise> GetSharedDictionaryUsageInfo();

shell/browser/api/electron_api_web_contents.cc

@@ -3757,16 +3757,15 @@ void WebContents::DoGetZoomLevel(
   std::move(callback).Run(GetZoomLevel());
 }
 
-std::vector<base::FilePath> WebContents::GetPreloadPaths() const {
-  auto result = SessionPreferences::GetValidPreloads(GetBrowserContext());
-
+std::optional<PreloadScript> WebContents::GetPreloadScript() const {
   if (auto* web_preferences = WebContentsPreferences::From(web_contents())) {
     if (auto preload = web_preferences->GetPreloadPath()) {
-      result.emplace_back(*preload);
+      auto preload_script = PreloadScript{
+          "", PreloadScript::ScriptType::kWebFrame, preload.value()};
+      return preload_script;
     }
   }
-
-  return result;
+  return std::nullopt;
 }
 
 v8::Local<v8::Value> WebContents::GetLastWebPreferences(
@@ -4520,7 +4519,7 @@ void WebContents::FillObjectTemplate(v8::Isolate* isolate,
       .SetMethod("setZoomFactor", &WebContents::SetZoomFactor)
       .SetMethod("getZoomFactor", &WebContents::GetZoomFactor)
       .SetMethod("getType", &WebContents::type)
-      .SetMethod("_getPreloadPaths", &WebContents::GetPreloadPaths)
+      .SetMethod("_getPreloadScript", &WebContents::GetPreloadScript)
       .SetMethod("getLastWebPreferences", &WebContents::GetLastWebPreferences)
       .SetMethod("getOwnerBrowserWindow", &WebContents::GetOwnerBrowserWindow)
       .SetMethod("inspectServiceWorker", &WebContents::InspectServiceWorker)

shell/browser/api/electron_api_web_contents.h

@@ -40,6 +40,7 @@
 #include "shell/browser/event_emitter_mixin.h"
 #include "shell/browser/extended_web_contents_observer.h"
 #include "shell/browser/osr/osr_paint_event.h"
+#include "shell/browser/preload_script.h"
 #include "shell/browser/ui/inspectable_web_contents_delegate.h"
 #include "shell/browser/ui/inspectable_web_contents_view_delegate.h"
 #include "shell/common/gin_helper/cleaned_up_at_exit.h"
@@ -344,8 +345,8 @@ class WebContents final : public ExclusiveAccessContext,
                       const std::string& features,
                       const scoped_refptr<network::ResourceRequestBody>& body);
 
-  // Returns the preload script path of current WebContents.
-  std::vector<base::FilePath> GetPreloadPaths() const;
+  // Returns the preload script of current WebContents.
+  std::optional<PreloadScript> GetPreloadScript() const;
 
   // Returns the web preferences of current WebContents.
   v8::Local<v8::Value> GetLastWebPreferences(v8::Isolate* isolate) const;

shell/browser/preload_script.h

@@ -0,0 +1,104 @@
+// Copyright (c) 2025 Salesforce, Inc.
+// Use of this source code is governed by the MIT license that can be
+// found in the LICENSE file.
+
+#ifndef ELECTRON_SHELL_BROWSER_PRELOAD_SCRIPT_H_
+#define ELECTRON_SHELL_BROWSER_PRELOAD_SCRIPT_H_
+
+#include <string_view>
+
+#include "base/containers/fixed_flat_map.h"
+#include "base/files/file_path.h"
+#include "base/uuid.h"
+#include "gin/converter.h"
+#include "shell/common/gin_converters/file_path_converter.h"
+#include "shell/common/gin_helper/dictionary.h"
+
+namespace electron {
+
+struct PreloadScript {
+  enum class ScriptType { kWebFrame, kServiceWorker };
+
+  std::string id;
+  ScriptType script_type;
+  base::FilePath file_path;
+
+  // If set, use the deprecated validation behavior of Session.setPreloads
+  bool deprecated = false;
+};
+
+}  // namespace electron
+
+namespace gin {
+
+using electron::PreloadScript;
+
+template <>
+struct Converter<PreloadScript::ScriptType> {
+  static v8::Local<v8::Value> ToV8(v8::Isolate* isolate,
+                                   const PreloadScript::ScriptType& in) {
+    using Val = PreloadScript::ScriptType;
+    static constexpr auto Lookup =
+        base::MakeFixedFlatMap<Val, std::string_view>({
+            {Val::kWebFrame, "frame"},
+            {Val::kServiceWorker, "service-worker"},
+        });
+    return StringToV8(isolate, Lookup.at(in));
+  }
+
+  static bool FromV8(v8::Isolate* isolate,
+                     v8::Local<v8::Value> val,
+                     PreloadScript::ScriptType* out) {
+    using Val = PreloadScript::ScriptType;
+    static constexpr auto Lookup =
+        base::MakeFixedFlatMap<std::string_view, Val>({
+            {"frame", Val::kWebFrame},
+            {"service-worker", Val::kServiceWorker},
+        });
+    return FromV8WithLookup(isolate, val, Lookup, out);
+  }
+};
+
+template <>
+struct Converter<PreloadScript> {
+  static v8::Local<v8::Value> ToV8(v8::Isolate* isolate,
+                                   const PreloadScript& script) {
+    gin::Dictionary dict(isolate, v8::Object::New(isolate));
+    dict.Set("filePath", script.file_path.AsUTF8Unsafe());
+    dict.Set("id", script.id);
+    dict.Set("type", script.script_type);
+    return ConvertToV8(isolate, dict).As<v8::Object>();
+  }
+
+  static bool FromV8(v8::Isolate* isolate,
+                     v8::Local<v8::Value> val,
+                     PreloadScript* out) {
+    gin_helper::Dictionary options;
+    if (!ConvertFromV8(isolate, val, &options))
+      return false;
+    if (PreloadScript::ScriptType script_type;
+        options.Get("type", &script_type)) {
+      out->script_type = script_type;
+    } else {
+      return false;
+    }
+    if (base::FilePath file_path; options.Get("filePath", &file_path)) {
+      out->file_path = file_path;
+    } else {
+      return false;
+    }
+    if (std::string id; options.Get("id", &id)) {
+      out->id = id;
+    } else {
+      out->id = base::Uuid::GenerateRandomV4().AsLowercaseString();
+    }
+    if (bool deprecated; options.Get("_deprecated", &deprecated)) {
+      out->deprecated = deprecated;
+    }
+    return true;
+  }
+};
+
+}  // namespace gin
+
+#endif  // ELECTRON_SHELL_BROWSER_PRELOAD_SCRIPT_H_

shell/browser/session_preferences.cc

@@ -30,22 +30,4 @@ SessionPreferences* SessionPreferences::FromBrowserContext(
   return static_cast<SessionPreferences*>(context->GetUserData(&kLocatorKey));
 }
 
-// static
-std::vector<base::FilePath> SessionPreferences::GetValidPreloads(
-    content::BrowserContext* context) {
-  std::vector<base::FilePath> result;
-
-  if (auto* self = FromBrowserContext(context)) {
-    for (const auto& preload : self->preloads()) {
-      if (preload.IsAbsolute()) {
-        result.emplace_back(preload);
-      } else {
-        LOG(ERROR) << "preload script must have absolute path: " << preload;
-      }
-    }
-  }
-
-  return result;
-}
-
 }  // namespace electron

shell/browser/session_preferences.h

@@ -9,6 +9,7 @@
 
 #include "base/files/file_path.h"
 #include "base/supports_user_data.h"
+#include "shell/browser/preload_script.h"
 
 namespace content {
 class BrowserContext;
@@ -20,17 +21,12 @@ class SessionPreferences : public base::SupportsUserData::Data {
  public:
   static SessionPreferences* FromBrowserContext(
       content::BrowserContext* context);
-  static std::vector<base::FilePath> GetValidPreloads(
-      content::BrowserContext* context);
 
   static void CreateForBrowserContext(content::BrowserContext* context);
 
   ~SessionPreferences() override;
 
-  void set_preloads(const std::vector<base::FilePath>& preloads) {
-    preloads_ = preloads;
-  }
-  const std::vector<base::FilePath>& preloads() const { return preloads_; }
+  std::vector<PreloadScript>& preload_scripts() { return preload_scripts_; }
 
  private:
   SessionPreferences();
@@ -38,7 +34,7 @@ class SessionPreferences : public base::SupportsUserData::Data {
   // The user data key.
   static int kLocatorKey;
 
-  std::vector<base::FilePath> preloads_;
+  std::vector<PreloadScript> preload_scripts_;
 };
 
 }  // namespace electron