Add lens:// protocol handling with a routing mechanism (#1949)

- Add lens:// protocol handling with a routing mechanism

- document the methods in an extension guide

- remove handlers when an extension is deactivated or removed

- make sure that the found extension when routing a request is currently enabled (as a backup)

- added documentation about the above behaviour to the guide

- tweaked the naming convention so that it is clearer that the router uses extension names as not IDs (which currently are folder paths)

- Convert the extension API to use an array for registering handlers

- switch design to execute both main and renderer handlers simultaneously, without any overlap checking

- change open to be a dev dep

- improve docs, export types for extensions, skip integration tests

- switch to event emitting renderer being ready

- Add logging and fix renderer:loaded send to main

Signed-off-by: Sebastian Malton <sebastian@malton.name>

src/main/app-updater.ts

@@ -4,6 +4,7 @@ import { isDevelopment, isTestEnv } from "../common/vars";
 import { delay } from "../common/utils";
 import { areArgsUpdateAvailableToBackchannel, AutoUpdateLogPrefix, broadcastMessage, onceCorrect, UpdateAvailableChannel, UpdateAvailableToBackchannel } from "../common/ipc";
 import { ipcMain } from "electron";
+import { once } from "lodash";
 
 let installVersion: null | string = null;
 
@@ -28,7 +29,7 @@ function handleAutoUpdateBackChannel(event: Electron.IpcMainEvent, ...[arg]: Upd
  * starts the automatic update checking
  * @param interval milliseconds between interval to check on, defaults to 24h
  */
-export function startUpdateChecking(interval = 1000 * 60 * 60 * 24): void {
+export const startUpdateChecking = once(function (interval = 1000 * 60 * 60 * 24): void {
   if (isDevelopment || isTestEnv) {
     return;
   }
@@ -83,7 +84,7 @@ export function startUpdateChecking(interval = 1000 * 60 * 60 * 24): void {
   }
 
   helper();
-}
+});
 
 export async function checkForUpdates(): Promise<void> {
   try {

src/main/index.ts

@@ -4,7 +4,7 @@ import "../common/system-ca";
 import "../common/prometheus-providers";
 import * as Mobx from "mobx";
 import * as LensExtensions from "../extensions/core-api";
-import { app, autoUpdater, dialog, powerMonitor } from "electron";
+import { app, autoUpdater, ipcMain, dialog, powerMonitor } from "electron";
 import { appName } from "../common/vars";
 import path from "path";
 import { LensProxy } from "./lens-proxy";
@@ -25,6 +25,7 @@ import { InstalledExtension, extensionDiscovery } from "../extensions/extension-
 import type { LensExtensionId } from "../extensions/lens-extension";
 import { installDeveloperTools } from "./developer-tools";
 import { filesystemProvisionerStore } from "./extension-filesystem";
+import { LensProtocolRouterMain } from "./protocol-handler";
 import { getAppVersion, getAppVersionFromProxyServer } from "../common/utils";
 import { bindBroadcastHandlers } from "../common/ipc";
 import { startUpdateChecking } from "./app-updater";
@@ -37,30 +38,54 @@ let windowManager: WindowManager;
 
 app.setName(appName);
 
+logger.info("📟 Setting as Lens as protocol client for lens://");
+
+if (app.setAsDefaultProtocolClient("lens")) {
+  logger.info("📟 succeeded ✅");
+} else {
+  logger.info("📟 failed ❗");
+}
+
 if (!process.env.CICD) {
   app.setPath("userData", workingDir);
 }
 
+if (process.env.LENS_DISABLE_GPU) {
+  app.disableHardwareAcceleration();
+}
+
 mangleProxyEnv();
 
 if (app.commandLine.getSwitchValue("proxy-server") !== "") {
   process.env.HTTPS_PROXY = app.commandLine.getSwitchValue("proxy-server");
 }
 
-const instanceLock = app.requestSingleInstanceLock();
-
-if (!instanceLock) {
+if (!app.requestSingleInstanceLock()) {
   app.exit();
+} else {
+  const lprm = LensProtocolRouterMain.getInstance<LensProtocolRouterMain>();
+
+  for (const arg of process.argv) {
+    if (arg.toLowerCase().startsWith("lens://")) {
+      lprm.route(arg)
+        .catch(error => logger.error(`${LensProtocolRouterMain.LoggingPrefix}: an error occured`, { error, rawUrl: arg }));
+    }
+  }
 }
 
-app.on("second-instance", () => {
+app.on("second-instance", (event, argv) => {
+  const lprm = LensProtocolRouterMain.getInstance<LensProtocolRouterMain>();
+
+  for (const arg of argv) {
+    if (arg.toLowerCase().startsWith("lens://")) {
+      lprm.route(arg)
+        .catch(error => logger.error(`${LensProtocolRouterMain.LoggingPrefix}: an error occured`, { error, rawUrl: arg }));
+    }
+  }
+
   windowManager?.ensureMainWindow();
 });
 
-if (process.env.LENS_DISABLE_GPU) {
-  app.disableHardwareAcceleration();
-}
-
 app.on("ready", async () => {
   logger.info(`🚀 Starting Lens from "${workingDir}"`);
   logger.info("🐚 Syncing shell environment");
@@ -128,7 +153,19 @@ app.on("ready", async () => {
 
   logger.info("🖥️  Starting WindowManager");
   windowManager = WindowManager.getInstance<WindowManager>(proxyPort);
-  windowManager.whenLoaded.then(() => startUpdateChecking());
+
+  ipcMain.on("renderer:loaded", () => {
+    startUpdateChecking();
+    LensProtocolRouterMain
+      .getInstance<LensProtocolRouterMain>()
+      .rendererLoaded = true;
+  });
+
+  extensionLoader.whenLoaded.then(() => {
+    LensProtocolRouterMain
+      .getInstance<LensProtocolRouterMain>()
+      .extensionsLoaded = true;
+  });
 
   logger.info("🧩 Initializing extensions");
 
@@ -174,8 +211,8 @@ let blockQuit = true;
 
 autoUpdater.on("before-quit-for-update", () => blockQuit = false);
 
-// Quit app on Cmd+Q (MacOS)
 app.on("will-quit", (event) => {
+  // Quit app on Cmd+Q (MacOS)
   logger.info("APP:QUIT");
   appEventBus.emit({name: "app", action: "close"});
 
@@ -188,6 +225,16 @@ app.on("will-quit", (event) => {
   }
 });
 
+app.on("open-url", (event, rawUrl) => {
+  // lens:// protocol handler
+  event.preventDefault();
+
+  LensProtocolRouterMain
+    .getInstance<LensProtocolRouterMain>()
+    .route(rawUrl)
+    .catch(error => logger.error(`${LensProtocolRouterMain.LoggingPrefix}: an error occured`, { error, rawUrl }));
+});
+
 // Extensions-api runtime exports
 export const LensExtensionsApi = {
   ...LensExtensions,

src/main/protocol-handler/__test__/router.test.ts

@@ -0,0 +1,259 @@
+import { LensProtocolRouterMain } from "../router";
+import { noop } from "../../../common/utils";
+import { extensionsStore } from "../../../extensions/extensions-store";
+import { extensionLoader } from "../../../extensions/extension-loader";
+import * as uuid from "uuid";
+import { LensMainExtension } from "../../../extensions/core-api";
+import { broadcastMessage } from "../../../common/ipc";
+import { ProtocolHandlerExtension, ProtocolHandlerInternal } from "../../../common/protocol-handler";
+
+jest.mock("../../../common/ipc");
+
+function throwIfDefined(val: any): void {
+  if (val != null) {
+    throw val;
+  }
+}
+
+describe("protocol router tests", () => {
+  let lpr: LensProtocolRouterMain;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    (extensionsStore as any).state.clear();
+    (extensionLoader as any).instances.clear();
+    LensProtocolRouterMain.resetInstance();
+    lpr = LensProtocolRouterMain.getInstance<LensProtocolRouterMain>();
+    lpr.extensionsLoaded = true;
+    lpr.rendererLoaded = true;
+  });
+
+  it("should throw on non-lens URLS", async () => {
+    try {
+      expect(await lpr.route("https://google.ca")).toBeUndefined();
+    } catch (error) {
+      expect(error).toBeInstanceOf(Error);
+    }
+  });
+
+  it("should throw when host not internal or extension", async () => {
+    try {
+      expect(await lpr.route("lens://foobar")).toBeUndefined();
+    } catch (error) {
+      expect(error).toBeInstanceOf(Error);
+    }
+  });
+
+  it("should not throw when has valid host", async () => {
+    const extId = uuid.v4();
+    const ext = new LensMainExtension({
+      id: extId,
+      manifestPath: "/foo/bar",
+      manifest: {
+        name: "@mirantis/minikube",
+        version: "0.1.1",
+      },
+      isBundled: false,
+      isEnabled: true,
+      absolutePath: "/foo/bar",
+    });
+
+    ext.protocolHandlers.push({
+      pathSchema: "/",
+      handler: noop,
+    });
+
+    (extensionLoader as any).instances.set(extId, ext);
+    (extensionsStore as any).state.set(extId, { enabled: true, name: "@mirantis/minikube" });
+
+    lpr.addInternalHandler("/", noop);
+
+    try {
+      expect(await lpr.route("lens://app")).toBeUndefined();
+    } catch (error) {
+      expect(throwIfDefined(error)).not.toThrow();
+    }
+
+
+    try {
+      expect(await lpr.route("lens://extension/@mirantis/minikube")).toBeUndefined();
+    } catch (error) {
+      expect(throwIfDefined(error)).not.toThrow();
+    }
+
+    expect(broadcastMessage).toHaveBeenNthCalledWith(1, ProtocolHandlerInternal, "lens://app");
+    expect(broadcastMessage).toHaveBeenNthCalledWith(2, ProtocolHandlerExtension, "lens://extension/@mirantis/minikube");
+  });
+
+  it("should call handler if matches", async () => {
+    let called = false;
+
+    lpr.addInternalHandler("/page", () => { called = true; });
+
+    try {
+      expect(await lpr.route("lens://app/page")).toBeUndefined();
+    } catch (error) {
+      expect(throwIfDefined(error)).not.toThrow();
+    }
+
+    expect(called).toBe(true);
+    expect(broadcastMessage).toBeCalledWith(ProtocolHandlerInternal, "lens://app/page");
+  });
+
+  it("should call most exact handler", async () => {
+    let called: any = 0;
+
+    lpr.addInternalHandler("/page", () => { called = 1; });
+    lpr.addInternalHandler("/page/:id", params => { called = params.pathname.id; });
+
+    try {
+      expect(await lpr.route("lens://app/page/foo")).toBeUndefined();
+    } catch (error) {
+      expect(throwIfDefined(error)).not.toThrow();
+    }
+
+    expect(called).toBe("foo");
+    expect(broadcastMessage).toBeCalledWith(ProtocolHandlerInternal, "lens://app/page/foo");
+  });
+
+  it("should call most exact handler for an extension", async () => {
+    let called: any = 0;
+
+    const extId = uuid.v4();
+    const ext = new LensMainExtension({
+      id: extId,
+      manifestPath: "/foo/bar",
+      manifest: {
+        name: "@foobar/icecream",
+        version: "0.1.1",
+      },
+      isBundled: false,
+      isEnabled: true,
+      absolutePath: "/foo/bar",
+    });
+
+    ext.protocolHandlers
+      .push({
+        pathSchema: "/page",
+        handler: () => { called = 1; },
+      }, {
+        pathSchema: "/page/:id",
+        handler: params => { called = params.pathname.id; },
+      });
+
+    (extensionLoader as any).instances.set(extId, ext);
+    (extensionsStore as any).state.set(extId, { enabled: true, name: "@foobar/icecream" });
+
+    try {
+      expect(await lpr.route("lens://extension/@foobar/icecream/page/foob")).toBeUndefined();
+    } catch (error) {
+      expect(throwIfDefined(error)).not.toThrow();
+    }
+
+    expect(called).toBe("foob");
+    expect(broadcastMessage).toBeCalledWith(ProtocolHandlerExtension, "lens://extension/@foobar/icecream/page/foob");
+  });
+
+  it("should work with non-org extensions", async () => {
+    let called: any = 0;
+
+    {
+      const extId = uuid.v4();
+      const ext = new LensMainExtension({
+        id: extId,
+        manifestPath: "/foo/bar",
+        manifest: {
+          name: "@foobar/icecream",
+          version: "0.1.1",
+        },
+        isBundled: false,
+        isEnabled: true,
+        absolutePath: "/foo/bar",
+      });
+
+      ext.protocolHandlers
+        .push({
+          pathSchema: "/page/:id",
+          handler: params => { called = params.pathname.id; },
+        });
+
+      (extensionLoader as any).instances.set(extId, ext);
+      (extensionsStore as any).state.set(extId, { enabled: true, name: "@foobar/icecream" });
+    }
+
+    {
+      const extId = uuid.v4();
+      const ext = new LensMainExtension({
+        id: extId,
+        manifestPath: "/foo/bar",
+        manifest: {
+          name: "icecream",
+          version: "0.1.1",
+        },
+        isBundled: false,
+        isEnabled: true,
+        absolutePath: "/foo/bar",
+      });
+
+      ext.protocolHandlers
+        .push({
+          pathSchema: "/page",
+          handler: () => { called = 1; },
+        });
+
+      (extensionLoader as any).instances.set(extId, ext);
+      (extensionsStore as any).state.set(extId, { enabled: true, name: "icecream" });
+    }
+
+    (extensionsStore as any).state.set("@foobar/icecream", { enabled: true, name: "@foobar/icecream" });
+    (extensionsStore as any).state.set("icecream", { enabled: true, name: "icecream" });
+
+    try {
+      expect(await lpr.route("lens://extension/icecream/page")).toBeUndefined();
+    } catch (error) {
+      expect(throwIfDefined(error)).not.toThrow();
+    }
+
+    expect(called).toBe(1);
+    expect(broadcastMessage).toBeCalledWith(ProtocolHandlerExtension, "lens://extension/icecream/page");
+  });
+
+  it("should throw if urlSchema is invalid", () => {
+    expect(() => lpr.addInternalHandler("/:@", noop)).toThrowError();
+  });
+
+  it("should call most exact handler with 3 found handlers", async () => {
+    let called: any = 0;
+
+    lpr.addInternalHandler("/", () => { called = 2; });
+    lpr.addInternalHandler("/page", () => { called = 1; });
+    lpr.addInternalHandler("/page/foo", () => { called = 3; });
+    lpr.addInternalHandler("/page/bar", () => { called = 4; });
+
+    try {
+      expect(await lpr.route("lens://app/page/foo/bar/bat")).toBeUndefined();
+    } catch (error) {
+      expect(throwIfDefined(error)).not.toThrow();
+    }
+
+    expect(called).toBe(3);
+    expect(broadcastMessage).toBeCalledWith(ProtocolHandlerInternal, "lens://app/page/foo/bar/bat");
+  });
+
+  it("should call most exact handler with 2 found handlers", async () => {
+    let called: any = 0;
+
+    lpr.addInternalHandler("/", () => { called = 2; });
+    lpr.addInternalHandler("/page", () => { called = 1; });
+    lpr.addInternalHandler("/page/bar", () => { called = 4; });
+
+    try {
+      expect(await lpr.route("lens://app/page/foo/bar/bat")).toBeUndefined();
+    } catch (error) {
+      expect(throwIfDefined(error)).not.toThrow();
+    }
+
+    expect(called).toBe(1);
+    expect(broadcastMessage).toBeCalledWith(ProtocolHandlerInternal, "lens://app/page/foo/bar/bat");
+  });
+});

src/main/protocol-handler/index.ts

@@ -0,0 +1 @@
+export * from "./router";

src/main/protocol-handler/router.ts

@@ -0,0 +1,112 @@
+import logger from "../logger";
+import * as proto from "../../common/protocol-handler";
+import Url from "url-parse";
+import { LensExtension } from "../../extensions/lens-extension";
+import { broadcastMessage } from "../../common/ipc";
+import { observable, when } from "mobx";
+
+export interface FallbackHandler {
+  (name: string): Promise<boolean>;
+}
+
+export class LensProtocolRouterMain extends proto.LensProtocolRouter {
+  private missingExtensionHandlers: FallbackHandler[] = [];
+
+  @observable rendererLoaded = false;
+  @observable extensionsLoaded = false;
+
+  /**
+   * Find the most specific registered handler, if it exists, and invoke it.
+   *
+   * This will send an IPC message to the renderer router to do the same
+   * in the renderer.
+   */
+  public async route(rawUrl: string): Promise<void> {
+    try {
+      const url = new Url(rawUrl, true);
+
+      if (url.protocol.toLowerCase() !== "lens:") {
+        throw new proto.RoutingError(proto.RoutingErrorType.INVALID_PROTOCOL, url);
+      }
+
+      logger.info(`${proto.LensProtocolRouter.LoggingPrefix}: routing ${url.toString()}`);
+
+      switch (url.host) {
+        case "app":
+          return this._routeToInternal(url);
+        case "extension":
+          await when(() => this.extensionsLoaded);
+
+          return this._routeToExtension(url);
+        default:
+          throw new proto.RoutingError(proto.RoutingErrorType.INVALID_HOST, url);
+      }
+
+    } catch (error) {
+      if (error instanceof proto.RoutingError) {
+        logger.error(`${proto.LensProtocolRouter.LoggingPrefix}: ${error}`, { url: error.url });
+      } else {
+        logger.error(`${proto.LensProtocolRouter.LoggingPrefix}: ${error}`, { rawUrl });
+      }
+    }
+  }
+
+  protected async _executeMissingExtensionHandlers(extensionName: string): Promise<boolean> {
+    for (const handler of this.missingExtensionHandlers) {
+      if (await handler(extensionName)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  protected async _findMatchingExtensionByName(url: Url): Promise<LensExtension | string> {
+    const firstAttempt = await super._findMatchingExtensionByName(url);
+
+    if (typeof firstAttempt !== "string") {
+      return firstAttempt;
+    }
+
+    if (await this._executeMissingExtensionHandlers(firstAttempt)) {
+      return super._findMatchingExtensionByName(url);
+    }
+
+    return "";
+  }
+
+  protected async _routeToInternal(url: Url): Promise<void> {
+    const rawUrl = url.toString(); // for sending to renderer
+
+    super._routeToInternal(url);
+
+    await when(() => this.rendererLoaded);
+
+    return broadcastMessage(proto.ProtocolHandlerInternal, rawUrl);
+  }
+
+  protected async _routeToExtension(url: Url): Promise<void> {
+    const rawUrl = url.toString(); // for sending to renderer
+
+    /**
+     * This needs to be done first, so that the missing extension handlers can
+     * be called before notifying the renderer.
+     *
+     * Note: this needs to clone the url because _routeToExtension modifies its
+     * argument.
+     */
+    await super._routeToExtension(new Url(url.toString(), true));
+    await when(() => this.rendererLoaded);
+
+    return broadcastMessage(proto.ProtocolHandlerExtension, rawUrl);
+  }
+
+  /**
+   * Add a function to the list which will be sequentially called if an extension
+   * is not found while routing to the extensions
+   * @param handler A function that tries to find an extension
+   */
+  public addMissingExtensionHandler(handler: FallbackHandler): void {
+    this.missingExtensionHandlers.push(handler);
+  }
+}

src/main/window-manager.ts

@@ -1,5 +1,5 @@
 import type { ClusterId } from "../common/cluster-store";
-import { observable, when } from "mobx";
+import { observable } from "mobx";
 import { app, BrowserWindow, dialog, shell, webContents } from "electron";
 import windowStateKeeper from "electron-window-state";
 import { appEventBus } from "../common/event-bus";
@@ -16,9 +16,6 @@ export class WindowManager extends Singleton {
   protected windowState: windowStateKeeper.State;
   protected disposers: Record<string, Function> = {};
 
-  @observable mainViewInitiallyLoaded = false;
-  whenLoaded = when(() => this.mainViewInitiallyLoaded);
-
   @observable activeClusterId: ClusterId;
 
   constructor(protected proxyPort: number) {
@@ -104,7 +101,6 @@ export class WindowManager extends Singleton {
       setTimeout(() => {
         appEventBus.emit({ name: "app", action: "start" });
       }, 1000);
-      this.mainViewInitiallyLoaded = true;
     } catch (err) {
       dialog.showErrorBox("ERROR!", err.toString());
     }