Secure Connection on Shared Machines

docs/SignalR-Startup-Mode.md

@@ -0,0 +1,236 @@
+# SignalR-Based Startup Mode for Electron.NET
+
+## Overview
+
+This feature adds a new startup mode for Electron.NET where:
+- **.NET/ASP.NET Core starts first** and binds to port 0 (dynamic port)
+- **Kestrel picks an available port** automatically
+- **Electron process is launched** with the actual URL
+- **SignalR is used for communication** instead of socket.io
+- **Blazor Server apps** can coexist with Electron control
+
+## Status
+
+✅ **Phases 1-5 Complete** - Infrastructure ready, basic functionality implemented
+⏸️ **Phase 6 Pending** - Full API integration, testing, and documentation
+
+## How It Works
+
+### Startup Sequence
+
+1. ASP.NET Core application starts
+2. Kestrel binds to `http://localhost:0` (random available port)
+3. `RuntimeControllerAspNetDotnetFirstSignalR` captures the actual port via `IServerAddressesFeature`
+4. Electron process is launched with `--electronUrl=http://localhost:XXXXX`
+5. Electron's main.js detects SignalR mode (via `--dotnetpackedsignalr` or `--unpackeddotnetsignalr` flag)
+6. Electron connects to SignalR hub at `/electron-hub`
+7. Hub notifies runtime controller of successful connection
+8. Application transitions to "Ready" state
+9. `ElectronAppReady` callback is invoked
+
+### Communication Flow
+
+```
+.NET/Kestrel (Port 0) ←→ SignalR Hub (/electron-hub) ←→ Electron Process
+         ↓                        ↓                           ↓
+    Blazor Server          ElectronHub class         SignalR Client
+    (/_blazor hub)         (API commands)           (main.js + signalr-bridge.js)
+```
+
+## Usage
+
+### 1. Enable SignalR Mode
+
+Set the environment variable:
+```bash
+ELECTRON_USE_SIGNALR=true
+```
+
+Or in launchSettings.json:
+```json
+{
+  "environmentVariables": {
+    "ELECTRON_USE_SIGNALR": "true"
+  }
+}
+```
+
+### 2. Configure ASP.NET Core
+
+In your `Program.cs`:
+
+```csharp
+using ElectronNET.API;
+using ElectronNET.API.Entities;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddRazorPages();
+builder.Services.AddElectron();
+
+builder.UseElectron(args, async () =>
+{
+    var window = await Electron.WindowManager.CreateWindowAsync(
+        new BrowserWindowOptions { Show = false });
+
+    window.OnReadyToShow += () => window.Show();
+});
+
+var app = builder.Build();
+
+// Configure middleware
+app.UseStaticFiles();
+app.UseRouting();
+
+// Map the Electron SignalR hub
+app.MapElectronHub();  // ← Required for SignalR mode
+app.MapRazorPages();
+
+app.Run();
+```
+
+### 3. Run Your Application
+
+Just press F5 in Visual Studio or run:
+```bash
+dotnet run
+```
+
+The application will:
+- Automatically detect SignalR mode via environment variable
+- Bind Kestrel to port 0
+- Launch Electron with the correct URL
+- Establish SignalR connection
+
+## Components
+
+### .NET Side
+
+- **`ElectronHub`** - SignalR hub at `/electron-hub`
+- **`SignalRFacade`** - Mimics `SocketIoFacade` interface for compatibility
+- **`RuntimeControllerAspNetDotnetFirstSignalR`** - Lifecycle management
+- **`StartupMethod.PackagedDotnetFirstSignalR`** - For packaged apps
+- **`StartupMethod.UnpackedDotnetFirstSignalR`** - For debugging
+
+### Electron Side
+
+- **`signalr-bridge.js`** - SignalR client wrapper
+- **`main.js`** - Detects SignalR mode and connects to hub
+- **`@microsoft/signalr`** npm package
+
+## Key Features
+
+✅ **Dynamic Port Assignment** - No hardcoded ports, no conflicts  
+✅ **Blazor Server Compatible** - Separate hub endpoints (`/electron-hub` vs `/_blazor`)  
+✅ **Bidirectional Communication** - Both .NET→Electron and Electron→.NET  
+✅ **Hot Reload Support** - SignalR automatic reconnection  
+✅ **Multiple Instances** - Each instance gets its own port  
+
+## Current Limitations (Phase 6 Work Needed)
+
+⚠️ **Electron API Integration** - Existing Electron APIs (WindowManager, Dialog, etc.) still use SocketIoFacade. Full integration requires:
+- Refactoring APIs to work with both facades, or
+- Creating an adapter pattern
+
+⚠️ **Request-Response Pattern** - Current hub methods are one-way. Need to implement proper async request-response for API calls.
+
+⚠️ **Event Routing** - Electron events need to be routed through SignalR back to .NET.
+
+⚠️ **Testing** - Integration tests needed to validate end-to-end functionality.
+
+## What's Implemented
+
+### Phase 1: Core Infrastructure ✅
+- New `StartupMethod` enum values
+- `ElectronHub` SignalR hub
+- Hub endpoint registration
+
+### Phase 2: Runtime Controller ✅
+- `RuntimeControllerAspNetDotnetFirstSignalR`
+- Port 0 binding logic
+- Electron launch with URL parameter
+- SignalR connection tracking
+
+### Phase 3: Electron/Node.js Side ✅
+- `@microsoft/signalr` package integration
+- SignalR connection module
+- Startup mode detection
+- URL parameter handling
+
+### Phase 4: API Bridge ✅ (Basic Structure)
+- `SignalRFacade` class
+- Event handler system
+- Hub connection integration
+
+### Phase 5: Configuration ✅
+- Environment variable detection
+- Port 0 configuration
+- Automatic service registration
+
+## Next Steps (Phase 6)
+
+To fully utilize this feature, the following work is recommended:
+
+1. **API Integration** - Make existing Electron APIs work with SignalR
+2. **Sample Application** - Create a Blazor Server demo
+3. **Integration Tests** - Validate end-to-end scenarios
+4. **Documentation** - Complete user guides and examples
+5. **Performance Testing** - Compare with socket.io mode
+
+## Files Changed
+
+### .NET
+- `src/ElectronNET.API/Runtime/Data/StartupMethod.cs`
+- `src/ElectronNET.AspNet/Hubs/ElectronHub.cs`
+- `src/ElectronNET.AspNet/Bridge/SignalRFacade.cs`
+- `src/ElectronNET.AspNet/Runtime/Controllers/RuntimeControllerAspNetDotnetFirstSignalR.cs`
+- `src/ElectronNET.AspNet/API/ElectronEndpointRouteBuilderExtensions.cs`
+- `src/ElectronNET.AspNet/API/WebHostBuilderExtensions.cs`
+- `src/ElectronNET.API/Runtime/StartupManager.cs`
+
+### Electron/Node.js
+- `src/ElectronNET.Host/package.json`
+- `src/ElectronNET.Host/main.js`
+- `src/ElectronNET.Host/api/signalr-bridge.js` (new file)
+
+## Commits
+
+```
+7f2ea48 - Add PackagedDotnetFirstSignalR and UnpackedDotnetFirstSignalR startup methods
+8ee81f6 - Add ElectronHub and SignalR infrastructure for new startup modes
+40aed60 - Add RuntimeControllerAspNetDotnetFirstSignalR for SignalR-based startup
+c1740b5 - Add SignalR client support to Electron Host for new startup modes
+cb7d721 - Add SignalRFacade for SignalR-based API communication
+268b9c9 - Update RuntimeControllerAspNetDotnetFirstSignalR to use SignalRFacade
+04ec522 - Fix compilation errors - Phase 4 complete (basic structure)
+054f5b1 - Complete Phase 5: Add SignalR startup detection and port 0 configuration
+```
+
+## Benefits Over Socket.io Mode
+
+- **Better Integration** - Native SignalR is part of ASP.NET Core stack
+- **Type Safety** - SignalR has better TypeScript support
+- **Performance** - SignalR is optimized for ASP.NET Core
+- **Reliability** - Built-in reconnection and error handling
+- **Scalability** - Can leverage SignalR's scale-out features
+- **Consistency** - Blazor Server already uses SignalR
+
+## Contributing
+
+To contribute to Phase 6 (full API integration):
+
+1. Focus on adapting existing Electron API classes to work with SignalRFacade
+2. Implement request-response pattern in ElectronHub
+3. Add integration tests
+4. Create sample applications
+5. Update documentation
+
+## License
+
+MIT - Same as Electron.NET
+
+---
+
+**Created**: January 30, 2026  
+**Status**: Infrastructure Complete, API Integration Pending  
+**Contact**: See Electron.NET maintainers

