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; the plugins support FOCA 0.18 and 0.19. Plugins so far, both experimental and released as 0.1.x: generic.routing.random and tes.routing.distance, plus the example generic.example.noop, the template of new plugins (never published). The first release train is foca-plugins 0.1.0.

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

Installation

Install plugins 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]==0.1.0), 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.

Citation

If you use FOCA plugins, please cite them with their DOI 10.5281/zenodo.23858996, which always resolves to the latest version on Zenodo; the Zenodo record lists the DOI of each version, too. The citation metadata is in CITATION.cff: on GitHub, "Cite this repository" in the sidebar of the repository formats it as APA or BibTeX.

Contributing

Contributions are welcome! See the contributing guide 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).