Plugin System

[tutman96]

As people want to build more and more features into the JetKVM ecosystem, being able to add additional subprocess executables that can communicate back with the main process will be important for maintaining scalability. I propose a plugin architecture to address these concerns.

The plugin architecture will be built off of subprocesses spawned by the main jetkvm_app process. Each plugin with have an RPC mechanism to talk back with the app process via JSON RPC, to maintain similar technology used other places in the system. This communication will happen with plugin-specific unix sockets created by the app process, and passed in as a JETKVM_PLUGIN_SOCK environment variable when the subprocess is spawned. The plugin should connect to this socket when spawned, and use it for communications with the main process.

Every plugin will start as a tar archive where the root contains a manifest.json file in the following format, with additional fields that could be added in the future for additional metadata.

{
  "manifest_version": "1",
  "name": "my-plugin",
  "version": "1.2.3",
  "description": "This is a really cool plugin",
  "homepage": "https://github.com/tutman96/my-plugin",
  "bin": "./my_plugin",
  "system_min_version": "0.35.0", // optional
}

Most importantly, the bin property describes the location of the binary to run as a subprocess for this executable. This binary should be bundled in the tar archive. Additional files can also be bundled in the archive, which will be accessible to the process relative to the root of the executable. How JetKVM discovers where to download these tar balls can be defined later, with the first implementation probably being a simple upload from the web ui, with later implementations potentially including a marketplace-style setup. The system_min_version (optional) defines the minimum version of the JetKVM that the plugin supports. If the plugin requires a newer version than what is currently running, the system should not attempt to start the plugin.

When a plugin starts up, it can optionally connect to JETKVM_PLUGIN_SOCK as a JSON RPC endpoint. The plugin should implement both a JSON RPC client and server, allowing bidirectional communication over the same socket. There should be at a minimum the getPluginSupportedMethods method implemented by the plugin, with getPluginStatus highly recommended.

Plugin Methods

getPluginSupportedMethods()

Initiated from jetkvm_app to the plugin to determine which RPC methods the plugin supports. Should return an object with a list of methods. The list must contain getPluginSupportedMethods to be a valid plugin.

{
  "supportedRpcMethods": [
    "getPluginSupportedMethods",
    "getPluginStatus",
  ]
}

getPluginStatus()

Initiated from jetkvm_app to the plugin to determine the readiness and health of the plugin. This rpc method may be called at any time and a response with the following parameters should be provided in a timely manor

{
  "status": "running", // "running", "loading", "pending-configuration", "error"
  "message": "" // Friendly text to show about the health of the plugin. For example, put error messages here, or information about configuration needed
}

getPluginConfiguration()

Called by jetkvm_app to determine what options to show to the user in the web-ui and how that maps back to configuration values. The payload consists of two main fields: "data" and "schema". The format of "schema" is to be determined in the future, but may be a small variation on JSON schema with extensions added to support automatic UI generation. The "data" field will be a JSON object opaque to the plugin system and directly editable in the web interface.

Plugins are responsible for persisting their own configuration if needed. An environment variable JETKVM_PLUGIN_WORKING_DIR will be provided to give the plugin a consistent and durable location to store files.

If this method is implemented, the updatePluginConfiguration method should also be implemented. If neither are implemented, then the UI won't provide any plugin-specific configuration options.

{
  "data": {
    "exampleConfig": 123
  },
  "schema": {
    // TBD
  }
}

updatePluginConfiguration(config: any)

Called whenever the plugin's configuration is updated through the WebUI. The payload consists of an opaque JSON object that can be managed by the plugin however it sees fit. The plugin should be responsible for handling the lifecycle of configuration changes gracefully without needing to be restarted.

[trevorstarick]

Additionally to subprocess, I wonder if WASM would fit the bill? We could load them via https://github.com/tetratelabs/wazero so no CGo dep compared to some of the other WASM libs.

[tutman96]

I do like WASM, just worry the barrier to entry would be too high for this use case. That being said, I think the interface looks very similar to subprocess, just instead of JSON RPC, you use native WebAssembly bindings. The plugin could define instead of a bin in the manifest to instead point to a wasm.

[ethanholz]

I think WASM would work very well, especially if you use something like extism. I’ve played with it quite a bit and it works surprisingly well, with little overhead. Using extism also allows for simpler support for supported plugin development kits from them.

[SuperQ]

I came across this thread which has some nice links to scripting plugin options and some benchmarks.

I also have some experience writing tooling in Starlark. Having Python-ish syntax, with the ability to easily wrap underlying Go functions makes for a nice way to build plugins without a lot of the downsides that things like WASM or external process management has.

[trevorstarick]

