Skip to content

Plugins

Jump to bottom
apryamostanov edited this page Apr 9, 2019 · 28 revisions

Pigeon Plugins

This page is about Pigeon Plugins - user-defined programmatical extensions of Pigeon.

For general information about Pigeon application please refer to Pigeon main wiki page.

❗ Refer to a collection of open source Pigeon Plugins for quick pick-up on SDK.

Introduction

Pigeon itself defines a mechanism of HTTP message distribution.

However it does not define neither incoming nor outgoing message formats.

This is left to the end-users - to implement their own propitiatory formats using a simple Pigeon Plugin SDK (Java/Groovy-based).

Furthermore - Pigeon behavior as a Web Application can also be extended using Plugins.

❇ You don't need IDE or any other special tools to develop or modify Pigeon Plugins. Even standard notepad.exe is enough. Once saved - the changes apply automatically - you don't even have to restart Pigeon.
The goal is to enable rapid development and deployment of the changes - if you want you can change Plugin code directly on Production system - and the changes will reflect immediately.
There are such situations... The Pigeon takes it with an understanding.

Pigeon Plugins SDK

Each Pigeon Plugin is nothing more than just a file with .groovy extension, containing a Groovy script or a Java code (compiled by Groovy Compiler).

By the SDK we mean a number of JAR modules already available to be used in Plugin code, as well as Plugin Parameter Binding - the input data "arguments" passed to the Plugin each time Pigeon runs it.

Please refer to Pigeon Gradle Build Scan for convenient view on the list of available classpath modules (JARs):

❇ Pigeon Build Scan dependency list

In short by default the following modules are available to be used in 'Pigeon Plugins' code:

  • Groovy
  • Spring Boot
  • Jackson Databind (JSON and YAML - via SnakeYaml)
  • BlackBox - logging code automation
  • Bobbin - SLF4J logger

Additionally JARs deployed by the user in the lib directory are also available on the Classpath (e.g. MySQLConnector or any other user-selected JARs).

Runtime data (arguments) plugin binding

Pigeon passes several objects serving as arguments to the plugin upon its execution.

Generally the binding objects are accessed as follows from within the plugin code:

Object pluginArgument = binding.getVariable("pluginArgumentName")

❇ binding is pre-defined Groovy script global variable.

The available data binding arguments are specific to individual Plugin Types and details can be found in the below sections.

Logging

The Pigeon takes amazing care about logging - including the User-defined Pigeon Plugins!
In practice the users writing or modifying Pigeon Plugins do not have to write any logging code - they just need to annotate their classes or methods with @BlackBox annotation - and the logging code will be added automatically using the Carburetor configuration.
That's it - the logs will start to output according to Bobbin configuration.

Plugin Types

Pigeon Plugins are placed on a file system according to the Pigeon Paths Configuration in application.properties:

pigeonOutPluginsDir=./conf/plugins/output/
pigeonInputPluginsRestDir=./conf/plugins/input/rest/
pigeonInputPluginsHttpDir=./conf/plugins/input/http/

The relative directory structure of Plugins normally is the following:

  • {Pigeon Home}
    • plugins
      • input
        • http
        • rest
      • output

Input Plugins

Input Plugins are used to extend the Pigeon functionality as a Web Application, i.e. acting as a Server.

As the primary use case of Pigeon is acting as a Client connecting to external endpoints - it is a safe assumption to say that Input Plugins server mainly the the supplementary internal role, not being critical for the Pigeon mission on Production.

The typical examples of such expansion are:

  • Self Test plugins
  • Mock Service plugins

Each input plugin becomes available as a URL resource (with a same name as Plugin except for the file extension) on the Pigeon URL context path:

<http(s)>://<pigeon ip>:<pigeon port>/<pigeon context path>/plugins/input/<input plugin type>/<plugin name excluding file extension>

The resource name in the end of URL corresponds to Plugin Name - and to its file name on the disk (however file name has .groovy extension which is removed from the resource name.

❗ Currently only POST and GET HTTP Methods are supported in all types of Input Plugins.

Input HTTP Plugins

Input HTTP Plugins are a generic form of Input Plugin and allow full manual control within the plugin over both HTTP Request and Response, including content type and response body.

However Input HTTP Plugins lack automatic content type negotiation feature of Input REST Plugins.

Use Input HTTP Plugins when you are exactly know the supported content types that are going to be used as well the expected response body format, for example SMS Gateway "HTTP API" mocking or forwarding:

Input HTTP Plugins become available as URL resources on the below path:

<http(s)>://<pigeon ip>:<pigeon port>/<pigeon context path>/plugins/input/rest/<plugin name excluding file extension>

For example: http://localhost:8089/pigeon/plugins/input/http/MOCK_SMSGLOBAL_HTTP

Input HTTP Plugins Parameters Binding
Variable name Class Description
httpServletRequest javax.servlet.http.HttpServletRequest Actual HttpServletRequest with the HTTP Request data such as Headers, URL
httpServletResponse javax.servlet.http.HttpServletResponse A modifiable response that will be returned to the Client calling this Input Plugin.
You can modify HTTP Response Headers and Body using this variable.
inputMessageRepository io.infinite.pigeon.springdatarest.repositories.InputMessageRepository Using this variable you can save and query Pigeon Input Messages
requestBody String Use this variable to reliably access the complete HTTP Request Body as a String.

Input REST Plugins

Output Plugins

Changing and adding Plugins

Restart

Clone this wiki locally