Kuzzle's Plugin Engine

Our prepackaged multi-feature backend solution will meet basic project requirements, but in some cases you may want to implement your own business logic.

For example, imagine you are developing a mobile application that accesses a third-party payment platform, such as Braintree, through this third-party's API. For security reasons, you will want to avoid accessing the third-party's API directly from the mobile device. Also, you will not want users to purchase more items than are currently in stock, so your backend will need to monitor what has been purchased. To achieve all this, you will want to develop a custom Plugin that lets Kuzzle communicate directly with the third-party payment platform.

Kuzzle's Plugin Engine is a powerful feature that ensures that Kuzzle meets any project requirement:


Plugins

Plugins are used to extend Kuzzle's functionalities. They are loaded into Kuzzle during startup and share its execution thread. A plugin can add the following components:

Hooks: add an asynchronous listener that performs operations triggered by data events. When the event occurs, the data is sent to the listener and Kuzzle continues its process without waiting for the listener to complete.

Example - "Write a log to a third-party logging service every time a document is deleted". The Logger Plugin (shipped with Kuzzle) uses this feature to log all the data-related events.

Pipes: add a synchronous listener that performs operations triggered by data events. Multiple synchronous listeners can be chained sequentially. When the event occurs, the data is passed through the series of synchronous listeners, each modifying the input data and returning the result to the next listener. Kuzzle waits until the last listener completes and returns its data. If any listener returns a standard error, it will interrupt the Kuzzle lifecycle, and the thrown error will be used as a response by Kuzzle.

Example - "Compare the ordered quantity with the available stock and return an error if the amount of ordered items exceeds the amount in stock".

Controllers & Routes: add a route to expose new entries in the API.

Example - "Expose a checkout API endpoint that handles a third-party payment process".

Strategies: add an authentication strategy to identify and authenticate users.

Example - "Enable OAuth based authentication in Kuzzle" Kuzzle Community Edition ships with the Local Strategy Plugin and thanks to PassportJS, more than 300 authentication strategies are readily available.

Protocols

Protocols add extended networking capabilities to your Kuzzle installation. These are useful if you need to handle various transport protocols.

Example - "Allow Kuzzle to interact with XMPP-oriented services" Kuzzle Community Edition ships with the MQTT Protocol.


Installing a Plugin

To install a plugin, you need to make it accessible in the plugins/enabled folder of your Kuzzle installation.

A common practice is to first copy the plugin to a plugins/available folder, and then creating a symbolic link from that folder to the plugins/enabled folder. This way, you can easily enable and disable a plugin just by creating or deleting a symbolic link, respectively.

Prior to loading the plugin into Kuzzle, you will need to load all of the plugin dependencies by running npm install from within the plugin folder.

To demonstrate, we are going to install the Plugin Boilerplate, a plugin example that uses all features available to a plugin.

Go to the Kuzzle installation folder and type:

# Open plugins/available folder
cd plugins/available

# Download Plugin to plugins/available folder
git clone https://github.com/kuzzleio/kuzzle-core-plugin-boilerplate.git

# Install the Plugin dependencies
cd kuzzle-core-plugin-boilerplate
npm install # add --unsafe-perm if installing from inside a docker container

# Open plugins/enabled folder
cd ../../enabled

# Creata the symbolic link from the enabled folder to the available folder
ln -s ../available/kuzzle-core-plugin-boilerplate .

# Restart Kuzzle to reload Plugins

Once Kuzzle has restarted, check the server information at http://localhost:7512/?pretty=true to confirm that the plugin has been installed. You should now see the kuzzle-core-plugin-boilerplate Plugin entry:

{
  "...": "...",

  "result": {
    "serverInfo": {
      "kuzzle": {
        "plugins": {
          "kuzzle-core-plugin-boilerplate": {
            "name": "kuzzle-core-plugin-boilerplate",
            "hooks": [
              "document:beforeCreateOrReplace",
              "document:beforeReplace",
              "document:beforeUpdate",
              "core:overload"
            ],
            "pipes": [
              "document:beforeCreate",
              "realtime:beforePublish"
            ],
            "controllers": [
              "kuzzle-core-plugin-boilerplate/myNewController"
            ],
            "routes": [
              {
                "verb": "get",
                "url": "/kuzzle-core-plugin-boilerplate/say-something/:property",
                "controller": "kuzzle-core-plugin-boilerplate/myNewController",
                "action": "myNewAction"
              },
              {
                "verb": "post",
                "url": "/kuzzle-core-plugin-boilerplate/say-something",
                "controller": "kuzzle-core-plugin-boilerplate/myNewController",
                "action": "myNewAction"
              }
            ],
            "strategies": [
              "dummy"
            ]
          }
        }
      }
    }
  }
}

Note that the plugin description above contains a property for each plugin component:

  • hooks asynchronous operations that depend on data-related events
  • pipes synchronous operations that depend on data-related events
  • controllers list of exposed actions in the API
  • routes list of exposed actions in the REST API
  • strategies list of exposed authentication strategies

Installing protocols

The steps to install a new protocol are exactly the same than for plugins, except that you have to use the protocols/ directory, instead of the plugins/ one.

For instance, to install the MQTT protocol:

# In Kuzzle's directory:
cd protocols/available

git clone https://github.com/kuzzleio/protocol-mqtt.git

# Install the protocol's dependencies
cd protocol-mqtt
npm install # add --unsafe-perm if installing from inside a docker container

# Open plugins/enabled folder
cd ../../enabled

# Creata the symbolic link from the enabled folder to the available folder
ln -s ../available/protocol-mqtt .

# Restart Kuzzle to reload protocols

Managing Plugins

To learn more about how to manage or configure plugins, please check our Plugin Reference Documentation.


Going Further

To get more insight into how plugins work, please refer to the Plugin Reference.

Here is a list of official plugins: