Skip to main content

Out-of-process plugin

Goal: declare a plugin written in another language and run it over stdio or HTTP.

Prerequisites​

  • The plugin's command or service, built and runnable from the worker.

Steps​

  1. Choose how the plugin runs: as a child process (stdio) or as a service (HTTP). Both speak JSON-RPC 2.0.

  2. Declare it with the Plugin kind, with the command that starts it and the environment variables it needs:

    apiVersion: afe.dev/v1alpha1
    kind: Plugin
    metadata:
      name: my-plugin
    spec:
      transport: stdio
      command:
        - my-plugin
        - serve
      env:
        MY_PLUGIN_TOKEN: "${MY_PLUGIN_TOKEN}"

  3. Run a flow. The engine calls describe to learn the ports, then one invoke per port call. It is the same contract as an in-process plugin.

Notes​

A stdio plugin receives only PATH, HOME and the variables declared in its manifest. No engine secret ever enters it.

Troubleshooting​

plugin 'my-plugin' did not start: [Errno 2] No such file or directory: 'my-plugin' The command names a binary the worker cannot find on PATH. Install the plugin on the worker, or use an absolute path in command.

plugin 'my-plugin' did not answer 'describe' The child process started, but did not reply within the transport's timeout. Check the plugin's own logs on stderr, and that it speaks line-delimited JSON-RPC 2.0 on stdout.

plugin 'my-plugin': <message> The plugin replied with a JSON-RPC error. The message is the plugin's own. Read it against the plugin's documentation or source.

See also​