The Hackerlab at `regexps.com`

## Driving Process Automation with arch Notifiers

up: arch Meets hello-world next: The arch Changeset Format prev: Speeding up arch with Revision Tree Libraries

Active Development Warning: The features described in this chapter are likely to change in incompatible ways before the `1` .0 release of `arch` .

In some circumstances, it is very useful to trigger actions upon the detection of changes to an archive. For example, you might want to send an email notification whenever new revisions are checked in.

The command `notify` provides this capability:

            % larch notify NOTIFICATION-DIR

That command reads configuration files found in `NOTIFICATION-DIR` . Those configuration files explain what parts of which repositories to monitor, and what actions to take upon changes. When changes are detected, `notify` invokes actions.

This chapter explains `notify` in general. It documents the format of a `NOTIFICATION-DIR` and the configuration files. It explains what `notify` does.

### The Four notify Configuration Files

|=rules.archives| |=rules.categories| |=rules.branches| |=rules.versions|

`notify` is controlled by four configuration files, found at the root of a `NOTIFICATION-DIR` . These are:

            =rules.archives
                    Specifies actions to take whenever new categories
                    are added to specific archives.

            =rules.categories
                    Specifies actions to take whenever new branches
                    are added to specific categories.

            =rules.branches
                    Specifies actions to take whenever new versions
                    are added to specific branches.

            =rules.versions
                    Specifies actions to take whenever new revisions
                    are added to specific versions.

Within these files, blank lines are permitted and comments begin with '#' and continue to the end of line.

The file `=rules.versions` contains lines with the format:

            VERSION         ACTION

where `VERSION` is a fully-qualified version name, and action a string (with no whitespace) of the form:

            COMMAND:THUNK

Whenever new revisions are detected in `VERSION` , `notify` invokes:

            larch COMMAND THUNK RVN ...

where `COMMAND` and `THUNK` are from the configuration file, and the trailing `RVN` arguments are a list of fully qualified revision names of newly detected revisions.

The file `=rules.branches` is similar. It contains lines of the form:

            BRANCH COMMAND:THUNK VERSION-ACTION

Whenever new versions are created in `BRANCH` , `notify` takes two actions. First, it invokes:

            larch COMMAND THUNK VSN ...

Second, it adds new rules to `=rules.versions` of the form:

            VSN     VERSION-ACTION

The files `=rules.categories` and `=rules.archives` are similar. The former contains lines of the form:

            CATEGORY COMMAND:THUNK BRANCH-ACTION VERSION-ACTION

and the latter lines of the form:

            ARCHIVE COMMAND:THUNK CATEGORY-ACT BRANCH-ACT VERSION-ACT

In addition to the configuration files, `notify` maintains its private state in `NOTIFY-DIR` . In particular, it keeps track of what notifications have already been sent, in order to try to avoid sending redundant notifications.

### Notifiers for Everything in a Repository

Configuring notifiers for every category, branch, and version in an archive is quite simple: you only need to write the `=rules.archives` file -- other configuration files will be automatically generated from that.

The initial `=rules.archives` file should contain lines of the form:

            ARCHIVE COMMAND:THUNK CATEGORY-ACT BRANCH-ACT VERSION-ACT

for each set of actions you want to trigger. After creating the config file, run `notify` in that directory. The first run will detect all categories in the repository, invoke `COMMAND` for those, and create a `rules.categories` file with lines:

            CATEGORY CATEGORY-ACT BRANCH-ACT VERSION-ACT

Then `notify` will read that config file, detect all the branches in the repository, invoke `CATEGORY-ACT` , and create `=rules.branches` .

Finally, `=rules.versions` will be automatically created in a similar way.

Whenever a new category, branch, or version is added to an archive, the rules files will be automatically updated to reflect the addition (when `notify` is run, of course).

### Mailing Out Notices

These commands can be used in notifier rules to send mail announcing new additions to an archive:

            mail-new-categories
            mail-new-branches
            mail-new-versions
            mail-new-revisions

This command, if invoked for new revisions, can be used to add those revisions to the revision library registered with `my-revision-library` :

            notify-library

Finally, the `noop` command can be used as a place-holder for notifier events where no actions is needed.

Putting those commands together, you can create an `=rules.archives` file that sends out announcements and updates a revision library for an archive (long lines wrapped for legibility):

/*insert

            lord@emf.net--2003              mail-new-categories:lord \
                                            mail-new-branches:lord \
                                            mail-new-versions:lord \
                                            mail-new-revisions:lord

            lord@emf.net--2003              noop:notify-library:lord \
                                            noop:notify-library:lord \
                                            noop:notify-library:lord \
                                            notify-library:lord

/*end-insert

### Robustness Issues with Notifiers

Unfortunately, some fundamental physical properties of the universe make it impossible for `notify` to guarantee that actions will be invoked only once for each new category, branch, version, or revision. A (presumably rare) well timed interrupt or system failure can cause `notify` to invoke actions more than once for a given change to the archive.

Consequently, actions should be designed to be robust against that eventuality.

`notify` is designed to be safe in the face of concurrent invocations: if two processes invoke `notify` at the same time, everything should work wonderfully with no resultant redundant actions or `NOTIFY-DIR` corruptions.

### Scheduling Notifiers with cron

One strategy for using `notify` is to run it from a `cron` job.

### Scheduling Notifiers From arch Commands

These commands (and only these commands) modify arch repositories in ways that are significant to `notify` :

            make-category
            make-branch
            make-version
            import
            commit
            tag

If you register a notifier directory with the command `my-notifier` :

            % larch my-notifier NOTIFIER-DIR

then the commands listed above will, after completing their work, spawn a detached daemon process that runs `larch notify` in that directory. Note that the start times and exit status of those daemons are recorded in `~/.arch-params/log-file` which can be useful when trying to debug problems. You may want to clear that file from time-to-time.

arch Meets hello-world: A Tutorial Introduction to The arch Revision Control System
The Hackerlab at `regexps.com`