src/ElectronNET.API/Bridge/BridgeConnector.cs

@@ -2,9 +2,11 @@
 // ReSharper disable once CheckNamespace
 namespace ElectronNET.API
 {
+    using ElectronNET.API.Bridge;
+
     internal static class BridgeConnector
     {
-        public static SocketIoFacade Socket
+        public static IFacade Socket
         {
             get
             {

src/ElectronNET.API/Bridge/IFacade.cs

@@ -0,0 +1,62 @@
+namespace ElectronNET.API.Bridge
+{
+    using System;
+    using System.Threading.Tasks;
+
+    /// <summary>
+    /// Common interface for communication facades (SocketIO and SignalR).
+    /// Provides methods for bidirectional communication between .NET and Electron.
+    /// </summary>
+    internal interface IFacade
+    {
+        /// <summary>
+        /// Raised when the bridge connection is established.
+        /// </summary>
+        event EventHandler BridgeConnected;
+
+        /// <summary>
+        /// Raised when the bridge connection is lost.
+        /// </summary>
+        event EventHandler BridgeDisconnected;
+
+        /// <summary>
+        /// Establishes the connection to Electron.
+        /// </summary>
+        void Connect();
+
+        /// <summary>
+        /// Registers a persistent event handler.
+        /// </summary>
+        void On(string eventName, Action action);
+
+        /// <summary>
+        /// Registers a persistent event handler with a typed parameter.
+        /// </summary>
+        void On<T>(string eventName, Action<T> action);
+
+        /// <summary>
+        /// Registers a one-time event handler.
+        /// </summary>
+        void Once(string eventName, Action action);
+
+        /// <summary>
+        /// Registers a one-time event handler with a typed parameter.
+        /// </summary>
+        void Once<T>(string eventName, Action<T> action);
+
+        /// <summary>
+        /// Removes an event handler.
+        /// </summary>
+        void Off(string eventName);
+
+        /// <summary>
+        /// Sends a message to Electron.
+        /// </summary>
+        Task Emit(string eventName, params object[] args);
+
+        /// <summary>
+        /// Disposes the connection.
+        /// </summary>
+        void DisposeSocket();
+    }
+}

src/ElectronNET.API/Bridge/SocketIOFacade.cs

@@ -4,11 +4,12 @@ namespace ElectronNET.API;
 
 using System;
 using System.Threading.Tasks;
+using ElectronNET.API.Bridge;
 using ElectronNET.API.Serialization;
 using SocketIO.Serializer.SystemTextJson;
 using SocketIO = SocketIOClient.SocketIO;
 
-internal class SocketIoFacade
+internal class SocketIoFacade : IFacade
 {
     private readonly SocketIO _socket;
     private readonly object _lockObj = new object();

src/ElectronNET.API/Common/Extensions.cs

@@ -14,6 +14,7 @@ public static bool IsUnpackaged(this StartupMethod method)
             {
                 case StartupMethod.UnpackedElectronFirst:
                 case StartupMethod.UnpackedDotnetFirst:
+                case StartupMethod.UnpackedDotnetFirstSignalR:
                     return true;
                 default:
                     return false;

src/ElectronNET.API/ElectronNetRuntime.cs

@@ -1,6 +1,7 @@
 namespace ElectronNET
 {
     using ElectronNET.API;
+    using ElectronNET.API.Bridge;
     using ElectronNET.Runtime;
     using ElectronNET.Runtime.Controllers;
     using ElectronNET.Runtime.Data;
@@ -49,7 +50,7 @@ static ElectronNetRuntime()
 
         internal static Func<Task> OnAppReadyCallback { get; set; }
 
-        internal static SocketIoFacade GetSocket()
+        internal static IFacade GetSocket()
         {
             return RuntimeControllerCore?.Socket;
         }

src/ElectronNET.API/Runtime/Controllers/RuntimeControllerBase.cs

@@ -1,6 +1,7 @@
 namespace ElectronNET.Runtime.Controllers
 {
     using ElectronNET.API;
+    using ElectronNET.API.Bridge;
     using ElectronNET.Runtime.Services;
     using ElectronNET.Runtime.Services.ElectronProcess;
     using ElectronNET.Runtime.Services.SocketBridge;
@@ -12,7 +13,7 @@ protected RuntimeControllerBase()
         {
         }
 
-        internal abstract SocketIoFacade Socket { get; }
+        internal abstract IFacade Socket { get; }
 
         internal abstract ElectronProcessBase ElectronProcess { get; }
 

src/ElectronNET.API/Runtime/Controllers/RuntimeControllerDotNetFirst.cs

@@ -1,6 +1,7 @@
 namespace ElectronNET.Runtime.Controllers
 {
     using ElectronNET.API;
+    using ElectronNET.API.Bridge;
     using ElectronNET.Common;
     using ElectronNET.Runtime.Data;
     using ElectronNET.Runtime.Helpers;
@@ -19,7 +20,7 @@ public RuntimeControllerDotNetFirst()
         {
         }
 
-        internal override SocketIoFacade Socket
+        internal override IFacade Socket
         {
             get
             {