feat: add protocol.handle

docs/api/client-request.md

@@ -234,6 +234,8 @@ it is not allowed to add or remove a custom header.
 * `encoding` string (optional)
 * `callback` Function (optional)
 
+Returns `this`.
+
 Sends the last chunk of the request data. Subsequent write or end operations
 will not be allowed. The `finish` event is emitted just after the end operation.
 

docs/api/protocol.md

@@ -109,6 +109,22 @@ The `<video>` and `<audio>` HTML elements expect protocols to buffer their
 responses by default. The `stream` flag configures those elements to correctly
 expect streaming responses.
 
+### `protocol.handle(scheme, handler)`
+
+* `scheme` string - scheme to handle, for example `https` or `my-app`. This is
+  the bit before the `:` in a URL.
+* `handler` Function<HandleProtocolResponse | Promise<HandleProtocolResponse>>
+  * `request` [ProtocolRequest](structures/protocol-request.md)
+
+Register a protocol handler for `scheme`. Requests made to URLs with this
+scheme will delegate to this handler to determine what response should be sent.
+
+### `protocol.unhandle(scheme)`
+
+* `scheme` string - scheme for which to remove the handler.
+
+Removes a protocol handler registered with `protocol.handle`.
+
 ### `protocol.registerFileProtocol(scheme, handler)`
 
 * `scheme` string

docs/api/structures/handle-protocol-response.md

@@ -0,0 +1,12 @@
+# HandleProtocolResponse Object
+
+* `error` Integer (optional) - When assigned, the request will fail with the
+  error defined by `error`. For the available error numbers you can use, see
+  the [net error list][net-error].
+* `statusCode` number (optional) - The HTTP response code. If not specified,
+  the response will be sent with status code 200.
+* `headers` Record<string, string | string[]> (optional) - The response headers.
+* `body` string | Buffer | ReadableStream | null (optional) - the body of the
+  response. If null or undefined, the body will be empty.
+
+[net-error]: https://source.chromium.org/chromium/chromium/src/+/main:net/base/net_error_list.h

filenames.auto.gni

