[RFC] Plugin system

[Tomaž Muraus]

Hello,

Plugins will be part of the next release and here is my proposal for the plugin system / interface.

Plugin definition

Plugin is a self-sustaining package which adds extra functionality to the Cast agent. Plugin packages mirror NPM package format which means they can be distributed using NPM and published on the NPM registry.

Plugins can be placed in an arbitrary directory on the agent server, but the user must specify plugin root directory and an object with the enabled plugins and their settings in the Cast config file.

Plugin part of the config file could look something like this:

"plugins": {
"root": "/data/cast-plugins/", // can be a relative or an absolute path. If it's relative,  it is joined with the Cast data directory
"enabled": {
"github": {
"username": "foobar",
"api_token": "…"
}
}
}

 

Resources and functionalities which plugins can provide / expose

• services - a long running services which starts on the agent startup when all the "core" services have been started
• HTTP endpoints / REST interface - a custom HTTP endpoint. Plugin HTTP endpoints can be accessed at /<api version>/plugins/<unique plugin slug>/...
• Jobs - jobs which are used by the plugin

For example, a Github plugin could provide a single HTTP endpoint which Github Webhook would hit. Hitting this endpoint would trigger a bundle creation and an application which is hosted in this git repository would be upgraded.

Plugin directory structure

plugin_name/
plugin_name/package.json -> contains all the required NPM fields and some Cast specific stuff. name field in this file should always be prefixed with "cast"
plugin_name/lib/core.js -> core plugin functionality
plugin_name/lib/services/ -> contains services
plugin_name/lib/http/ -> contains http api endpoints
plugin_name/lib/jobs/ -> contains jobs

Plugin specific settings in plugin package.json

• services - a list of services which plugin provides
• agent_version - a string which specifies minimum and maximum version of the Cast Agent with which this plugin will work (e.g. ">= 0.1.0 <= 0.2.0")
• settings - an object which specifies all the available settings for this plugin and the setting types (string, number, boolean).

Installing, enabling, disabling and removing plugins

To make the whole process easier we should probably also add "plugins" command to the client. This will be especially useful in Cast cluster version when user will want to distribute plugins to multiple servers.

"plugins" command would have the following sub-commands:

• install <path to the plugin tarball file|url to the plugin tarball file> - installs a plugin
• update <plugin name> <path to the plugin tarball file|url to the plugin tarball file> - updates an existing plugin to a new version
• remove <plugin name> - removes the plugin
• enable <plugin name> - enables a plugin
• disable <plugin name> - disables a plugin
• export <plugin name> - exports the plugin settings

Open questions

We have already discussed a bit about this on the IRC channel, but there are still many open questions so feedback is more than welcome.

I will also try to post a sample plugin soon which will give you more context and details about some of the plugin APIs.

Thanks,
Tomaz

[Tomaž Muraus]

Another things

Each plugin should expose all of it's available and currently configured settings over a special HTTP endpoints - GET /plugins/<plugin_name>/settings

Actual JSON response should look something like this:

{
  "available": {
    "username": {
      "type": "string"
    },
    "api_token": {
      "type": "string"
    },
    "project_names": {
      "type": "array"
    }
  },
   "configured": {
      "username": "user",
      "api_token": "barfo123456",
      "project_names": ["project1", "project2"]
    }
}