feat: initial protocol API

Author: Denny09310

src/ElectronNET.API/API/Electron.cs

@@ -186,7 +186,7 @@ public static Dock Dock
         }
 
         /// <summary>
-        /// Electeon extensions to the Nodejs process object.
+        /// Electron extensions to the Nodejs process object.
         /// </summary>
         public static Process Process
         {
@@ -195,5 +195,16 @@ public static Process Process
                 return Process.Instance;
             }
         }
+
+        /// <summary>
+        /// Register a custom protocol and intercept existing protocol requests.
+        /// </summary>
+        public static Protocol Protocol
+        {
+            get
+            {
+                return Protocol.Instance;
+            }
+        }
     }
 }

src/ElectronNET.API/API/Protocol.cs

@@ -0,0 +1,196 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace ElectronNET.API
+{
+
+    public sealed class Protocol : ApiBase
+    {
+        protected override SocketTaskEventNameTypes SocketTaskEventNameType => SocketTaskEventNameTypes.DashesLowerFirst;
+        protected override SocketTaskMessageNameTypes SocketTaskMessageNameType => SocketTaskMessageNameTypes.DashesLowerFirst;
+
+        internal Protocol()
+        {
+        }
+
+        internal static Protocol Instance
+        {
+            get
+            {
+                if (_protocol == null)
+                {
+                    lock (_syncRoot)
+                    {
+                        _protocol ??= new Protocol();
+                    }
+                }
+
+                return _protocol;
+            }
+        }
+
+        private static Protocol _protocol;
+
+        private static readonly object _syncRoot = new();
+
+        /// <summary>
+        /// Registers the scheme as standard, secure, bypasses content security policy for resources, allows registering ServiceWorker, supports fetch API, streaming video/audio, and V8 code cache. 
+        /// Specify a privilege with the value of true to enable the capability.
+        /// </summary>
+        /// <param name="customSchemes">Custom schemes to be registered with options.</param>
+        /// <remarks>This method can only be used before the <see cref="App.Ready"/> event of the app module gets emitted and can be called only once.</remarks>
+        public Task RegisterSchemesAsPrivilegedAsync(params CustomScheme[] customSchemes)
+        {
+            var tsc = new TaskCompletionSource();
+
+            BridgeConnector.Socket.Once("registerSchemesAsPrivilegedComplete", tsc.SetResult);
+            BridgeConnector.Socket.Emit("registerSchemesAsPrivileged", customSchemes);
+
+            return tsc.Task;
+        }
+
+        /// <summary>
+        /// 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.
+        /// </summary>
+        /// <param name="scheme">scheme to handle, for example https or my-app. This is the bit before the : in a URL.</param>
+        /// <param name="handler">Either a <see cref="Response" /> or a <see cref="Task{Response}"/> can be returned.</param>
+        public void Handle(string scheme, Func<Request, Response> handler)
+        {
+            if (string.IsNullOrWhiteSpace(scheme))
+                throw new ArgumentException("Scheme must not be null or empty.", nameof(scheme));
+
+            if (handler == null)
+                throw new ArgumentNullException(nameof(handler));
+
+            Handle(scheme, req => Task.FromResult(handler(req)));
+        }
+
+        public void Handle(string scheme, Func<Request, Task<Response>> handler)
+        {
+            if (string.IsNullOrWhiteSpace(scheme))
+                throw new ArgumentException("Scheme must not be null or empty.", nameof(scheme));
+
+            if (handler == null)
+                throw new ArgumentNullException(nameof(handler));
+
+            var tsc = new TaskCompletionSource();
+
+            // Tell TS to register protocol.handle for this scheme.
+            BridgeConnector.Socket.Emit("protocol-handle-register", new
+            {
+                scheme
+            });
+
+            // Listen for incoming requests from TS
+            BridgeConnector.Socket.On<Request>("protocol-handle-request", async (request) =>
+            {
+                try
+                {
+                    if (request == null || !string.Equals(request.Scheme, scheme, StringComparison.OrdinalIgnoreCase))
+                        return; // Not our scheme, ignore.
+
+                    var response = await handler(request).ConfigureAwait(false) ?? new Response
+                    {
+                        Status = 204
+                    };
+
+                    // Ensure headers dictionary exists
+                    response.Headers ??= new();
+
+                    // Push ContentType also as header, for TS convenience
+                    if (!string.IsNullOrEmpty(response.ContentType))
+                    {
+                        response.Headers["content-type"] = new[] { response.ContentType! };
+                    }
+
+                    BridgeConnector.Socket.Emit("protocol-handle-response", new
+                    {
+                        id = request.Id,
+                        status = response.Status,
+                        headers = response.Headers,
+                        body = response.Body != null
+                            ? Convert.ToBase64String(response.Body)
+                            : null
+                    });
+                }
+                catch (Exception ex)
+                {
+                    // In case of error, send a 500 back
+                    var errorBody = Encoding.UTF8.GetBytes("Protocol handler error:\n" + ex);
+
+                    BridgeConnector.Socket.Emit("protocol-handle-response", new
+                    {
+                        id = request.Id,
+                        status = 500,
+                        headers = new
+                        {
+                            // minimal header set
+                            contentType = new[] { "text/plain; charset=utf-8" }
+                        },
+                        body = Convert.ToBase64String(errorBody)
+                    });
+                }
+            });
+        }
+    }
+
+    public sealed class Request
+    {
+        public string Id { get; set; } = default!;
+        public string Scheme { get; set; } = default!;
+        public string Url { get; set; } = default!;
+        public string Method { get; set; } = "GET";
+
+        // Case-insensitive header name, multiple values per header.
+        public Dictionary<string, string[]> Headers { get; set; } = new(StringComparer.OrdinalIgnoreCase);
+
+        /// <summary>
+        /// Request body as raw bytes, or null if none.
+        /// </summary>
+        public byte[] Body { get; set; }
+    }
+
+    public sealed class Response
+    {
+        /// <summary>
+        /// HTTP-like status code. Default 200.
+        /// </summary>
+        public int Status { get; set; } = 200;
+
+        /// <summary>
+        /// Content-Type header value; convenience property.
+        /// </summary>
+        public string ContentType { get; set; }
+
+        /// <summary>
+        /// Response headers (without Content-Type).
+        /// </summary>
+        public Dictionary<string, string[]> Headers { get; set; } = new(StringComparer.OrdinalIgnoreCase);
+
+        /// <summary>
+        /// Raw response body (may be null for no body).
+        /// </summary>
+        public byte[] Body { get; set; }
+    }
+
+    public sealed class CustomScheme
+    {
+        public string Scheme { get; set; }
+        public CustomSchemePrivileges Privileges { get; set; }
+
+    }
+    public sealed class CustomSchemePrivileges
+    {
+        public bool? Standard { get; set; }
+        public bool? Secure { get; set; }
+        public bool? BypassCSP { get; set; }
+        public bool? AllowServiceWorkers { get; set; }
+        public bool? SupportFetchAPI { get; set; }
+        public bool? CorsEnabled { get; set; }
+        public bool? Stream { get; set; }
+        public bool? CodeCache { get; set; }
+    }
+
+}

src/ElectronNET.Host/api/protocol.ts

@@ -0,0 +1,101 @@
+import { Socket } from "net";
+import { protocol } from "electron";
+import { randomUUID } from "crypto"; // Node 14+; or a simple counter
+
+let electronSocket: Socket;
+
+type Request1 = {
+    id: string;
+    scheme: string;
+    url: string;
+    method: string;
+    headers: Record<string, string[]>;
+    body?: string | null;
+};
+
+type Response1 = {
+    id: string;
+    status: number;
+    headers: Record<string, string[]>;
+    body?: string | null;
+};
+
+export = (socket: Socket) => {
+    electronSocket = socket;
+
+    // Already handled earlier:
+    socket.on("registerSchemesAsPrivileged", (schemes) => {
+        protocol.registerSchemesAsPrivileged(schemes);
+        electronSocket.emit("registerSchemesAsPrivilegedCompleted");
+    });
+
+    // New: protocol.handle
+    socket.on("protocol-handle-register", ({ scheme }: { scheme: string }) => {
+        protocol.handle(scheme, (request) => handle(scheme, request));
+    });
+};
+
+async function handle(scheme: string, request: Request): Promise<Response> {
+    const id = randomUUID();
+
+    const headers: Record<string, string[]> = {};
+    for (const [value, key] of request.headers) {
+        headers[key] = Array.isArray(value) ? value : [value];
+    }
+
+    let body: string | undefined;
+    if (request.body) {
+        const buffer = Buffer.from(await request.arrayBuffer());
+        body = buffer.toString("base64");
+    }
+
+    const dto: Request1 = {
+        id,
+        scheme,
+        url: request.url,
+        method: request.method,
+        headers,
+        body
+    };
+
+    return new Promise<Response>((resolve, reject) => {
+        const handle = (res: Response1) => {
+            // Filter by correlation ID
+            if (res?.id !== id) {
+                return;
+            }
+
+            electronSocket.off("protocol-handle-response", handle as any);
+
+            try {
+                const status = res.status ?? 200;
+                const headers = new Headers();
+
+                if (res.headers) {
+                    for (const [key, values] of Object.entries(res.headers)) {
+                        if (Array.isArray(values)) {
+                            for (const v of values) {
+                                headers.append(key, v);
+                            }
+                        } else if (typeof values === "string") {
+                            headers.append(key, values);
+                        }
+                    }
+                }
+
+                let body: Buffer | undefined;
+                if (res.body) {
+                    body = Buffer.from(res.body, "base64");
+                }
+
+                const response = new Response(body, { status, headers });
+                resolve(response);
+            } catch (err) {
+                reject(err);
+            }
+        };
+
+        electronSocket.on("protocol-handle-response", handle);
+        electronSocket.emit("protocol-handle-request", dto);
+    });
+}

