chore: Add new webFrame IsolatedWorldInfo API and deprecate (backport: 5-0-x) (#16932)

* chore: Add new webFrame IsolatedWorldInfo API and deprecate

* Flag deprecated methods in documentation

* address comments

* Address review comments

* remove unused variable

* Update based on review

atom/renderer/api/atom_api_web_frame.cc

@@ -399,6 +399,26 @@ void SetIsolatedWorldHumanReadableName(v8::Local<v8::Value> window,
       world_id, blink::WebString::FromUTF8(name));
 }
 
+void SetIsolatedWorldInfo(v8::Local<v8::Value> window,
+                          int world_id,
+                          const mate::Dictionary& options,
+                          mate::Arguments* args) {
+  std::string origin, csp, name;
+  options.Get("securityOrigin", &origin);
+  options.Get("csp", &csp);
+  options.Get("name", &name);
+
+  if (!csp.empty() && origin.empty()) {
+    args->ThrowError(
+        "If csp is specified, securityOrigin should also be specified");
+    return;
+  }
+
+  SetIsolatedWorldSecurityOrigin(window, world_id, origin);
+  SetIsolatedWorldContentSecurityPolicy(window, world_id, csp);
+  SetIsolatedWorldHumanReadableName(window, world_id, name);
+}
+
 blink::WebCache::ResourceTypeStats GetResourceUsage(v8::Isolate* isolate) {
   blink::WebCache::ResourceTypeStats stats;
   blink::WebCache::GetResourceTypeStats(&stats);
@@ -530,12 +550,13 @@ void Initialize(v8::Local<v8::Object> exports,
   dict.SetMethod("executeJavaScript", &ExecuteJavaScript);
   dict.SetMethod("executeJavaScriptInIsolatedWorld",
                  &ExecuteJavaScriptInIsolatedWorld);
-  dict.SetMethod("setIsolatedWorldSecurityOrigin",
+  dict.SetMethod("_setIsolatedWorldSecurityOrigin",
                  &SetIsolatedWorldSecurityOrigin);
-  dict.SetMethod("setIsolatedWorldContentSecurityPolicy",
+  dict.SetMethod("_setIsolatedWorldContentSecurityPolicy",
                  &SetIsolatedWorldContentSecurityPolicy);
-  dict.SetMethod("setIsolatedWorldHumanReadableName",
+  dict.SetMethod("_setIsolatedWorldHumanReadableName",
                  &SetIsolatedWorldHumanReadableName);
+  dict.SetMethod("setIsolatedWorldInfo", &SetIsolatedWorldInfo);
   dict.SetMethod("getResourceUsage", &GetResourceUsage);
   dict.SetMethod("clearCache", &ClearCache);
   dict.SetMethod("_findFrameByRoutingId", &FindFrameByRoutingId);

docs/api/breaking-changes.md

@@ -71,6 +71,23 @@ Child windows opened with the `nativeWindowOpen` option will always have Node.js
 Renderer process APIs `webFrame.setRegisterURLSchemeAsPrivileged` and `webFrame.registerURLSchemeAsBypassingCSP` as well as browser process API `protocol.registerStandardSchemes` have been removed.
 A new API, `protocol.registerSchemesAsPrivileged` has been added and should be used for registering custom schemes with the required privileges. Custom schemes are required to be registered before app ready.
 
+## webFrame Isolated World APIs 
+
+```js
+// Deprecated
+webFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)
+webFrame.setIsolatedWorldHumanReadableName(worldId, name)
+webFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)
+// Replace with
+webFrame.setIsolatedWorldInfo(
+  worldId,
+  {
+    securityOrigin: 'some_origin',
+    name: 'human_readable_name',
+    csp: 'content_security_policy'
+  })
+```
+
 # Planned Breaking API Changes (4.0)
 
 The following list includes the breaking API changes made in Electron 4.0.

docs/api/web-frame.md

@@ -127,27 +127,37 @@ this limitation.
 
 Work like `executeJavaScript` but evaluates `scripts` in an isolated context.
 
-### `webFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)`
+### `webFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)` _(Deprecated)_
 
 * `worldId` Integer - The ID of the world to run the javascript in, `0` is the default world, `999` is the world used by Electrons `contextIsolation` feature.  You can provide any integer here.
 * `csp` String
 
 Set the content security policy of the isolated world.
 
-### `webFrame.setIsolatedWorldHumanReadableName(worldId, name)`
+### `webFrame.setIsolatedWorldHumanReadableName(worldId, name)` _(Deprecated)_
 
 * `worldId` Integer - The ID of the world to run the javascript in, `0` is the default world, `999` is the world used by Electrons `contextIsolation` feature.  You can provide any integer here.
 * `name` String
 
 Set the name of the isolated world. Useful in devtools.
 
-### `webFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)`
+### `webFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)` _(Deprecated)_
 
 * `worldId` Integer - The ID of the world to run the javascript in, `0` is the default world, `999` is the world used by Electrons `contextIsolation` feature.  You can provide any integer here.
 * `securityOrigin` String
 
 Set the security origin of the isolated world.
 
+### `webFrame.setIsolatedWorldInfo(worldId, info)`
+* `worldId` Integer - The ID of the world to run the javascript in, `0` is the default world, `999` is the world used by Electrons `contextIsolation` feature.  You can provide any integer here.
+* `info` Object
+  * `securityOrigin` String (optional) - Security origin for the isolated world.
+  * `csp` String (optional) - Content Security Policy for the isolated world.
+  * `name` String (optional) - Name for isolated world. Useful in devtools.
+
+Set the security origin, content security policy and name of the isolated world.
+Note: If the `csp` is specified, then the `securityOrigin` also has to be specified.
+
 ### `webFrame.getResourceUsage()`
 
 Returns `Object`:

lib/renderer/api/web-frame.js

@@ -2,6 +2,7 @@
 
 const { EventEmitter } = require('events')
 const binding = process.atomBinding('web_frame')
+const { deprecate } = require('electron')
 
 class WebFrame extends EventEmitter {
   constructor (context) {
@@ -47,6 +48,23 @@ class WebFrame extends EventEmitter {
   get routingId () {
     return binding._getRoutingId(this.context)
   }
+
+  // Deprecations
+  // TODO(nitsakh): Remove in 6.0
+  setIsolatedWorldSecurityOrigin (worldId, securityOrigin) {
+    deprecate.warn('webFrame.setIsolatedWorldSecurityOrigin', 'webFrame.setIsolatedWorldInfo')
+    binding._setIsolatedWorldSecurityOrigin(this.context, worldId, securityOrigin)
+  }
+
+  setIsolatedWorldContentSecurityPolicy (worldId, csp) {
+    deprecate.warn('webFrame.setIsolatedWorldContentSecurityPolicy', 'webFrame.setIsolatedWorldInfo')
+    binding._setIsolatedWorldContentSecurityPolicy(this.context, worldId, csp)
+  }
+
+  setIsolatedWorldHumanReadableName (worldId, name) {
+    deprecate.warn('webFrame.setIsolatedWorldHumanReadableName', 'webFrame.setIsolatedWorldInfo')
+    binding._setIsolatedWorldHumanReadableName(this.context, worldId, name)
+  }
 }
 
 // Populate the methods.