hookworm

README

hookworm

GitHub & Travis hook receiving thingydoo.

Usage

Usage: hookworm-server [options] [key=value...]
  -D="": Working directory (scratch pad) [HOOKWORM_WORKING_DIR]
  -P="": PID file (only written if flag given) [HOOKWORM_PID_FILE]
  -S="": Public static directory (default $PWD/public) [HOOKWORM_STATIC_DIR]
  -T=30: Timeout for handler executables (in seconds) [HOOKWORM_HANDLER_TIMEOUT]
  -W="": Worm directory that contains handler executables [HOOKWORM_WORM_DIR]
  -a=":9988": Server address [HOOKWORM_ADDR]
  -b="": Basic auth username:password [HOOKWORM_BASIC_AUTH]
  -d=false: Show debug output [HOOKWORM_DEBUG]
  -github.path="/github": Path to handle Github payloads [HOOKWORM_GITHUB_PATH]
  -rev=false: Print revision and exit
  -travis.path="/travis": Path to handle Travis payloads [HOOKWORM_TRAVIS_PATH]
  -version=false: Print version and exit
  -version+=false: Print version, revision, and build tags

Hookworm is designed to listen for GitHub and Travis webhook payloads and delegate handling to a pipeline of executables. In this way, the long-running server process stays smallish (~6MB) and any increase in memory usage at payload handling time is ephemeral, assuming the handler executables aren't doing anything silly.

An example invocation that uses the handler executables shipped with hookworm would look like this, assuming the hookworm repo has been cloned into /var/lib/hookworm:

mkdir -p /var/run/hookworm-main
hookworm-server -d \
  -D /var/run/hookworm-main \
  -W /var/lib/hookworm/worm.d \
  syslog=yes >> /var/log/hookworm-main.log 2>&1

Handler contract

Handler executables are expected to fulfill the following contract:

• has one of the following file extensions: .js, .pl, .py, .rb, .sh, .bash
• does not begin with . (hidden file)
• accepts a positional argument of configure
• accepts positional arguments of handle github
• accepts positional arguments of handle travis
• writes only the (potentially modified) payload to standard output
• exits 0 on success
• exits 78 on no-op (roughly ENOSYS)

It is up to the handler executable to decide what is done for each command invocation. The execution environment includes the HOOKWORM_WORKING_DIR variable, which may be used as a scratch pad for temporary files.

<interpreter> <handler-executable> configure

The configure command is invoked at server startup time for each handler executable, passing the handler configuration as a JSON object on the standard input stream. The configuration object is guaranteed to have all of the values provided as flags to hookworm-server.

Additionally, any key-value pairs provided as postfix arguments will be added to a worm_flags hash such as the syslog=yes argument given in the above example. Bare keys are assigned a JSON value of true. String values of true, yes, and on are converted to JSON true, and string values of false, no, and off are converted to JSON false.

<interpreter> <handler-executable> handle github

The handle github command is invoked whenever a payload is received at the GitHub-handling path (/github by default). The payload is passed to the handler executable as a JSON object on the standard input stream.

<interpreter> <handler-executable> handle travis

The handle travis command is invoked whenever a payload is received at the Travis-handling path (/travis by default). The payload is passed to the handler executable as a JSON object on the standard input stream.

Handler logging

Each handler that uses the hookworm-base gem has a log that writes to $stderr, the level for which may be set via the log_level postfix argument as long as it is a valid string log level, e.g. log_level=debug.

Documentation

Index

• Variables
• func NewServer(basicAuthStr string, cfg *HandlerConfig) (*martini.ClassicMartini, error)
• func ServerMain(c *serverSetupContext) int
• type Handler
  • func NewHandlerPipeline(cfg *HandlerConfig) (Handler, error)
• type HandlerConfig

Variables

var (
	// VersionString is the git description set via ldflags
	VersionString string
	// RevisionString is the git revision set via ldflags
	RevisionString string
	// BuildTags are the tags used at build time set via ldflags
	BuildTags string
)

Functions

func NewServer

func NewServer(basicAuthStr string, cfg *HandlerConfig) (*martini.ClassicMartini, error)

NewServer builds a martini.ClassicMartini instance given a HandlerConfig

func ServerMain

func ServerMain(c *serverSetupContext) int

ServerMain is the `main` entry point used by the `hookworm-server` executable

Types

type Handler

type Handler interface {
	HandleGithubPayload(string) (string, error)
	HandleTravisPayload(string) (string, error)
	SetNextHandler(Handler)
	NextHandler() Handler
}

Handler is the interface each pipeline handler must fulfill

func NewHandlerPipeline

func NewHandlerPipeline(cfg *HandlerConfig) (Handler, error)

NewHandlerPipeline constructs a linked-list-like pipeline of handlers, each responsible for passing control to the next if deemed appropriate.

type HandlerConfig

type HandlerConfig struct {
	Debug         bool         `json:"debug"`
	GithubPath    string       `json:"github_path"`
	ServerAddress string       `json:"server_address"`
	ServerPidFile string       `json:"server_pid_file"`
	StaticDir     string       `json:"static_dir"`
	TravisPath    string       `json:"travis_path"`
	WorkingDir    string       `json:"working_dir"`
	WormDir       string       `json:"worm_dir"`
	WormTimeout   int          `json:"worm_timeout"`
	WormFlags     *wormFlagMap `json:"worm_flags"`
	Version       string       `json:"version"`
}

HandlerConfig contains the bag of configuration poo used by all handlers