# Anatomy of a plugin

This page describes the general anatomy of a plugin, and its (simplified) execution in Hansken.

## The plugin itself

Each plugin must implement two methods:

* `pluginInfo()`: This method returns information about the plugin.
* `process()`: This method performs the extraction task of the plugin.

Lets dive a bit deeper into these methods in the next sections!

### The method `pluginInfo()`

The `pluginInfo()` method returns a `PluginInfo` object. Hansken needs this object to be able to know the capabilities
of the plugin, and to show the plugin in the list of tools. The most important fields that must be set on `PluginInfo`
are the following:

| `id`          | The identifier of the plugin. This will be used as a unique name for the plugin Hansken.            |
| `description` | A description of the plugin that is shown in Hansken.                                               |
| `author`      | The author of the plugin that is shown in Hansken.                                                  |
| `license`     | The type of license of the plugin that is shown in Hansken.                                         |
| `matcher`     | This matcher is used by Hansken to determine which Traces are sent to the Plugin during extraction. |

### The method `process()`

During extraction, Hansken calls the `process()` method for every matching trace. The `matcher` attribute of
the `PluginInfo` is very important as it determines which traces will be sent to the `process` method.

Although the plugin developer is free to program whatever seems useful, the following tasks are typically performed
within the `process()` method:

* Creating child-traces
* Reading trace properties
* Adding trace properties
* Reading the data that the Trace represents
* Writing data on a Trace

Depending on the type of plugin that is implemented, different functionality is available in the `process()` method.
See [Plugin Types](plugin_types.md) for more details.

## The execution in Hansken

This describes the process of running a plugin from the perspective of Hansken. The perspective of the user is described
in [Hansken Extraction Plugins](extraction_plugins.md).

### Plugin discovery

Hansken manages a list of tools that can be used in extractions. The available plugins must be added to this list so
that the user can select them. To accomplish this, Hansken scans the Docker registry for docker images that are plugins.
Each image is started up, and a call is done to its `pluginInfo()` method. If the call resulted in a valid `PluginInfo`
object, the Extraction Plugin is added to the list of tools visible to users. After the `PluginInfo` is retrieved, the
docker image is shutdown again.

### Starting an extraction

Hansken checks if any plugins are selected by the user that started the extraction. For each selected plugin, at least
one docker image will be started. See [Kubernetes autoscaling](kubernetes_autoscaling.md) for more details on expanding
the number of instances for each plugin.

### Extracting

During an extraction, Hansken will iteratively loop through all selected tools, including Extraction Plugins. For each
trace that matches on a tool, Hansken will call its `process` method. For Extraction Plugins, this means that
the `process` method is called via the gRPC protocol. The trace to be processed is sent over gRPC to the plugin, and any
other communication between Hansken and the Extraction Plugin (like created properties and child traces, search requests
and written data) are done using gRPC.

### Finishing an extraction

At the end of an extraction, Hansken will stop all associated plugins.