Improve SignalR plugin error handling and URL resolution

Refactor plugin JS to wrap hub connection logic in try/catch,
add _resolveHubUrl helper for absolute URL resolution, and
display inline connection errors in the UI with new CSS styling.
Add integration tests to verify presence of the new helper and
error style in embedded resources.

Author: icnocop

src/SignalR.OpenApi.SwaggerUi/Resources/signalr-openapi-plugin.js

@@ -308,78 +308,85 @@ var SignalROpenApiPlugin = function (system) {
       return Promise.resolve(_hubs[hubPath]);
     }
 
-    var token = _getAccessToken();
-    var configs = system.getConfigs ? system.getConfigs() : {};
-    var options = {};
-    if (token) {
-      options.accessTokenFactory = function () { return token; };
-    }
-
-    // Apply custom headers from configuration (e.g. "X-Custom-Header")
-    var configuredHeaders = configs.signalRHeaders;
-    if (configuredHeaders && typeof configuredHeaders === "object") {
-      options.headers = {};
-      Object.keys(configuredHeaders).forEach(function (key) {
-        options.headers[key] = configuredHeaders[key];
-      });
-    }
+    // Wrap in try/catch so synchronous errors (e.g. URL resolution
+    // failures in Electron/Node-like environments) are surfaced as
+    // rejected promises instead of uncaught exceptions.
+    try {
+      var token = _getAccessToken();
+      var configs = system.getConfigs ? system.getConfigs() : {};
+      var options = {};
+      if (token) {
+        options.accessTokenFactory = function () { return token; };
+      }
 
-    // Merge apiKey headers entered via the SwaggerUI Authorize dialog
-    var apiKeyHeaders = _getApiKeyHeaders();
-    if (apiKeyHeaders) {
-      if (!options.headers) {
+      // Apply custom headers from configuration (e.g. "X-Custom-Header")
+      var configuredHeaders = configs.signalRHeaders;
+      if (configuredHeaders && typeof configuredHeaders === "object") {
         options.headers = {};
+        Object.keys(configuredHeaders).forEach(function (key) {
+          options.headers[key] = configuredHeaders[key];
+        });
       }
 
-      Object.keys(apiKeyHeaders).forEach(function (key) {
-        options.headers[key] = apiKeyHeaders[key];
-      });
-    }
+      // Merge apiKey headers entered via the SwaggerUI Authorize dialog
+      var apiKeyHeaders = _getApiKeyHeaders();
+      if (apiKeyHeaders) {
+        if (!options.headers) {
+          options.headers = {};
+        }
 
-    // Browsers cannot send custom HTTP headers on WebSocket or
-    // Server-Sent Events connections. When custom headers are
-    // configured, fall back to Long Polling which includes headers
-    // with every HTTP request so the server can read them on each
-    // hub invocation.
-    if (options.headers && Object.keys(options.headers).length > 0) {
-      options.transport = signalR.HttpTransportType.LongPolling;
-    }
+        Object.keys(apiKeyHeaders).forEach(function (key) {
+          options.headers[key] = apiKeyHeaders[key];
+        });
+      }
 
-    var connection = new signalR.HubConnectionBuilder()
-      .withUrl(hubPath, options)
-      .withAutomaticReconnect()
-      .build();
+      // Browsers cannot send custom HTTP headers on WebSocket or
+      // Server-Sent Events connections. When custom headers are
+      // configured, fall back to Long Polling which includes headers
+      // with every HTTP request so the server can read them on each
+      // hub invocation.
+      if (options.headers && Object.keys(options.headers).length > 0) {
+        options.transport = signalR.HttpTransportType.LongPolling;
+      }
 
-    _hubs[hubPath] = connection;
+      var connection = new signalR.HubConnectionBuilder()
+        .withUrl(_resolveHubUrl(hubPath), options)
+        .withAutomaticReconnect()
+        .build();
 
-    // Store the auth fingerprint so we can detect changes later
-    _hubAuthFingerprints[hubPath] = currentFingerprint;
+      _hubs[hubPath] = connection;
 
-    // Track connection state changes for UI updates
-    connection.onreconnecting(function () {
-      if (_eventListeners[hubPath]) {
-        _eventListeners[hubPath].forEach(function (fn) { fn(); });
-      }
-    });
+      // Store the auth fingerprint so we can detect changes later
+      _hubAuthFingerprints[hubPath] = currentFingerprint;
 
-    connection.onreconnected(function () {
-      if (_eventListeners[hubPath]) {
-        _eventListeners[hubPath].forEach(function (fn) { fn(); });
-      }
-    });
+      // Track connection state changes for UI updates
+      connection.onreconnecting(function () {
+        if (_eventListeners[hubPath]) {
+          _eventListeners[hubPath].forEach(function (fn) { fn(); });
+        }
+      });
 
-    connection.onclose(function () {
-      if (_eventListeners[hubPath]) {
-        _eventListeners[hubPath].forEach(function (fn) { fn(); });
-      }
-    });
+      connection.onreconnected(function () {
+        if (_eventListeners[hubPath]) {
+          _eventListeners[hubPath].forEach(function (fn) { fn(); });
+        }
+      });
+
+      connection.onclose(function () {
+        if (_eventListeners[hubPath]) {
+          _eventListeners[hubPath].forEach(function (fn) { fn(); });
+        }
+      });
 
-    // Subscribe to client events once connected
-    _subscribeClientEvents(hubPath, connection);
+      // Subscribe to client events once connected
+      _subscribeClientEvents(hubPath, connection);
 
-    return connection.start().then(function () {
-      return connection;
-    });
+      return connection.start().then(function () {
+        return connection;
+      });
+    } catch (err) {
+      return Promise.reject(err);
+    }
   };
 
   // Parse the x-signalr extension from an operation
@@ -406,6 +413,39 @@ var SignalROpenApiPlugin = function (system) {
     return signalrExt.hubPath || ("/" + signalrExt.hub.toLowerCase());
   };
 
+  // Resolve a relative hub path to an absolute URL so the SignalR client
+  // does not need to use its platform-specific URL resolution logic.
+  // In Electron / Electron.NET renderers the SignalR isBrowser check
+  // returns false (Node.js process global is present), causing
+  // "Cannot resolve '/...'" errors for relative paths. Absolute URLs
+  // starting with http:// or https:// bypass that check entirely.
+  var _resolveHubUrl = function (hubPath) {
+    if (hubPath.indexOf("http://") === 0 || hubPath.indexOf("https://") === 0) {
+      return hubPath;
+    }
+
+    // Prefer the first server URL from the OpenAPI spec (matches what
+    // SwaggerUI shows the user and handles reverse-proxy scenarios).
+    var specIm = system.specSelectors.specJson();
+    var serversIm = specIm && specIm.get("servers");
+    if (serversIm && serversIm.size > 0) {
+      var serverUrl = serversIm.getIn([0, "url"]);
+      if (serverUrl && typeof serverUrl === "string"
+        && (serverUrl.indexOf("http://") === 0 || serverUrl.indexOf("https://") === 0)) {
+        // Strip trailing slash from server URL before appending path
+        return serverUrl.replace(/\/+$/, "") + hubPath;
+      }
+    }
+
+    // Fall back to the current page origin
+    if (typeof window !== "undefined" && window.location && window.location.origin) {
+      return window.location.origin + hubPath;
+    }
+
+    // Last resort: return as-is (standard browser environments resolve it fine)
+    return hubPath;
+  };
+
   // Discover all unique hub paths from the spec's x-signalr extensions.
   // Returns an array of { hubPath, hubName } objects.
   var _getHubPaths = function () {
@@ -663,6 +703,10 @@ var SignalROpenApiPlugin = function (system) {
     var isManualConnecting = connectingHook[0];
     var setManualConnecting = connectingHook[1];
 
+    var errorHook = React.useState(null);
+    var connectionError = errorHook[0];
+    var setConnectionError = errorHook[1];
+
     React.useEffect(function () {
       var listener = function () { forceUpdate(function (n) { return n + 1; }); };
 
@@ -682,19 +726,23 @@ var SignalROpenApiPlugin = function (system) {
 
     var handleConnect = function () {
       setManualConnecting(true);
+      setConnectionError(null);
       _getOrCreateHub(hubPath)
         .then(function () {
           setManualConnecting(false);
           forceUpdate(function (n) { return n + 1; });
         })
         .catch(function (err) {
           setManualConnecting(false);
+          var message = err && (err.message || err.toString()) || "Unknown error";
           console.error("[SignalR OpenAPI] Manual connect failed:", err);
+          setConnectionError(message);
           forceUpdate(function (n) { return n + 1; });
         });
     };
 
     var handleDisconnect = function () {
+      setConnectionError(null);
       _disconnectHub(hubPath).then(function () {
         forceUpdate(function (n) { return n + 1; });
       });
@@ -716,16 +764,29 @@ var SignalROpenApiPlugin = function (system) {
         ? handleConnect
         : undefined;
 
-    return React.createElement("div", {
-      className: "signalr-hub-connection-bar",
-      onClick: function (e) { e.stopPropagation(); },
-    },
+    var children = [
       React.createElement("button", {
+        key: "btn",
         className: buttonClass,
         onClick: handleClick,
         disabled: showConnecting,
-      }, buttonText)
-    );
+      }, buttonText),
+    ];
+
+    if (connectionError) {
+      children.push(
+        React.createElement("span", {
+          key: "err",
+          className: "signalr-connection-error",
+          title: connectionError,
+        }, connectionError)
+      );
+    }
+
+    return React.createElement("div", {
+      className: "signalr-hub-connection-bar",
+      onClick: function (e) { e.stopPropagation(); },
+    }, children);
   }
 
   // React component for client event log panel
@@ -744,9 +805,14 @@ var SignalROpenApiPlugin = function (system) {
     var isConnected = _hubs[hubPath] && _hubs[hubPath].state === signalR.HubConnectionState.Connected;
 
     var connectAndListen = function () {
-      _getOrCreateHub(hubPath).then(function () {
-        forceUpdate(function (n) { return n + 1; });
-      });
+      _getOrCreateHub(hubPath)
+        .then(function () {
+          forceUpdate(function (n) { return n + 1; });
+        })
+        .catch(function (err) {
+          console.error("[SignalR OpenAPI] Connect & Listen failed:", err);
+          forceUpdate(function (n) { return n + 1; });
+        });
     };
 
     var clearLog = function () {

src/SignalR.OpenApi.SwaggerUi/Resources/signalr-openapi.css

@@ -106,3 +106,14 @@
   font-size: 13px;
   gap: 8px;
 }
+
+/* Inline error message shown after a failed connect attempt */
+.signalr-connection-error {
+  color: #f93e3e;
+  font-size: 12px;
+  font-family: monospace;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  max-width: 600px;
+}

test/SignalR.OpenApi.Tests/SwaggerUiIntegrationTests.cs

@@ -208,6 +208,43 @@ public async Task EmbeddedResources_ServesPluginJs()
         Assert.IsTrue(content.Contains("SignalROpenApiPlugin"));
     }
 
+    /// <summary>
+    /// Verifies that the plugin JS contains the _resolveHubUrl helper
+    /// that converts relative hub paths to absolute URLs for environments
+    /// where the SignalR client cannot resolve relative URLs (e.g. Electron).
+    /// </summary>
+    /// <returns>A <see cref="Task"/> representing the asynchronous test.</returns>
+    [TestMethod]
+    public async Task EmbeddedResources_PluginJs_ContainsResolveHubUrl()
+    {
+        using var host = await CreateTestHost();
+        using var client = host.GetTestClient();
+
+        using var response = await client.GetAsync("/signalr-swagger/_resources/signalr-openapi-plugin.js");
+
+        Assert.AreEqual(System.Net.HttpStatusCode.OK, response.StatusCode);
+        var content = await response.Content.ReadAsStringAsync();
+        Assert.IsTrue(content.Contains("_resolveHubUrl"), "Plugin JS should contain _resolveHubUrl helper for absolute URL resolution");
+    }
+
+    /// <summary>
+    /// Verifies that the plugin CSS contains the connection error style
+    /// for displaying inline error messages on failed connect attempts.
+    /// </summary>
+    /// <returns>A <see cref="Task"/> representing the asynchronous test.</returns>
+    [TestMethod]
+    public async Task EmbeddedResources_Css_ContainsConnectionErrorStyle()
+    {
+        using var host = await CreateTestHost();
+        using var client = host.GetTestClient();
+
+        using var response = await client.GetAsync("/signalr-swagger/_resources/signalr-openapi.css");
+
+        Assert.AreEqual(System.Net.HttpStatusCode.OK, response.StatusCode);
+        var content = await response.Content.ReadAsStringAsync();
+        Assert.IsTrue(content.Contains("signalr-connection-error"), "CSS should contain signalr-connection-error class for inline error display");
+    }
+
     /// <summary>
     /// Verifies embedded CSS resource is served.
     /// </summary>