feat: redesign preload APIs (#45230)

* feat: redesign preload APIs

* docs: remove service-worker mentions for now

* fix lint

* remove service-worker ipc code

* add filename

* fix: web preferences preload not included

* fix: missing common init

* fix: preload bundle script error

lib/browser/api/session.ts

@@ -1,4 +1,5 @@
 import { fetchWithSession } from '@electron/internal/browser/api/net-fetch';
+import * as deprecate from '@electron/internal/common/deprecate';
 
 import { net } from 'electron/main';
 
@@ -36,6 +37,31 @@ Session.prototype.setDisplayMediaRequestHandler = function (handler, opts) {
   }, opts);
 };
 
+const getPreloadsDeprecated = deprecate.warnOnce('session.getPreloads', 'session.getPreloadScripts');
+Session.prototype.getPreloads = function () {
+  getPreloadsDeprecated();
+  return this.getPreloadScripts()
+    .filter((script) => script.type === 'frame')
+    .map((script) => script.filePath);
+};
+
+const setPreloadsDeprecated = deprecate.warnOnce('session.setPreloads', 'session.registerPreloadScript');
+Session.prototype.setPreloads = function (preloads) {
+  setPreloadsDeprecated();
+  this.getPreloadScripts()
+    .filter((script) => script.type === 'frame')
+    .forEach((script) => {
+      this.unregisterPreloadScript(script.id);
+    });
+  preloads.map(filePath => ({
+    type: 'frame',
+    filePath,
+    _deprecated: true
+  }) as Electron.PreloadScriptRegistration).forEach(script => {
+    this.registerPreloadScript(script);
+  });
+};
+
 export default {
   fromPartition,
   fromPath,

lib/browser/rpc-server.ts

@@ -5,6 +5,7 @@ import { IPC_MESSAGES } from '@electron/internal/common/ipc-messages';
 import { clipboard } from 'electron/common';
 
 import * as fs from 'fs';
+import * as path from 'path';
 
 // Implements window.close()
 ipcMainInternal.on(IPC_MESSAGES.BROWSER_WINDOW_CLOSE, function (event) {
@@ -43,22 +44,40 @@ ipcMainUtils.handleSync(IPC_MESSAGES.BROWSER_CLIPBOARD_SYNC, function (event, me
   return (clipboard as any)[method](...args);
 });
 
-const getPreloadScript = async function (preloadPath: string) {
-  let preloadSrc = null;
-  let preloadError = null;
+const getPreloadScriptsFromEvent = (event: ElectronInternal.IpcMainInternalEvent) => {
+  const session: Electron.Session = event.sender.session;
+  const preloadScripts = session.getPreloadScripts();
+  const framePreloads = preloadScripts.filter(script => script.type === 'frame');
+
+  const webPrefPreload = event.sender._getPreloadScript();
+  if (webPrefPreload) framePreloads.push(webPrefPreload);
+
+  // TODO(samuelmaddock): Remove filter after Session.setPreloads is fully
+  // deprecated. The new API will prevent relative paths from being registered.
+  return framePreloads.filter(script => path.isAbsolute(script.filePath));
+};
+
+const readPreloadScript = async function (script: Electron.PreloadScript): Promise<ElectronInternal.PreloadScript> {
+  let contents;
+  let error;
   try {
-    preloadSrc = await fs.promises.readFile(preloadPath, 'utf8');
-  } catch (error) {
-    preloadError = error;
+    contents = await fs.promises.readFile(script.filePath, 'utf8');
+  } catch (err) {
+    if (err instanceof Error) {
+      error = err;
+    }
   }
-  return { preloadPath, preloadSrc, preloadError };
+  return {
+    ...script,
+    contents,
+    error
+  };
 };
 
 ipcMainUtils.handleSync(IPC_MESSAGES.BROWSER_SANDBOX_LOAD, async function (event) {
-  const preloadPaths = event.sender._getPreloadPaths();
-
+  const preloadScripts = getPreloadScriptsFromEvent(event);
   return {
-    preloadScripts: await Promise.all(preloadPaths.map(path => getPreloadScript(path))),
+    preloadScripts: await Promise.all(preloadScripts.map(readPreloadScript)),
     process: {
       arch: process.arch,
       platform: process.platform,
@@ -71,7 +90,8 @@ ipcMainUtils.handleSync(IPC_MESSAGES.BROWSER_SANDBOX_LOAD, async function (event
 });
 
 ipcMainUtils.handleSync(IPC_MESSAGES.BROWSER_NONSANDBOX_LOAD, function (event) {
-  return { preloadPaths: event.sender._getPreloadPaths() };
+  const preloadScripts = getPreloadScriptsFromEvent(event);
+  return { preloadPaths: preloadScripts.map(script => script.filePath) };
 });
 
 ipcMainInternal.on(IPC_MESSAGES.BROWSER_PRELOAD_ERROR, function (event, preloadPath: string, error: Error) {

lib/sandboxed_renderer/init.ts

@@ -1,6 +1,7 @@
+import '@electron/internal/sandboxed_renderer/pre-init';
 import { IPC_MESSAGES } from '@electron/internal/common/ipc-messages';
-import type * as ipcRendererInternalModule from '@electron/internal/renderer/ipc-renderer-internal';
 import type * as ipcRendererUtilsModule from '@electron/internal/renderer/ipc-renderer-internal-utils';
+import { createPreloadProcessObject, executeSandboxedPreloadScripts } from '@electron/internal/sandboxed_renderer/preload';
 
 import * as events from 'events';
 import { setImmediate, clearImmediate } from 'timers';
@@ -11,35 +12,14 @@ declare const binding: {
   createPreloadScript: (src: string) => Function
 };
 
-const { EventEmitter } = events;
-
-process._linkedBinding = binding.get;
-
 const v8Util = process._linkedBinding('electron_common_v8_util');
-// Expose Buffer shim as a hidden value. This is used by C++ code to
-// deserialize Buffer instances sent from browser process.
-v8Util.setHiddenValue(global, 'Buffer', Buffer);
-// The process object created by webpack is not an event emitter, fix it so
-// the API is more compatible with non-sandboxed renderers.
-for (const prop of Object.keys(EventEmitter.prototype) as (keyof typeof process)[]) {
-  if (Object.hasOwn(process, prop)) {
-    delete process[prop];
-  }
-}
-Object.setPrototypeOf(process, EventEmitter.prototype);
-
-const { ipcRendererInternal } = require('@electron/internal/renderer/ipc-renderer-internal') as typeof ipcRendererInternalModule;
 const ipcRendererUtils = require('@electron/internal/renderer/ipc-renderer-internal-utils') as typeof ipcRendererUtilsModule;
 
 const {
   preloadScripts,
   process: processProps
 } = ipcRendererUtils.invokeSync<{
-  preloadScripts: {
-    preloadPath: string;
-    preloadSrc: string | null;
-    preloadError: null | Error;
-  }[];
+  preloadScripts: ElectronInternal.PreloadScript[];
   process: NodeJS.Process;
 }>(IPC_MESSAGES.BROWSER_SANDBOX_LOAD);
 
@@ -60,8 +40,7 @@ const loadableModules = new Map<string, Function>([
   ['node:url', () => require('url')]
 ]);
 
-// Pass different process object to the preload script.
-const preloadProcess: NodeJS.Process = new EventEmitter() as any;
+const preloadProcess = createPreloadProcessObject();
 
 // InvokeEmitProcessEvent in ElectronSandboxedRendererClient will look for this
 v8Util.setHiddenValue(global, 'emit-process-event', (event: string) => {
@@ -72,77 +51,22 @@ v8Util.setHiddenValue(global, 'emit-process-event', (event: string) => {
 Object.assign(preloadProcess, binding.process);
 Object.assign(preloadProcess, processProps);
 
-Object.assign(process, binding.process);
 Object.assign(process, processProps);
 
-process.getProcessMemoryInfo = preloadProcess.getProcessMemoryInfo = () => {
-  return ipcRendererInternal.invoke<Electron.ProcessMemoryInfo>(IPC_MESSAGES.BROWSER_GET_PROCESS_MEMORY_INFO);
-};
-
-Object.defineProperty(preloadProcess, 'noDeprecation', {
-  get () {
-    return process.noDeprecation;
-  },
-  set (value) {
-    process.noDeprecation = value;
-  }
-});
-
-// This is the `require` function that will be visible to the preload script
-function preloadRequire (module: string) {
-  if (loadedModules.has(module)) {
-    return loadedModules.get(module);
-  }
-  if (loadableModules.has(module)) {
-    const loadedModule = loadableModules.get(module)!();
-    loadedModules.set(module, loadedModule);
-    return loadedModule;
-  }
-  throw new Error(`module not found: ${module}`);
-}
-
-// Process command line arguments.
-const { hasSwitch } = process._linkedBinding('electron_common_command_line');
-
-// Similar to nodes --expose-internals flag, this exposes _linkedBinding so
-// that tests can call it to get access to some test only bindings
-if (hasSwitch('unsafely-expose-electron-internals-for-testing')) {
-  preloadProcess._linkedBinding = process._linkedBinding;
-}
-
 // Common renderer initialization
 require('@electron/internal/renderer/common-init');
 
-// Wrap the script into a function executed in global scope. It won't have
-// access to the current scope, so we'll expose a few objects as arguments:
-//
-// - `require`: The `preloadRequire` function
-// - `process`: The `preloadProcess` object
-// - `Buffer`: Shim of `Buffer` implementation
-// - `global`: The window object, which is aliased to `global` by webpack.
-function runPreloadScript (preloadSrc: string) {
-  const preloadWrapperSrc = `(function(require, process, Buffer, global, setImmediate, clearImmediate, exports, module) {
-  ${preloadSrc}
-  })`;
-
-  // eval in window scope
-  const preloadFn = binding.createPreloadScript(preloadWrapperSrc);
-  const exports = {};
-
-  preloadFn(preloadRequire, preloadProcess, Buffer, global, setImmediate, clearImmediate, exports, { exports });
-}
-
-for (const { preloadPath, preloadSrc, preloadError } of preloadScripts) {
-  try {
-    if (preloadSrc) {
-      runPreloadScript(preloadSrc);
-    } else if (preloadError) {
-      throw preloadError;
-    }
-  } catch (error) {
-    console.error(`Unable to load preload script: ${preloadPath}`);
-    console.error(error);
-
-    ipcRendererInternal.send(IPC_MESSAGES.BROWSER_PRELOAD_ERROR, preloadPath, error);
+executeSandboxedPreloadScripts({
+  loadedModules,
+  loadableModules,
+  process: preloadProcess,
+  createPreloadScript: binding.createPreloadScript,
+  exposeGlobals: {
+    Buffer,
+    // FIXME(samuelmaddock): workaround webpack bug replacing this with just
+    // `__webpack_require__.g,` which causes script error
+    global: globalThis,
+    setImmediate,
+    clearImmediate
   }
-}
+}, preloadScripts);

lib/sandboxed_renderer/pre-init.ts

@@ -0,0 +1,30 @@
+// Pre-initialization code for sandboxed renderers.
+
+import * as events from 'events';
+
+declare const binding: {
+  get: (name: string) => any;
+  process: NodeJS.Process;
+};
+
+// Expose internal binding getter.
+process._linkedBinding = binding.get;
+
+const { EventEmitter } = events;
+const v8Util = process._linkedBinding('electron_common_v8_util');
+
+// Include properties from script 'binding' parameter.
+Object.assign(process, binding.process);
+
+// Expose Buffer shim as a hidden value. This is used by C++ code to
+// deserialize Buffer instances sent from browser process.
+v8Util.setHiddenValue(global, 'Buffer', Buffer);
+
+// The process object created by webpack is not an event emitter, fix it so
+// the API is more compatible with non-sandboxed renderers.
+for (const prop of Object.keys(EventEmitter.prototype) as (keyof typeof process)[]) {
+  if (Object.hasOwn(process, prop)) {
+    delete process[prop];
+  }
+}
+Object.setPrototypeOf(process, EventEmitter.prototype);

lib/sandboxed_renderer/preload.ts

@@ -0,0 +1,101 @@
+import { IPC_MESSAGES } from '@electron/internal/common/ipc-messages';
+import { ipcRendererInternal } from '@electron/internal/renderer/ipc-renderer-internal';
+
+import { EventEmitter } from 'events';
+
+interface PreloadContext {
+  loadedModules: Map<string, any>;
+  loadableModules: Map<string, any>;
+
+  /** Process object to pass into preloads. */
+  process: NodeJS.Process;
+
+  createPreloadScript: (src: string) => Function
+
+  /** Globals to be exposed to preload context. */
+  exposeGlobals: any;
+}
+
+export function createPreloadProcessObject (): NodeJS.Process {
+  const preloadProcess: NodeJS.Process = new EventEmitter() as any;
+
+  preloadProcess.getProcessMemoryInfo = () => {
+    return ipcRendererInternal.invoke<Electron.ProcessMemoryInfo>(IPC_MESSAGES.BROWSER_GET_PROCESS_MEMORY_INFO);
+  };
+
+  Object.defineProperty(preloadProcess, 'noDeprecation', {
+    get () {
+      return process.noDeprecation;
+    },
+    set (value) {
+      process.noDeprecation = value;
+    }
+  });
+
+  const { hasSwitch } = process._linkedBinding('electron_common_command_line');
+
+  // Similar to nodes --expose-internals flag, this exposes _linkedBinding so
+  // that tests can call it to get access to some test only bindings
+  if (hasSwitch('unsafely-expose-electron-internals-for-testing')) {
+    preloadProcess._linkedBinding = process._linkedBinding;
+  }
+
+  return preloadProcess;
+}
+
+// This is the `require` function that will be visible to the preload script
+function preloadRequire (context: PreloadContext, module: string) {
+  if (context.loadedModules.has(module)) {
+    return context.loadedModules.get(module);
+  }
+  if (context.loadableModules.has(module)) {
+    const loadedModule = context.loadableModules.get(module)!();
+    context.loadedModules.set(module, loadedModule);
+    return loadedModule;
+  }
+  throw new Error(`module not found: ${module}`);
+}
+
+// Wrap the script into a function executed in global scope. It won't have
+// access to the current scope, so we'll expose a few objects as arguments:
+//
+// - `require`: The `preloadRequire` function
+// - `process`: The `preloadProcess` object
+// - `Buffer`: Shim of `Buffer` implementation
+// - `global`: The window object, which is aliased to `global` by webpack.
+function runPreloadScript (context: PreloadContext, preloadSrc: string) {
+  const globalVariables = [];
+  const fnParameters = [];
+  for (const [key, value] of Object.entries(context.exposeGlobals)) {
+    globalVariables.push(key);
+    fnParameters.push(value);
+  }
+  const preloadWrapperSrc = `(function(require, process, exports, module, ${globalVariables.join(', ')}) {
+  ${preloadSrc}
+  })`;
+
+  // eval in window scope
+  const preloadFn = context.createPreloadScript(preloadWrapperSrc);
+  const exports = {};
+
+  preloadFn(preloadRequire.bind(null, context), context.process, exports, { exports }, ...fnParameters);
+}
+
+/**
+ * Execute preload scripts within a sandboxed process.
+ */
+export function executeSandboxedPreloadScripts (context: PreloadContext, preloadScripts: ElectronInternal.PreloadScript[]) {
+  for (const { filePath, contents, error } of preloadScripts) {
+    try {
+      if (contents) {
+        runPreloadScript(context, contents);
+      } else if (error) {
+        throw error;
+      }
+    } catch (error) {
+      console.error(`Unable to load preload script: ${filePath}`);
+      console.error(error);
+      ipcRendererInternal.send(IPC_MESSAGES.BROWSER_PRELOAD_ERROR, filePath, error);
+    }
+  }
+}