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.

How it fits together

• FOCA provides the plugin engine (foca.plugins): the plugin API (Plugin, the hooks of the phases request, route, forward and response, the plain request models), the loader of entry points, the pipelines, and the provenance of each request. Its plugins page documents the API and the configuration (the plugins section).
• Gateway apps such as proTES (and, later, proWES) declare themselves as gateways to FOCA, run the pipelines in their controllers, and forward requests to their backends.
• This repository holds plugins: installable distributions that register a plugin class under the entry point group foca.plugins. Operators install them into the app's image and enable them in the app's configuration.

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.

Contents

• Installing: extras of the meta distribution, single distributions, and an image derived from the app's image.
• Writing a plugin: the conventions of this repository and the template.
• Plugin catalogue: the plugins of this repository.
• Contributing: development setup, checks, pull requests, commit messages and the Python guidelines.
• Releasing: versions, tags, changelogs and the release workflow.

License

This project is covered by the Apache License 2.0 also shipped with this repository and with each distribution.

Contact

The project is a collaborative effort under the umbrella of ELIXIR On-Cloud. Follow the link to get in touch with us via chat or email. Please mention the name of this project for any inquiry, proposal, question etc.