Introduction
Golem Plugins provide ways to extend the functionality of Golem without having to modify the core codebase. Plugins can be installed to both the open-source and the hosted versions of Golem.
This page introduces the types of plugins Golem supports and explains their lifecycle.
Plugin support is experimental and not fully available in Golem 1.1 yet. The next release will include stronger guarantees, UI support and better documentation and examples.
Types of plugins
Golem supports the following types of plugins:
- Component transformer plugins can alter an uploaded component when it gets uploaded to Golem
- Oplog processor plugins can observe running workers
Component transformer plugins
Component transformer plugins are external web services providing a HTTP endpoint that receives a WASM component and returns a transformed WASM component. The most common use case for this type of plugin is to use component composition to achieve one of the following goals:
- Replace one or more of the host interfaces provided by Golem. For example a component transformer plugin may implement the WASI KeyValue store interface for a component by connecting to a third party database, instead of using the one provided by Golem.
- Wrap the host interfaces provided by Golem. In this case the adapter the plugin composes the uploaded component with both imports and exports the same interfaces, and by that wraps Golem's implementation for example to publish metrics or perform logging.
- Extend the provided interface of the component by exporting additional invokeable functions.
Oplog processor plugins
Oplog processor plugins are special golem workers implementing the golem:api@1.1.0/oplog-processor interface. These plugins are instantiated and by Golem, and got periodically invoked with oplog entries - a journal of operations performed by workers where the plugin is installed.
Oplog processor plugin support is experimental. The final version will guarantee exactly-once semantics for processing the oplog of the workers, which means that if the plugin is installed and activated for a worker, we guarantee that the plugin will receive all of the oplog entries of that worker (even from before the plugin was acitve), and each entry will be only sent exactly once. This guarantee is not implemented yet.
Plugin configuration
Plugins can have configuration in the form of key-value pairs, which are customizable for each plugin installation. Golem sends these configuration values to the plugins when they are invoked.
Plugin lifecycle
Plugins are first defined using Golem's Plugin API (using the REST API, CLI or the Console). Each defined plugin is identified by a name and a version. In Golem Cloud plugins are defined per account.
Defining a plugin does not immediately make that plugin used by Golem. To make use of a plugin, it must be installed to a component. This can be done either when a component is created, or later using the Component API. In Golem Cloud plugins can also be installed to projects, in which case each new component created in the given project will have those plugins installed.
Installing a plugin to a component creates a new component version, similarly how updating a component's WASM file does. This guarantees that already running workers are not affected by the plugin installation process. To make an existing worker use of an installed plugin, the worker must be updated to the new component version.
Oplog processor plugins can also be activated and deactivated on a running worker dynamically using the Worker API. This is an advanced feature which allows the user to temporarily pause an effect of a plugin for a given worker.