Commit 939256e

---

language: go

go:

- 1.1

script: go get "code.google.com/p/go.crypto/ssh/terminal" && make test

before_install:

- git clone https://github.com/sstephenson/bats.git /tmp/bats && sudo /tmp/bats/install.sh /usr/local

env:

global:

- ARTIFACTS_AWS_REGION=us-east-1

- ARTIFACTS_S3_BUCKET=progrium-pluginhook

- secure: "eGrQigTCcuV/UiiNtAWUyTxgSVinyu7GliN8zVzWBsT2Qcp+YWYIc3vbbMFV\ntBizU6MLUvhvdpbTV7hQN1X4kP7DIBnMuNpuF38vcolFHlDh57rFNj6A6HjA\nlOkpScF0APuaqd50bIxjDOs3cR9Ef2JqmBaFNVR+gJ8poG485Rw="

- secure: "OWHMXQRDXPBU6KUmTiCueteT2TJDlebzl3dU3WRjvYK/hzt6mstpjGyr+7lF\nb+GdKiik8xLf452uC/bhX1iLmeYw7kmHU6y9434EHvp6MjNIsN/Zkb9urwZp\nRIKO0dNeRvNUipPE9QhI+DfqgBoxbGQSWXcpGLpfNsQ7racCzTs="

VERSION = 0.1.1

build: pluginhook

pluginhook:

go build -o pluginhook

GOOS=linux go build -o pluginhook.linux

test: build

PLUGIN_PATH=./tests/plugins BIN=./pluginhook tests/run_tests.sh

package: test build

rm -rf package

mkdir -p package/bin

mv pluginhook.linux package/bin/pluginhook

cd package && fpm -s dir -t deb -n pluginhook -v ${VERSION} --prefix /usr/local bin

release: package

s3cmd -P put package/pluginhook_${VERSION}_amd64.deb s3://progrium-pluginhook

A simple plugin system for Bash programs that's better than just hook scripts.

Let's take the core benefits of hook scripts and re-structure it slightly:

1. Instead of focusing on hook scripts, we focus on plugins -- a directory of hook scripts

1. Like hook scripts, plugins are active by being in a certain place. But they can be named anything

1. Multiple plugins can handle a hook. Either for fanout event triggering, or for pipeline filtering

So what is a plugin? A directory full of hook scripts. When a hook is triggered, all arguments provided

in the trigger are given to each hook script. They also receive STDIN in a pipelined fashion.

You use the `pluginhook` command to trigger hooks as if you might call a traditional hook script directly.

Where before you might have triggered by calling something like:

hooks/post-commit $REV $USER

You'd instead trigger like this:

pluginhook post-commit $REV $USER

The `pluginhook` command simply loops through all plugin directories found in the path defined by the environment variable `PLUGIN_PATH` and passes the same arguments to any hook scripts by that name. This means installing a plugin is as simple as putting it in your `PLUGIN_PATH`. Then any plugin that has the `post-commit` hook script will be run.

You don't just get a "broadcast" mechanism for arguments. You also get stream pipelining. If you pipe a stream

into pluginhook, it will be passed *through* each plugin hook, letting each plugin act as a filtering process. By clearly

defining how a hook should be used and how it can play well with others, this becomes very powerful infrastructure.

Here is a plugin we'll call `upper` implementing a `text` hook (which would be in `$PLUGIN_PATH/upper/text`):

#!/usr/bin/env python

import sys

sys.stdout.write(sys.stdin.read().upper())

Here is a plugin we'll call `reverse` that also implements a `text` hook (`$PLUGIN_PATH/reverse/text`):

#!/usr/bin/env ruby

puts STDIN.read.strip.reverse

One plugin uses Python to implement the hook, the other uses Ruby. But it doesn't matter, they work together when you trigger the hook:

$ echo "hello world" | pluginhook text

DLROW OLLEH

Only plugins that implement a hook are used as filters for that hook, so there's no need to implement pass-through hooks if a

plugin doesn't care about a hook.

If ordering is important, you can always rename your plugin directory to start with a number, which will define an order of

execution. A plugin author might care about when it is run, but it's up to the user to take their advice or decide

to run it in a different position in the order, by simply renaming the plugin script.