src/ElectronNET.Host/main.js

@@ -7,7 +7,7 @@ const portscanner = require('portscanner');
 const { imageSize } = require('image-size');
 const { HookService } = require('electron-host-hook');
 let io, server, browserWindows, ipc, apiProcess, loadURL;
-let appApi, menu, dialogApi, notification, tray, webContents;
+let appApi, menu, dialogApi, notification, tray, webContents, protocolApi;
 let globalShortcut, shellApi, screen, clipboard, autoUpdater;
 let commandLine, browserView;
 let powerMonitor;
@@ -329,6 +329,7 @@ function startSocketApiBridge(port) {
         if (nativeTheme === undefined) nativeTheme = require('./api/nativeTheme')(socket);
         if (dock === undefined) dock = require('./api/dock')(socket);
         if (processInfo === undefined) processInfo = require('./api/process')(socket);
+        if (protocolApi === undefined) protocolApi = require('./api/protocol')(socket);
 
         socket.on('register-app-open-file', (id) => {
             global['electronsocket'] = socket;
@@ -373,7 +374,7 @@ function startSocketApiBridge(port) {
 function startAspCoreBackend(electronPort) {
     startBackend();
 
-    function startBackend() {           
+    function startBackend() {
         loadURL = `about:blank`;
         const envParam = getEnvironmentParameter();
         const parameters = [
@@ -437,4 +438,4 @@ function getEnvironmentParameter() {
     }
 
     return '';
-}
+}

src/ElectronNET.WebApp/Program.cs

@@ -102,4 +102,4 @@ private static void AddDevelopmentTests()
             }
         }
     }
-}
+}