plugin

Overview ¶

This package contains the implementation of the plugin system for extending sinkholed.

A sinkholed plugin is just a go plugin. A go plugin should reside in the main package and implement at least the Plugin interface as defined in this package.

There are three kinds of plugins in sinkholed:

Downstream plugins: Plugins that recieve events. These plugins could be used to broadcast events to other services, store events etc.

Upstream plugins: Plugins that produce events to be consumed by downstream plugins. These plugins make use of the event channel passed into their Init method, piping all events they produce into it. This will cause the event to be consumed and processed by sinkholed.

Middleware plugins: Plugins that filter or change events. These act like middleware and can be used to drop events, causing them to not be processed or modify events to do actions such as adding extra metadata or removing unwanted data.

Any plugin can implment more than one or all of the previously described interfaces and sinkholed will automatically figure out what capability the plugin has. This means that a single plugin can act as an upstream, downstream and milddleware plugin all at once.

To load a plugin, define a configuration object in the "Plugins" map in the sinkholed config file, using the plugin file name without the extension plugin as the key. Example:

Plugins:
  "pluginName":
    ConfigVariable: config value

The configuration object (stored in the main sinkholed config file in the "Plugins" map) will be passed to the plugin Init function as a *viper.Viper config object. Included in this map will also be two extra values: `LogPath`, which is the path to be used for the log file, and `LogLevel`, which is the log level to use. This can be overridden if you provide a value for LogPath in your plugin's config.

An example plugin is shown below:

package main

import (
    log "github.com/sirupsen/logrus"

    "github.com/spf13/viper"

    "github.com/scrapbird/sinkholed/pkg/core"
    "github.com/scrapbird/sinkholed/pkg/plugin"
)

type demo struct {
    plugin.Plugin
    cfg *viper.Viper
    downstream chan *core.Event
}

func (p *demo) Init(cfg *viper.Viper, downstream chan *core.Event) error {
    log.Println("Initializing demo plugin")
    p.downstream = downstream
    return nil
}

func (p *demo) Halt() error {
    return nil
}

func (p *demo) Inbox(event *core.Event) error {
    log.Println("New event:", event)
    return nil
}

// Export the plugin
var Plugin demo

To compile this plugin:

go build -buildmode=plugin -o main.so main.go