Documentation

Plugins

Express Gateway v1.2.0+ comes with a plugin framework used to extend the Express Gateway core. The plugin framework enables anyone to take Express middleware and integrate them into Express Gateway as plugins. Express Gateway provides a declarative way to take advantage of Express middleware to be driven centrally and executed dynamically.

Note: Existing policies within the Express Gateway core will be eventually refactored out of the core into Express Gateway plugins using this framework.

Plugin Structure

An Express Gateway plugin contains entities and allows event subscription. You can think of a plugin as a container of Express Gateway entities that extend the core and by adding entities and providing event handlers.

In the first iteration of the plugin framework, the following entities are supported:

• Policies
• Conditions
• Custom routes and middleware for admin and gateway servers

For all extension points under consideration please refer to the Express Gateway Plugin Specification.

The plugin framework exposes an Event Bus and can react to events in the Express Gateway lifecycle.

Automated Plugin Installation

Plugins are bundled as Node modules and distributed through npm. The Express Gateway CLI is used to install and configure plugins.

Installed plugins are declared in the system.config.yml and are then ready to be used. Express Gateway CLI is a convenient way to install and enable plugins. eg plugin install __name__ Plugins CLI commands

Example

The Express Gateway Plugin Example has a npm package name of express-gateway-plugin-example. After installing the example plugin, the system.config.yml will contain a new entry for the example plugin under the plugins as shown:

plugins:
   example: # "express-gateway-plugin-example"
      param1: 'global per plugin param1'

Parameters for plugins that are specified within this section are global to the entire gateway instance.

Manually Plugin Installation

Plugins can also be installed manually by following the steps outlined below:

1. npm install __name__ --save
2. open config/system.config.yml
3. find plugins: section
4. add your plugin name under it
5. provide global plugin parameters (if applicable)

Plugins not located on NPM

In the rare case when a plugin is not on NPM (this might happen in case you have a private code repository), you can specify the exact entrypoint using the package property of the specific plugin section:

plugins:
   example: # "express-gateway-plugin-example"
      param1: 'global per plugin param1'
      package: '../manifest.js'

Plugin Naming Convention

Express Gateway will load pugins by convention using the prefix express-gateway-plugin- within the npm package module name. Plugins that do not follow this convention can still be loaded by specifying the package name within the package property.

Example

The Acme Corp SSO Plugin has a npm package name acme-corp-sso-eg-plugin and resides on a private npm registry

After installing the plugin, the system.config.yml will contain the following:

plugins:
    acme-sso:  # the plugin name is specified within the plugin manifest
        package: 'acme-corp-sso-eg-plugin'
        # parameters required by plugin
        param1: 'p1'
        # other parameters

Developing a plugin

Express Gateway is a thin layer on top of ExpressJS Node.JS framework and uses a lot of concepts from it. So it is good to have some idea of it, especially the Middleware

To understand when different parts of plugin are registered and loaded check the Express Gateway Boot Sequence explanation

All extension points are covered in the Development Guide

Here is Example Plugin with all extension points utilized

And if you want to write only custom policy this is Policy Developing Guide