Skip to content

Plugins

consortium.framework.plugins

The plugins framework provides the building blocks for defining server plugins.

A plugin is a long-lived background component that runs alongside the server, implemented by subclassing BasePlugin. Plugins are used to integrate with external services, schedule recurring work, or otherwise augment server behavior, and are driven through the standard component lifecycle hooks.

BasePlugin()

Bases: ComponentMetadata, ComponentLifeCycle

Base class for implementing custom server plugins in the Consortium framework.

Plugins run as long-lived background components alongside the server, performing tasks such as integrating with external services, scheduling work, or augmenting server behavior. All custom plugins must inherit from this class and implement the required lifecycle hook methods.

Attributes:

Name Type Description
plugin_id UUID

Unique framework-wide identifier for this plugin instance, generated as a UUID4.
name str | None

Human-readable name for identifying this plugin.
description str

Brief description of the plugin's purpose and functionality.
version str | None

Version of this plugin, specified as a PEP 440 version string.
compatible_framework_version str | None

Framework version specifier defining which versions of Consortium this plugin is compatible with.
authors set[str] | None

Set of authors associated with this plugin.
component_dependencies set[str] | None

Version-pinned dependencies on other framework components, defined using PEP 440 specifiers.
third_party_dependencies set[str] | None

Third-party library dependencies required for this plugin to function.
autostart bool

Whether the framework should start this plugin automatically on server startup. Defaults to True.
environment SimpleNamespace

Namespace for storing plugin-specific state shared across lifecycle hook calls without naming conflicts.
logger Logger

Plugin-specific logger instance, automatically tagged with the plugin's name and ID for easy identification in logs.
event_logger EventLogger

Plugin-specific event logger used to record structured, client-facing lifecycle events (successes, failures, informational messages, progress updates). Entries are optionally mirrored to the plugin's system logger.

autostart = True class-attribute instance-attribute

plugin_id = uuid.uuid4() instance-attribute

environment = types.SimpleNamespace() instance-attribute

logger = loguru.logger.bind(logger_name=f'Plugin - {self}', logger_type=(LoggerType.PLUGIN_LOGGER)) instance-attribute

event_logger = EventLogger(event_log=(EventLog(subject_id=(self.plugin_id))), system_logger=(self.logger)) instance-attribute

on_started() async

Called once immediately after the plugin enters the running state.

on_running() async

Called on each iteration of the plugin's main loop while running.

on_stopped() async

Called once after the plugin has been successfully stopped.

on_completed() async

Called when the plugin's main loop exits normally without being stopped.

on_cancelled() async

Called once after the plugin run has been cancelled.

on_errored(error) async

Called when a runtime error occurs during the plugin's execution.

Override to add custom error handling or alerting logic in addition to or instead of the default behaviour of recording the error as a failure event.

Parameters:

Name Type Description Default
error PluginRuntimeError

The runtime error describing what went wrong during plugin execution, including the error message and any diagnostic detail.

 required

on_fatal(exc, phase) async

Called when an unhandled exception causes the plugin to terminate fatally.

Override to add custom alerting or cleanup logic when a fatal failure occurs. The default implementation logs the full traceback at error level.

Parameters:

Name Type Description Default
exc Exception

The unhandled exception that triggered the fatal shutdown.

 required
phase ComponentLifeCyclePhase

The lifecycle phase during which the fatal exception occurred (starting, running, stopping, cancelling, or error handling).

 required

start() async

Start the plugin and begin executing its main loop.

Raises:

Type Description
PluginAlreadyRunningError

If the plugin is already in a running state.
PluginStartError

If the plugin fails to start due to a lifecycle error.
PluginFatalError

If an unhandled exception escapes on_started, leaving the plugin in a fatal state. The original exception is chained onto it as __cause__.

stop() async

Stop the plugin and exit its main loop.

Raises:

Type Description
PluginNotRunningError

If the plugin is not currently running.
PluginStopError

If the plugin fails to stop cleanly.
PluginFatalError

If an unhandled exception escapes on_stopped, leaving the plugin in a fatal state. The original exception is chained onto it as __cause__.

cancel() async

Cancel the plugin run immediately.

Raises:

Type Description
PluginNotRunningError

If the plugin is not currently running.
PluginFatalError

If an unhandled exception escapes on_cancelled, leaving the plugin in a fatal state. The original exception is chained onto it as __cause__.

to_json(limit=10, offset=None)

Serialize the plugin's metadata and current state to a JSON-compatible dictionary.

Parameters:

Name Type Description Default
limit int

Maximum number of event log entries to include.

 10
offset int | None

Sequence offset to start the event log window from. If None, the tail (most recent entries up to limit) is returned.

 None

Returns:

Type Description
dict[str, JsonValue]

A dictionary containing the plugin ID, label, name, description, version,
dict[str, JsonValue]

framework compatibility, authors, dependencies, autostart flag, status, and
dict[str, JsonValue]

event log.

to_json_reference()

Serialize a compact reference to this plugin.

Returns:

Type Description
dict[str, JsonValue]

A dictionary containing only the plugin ID, label, and name, suitable
dict[str, JsonValue]

for embedding as a lightweight foreign key reference in other JSON objects.