@@ -85,6 +85,7 @@ auto_filenames = {
     "docs/api/structures/file-filter.md",
     "docs/api/structures/file-path-with-headers.md",
     "docs/api/structures/gpu-feature-status.md",
+    "docs/api/structures/handle-protocol-response.md",
     "docs/api/structures/hid-device.md",
     "docs/api/structures/input-event.md",
     "docs/api/structures/io-counters.md",

lib/browser/api/net.ts

@@ -10,8 +10,6 @@ const {
   createURLLoader
 } = process._linkedBinding('electron_browser_net');
 
-const kSupportedProtocols = new Set(['http:', 'https:']);
-
 // set of headers that Node.js discards duplicates for
 // see https://nodejs.org/api/http.html#http_message_headers
 const discardableDuplicateHeaders = new Set([
@@ -203,9 +201,6 @@ function parseOptions (optionsIn: ClientRequestConstructorOptions | string): Nod
   if (!urlStr) {
     const urlObj: url.UrlObject = {};
     const protocol = options.protocol || 'http:';
-    if (!kSupportedProtocols.has(protocol)) {
-      throw new Error('Protocol "' + protocol + '" not supported');
-    }
     urlObj.protocol = protocol;
 
     if (options.host) {

lib/browser/api/protocol.ts

@@ -1,33 +1,56 @@
-import { app, session } from 'electron/main';
+import { session } from 'electron/main';
 
 // Global protocol APIs.
-const protocol = process._linkedBinding('electron_browser_protocol');
-
-// Fallback protocol APIs of default session.
-Object.setPrototypeOf(protocol, new Proxy({}, {
-  get (_target, property) {
-    if (!app.isReady()) return;
-
-    const protocol = session.defaultSession!.protocol;
-    if (!Object.prototype.hasOwnProperty.call(protocol, property)) return;
-
-    // Returning a native function directly would throw error.
-    return (...args: any[]) => (protocol[property as keyof Electron.Protocol] as Function)(...args);
-  },
-
-  ownKeys () {
-    if (!app.isReady()) return [];
-    return Reflect.ownKeys(session.defaultSession!.protocol);
-  },
-
-  has: (target, property: string) => {
-    if (!app.isReady()) return false;
-    return Reflect.has(session.defaultSession!.protocol, property);
-  },
-
-  getOwnPropertyDescriptor () {
-    return { configurable: true, enumerable: true };
-  }
-}));
+const { registerSchemesAsPrivileged, getStandardSchemes, Protocol } = process._linkedBinding('electron_browser_protocol');
+
+const ERR_UNEXPECTED = -9;
+
+const isBuiltInScheme = (scheme: string) => scheme === 'http' || scheme === 'https';
+
+Protocol.prototype.handle = function (this: Electron.Protocol, scheme: string, handler: (req: any) => Promise<any>) {
+  const register = isBuiltInScheme(scheme) ? this.interceptProtocol : this.registerProtocol;
+  const success = register.call(this, scheme, async (req: any, cb: any) => {
+    const res = await handler(req);
+    if (!res || typeof res !== 'object') {
+      return cb({ error: ERR_UNEXPECTED });
+    }
+    const { error, body, headers, statusCode } = res;
+    cb({
+      data: body,
+      headers,
+      error,
+      statusCode
+    });
+  });
+  if (!success) throw new Error(`Failed to register protocol: ${scheme}`);
+};
+
+Protocol.prototype.unhandle = function (this: Electron.Protocol, scheme: string) {
+  const unregister = isBuiltInScheme(scheme) ? this.uninterceptProtocol : this.unregisterProtocol;
+  if (!unregister.call(this, scheme)) { throw new Error(`Failed to unhandle protocol: ${scheme}`); }
+};
+
+const protocol = {
+  registerSchemesAsPrivileged,
+  getStandardSchemes,
+  registerStringProtocol: (...args) => session.defaultSession.protocol.registerStringProtocol(...args),
+  registerBufferProtocol: (...args) => session.defaultSession.protocol.registerBufferProtocol(...args),
+  registerStreamProtocol: (...args) => session.defaultSession.protocol.registerStreamProtocol(...args),
+  registerFileProtocol: (...args) => session.defaultSession.protocol.registerFileProtocol(...args),
+  registerHttpProtocol: (...args) => session.defaultSession.protocol.registerHttpProtocol(...args),
+  registerProtocol: (...args) => session.defaultSession.protocol.registerProtocol(...args),
+  unregisterProtocol: (...args) => session.defaultSession.protocol.unregisterProtocol(...args),
+  isProtocolRegistered: (...args) => session.defaultSession.protocol.isProtocolRegistered(...args),
+  interceptStringProtocol: (...args) => session.defaultSession.protocol.interceptStringProtocol(...args),
+  interceptBufferProtocol: (...args) => session.defaultSession.protocol.interceptBufferProtocol(...args),
+  interceptStreamProtocol: (...args) => session.defaultSession.protocol.interceptStreamProtocol(...args),
+  interceptFileProtocol: (...args) => session.defaultSession.protocol.interceptFileProtocol(...args),
+  interceptHttpProtocol: (...args) => session.defaultSession.protocol.interceptHttpProtocol(...args),
+  interceptProtocol: (...args) => session.defaultSession.protocol.interceptProtocol(...args),
+  uninterceptProtocol: (...args) => session.defaultSession.protocol.uninterceptProtocol(...args),
+  isProtocolIntercepted: (...args) => session.defaultSession.protocol.isProtocolIntercepted(...args),
+  handle: (...args) => session.defaultSession.protocol.handle(...args),
+  unhandle: (...args) => session.defaultSession.protocol.unhandle(...args)
+} as typeof Electron.protocol;
 
 export default protocol;

shell/browser/api/electron_api_protocol.cc

@@ -273,9 +273,17 @@ gin::Handle<Protocol> Protocol::Create(
       isolate, new Protocol(isolate, browser_context->protocol_registry()));
 }
 
-gin::ObjectTemplateBuilder Protocol::GetObjectTemplateBuilder(
-    v8::Isolate* isolate) {
-  return gin::Wrappable<Protocol>::GetObjectTemplateBuilder(isolate)
+// static
+gin::Handle<Protocol> Protocol::New(gin_helper::ErrorThrower thrower) {
+  thrower.ThrowError("Protocol cannot be created from JS");
+  return gin::Handle<Protocol>();
+}
+
+// static
+v8::Local<v8::ObjectTemplate> Protocol::FillObjectTemplate(
+    v8::Isolate* isolate,
+    v8::Local<v8::ObjectTemplate> tmpl) {
+  return gin::ObjectTemplateBuilder(isolate, "Protocol", tmpl)
       .SetMethod("registerStringProtocol",
                  &Protocol::RegisterProtocolFor<ProtocolType::kString>)
       .SetMethod("registerBufferProtocol",
@@ -304,7 +312,8 @@ gin::ObjectTemplateBuilder Protocol::GetObjectTemplateBuilder(
       .SetMethod("interceptProtocol",
                  &Protocol::InterceptProtocolFor<ProtocolType::kFree>)
       .SetMethod("uninterceptProtocol", &Protocol::UninterceptProtocol)
-      .SetMethod("isProtocolIntercepted", &Protocol::IsProtocolIntercepted);
+      .SetMethod("isProtocolIntercepted", &Protocol::IsProtocolIntercepted)
+      .Build();
 }
 
 const char* Protocol::GetTypeName() {
@@ -333,6 +342,7 @@ void Initialize(v8::Local<v8::Object> exports,
                 void* priv) {
   v8::Isolate* isolate = context->GetIsolate();
   gin_helper::Dictionary dict(isolate, exports);
+  dict.Set("Protocol", electron::api::Protocol::GetConstructor(context));
   dict.SetMethod("registerSchemesAsPrivileged", &RegisterSchemesAsPrivileged);
   dict.SetMethod("getStandardSchemes", &electron::api::GetStandardSchemes);
 }

shell/browser/api/electron_api_protocol.h

@@ -12,6 +12,7 @@
 #include "gin/handle.h"
 #include "gin/wrappable.h"
 #include "shell/browser/net/electron_url_loader_factory.h"
+#include "shell/common/gin_helper/constructible.h"
 
 namespace electron {
 
@@ -37,15 +38,19 @@ enum class ProtocolError {
 };
 
 // Protocol implementation based on network services.
-class Protocol : public gin::Wrappable<Protocol> {
+class Protocol : public gin::Wrappable<Protocol>,
+                 public gin_helper::Constructible<Protocol> {
  public:
   static gin::Handle<Protocol> Create(v8::Isolate* isolate,
                                       ElectronBrowserContext* browser_context);
 
+  static gin::Handle<Protocol> New(gin_helper::ErrorThrower thrower);
+
   // gin::Wrappable
   static gin::WrapperInfo kWrapperInfo;
-  gin::ObjectTemplateBuilder GetObjectTemplateBuilder(
-      v8::Isolate* isolate) override;
+  static v8::Local<v8::ObjectTemplate> FillObjectTemplate(
+      v8::Isolate* isolate,
+      v8::Local<v8::ObjectTemplate> tmpl);
   const char* GetTypeName() override;
 
  private: