Add lens:// protocol handling with a routing mechanism

Makefile

@@ -9,7 +9,7 @@ else
     DETECTED_OS := $(shell uname)
 endif
 
-binaries/client:
+binaries/client: node_modules
 	yarn download-bins
 
 node_modules: yarn.lock
@@ -37,17 +37,17 @@ test: binaries/client
 	yarn test
 
 .PHONY: integration-linux
-integration-linux: build-extension-types build-extensions
+integration-linux: binaries/client build-extension-types build-extensions
 	yarn build:linux
 	yarn integration
 
 .PHONY: integration-mac
-integration-mac: build-extension-types build-extensions
+integration-mac: binaries/client build-extension-types build-extensions
 	yarn build:mac
 	yarn integration
 
 .PHONY: integration-win
-integration-win: build-extension-types build-extensions
+integration-win: binaries/client build-extension-types build-extensions
 	yarn build:win
 	yarn integration
 

docs/extensions/guides/README.md

@@ -21,12 +21,13 @@ Each guide or code sample includes the following:
 | [Components](components.md) | |
 | [KubeObjectListLayout](kube-object-list-layout.md) | |
 | [Working with mobx](working-with-mobx.md) | |
+| [Protocol Handlers](protocol-handlers.md) | |
 
 ## Samples
 
 | Sample | APIs |
 | ----- | ----- |