Lots of shell-based systems use hook scripts as a means to allow users to extend or customize behavior. Popular examples

are [Git](https://www.kernel.org/pub/software/scm/git/docs/githooks.html) and [SVN](http://svnbook.red-bean.com/nightly/en/svn.ref.reposhooks.html), but many systems from [libvirt](http://www.libvirt.org/hooks.html) to [NPM](https://npmjs.org/doc/scripts.html) to [OS X](http://superuser.com/questions/295924/how-to-run-a-script-at-login-logout-in-os-x) use this pattern. Shell scripts make

for a great way to expose hooks because the shell environment is ubiquitous and lets you easily call into

scripts or programs written in your language of choice.

The standard implementation of hook scripts is to have a shell script with an execute bit in a particular location

that's named after the hook. The most famous example is the "post-commit" hook of SVN, which if `hooks/post-commit`

exists in your repository directory with an execute bit, it will trigger this script after each commit. Some systems

let you register hooks by providing a location instead of using convention.

However, in either case, each hook points to **one** script. The only way for a third-party piece of software to

"hook in" is to install itself as the one hook script, or have you manually install it by calling it from your

existing hook script. What's more, if a third-party piece of software wants to use multiple hooks, you have to

deal with this several times over. Not only is this a hassle, but leads to complex and non-obvious configurations.

Jeff Lindsay <progrium@gmail.com>

MIT

package main

import (

"os"

"fmt"

"os/exec"

"syscall"

"path/filepath"

"log"

"flag"

"bytes"

"strings"

"code.google.com/p/go.crypto/ssh/terminal"

)

func main() {

var parallel = flag.Bool("p", false, "Run hooks in parallel")

var trace = flag.Bool("x", false, "Trace mode")

flag.Parse()

if len(os.Getenv("PLUGINHOOK_TRACE")) > 0 {

*trace = true

}

pluginPath := os.Getenv("PLUGIN_PATH")

if pluginPath == "" {

log.Fatal("[ERROR] Unable to locate plugins: set $PLUGIN_PATH\n")

os.Exit(1)

}

if flag.NArg() < 1 {

log.Fatal("[ERROR] Hook name argument is required\n")

os.Exit(1)

}

cmds := make([]exec.Cmd, 0)

var matches, _ = filepath.Glob(fmt.Sprintf("%s/*/%s", pluginPath, flag.Arg(0)))

for _, hook := range matches {

cmd := exec.Command(hook, flag.Args()[1:]...)

cmds = append(cmds, *cmd)

}

for i := len(cmds)-1; i >= 0; i-- {

cmds[i].Stderr = os.Stderr

if i == len(cmds)-1 {

cmds[i].Stdout = os.Stdout

}

if i > 0 {

if *parallel {

stdout, err := cmds[i-1].StdoutPipe()

if err != nil {

log.Fatal(err)

}

cmds[i].Stdin = stdout

} else {

var buf bytes.Buffer

cmds[i-1].Stdout = &buf

cmds[i].Stdin = &buf

}

}

if i == 0 && !terminal.IsTerminal(syscall.Stdin) {

cmds[i].Stdin = os.Stdin

}

}

if *parallel {

done := make(chan bool, len(cmds))

for i := 0; i < len(cmds); i++ {

go func(cmd exec.Cmd, i int) {

if *trace {

fmt.Fprintln(os.Stderr, "+", strings.Join(cmds[i].Args, " "))

}

err := cmd.Run()

if msg, ok := err.(*exec.ExitError); ok { // there is error code

os.Exit(msg.Sys().(syscall.WaitStatus).ExitStatus())

}

done <- true

}(cmds[i], i)

}

for i := 0; i < len(cmds); i++ {

<-done

}

} else {

for i := 0; i < len(cmds); i++ {

if *trace {

fmt.Fprintln(os.Stderr, "+", strings.Join(cmds[i].Args, " "))

}

err := cmds[i].Run()

if msg, ok := err.(*exec.ExitError); ok { // there is error code

os.Exit(msg.Sys().(syscall.WaitStatus).ExitStatus())

}

}

}

}

cat

cat

echo "bar pre-build $2 $3 $4 $5"

echo "bar pre-deploy"

puts STDIN.read.strip.reverse

date +%s

sleep 2