Regarding the manifest.json I think it would be useful include a version key for the manifest version as well as version for the plugin itself. This would be critical to make breaking changes. Additionally I think we should have a key for permissions so users can see what plugins might be using (although who knows what they're actually doing). The manifest.json for browser extensions might be reference doc for some good ideas.

[tutman96]

"permissions" is an interesting idea, but without something like process namespacing or selinux it's just a suggestion. Might make more sense for a WASM or scripting language type plugins in the future though. 👍 for the manifest_version. I'll add that

[trevorstarick]

I think it could be used for at least accessing the kvm resources (shared config, maybe inter-plugin networking, auth to certain resources), but yeah without any magic sandboxing, it's more of a nice thought than something actual concrete.

[Albirew]

maybe also adding an "update_url" pointing to a manifest containing the latest version number associated with min and max supported system version to allow it to be either kept, disabled or updated at each main FW update (alongside manual plugin update check)

{
  "manifest_version": "1",
  "name": "my-plugin", // may be useful for a "plugin center" like nextcloud's app center
  "description": "This is a really cool plugin", // same as over
  "1.2.3": {
    "version_url": "https://github.com/tutman96/my-plugin/releases/download/1.2.3/my-plugin-1.2.3.tar", // file download url
    "system_version_min": "0.35.0", // lowest supported version for this version
    "system_version": "0.35.0", // supported version
  },
  "0.1.8": {
    "version_url": "https://github.com/tutman96/my-plugin/releases/download/0.1.8/my-plugin-0.1.8.tar",
    "system_version_min": "0.34.0", // keep only last version for each system version for retro-compatibility
    "system_version": "0.35.0",
  },
}

[tutman96]

I'm trying to come up with a folder structure for the plugins. Right now everything is out of /userdata/jetkvm/plugins as the base, but want to keep this flexible enough for additional use cases.

At the base of the directory, there will be:

• uploads/ directory to hold the temporary archive uploads prior to them being extracted
• extracts/ directory containing all plugin extracts. In this folder there will be a folder for each plugin + version. The folder names will be generated such that uploading a newer version of a plugin doesn't overwrite the old one
• working_dirs/ will contain a list of directories, one for each installed plugin and which will be passed into the plugin with the JETKVM_PLUGIN_WORKING_DIR environment variable. In this directory will also be the relevant JETKVM_PLUGIN_SOCK
• plugins.json a json object storing the list of installed plugins, whether they are active or not, which version is active, and mappings of version numbers to their extract directories

When a plugin is uploaded it will land into uploads/ and then be extracted into extracts/. The user will have the option at that point whether or not to fully "install" the plugin but they will first be presented with information from the plugin's manifest. Once enabled, it will be marked as active in the plugins.json file and the subprocess manager will run/terminate the relevant processes. If the user decides to not install the plugin after reviewing the manifest, then the extraction will be deleted and the metadata removed from the plugins.json file.

[trevorstarick]

Should there be a version inside of the plugin dirs within working_dirs so a certain level of backwards compatibility is maintained?

[tutman96]

You mean like have versioned working_dirs? The thought is the working_dir stays the same when a plugin is updated, so I don't think that would work all that well...

[Nevexo]

I'd say it's better to let the plugin deal with migrations between versions.

Maybe the plugin could have migration scripts defined in it's manifest so if it's a major version bump, we can call the migration script before launching the plugin? That feels a bit scope-creepy though.

[tutman96]

Yeah, that all feels like stuff that would be plug-in specific that I’m not sure would be a ton of value add to the system. If a plugin cares about what version was running previously, it could always just write it’s own “last version” file to its own directory.

[offbyone]

Is there any reason the plugin data needs to be json? I can imagine a scenario where concurrent updates to the plugins (say, if an unattended upgrade is running at the same time as the user is installing a plugin) results in corruption there. Maybe it would make more sense to use sqlite for the plugin database.

[Nevexo]

An events system would be pretty useful too, like general system state changes etc.

Potentially in a pubsub form?

[SuperQ]

In general having a pubsub, maybe MQTT, would be a good idea. Probably a separate feature discussion.

[Nevexo]

Yeah, just generally a way of getting system events down to the plugins without too much effort on the plugin side, as some events will be coming from native, and some from the app, I think it's up to the plugin system to deal with distributing it down to the plugin processes.

[tutman96]

Simply having some rpc methods implemented by the plugin in the format "onX" would be sufficient. The advertisement of which methods the plugin supports would be an easy way to denote "subscribing". I like this idea.

[tutman96]

Actually, I am going to remove the requirement for RPC communication from the plugin system. If the plugin connects to the rpc endpoint, then it must implement the getPluginSupportedMethods method. getPluginStatus will be optional, but highly recommended. This should make plugin adoption a bit easier

[Nevexo]

Simple UI Framework

Out of scope for the current PR, and goal of the system, but would come in handy nevertheless.

I have two schools of thought for it:

• A UI-manifest is created (or extends manifest.json) to register UI components permanently (visibility could still be toggled, I guess)
• UI components are registered by RPC calls at run-time, either during init or as they're required, could also be de-registered if they're nolonger required due to configuration etc.

Once registered, clicking/interacting with controls could call an interactivity event RPC on the plugin with the ID of the control, and any payload data, such as text-box input, drop-down selection etc.

There would also need to be a way for plugins to request user input, for example, by calling an RPC that opens a modal requesting the user choose an option, or enter some text. The users response could then be sent back in the same way (by sending an interactivity event)

This would allow for plugins to be much more integrated into the system, but might blur the line between what should be a plugin, vs what should be upstreamed? Maybe not, just thinking as I type...

All in all, having the UI managed by the plugin infrastructure allows us the control the UI/UX for the user (keeping everything consistent between JetKVM's app, and the plugins) and avoids multiple plugins trying to build their own way of interacting with the plugin.

I think, if we were to do this, it'd be worth adding an extra action bar that appears as necessary, under the JetKVM action bar.

Multi-port Serial Extension UI Idea

Just a random idea that implements the UI:

An extension board that has multiple RS232 interfaces and connects to JetKVM with the extension port.

It has it's own plugin on the KVM that creates 4 buttons on the "extension action bar" to switch between the ports.
As it does, the plugin replays the scrollback buffer onto the page and tells the extenion board's MCU to start monitoring the port, and to forward any user input to it.

[Nevexo]

Oh and maybe be able to register controls into the touchscreen menu(s) too, but that requires more knowledge (and features) in jetkvm_native