Workflows

Workflows in Porla are inspired by GitHub actions and allows the user to trigger various actions when different events occur.

For example, you can use workflows to move finished torrents to a long-term seeding storage, or to announce a torrent after a specific delay in order to be early in a racing swarm.

Getting started

Workflows are defined in simple YAML files and Porla will load all workflows from a single directory when it starts. The directory is specified in the porla.toml file with the workflow_dir key.

A simple workflow can be something like;

on: torrent_added

steps:
  - uses: log
    with:
      message: Torrent ${{ torrent.name }} added

Which will log a message whenever a torrent is added.

Steps, inputs and outputs

Each workflow contains a series of steps. A step defines the action along with its parameters.

In the example above, we specify the log action, and set the message parameter to a user-specified value. The input parameters differ among actions so refer to each action to see how they work.

An action can also produce output, which you can use in subsequent steps. The log action produces the rendered_message output, which is the message that was rendered. You can access these outputs using the steps context, such as;

on: torrent_added

steps:
  - uses: log
    with:
      message: Torrent ${{ torrent.name }} added

  - uses: log
    with:
      message: Previous step rendered ${{ steps[0].rendered_message }}

Using actions that produce outputs, a user can create complex workflows to fit their specific needs.

Actions

Porla bundles a bunch of useful actions, and new ones are added as requested by users.

log

Prints a message to the log output.

Inputs

• message - the message to print.

Outputs

• rendered_message - the message that was printed.

sleep

Sleeps (non-blocking) for a user-defined timeout. Can be used to wait before the next step is invoked.

Inputs

• timeout - the timeout (in milliseconds) to sleep.

Outputs

None.

push/discord

Sends a message to a Discord channel using the Discord webhook API.

Inputs

• url - the complete URL as copied from the Discord webhook page.
• message - the message to send.

Outputs

None.

push/ntfy-sh

Sends a push notification using ntfy.sh.

Inputs

• topic - the topic to use as per the ntfy.sh docs. Use something unique and hard to guess, such as a value generated by porla key:generate.
• message - the message to push.

Outputs

None.

torrents/move

Moves a torrent to the specified path. The step will not complete until the data is actually moved to the new path as reported by libtorrent.

Requires a torrent context - provided by the torrent events.

Inputs

• path - the path where the torrent should be moved.

Outputs

None.

torrents/reannounce

Reannounces a torrent to its trackers.

Requires a torrent context - provided by the torrent events.

Inputs

None.

Outputs

None.

torrents/remove

Removes a torrent from the session and optionally removes the downloaded files as well.

Requires a torrent context - provided by the torrent events.

Inputs

• remove_files - set to true to remove the downloaded files. Defaults to false.

Outputs

None.

Contexts

Each invoked workflow has a number of contexts depending on which event that triggered it. All workflows has the steps context where step outputs are stored for that specific invocation.

torrent

The torrent context is available for the torrent specific events, such as torrent_added, torrent_finished etc. It provides torrent data for the torrent that triggered the workflow.

Data

{
  "name": "debian",
  "info_hash": [ "v1", "v2" ],
  "progress": 0.674,
  "save_path": "/dl",
  "total": 4781293,
  "total_done": 237823,
  "total_wanted": 238787
}