Add specification/testing info about the CLI interface for whck
Add a skeleton for web spec/testing info and for setup documentation
This commit is contained in:
parent
24bfd29c0f
commit
d07f677eab
79
README.md
79
README.md
|
|
@ -5,18 +5,77 @@ template = "project.html"
|
|||
|
||||
# Webhook endpoints
|
||||
|
||||
This repository contains the specification and tests for the forge webhook endpoints.
|
||||
This repository contains documentation and tests about running webhook endpoints as part of a [forge suite](https://thunix.net/~southerntofu/forge) setup. There are tests for CLI webhook validation programs (such as [whck](https://tildegit.org/forge/whck)), as well as for HTTP endpoints calling such webhook checkers. A certain number of conventions (environment variables and folder structure) should make it "just work" for different kinds of setups including shared hosts with unprivileged accounts. **For setup information, please head over to the [Setup section](#setup).**
|
||||
|
||||
# Running tests
|
||||
Below, you will find specifications for the [CLI](#cli) and [Web](#web) programs. For the reference of supported webhook sources and their respective property, please read the [Sources section](#sources)
|
||||
|
||||
Running tests requires the bats framework (`apt install bats`). You can run the `test.sh` script to start the tests. If you are not running from the implementation's folder, you may pass it as first argument the path to the program starting the local server (for tests).
|
||||
# Command-line interface {#cli}
|
||||
|
||||
```
|
||||
$ ./test_web.sh ~/endpoints.php/server
|
||||
```
|
||||
A CLI webhook validator is a program that parses an identifier, a webhook body as well as a claimed secret provided by the caller, and attempts to validate the claim against the actual secret matching the provided identifier (if it was found). The following verification mechanisms are supported so far:
|
||||
|
||||
If you're running test for a CLI program to check credentials (like [whck](https://tildegit.org/forge/whck)), use test_cli.sh instead:
|
||||
- `hmac-sha256`: used by Github and Gitea to sign the JSON payload
|
||||
- `token`: used by Gitlab without signatures, so the body (payload) is ignored
|
||||
|
||||
```
|
||||
$ ./test_cli.sh ~/whck/target/debug/whck
|
||||
```
|
||||
The webhook validator uses the following syntax:
|
||||
|
||||
- `whck KIND IDENTIFIER CLAIM (+ BODY as STDIN)`, where:
|
||||
- `KIND` is a supported verification mechanism (`hmac-sha256` or `token`)
|
||||
- `IDENTIFIER` is the repository unique ID, usually a base16 or base64 encoding of the repo URL
|
||||
- `CLAIM` is the claimed signature or secret token
|
||||
- `BODY` is the actual HTTP body (usually a JSON payload), passed via STDIN
|
||||
|
||||
The webhook validator returns 0 when validation succeeded, or any other exit code if it fails. In the future, error codes could be standardized.
|
||||
|
||||
## Conventions
|
||||
|
||||
In order to facilitate deployment in varied setups, the following conventions are respected:
|
||||
|
||||
- the secrets directory is generated from the following possibilities, in order of precedence:
|
||||
- from the `WHCK_DIR` environment variable (automated tests)
|
||||
- from the `XDG_CONFIG_HOME` environment variable, with "whck" appended (user operating CLI, or WWW running as user)
|
||||
- from the `HOME` environment variable, with ".config/whck" appended (user operating CLI, or WWW running as user)
|
||||
- from the current path to the executable, checking if it's inside a /home/ folder, and if so appending ".config/whck" (WWW running as system account, calling a symlink to a user-provided executable)
|
||||
- **if all those discovery methods failed, the validator program fails to start and returns an error code**
|
||||
- each implementation contains a `spec` submodule containing this very repository (*forge/endpoints*)
|
||||
- each implementation contains a `test.sh` executable script allowing to start the automated tests for this codebase, as explained in the next section ; the script should also check for the presence of the `specs` submodule and clone it if it was not already done
|
||||
- each implementation contains a `cli` executable script which will build the code and if it succeeds return a 0 exit code with the absolute path to the executable printed to STDOUT
|
||||
|
||||
## Testing
|
||||
|
||||
**If you want to run tests for an existing implementation, please run the test.sh script from the implementation's repository.**
|
||||
|
||||
**NOTE:** Running tests requires the bats testing framework. You can usually find it in your distro repositories. If not, head over to the [bats repository](https://github.com/bats-core/bats-core/).
|
||||
|
||||
The `test_cli.sh` script is used for testing CLI webhook validators (such as [whck](https://tildegit.org/forge/whck)). It takes as first positional argument a path to the `cli` script returning the (compiled) program to check. If no program is provided as argument, the following paths will be attempted, in order of precedence:
|
||||
|
||||
- `./cli`, relative to the directory from which you called the tests (eg. if you're running `specs/test_cli.sh` from whck repository)
|
||||
- `../cli`, relative to the directory containing test_cli.sh (eg. if you're running `./test_web.sh` from specs submodule in whck repository)
|
||||
- if no path was matched, the test suite fails to start
|
||||
|
||||
**To run tests, simply call ./test.sh from your implementation repository**.
|
||||
|
||||
If you're making an implementation from scratch, you need to write your custom `cli` script. Then, you can copy the `test.sh` script from [whck](https://tildegit.org/forge/whck) and it should work.
|
||||
|
||||
**Note: to test that the test suites can be called from several folders using different kind of relative/absolute paths, use the `test_tests.sh` script.:**
|
||||
|
||||
# Web interface {#web}
|
||||
|
||||
## Conventions
|
||||
|
||||
## Testing
|
||||
|
||||
**If you want to run tests for an existing implementation, please run the test.sh script from the implementation's repository.**
|
||||
|
||||
**NOTE:** Running tests requires the bats testing framework. You can usually find it in your distro repositories. If not, head over to the [bats repository](https://github.com/bats-core/bats-core/).
|
||||
|
||||
Or you can call test_web.sh with an absolute path to a server starting script for an implementation
|
||||
|
||||
# Setup {#setup}
|
||||
|
||||
Now it gets tricky... In all cases you need some kind of shell account!
|
||||
|
||||
## Unprivileged user, web server running as user
|
||||
|
||||
## Unprivileged user, web server running as system account
|
||||
|
||||
## Privileged user (requires root)
|
||||
|
|
|
|||
Loading…
Reference in New Issue