webhookey/README.md

# Webhookey
Webhookey is a webserver listening for requests as for example sent by
gitea's webhooks. Further, Webhookey allows you to specifiy rules
which are matched against the data received to trigger certain
actions.

## Build

### Install Rust
Install the Rust toolchain from [rustup.rs](https://rustup.rs).

Further, for Rocket we need to have the nightly toolchain installed:
``` sh
    rustup toolchain install nightly
```

### Build Webhookey
The webhookey project can be built for development:
``` sh
    cargo b
```

or for releasing:
``` sh
    cargo b --release
```

### Install Webhookey
When a Rust toolchain installed you can also install Webhookey
directly without cloning it manualy:
``` sh
    cargo install --git https://git.onders.org/finga/webhookey.git webhookey
```

or from within the project:
``` sh
    cargo install webhookey
```

### Run Webhookey
Webhookey can either be run from the project directory with:
``` sh
    cargo b
```

or you can copy the produced binary somewhere else from
`webhookey/target/{debug, release}/webhookey` depending on which one
you built.

## Configuration
Configuration syntax is YAML and it's paths as well as it's
configuration format is described in the following sections.

### Configuration paths
Following locations are checked for a configuration file:
- `/etc/webhookey/config.yml`
- `<config_dir>/webhookey/config.yml`
- `./config.yml`

Whereas `<config_dir>` depends on the platform:
- Linux:   `$XDG_CONFIG_HOME` or `$HOME/.config`
- macOS:   `$HOME/Library/Application Support`
- Windows: `{FOLDERID_RoamingAppData}`

### Configuration parameters

#### Hooks
With `hooks` you can configure a sequence of hooks. A single hook
consists of the following fields:
- command: A command to be executed if a filter matches
- allow/deny: An optional parameter to either allow or deny specific
  source addresses or ranges.
- signature: Name of the HTTP header field containing the signature.
- secrets: List of secrets.
- filters: List of filters.

Example:
```yaml
hooks:
  hook1:
    command: /usr/bin/local/script_xy.sh {{ /repository/name }}
    signature: X-Gitea-Signature
    ip_filter:
      allow:
        - 127.0.0.1
        - 127.0.0.1/31
    secrets:
      - secret_key_01
      - secret_key_02
    filters:
      match_ref:
        pointer: /ref
        regex: refs/heads/master
```

##### Command
To pass data to a command following two different methods can be used.

Example: `script_foo {{ header X-Gitea-Event }} {{ /field/foo }}`

###### JSON Pointers
Use JSON pointers ([RFC 6901](https://tools.ietf.org/html/rfc6901))
point to values of a JSON field from the JSON data.

Example: `{{ /field/pointed/to }}`.

###### Header
Use values from header fields sent with the HTTP request.

Example: `{{ header X-Gitea-Event }}`.

##### Allow and Deny
To allow or deny specific network ranges source is an optional
configuration parameter which either contains an allow or a deny field
with sequences containing networks. Note that IPv6 addresses have to
be put in single quotes due to the colons.

Example:
```yaml
allow:
  - 127.0.0.1
  - 127.0.0.1/31
  - "::1"
```

```yaml
deny:
  - 127.0.0.1
  - 127.0.0.1/31
  - "::1"
```

##### Signature
Set the name of the HTTP header field containing the HMAC signature.

##### Secrets
Configure a list of secrets to validate the hook.

##### Filter
Each filter must have following fields:
- pointer: pointer to the JSON field according to [RFC
  6901](https://tools.ietf.org/html/rfc6901)
- regex: regular expression which has to match the field pointed to by
  the pointer

# TODOs
## Use `clap` to parse command line arguments
## Configure rocket via config.yml
## Security
### https support
basically supported, but related to "Configure rocket via config.yml".
### Authentication features
## Use proptest or quickcheck for tests of parsers