-[helloworld](https://github.com/lensapp/lens-extension-samples/tree/master/helloworld-sample) | LensMainExtension <br> LensRendererExtension <br> Component.Icon <br> Component.IconProps |
+[hello-world](https://github.com/lensapp/lens-extension-samples/tree/master/helloworld-sample) | LensMainExtension <br> LensRendererExtension <br> Component.Icon <br> Component.IconProps |
 [minikube](https://github.com/lensapp/lens-extension-samples/tree/master/minikube-sample) | LensMainExtension <br> Store.clusterStore <br> Store.workspaceStore |
 [styling-css-modules-sample](https://github.com/lensapp/lens-extension-samples/tree/master/styling-css-modules-sample) | LensMainExtension <br> LensRendererExtension <br> Component.Icon <br> Component.IconProps |
 [styling-emotion-sample](https://github.com/lensapp/lens-extension-samples/tree/master/styling-emotion-sample) | LensMainExtension <br> LensRendererExtension <br> Component.Icon <br> Component.IconProps |

docs/extensions/guides/protocol-handlers.md

@@ -0,0 +1,83 @@
+# Lens Protocol Handlers
+
+Lens has a file association with the `lens://` protocol.
+This means that Lens can be opened by external programs by providing a link that has `lens` as its protocol.
+Lens provides a routing mechanism that extensions can use to register custom handlers.
+
+## Registering A Protocol Handler
+
+The field `protocolHandlers` exists both on [`LensMainExtension`](extensions/api/classes/lensmainextension/#protocolhandlers) and on [`LensRendererExtension`](extensions/api/classes/lensrendererextension/#protocolhandlers).
+This field will be iterated through every time a `lens://` request gets sent to the application.
+The `pathSchema` argument must comply with the [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) package's `compileToRegex` function.
+
+Once you have registered a handler it will be called when a user opens a link on their computer.
+Handlers will be run in both `main` and `renderer` in parallel with no synchronization between the two processes.
+Furthermore, both `main` and `renderer` are routed separately.
+In other words, which handler is selected in either process is independent from the list of possible handlers in the other.
+
+Example of registering a handler:
+
+```typescript
+import { LensMainExtension, Interface } from "@k8slens/extensions";
+
+function rootHandler(params: Iterface.ProtocolRouteParams) {
+  console.log("routed to ExampleExtension", params);
+}
+
+export default class ExampleExtensionMain extends LensMainExtension {
+  protocolHandlers = [
+    pathSchema: "/",
+    handler: rootHandler,
+  ]
+}
+```
+
+For testing the routing of URIs the `open` (on macOS) or `xdg-open` (on most linux) CLI utilities can be used.
+For the above handler, the following URI would be always routed to it:
+
+```
+open lens://extension/example-extension/
+```
+
+## Deregistering A Protocol Handler
+
+All that is needed to deregister a handler is to remove it from the array of handlers.
+
+## Routing Algorithm
+
+The routing mechanism for extensions is quite straight forward.
+For example consider an extension `example-extension` which is published by the `@mirantis` org.
+If it were to register a handler with `"/display/:type"` as its corresponding link then we would match the following URI like this:
+
+![Lens Protocol Link Resolution](images/routing-diag.png)
+
+Once matched, the handler would be called with the following argument (note both `"search"` and `"pathname"` will always be defined):
+
+```json
+{
+  "search": {
+    "text": "Hello"
+  },
+  "pathname": {
+    "type": "notification"
+  }
+}
+```
+
+As the diagram above shows, the search (or query) params are not considered as part of the handler resolution.
+If the URI had instead been `lens://extension/@mirantis/example-extension/display/notification/green` then a third (and optional) field will have the rest of the path.
+The `tail` field would be filled with `"/green"`.
+If multiple `pathSchema`'s match a given URI then the most specific handler will be called.
+
+For example consider the following `pathSchema`'s:
+
+1. `"/"`
+1. `"/display"`
+1. `"/display/:type"`
+1. `"/show/:id"`
+
+The URI sub-path `"/display"` would be routed to #2 since it is an exact match.
+On the other hand, the subpath `"/display/notification"` would be routed to #3.
+
+The URI is routed to the most specific matching `pathSchema`.
+This way the `"/"` (root) `pathSchema` acts as a sort of catch all or default route if no other route matches.

docs/getting-started/README.md

@@ -28,6 +28,28 @@ Review the [System Requirements](/supporting/requirements/) to check if your com
 
 See the [Download Lens](https://github.com/lensapp/lens/releases) page for a complete list of available installation options.
 
+After installing Lens manually (not using a package manager file such as `.deb` or `.rpm`) the following will need to be done to allow protocol handling.
+This assumes that your linux distribution uses `xdg-open` and the `xdg-*` suite of programs for determining which application can handle custom URIs.
+
+1. Create a file called `lens.desktop` in either `~/.local/share/applications/` or `/usr/share/applications` (if you have permissions and are installing Lens for all users).
+1. That file should have the following contents, with `<path/to/executable>` being the absolute path to where you have installed the unpacked `Lens` executable:
+    ```
+    [Desktop Entry]
+    Name=Lens
+    Exec=<path/to/executable> %U
+    Terminal=false
+    Type=Application
+    Icon=lens
+    StartupWMClass=Lens
+    Comment=Lens - The Kubernetes IDE
+    MimeType=x-scheme-handler/lens;
+    Categories=Network;
+    ```
+1. Then run the following command:
+    ```
+    xdg-settings set default-url-scheme-handler lens lens.desktop
+    ```
+1. If that succeeds (exits with code `0`) then your Lens install should be set up to handle `lens://` URIs.
 
 ### Snap
 
@@ -52,4 +74,3 @@ To stay current with the Lens features, you can review the [release notes](https
 
 - [Add clusters](../clusters/adding-clusters.md)
 - [Watch introductory videos](./introductory-videos.md)
-

integration/__tests__/app.tests.ts

@@ -2,23 +2,35 @@ import { Application } from "spectron";
 import * as utils from "../helpers/utils";
 import { listHelmRepositories } from "../helpers/utils";
 import { fail } from "assert";
-
+import open from "open";
+import { AbortController } from "abort-controller";
 
 jest.setTimeout(60000);
 
 // FIXME (!): improve / simplify all css-selectors + use [data-test-id="some-id"] (already used in some tests below)
 describe("Lens integration tests", () => {
   let app: Application;
+  let abortContoller: AbortController;
 
   describe("app start", () => {
-    beforeAll(async () => app = await utils.appStart(), 20000);
+    beforeAll(async () => {
+      app = await utils.appStart();
+    }, 20000);
+
+    beforeEach(() => {
+      abortContoller = new AbortController();
+    });
 
     afterAll(async () => {
       if (app?.isRunning()) {
         await utils.tearDown(app);
       }
     });
 
+    afterEach(() => {
+      abortContoller.abort();
+    });
+
     it('shows "whats new"', async () => {
       await utils.clickWhatsNew(app);
     });
@@ -28,6 +40,26 @@ describe("Lens integration tests", () => {
       await app.client.waitUntilTextExists("h2", "Add Cluster");
     });
 
+    /**
+     * skipping this for the time being until we can figure out why they are opening a second instace
+     * and seemingly bypassing the single instance lock
+     */
+    describe.skip("protocol app start", () => {
+      it("should handle opening lens:// links", async () => {
+        await open("lens://app/foobar");
+
+        await utils.waitForLogsToContain(app, abortContoller, {
+          main: ["No handler", "lens://app/foobar"],
+          renderer: ["No handler", "lens://app/foobar"],
+        });
+      });
+
+      it("should opening lens://app/preferences", async () => {
+        await open("lens://app/preferences");
+        await app.client.waitUntilTextExists("h2", "Preferences");
+      });
+    });
+
     describe("preferences page", () => {
       it('shows "preferences"', async () => {
         const appName: string = process.platform === "darwin" ? "Lens" : "File";