From fa87d9edbdb109b194e2b0b926a6e9be48d2c04f Mon Sep 17 00:00:00 2001 From: Sebastian Malton Date: Fri, 21 May 2021 11:31:56 -0400 Subject: [PATCH] add some more docs, change names to handleRpc and invokeRpc Signed-off-by: Sebastian Malton --- docs/extensions/guides/ipc.md | 28 ++++++++++++++-------------- src/extensions/ipc/ipc-main.ts | 2 +- src/extensions/ipc/ipc-renderer.ts | 8 ++++++-- 3 files changed, 21 insertions(+), 17 deletions(-) diff --git a/docs/extensions/guides/ipc.md b/docs/extensions/guides/ipc.md index 91d811bdf0..6e81f87901 100644 --- a/docs/extensions/guides/ipc.md +++ b/docs/extensions/guides/ipc.md @@ -7,12 +7,12 @@ For example, if a user logs into a service that your extension is a facade for a IPC channels are blocked off per extension. Meaning that each extension can only communicate with itself. -## Types of IPC +## Types of Communication -There are two flavours of IPC that are provided: +There are two flavours of communication that are provided: -- Event based -- Request based +- Event based (IPC) +- Request based (RPC) ### Event Based IPC @@ -42,8 +42,8 @@ To register either a handler or a listener, you should do something like the fol `main.ts`: ```typescript -import { LensMainExtension, Interface, Types, Store } from "@k8slens/extensions"; -import { registerListeners, IpcMain } from "./helpers/main"; +import { LensMainExtension } from "@k8slens/extensions"; +import { IpcMain } from "./helpers/main"; export class ExampleExtensionMain extends LensMainExtension { onActivate() { @@ -59,9 +59,9 @@ Lens will automatically clean up that store and all the handlers on deactivation `helpers/main.ts`: ```typescript -import { Store } from "@k8slens/extensions"; +import { Ipc, Types } from "@k8slens/extensions"; -export class IpcMain extends Store.MainIpcStore { +export class IpcMain extends Ipc.IpcMain { constructor(extension: LensMainExtension) { super(extension); @@ -81,7 +81,7 @@ It should be able to just call `getInstance()` everywhere in your extension as n `renderer.ts`: ```typescript -import { LensRendererExtension, Interface, Types } from "@k8slens/extensions"; +import { LensRendererExtension } from "@k8slens/extensions"; import { IpcRenderer } from "./helpers/renderer"; export class ExampleExtensionRenderer extends LensRendererExtension { @@ -99,9 +99,9 @@ It is also needed to create an instance to broadcast messages too. `helpers/renderer.ts`: ```typescript -import { Store } from "@k8slens/extensions"; +import { Ipc } from "@k8slens/extensions"; -export class IpcMain extends Store.RendererIpcStore {} +export class IpcRenderer extends Ipc.IpcRenderer {} ``` It is necessary to create child classes of these `abstract class`'s in your extension before you can use them. @@ -112,10 +112,10 @@ As this example shows: the channel names *must* be the same. It should also be noted that "listeners" and "handlers" are specific to either `LensRendererExtension` and `LensMainExtension`. There is no behind the scenes transfer of these functions. -If you want to register a "handler" you would call `Store.MainIpcStore.handleIpc(...)` instead. +If you want to register a "handler" you would call `Ipc.IpcMain.handleRpc(...)` instead. The cleanup of these handlers is handled by Lens itself. -`Store.RendererIpcStore.broadcastIpc(...)` and `Store.MainIpcStore.broadcastIpc(...)` sends an event to all renderer frames and to main. +`Ipc.IpcRenderer.broadcastIpc(...)` and `Ipc.IpcMain.broadcastIpc(...)` sends an event to all renderer frames and to main. Because of this, no matter where you broadcast from, all listeners in `main` and `renderer` will be notified. ### Allowed Values @@ -128,4 +128,4 @@ This means that more types than what are JSON serializable can be used, but not Calling IPC is very simple. If you are meaning to do an event based call, merely call `broadcastIpc(, ...)` from within your extension. -If you are meaning to do a request based call from `renderer`, you should do `const res = await Store.RendererIpcStore.invokeIpc(, ...));` instead. +If you are meaning to do a request based call from `renderer`, you should do `const res = await Ipc.IpcRenderer.invokeRpc(, ...));` instead. diff --git a/src/extensions/ipc/ipc-main.ts b/src/extensions/ipc/ipc-main.ts index fcc97fc42f..c77709501b 100644 --- a/src/extensions/ipc/ipc-main.ts +++ b/src/extensions/ipc/ipc-main.ts @@ -52,7 +52,7 @@ export abstract class IpcMain extends IpcRegistrar { * @param channel The name of the RPC * @param handler The remote procedure that is called */ - handleIpc(channel: string, handler: (event: Electron.IpcMainInvokeEvent, ...args: any[]) => any): void { + handleRpc(channel: string, handler: (event: Electron.IpcMainInvokeEvent, ...args: any[]) => any): void { const prefixedChannel = `extensions@${this[IpcPrefix]}:${channel}`; ipcMain.handle(prefixedChannel, handler); diff --git a/src/extensions/ipc/ipc-renderer.ts b/src/extensions/ipc/ipc-renderer.ts index 2a60d95388..87c552a76d 100644 --- a/src/extensions/ipc/ipc-renderer.ts +++ b/src/extensions/ipc/ipc-renderer.ts @@ -32,7 +32,9 @@ export abstract class IpcRenderer extends IpcRegistrar { } /** - * Listen for broadcasts within your extension + * Listen for broadcasts within your extension. + * If the lifetime of the listener should be tied to the mounted lifetime of + * a component then putting the returned value in a `disposeOnUnmount` call will suffice. * @param channel The channel to listen for broadcasts on * @param listener The function that will be called with the arguments of the broadcast * @returns An optional disopser, Lens will cleanup even if this is not called @@ -49,11 +51,13 @@ export abstract class IpcRenderer extends IpcRegistrar { /** * Request main to execute its function over the `channel` channel. + * This function only interacts with functions registered via `Ipc.IpcMain.handleRpc` + * An error will be thrown if no function has been registered on `main` with this channel ID. * @param channel The channel to invoke a RPC on * @param args The arguments to pass to the RPC * @returns A promise of the resulting value */ - invokeIpc(channel: string, ...args: any[]): Promise { + invokeRpc(channel: string, ...args: any[]): Promise { const prefixedChannel = `extensions@${this[IpcPrefix]}:${channel}`; return ipcRenderer.invoke(prefixedChannel, ...args);