Feature Proposal: Event Hooks

[Tristan Maat <tristan maat codethink co uk>]

Hi,

We have had a bit of discussion on a thing called "event plugins",
which would essentially be a way to run scripts on certain events
within BuildStream (such as completed tracking, a completed build, or
an error). To keep with other applications' naming convention for this
I prefer the name "event hooks".

My personal use case for this is to make BuildStream send a
notification using `notify-send` when a build finishes/errors out.
That way I don't have to keep manually jumping to my terminal and dig
up the screen window in which it runs just to check if my CI has
finished yet (screen's monitor mode could also really use this
feature), but I can see this being useful for other things.

For now I would like to share an initial implementation proposal, but
I think we also want to collect more use cases, so that we can find
something that is more generally useful.

Proposed implementation
-----------------------

While this is far from complete, I propose adding a 'hooks' section to
the user configuration file.

The section would have a handful of hard-coded hooks that map to
certain events that may occur when running BuildStream, and allow the
user to specify commands to be run when a hook triggers.

I think that we do *not* want users to modify their projects to add
hooks, since projects will be in git repositories, and hooks are
generally very user-specific. It would be annoying to push and pull
BuildStream projects if element files or the project configuration
could contain hooks - that someone just uses to send notifications to
their desktop, but triggers health checks on the project build server.

To add some context to the events, BuildStream could pass text on
stdin (exact format to be determined). I prefer this over using
environment variables, since it makes using external commands without
intermediate scripts easier.

The currently proposed configuration would look something like this:

    hooks:
      - on-error:
        - commands:
          - /usr/bin/xargs /usr/bin/notify-send 'BuildStream failed'
          - /home/tlater/bin/flash-screen #FF00000
      - build-finished:
        - commands:
          - /usr/bin/notify-send 'BuildStream finished!'
          - /home/tlater/bin/flash-screen #00FF00

I can see it being slightly problematic that these events would just
trigger on all projects and elements, so there should probably also be
events that trigger on specific elements and projects. E.g., for the
'pony.bst' element in the 'ponies' project:

    hooks:
      - on-error-ponies:
        - commands:
          - /usr/bin/notify-send 'Oh no! One of the ponies broke!'
      - build-finished-ponies:pony.bst:
        - commands:
          - /usr/bin/notify-send 'Your pony is done!'

A serious proposal for plugin-defined hooks is probably out of scope
for now, however, if there is enough interest in this, element and
source plugins could specify their own hooks, allowing fun things like
this:

    hooks:
      - git-pre-commit-ponies:pony.bst:
        - commands:
          - /usr/bin/notify-send 'We probably never even run a git 
pre-commit hook with BuildStream'

===

I have no hopes at all of this covering all use cases, any input is
much appreciated :)

Thanks,

Tristan Maat