Plugin system proposal

[advplyr]

The following is a proposal to support plugins in Abs. Corresponding draft PR

Why

Users often request features that will likely not be a part of the core project for various reasons. This plugin system would allow extending Abs functionality to support those features.

See these tagged issues for examples of feature requests that might be possible to build with this plugin system.

How

Plugins are folders that are placed in /metadata/plugins.
The folders require 2 files (but may contain others):

1. index.js - Entry script
2. manifest.json - Includes all the details about the plugin like name, description, etc. as well as config & extensions (explained below)

Plugins are loaded and validated on server startup.

Each plugin will have a record in the plugins table. The primary purpose of this table is to allow plugins to store any config data it may need. The config data is stored in a JSON column.

index.js

Example minimal index.js file

Requires an init function that is called on server startup.
Supports optional onAction and onConfigSave functions.

Each function is passed a context object that contains (so far):

audiobookshelf/server/managers/PluginManager.js

Lines 13 to 21 in c8682c8

	* @typedef PluginContext
	* @property {import('../Logger')} Logger
	* @property {import('../Database')} Database
	* @property {import('../SocketAuthority')} SocketAuthority
	* @property {import('../managers/TaskManager')} TaskManager
	* @property {import('../models/Plugin')} pluginInstance
	* @property {import('../managers/ShareManager')} ShareManager
	* @property {import('../managers/RssFeedManager')} RssFeedManager
	* @property {import('../managers/PodcastManager')} PodcastManager

pluginInstance is the Sequelize Plugin model instance for that plugin. This allows for easily reading and updating its config.

In this example init function the plugins config is updated using the pluginInstance and a Sequelize hook is setup to listen for updates to the mediaProgresses table.

audiobookshelf/test/server/managers/plugins/Example/index.js

Lines 6 to 23 in c8682c8

	module.exports.init = async (context) => {
	// Set default config on first init
	if (!context.pluginInstance.config) {
	context.Logger.info('[ExamplePlugin] First init. Setting default config')
	context.pluginInstance.config = {
	requestAddress: '',
	enable: false
	}
	await context.pluginInstance.save()
	}
	context.Database.mediaProgressModel.addHook('afterSave', (instance, options) => {
	context.Logger.debug(`[ExamplePlugin] mediaProgressModel afterSave hook for mediaProgress ${instance.id}`)
	handleMediaProgressUpdate(context, instance)
	})
	context.Logger.info('[ExamplePlugin] Example plugin initialized')
	}

manifest.json

Example manifest.json

The structure for this file is still a work in progress but the idea is that this file fully describes the plugin.

UI Extensions

The manifest extensions array is a way to extend the Abs web client UI.
The purpose is to allow for triggering actions on specific pages and/or for specific entities.

Some key properties in the extension definition:

• name - used to identify the extension in the onAction function
• target - defines what page and where the extension is going
• label - shown to the user in the gui
• prompt - optionally defined to show a modal to collect additional information or to just confirm the action

The only extension allowed so far requires the target property of the extension to be item.detail.actions. This means the extension is added to the context menu on the item details page.

When the extension is pressed it will either a) load a prompt modal or b) make an API request that calls the plugins onAction function.

This example extension has prompt defined with formFields to collect information.

The plugin receives the form input values in a data object. Example onAction

Extensions can be restricted to only show for users with a certain account type using the restrictToAccountTypes array property.

Config

The manifest config object is used to populate the plugins config page that will be available in the web client.

In this example config 2 form fields are specified, a text input and a checkbox.

Note: UI is currently using default HTML elements and will be updated to use Abs themed inputs.

When the config page is saved it makes an API request that will call the plugins onConfigSave function. Example

The config page also links to the documentationUrl and repositoryUrl defined in the manifest.json.

This page might be further expanded on to show the plugin version, changelog, etc.

Localization

This is undecided and not fully utilized in the demo. The idea is to support a localization object in the manifest so that plugins can supply translations for all of their text.

Enabling plugins

Plugins will be opt-in (via environment variable) until/if the plugin system is stable.
Set env variable ALLOW_PLUGINS to 1 or if running locally the dev.js file can export AllowPlugins: true

Once enabled, plugins are loaded on server startup and the config page will include the Plugins nav item.

Test with the Report for Review plugin

To test the plugin system checkout the branch in the PR: #3745

Download the latest zip file for the Report for Review plugin here and extract the contents in /metadata/plugins. (this example plugin was inspired by the feature request #3572)

Note: The name of the folder for the plugin must match the name in the manifest.json file. This will probably change to prevent collisions but the idea is that the /metadata/plugins folder clearly shows which plugins are downloaded and they aren't obfuscated.

After starting the server with the Report for Review plugin you will see 2 new menu items on the item details page if you are an admin and 1 new menu item if you are a user.

You will also find the extension config page available on the plugins config page.