FOCA plugins

Plugins for gateway services built with FOCA, such as proTES (GA4GH TES) and, later, proWES (GA4GH WES), brought to you by ELIXIR On-Cloud. Gateways accept requests from clients and forward them to backends; plugins process these requests on the way: they change tasks (e.g., add inputs or executors), reject them by policy, choose and order the backends, and adapt each forwarded request.

FOCA's plugin engine (foca.plugins) loads plugins from installed Python distributions (entry point group foca.plugins) and runs them in the pipelines that operators configure; the same plugins serve every gateway app. This repository holds the plugins of ELIXIR On-Cloud: one distribution per plugin (foca-plugin-<group>-<subgroup>-<name>), grouped by the gateway API (generic, tes, wes) and by function (e.g., routing, policy), plus the meta distribution foca-plugins, whose extras install a group or subgroup of plugin versions tested together. Plugins from other repositories work the same way.

Status: the plugin API is new in FOCA 0.18.0, which is not released yet: the packages of this repository use FOCA's dev branch until then, and no plugins have been released. The only plugin so far is the example generic.example.noop, the template of new plugins.

Read the documentation for installing plugins, writing them, the plugin catalogue, contributing and releasing.

Installation

Nothing is published yet. Once plugins are released, install them into the environment of the gateway app, usually in an image derived from the app's image, then enable them in the app's configuration (FOCA's plugins section): installed is not enabled. Either a group or subgroup of a release train, as an extra of the meta distribution foca-plugins (e.g., foca-plugins[tes]), or single plugin distributions (foca-plugin-<group>-<subgroup>-<name>).

See Installing for the extras, single distributions and the derived-image recipe.

Layout

plugins/<group>/<subgroup>/<name>/  one distribution per plugin:
  pyproject.toml                    foca-plugin-<group>-<subgroup>-<name>
  src/foca_plugins/<group>/<subgroup>/<name>/
  tests/, README.md, CHANGELOG.md, LICENSE
meta/                               the meta distribution foca-plugins (extras only)
scripts/                            change detection, checks, new plugins
docs/                               this documentation (MkDocs)
pyproject.toml                      uv workspace root: tool configuration, dev groups

Item	Convention
Plugin ID (entry point name)	<group>.<subgroup>.<name>, e.g., tes.routing.distance
Distribution	foca-plugin-<group>-<subgroup>-<name>
Import path	foca_plugins.<group>.<subgroup>.<name> (with _ for -)
Entry point group	foca.plugins
Release tag	<distribution>-v<version>

foca_plugins, foca_plugins.<group> and foca_plugins.<group>.<subgroup> are namespace packages (PEP 420, no __init__.py), shared by all plugin distributions.

Contributing

Contributions are welcome! See CONTRIBUTING.md and Contributing in the documentation, and mind our code of conduct. To start a plugin, run python scripts/new_plugin.py <group> <subgroup> <name> (see Writing a plugin).