RFC: Revamp hook system

[MZAWeb]

While working on #3229 I thought about a potential improvement about how we implement Hooks.

There are fundamentally two classes of scripts that want to hook into Taskwarrior.

The first class I'm calling filters and they want to receive a value with the intention of modifying it and returning it to Task to persist it. For example, a script that hooks into on-add and based on some conditions adds a tag to the task. Due to the nature of these, we need to run them synchronously and wait for their response.

The second class I'm calling triggers and they want to receive one or multiple values but they don't need to return any change to Task. They want the data to run an "offline" operation like logging, doing a backup, sending a notification, etc. These scripts could be run in a "fire and forget" kind of way, spawning a separate thread, and not block Task execution waiting. This would allow us to be less conservative on how many of these triggers we add around the codebase, making Taskwarrior more extensible and flexible without compromising UX.

The new Hooks API would expose a few methods to trigger these hooks, passing a name, one of the most common values we may want to trigger for, and an arbitrary vector of string parameters to send to the script:

void trigger_hook (std::string, Task, std::vector<std::string>)
void trigger_hook (std::string, std::string, std::vector<std::string>)
void trigger_hook (std::string, float, std::vector<std::string>)
void trigger_hook (std::string, int, std::vector<std::string>)

And another set of functions to filter the 4 most common types of data we may want to have filters for. These will also support passing an arbitrary vector of extra data to share with the script, if needed. The first parameter would be the filter name.

Task apply_filters (std::string, Task, std::vector<std::string>)
std::string apply_filters (std::string, std::string, std::vector<std::string>)
float apply_filters (std::string, float, std::vector<std::string>)
int apply_filters (std::string, int, std::vector<std::string>)

On the script registration side I see two main paths:

1. We keep the current system, using file names to tell Task where to hook to. In this case we can extend the nomenclature to define triggers vs filters.

2. We remove a little bit of magic and make users configure these hooks in the config file. This would mean a bit extra work from the user, but could allow a few interesting changes:

• Multiple hooks could be funneled to the same script, making distribution / maintenance much easier for plugin developers.
• For filters, we could let users define a priority, effectively determining the order in which we chain these scripts sequentially.

[djmitche]

A few things to consider, while thinking broadly about hooks:

• It's not clear how they interact with sync. Does a hook run on a change that arrives via task sync, or just changes that are generated locally (e.g., task add, task mod)?
• Sync now handles changes in a very granular fashion: one attribute change at a time. Do hooks operate on each individual attribute change, or are these aggregated somehow? If so, how?
• In a situation with multiple replicas (such as my laptop and desktop), do hooks run on all replicas or just one? Is it up to me as a user to make sure that hooks only run in one place?
• Could recurrence be implemented with hooks? That already has the issue of making sure it only runs in one place.
• A part of the goal for using Taskchampion for data storage is to use sync for more things. For example, a tool to generate tasks for GitHub issues would have its own replica into which it inserts tasks, and those would be communicated to my laptop and desktop via sync. Maybe hooks could do a similar thing, acting on a dedicated replica and communicating with other replicas via sync.
• Further to that point, maybe hooks could/should be written directly against Taskchampion, using its granular data model? (that doesn't necessarily mean in Rust -- that data model could be exposed to shell via JSON, or via Lua, or Python, or whatever)

I'm only presenting these for consideration -- maybe something sparks a broader, more comprehensive new Hooks design that would enable some cool new things.

[ryneeverett]

It seems like one way to address these concerns would be to introduce the concept of a conditional operation:

1. Add a condition field to each ReplicaOp variant. (But not SyncOp -- these are local only.)
2. On sync, the replica checks the condition of each operation before syncing it.
   a. If it evaluates true, it runs AddVersion.
   b. if it evaluates false, the operation is dropped altogether.

In this way, for example, recurring tasks could have a condition that checks whether they have already recurred. Hooks could likewise set both a status/timestamp field and a condition on the given tasks they operate on which indicates whether they've already run. In this way you could have the benefits of these kinds of features staying up-to-date on all your devices without having to run a special replica for them.

The biggest challenge that comes to mind with this idea is that the condition would need to have a way to operate in the context of the latest synced version while disregarding un-synchronized operations.

[MZAWeb]

Good questions, @djmitche. I'm not a big user of sync, so I haven't thought much about those. Will leave the community to comment.

Some of these could be configured by the user if we are willing to give up on the simplicity of just dropping a file and make hooks configurable on the config file. Or we can have sane defaults for just drop ins.

On your second point, I do not think filtering each individual field would be good for performance or for plugin developer UX. It'll be better to be able to filter the change set at the individual task level, imo.