https://github.com/jimurrito/hook-relay
https://github.com/jimurrito/hook-relay
Last synced: about 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/jimurrito/hook-relay
- Owner: jimurrito
- Created: 2025-02-05T17:50:40.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-02-05T22:27:53.000Z (4 months ago)
- Last Synced: 2025-02-05T22:38:47.865Z (4 months ago)
- Language: Elixir
- Size: 21.5 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Hook Relay
Lite webhook request proxy. Allows apps to reduce their attack surface by using this service as a proxy just for WebHooks.
Links:
- [Github](https://github.com/jimurrito/hook-relay)
- [Docker Hub](https://hub.docker.com/r/jimurrito/hook-relay)
**Table of Contents**
- [Hook Relay](#hook-relay)
- [Features](#features)
- [Docker](#docker)
- [CLI](#cli)
- [Compose](#compose)
- [Environmental variables](#environmental-variables)
- [From source](#from-source)
- [Dependencies](#dependencies)
- [Deployment](#deployment)
- [Using `relay.conf`](#using-relayconf)
- [Configuration path](#configuration-path)
- [Breakdown](#breakdown)
- [Utilizing Hook-Relay](#utilizing-hook-relay)
- [Powershell](#powershell)
- [Bash](#bash)
- [Async mode](#async-mode)
- [FAQ](#faq)
- [Can I nest relays?](#can-i-nest-relays)
- [Is `proof_key` required?](#is-proof_key-required)
- [What does *Live Reloading* mean for this app?](#what-does-live-reloading-mean-for-this-app)
- [Any issues?](#any-issues)
# Features
- Blazingly fast!
- Handles all requests in parallel for maximum throughput.
- Live reloading - never restart the server for configuration changes!
- TOML configuration files.
- Optional async mode for request relaying.
- Small container foot print (<85 MB in size!).
- Highly scalable.
- Supports vertical and horizontal scaling.
- ~~Multi-Architecture Support~~. (Coming soon)
- Supports Windows and Linux.
# Docker
The Alpine Linux based image was built to have the smallest footprint possible. (<85 MB in size!)
## CLI
```bash
docker run \
--name hook-relay \
-p 4000:4000 \
-v path/to/config/dir:/config \
jimurrito/hook-relay:latest
```
## Compose
```yaml
services:
hook-relay:
container_name: hook-relay
ports:
- 4000:4000
volumes:
- path/to/config/dir:/config
image: jimurrito/hook-relay:latest
```
*See section on [Environmental Variables](#environmental-variables) for more options.*
Using the volume mount we setup for `/config` on the container, the server will check for a file called `relay.conf`. If this file is not present, one will be created with a default configuration.
*Go to the [Using relay.conf](#using-relayconf) section to learn more about the `relay.conf` file.*
# Environmental variables
| Env Var | Options | Default | Description |
| ------------- | ----------- | ------- | ------------------------------------------------------------------------------------------------- |
| `PORT` | *-integer-* | 4000 | Port the server will use |
| `APP_ENV` | prod, dev | prod | **Prod** => Info logs. **Dev** => Debug logs |
| `CONFIG_PATH` | *-path-* | /config | Folder containing the required `relay.conf` file. *Only supported on 'From Source' deployments.w* |
# From source
If you need to use this compiled from source, please follow these steps. For ease of use, I highly recommend using the [Docker deployment method](#docker) above.
## Dependencies
- inotify-tools
- Elixir 1.17+
- Erlang OTP 27+
## Deployment
```bash
# From the root directory of this repo
cd src/
mix deps.get
CONFIG_PATH=path/to/config/dir mix hook_relay
```
# Using `relay.conf`
This file contains the relay endpoints and targets for the server. The file is formatted using [TOML](https://toml.io/en/).
**The server will generate a default config if not present in the provided directory.**
### Configuration path
The server will check for the file using the `CONFIG_PATH` environmental variable. This variable must be a directory, and not the file itself. If you are deploying by docker, you can disregard this as the variable is not configurable.
> **NOTE:**
>
> The directory provided will be watched recursively. Please ensure there are not nested files within this folder.
## Breakdown
Here is the default configuration that will be generated by the server:
```TOML
[relay]
proof_key = "trust-me-bro"
target = "https://hook-relay.requestcatcher.com/test"
async = false
[relay_async]
proof_key = "trust-me-bro"
target = "https://hook-relay.requestcatcher.com/test"
async = true
```
This configuration defines **2** relay endpoints. *relay* and *relay_async*. Each relay will have its own endpoint. For example, this configuration will have the server listen on `/relay` and `/relay_async`.
For each relay, we see a set of **3** parameters.
- `proof_key` This is a secret that protects the relay. **If unset, authentication will be disabled for the relay endpoint.** This must be provided at the root level of the JSON request body used for the webhook. *This will be covered more in-depth in [Utilizing Hook-Relay](#utilizing-hook-relay).*
- `target` This is the endpoint that the request should be relayed to.
- `async` This defines whether the relay to the `target` will be asynchronous or not. If async is enabled, and the request to the relay target fails, only the server logs will indicate the failure. During synchronous mode, the WebHook sending client will be told if the relayed request was successful or not.
Each relay will have it's requests handled in parallel. There is no limit to the amount of relays that can be created.
**All 3 parameters are required for each relay declaration.**
# Utilizing Hook-Relay
Once this is up and running, we can use one of the below examples to test the function of the relay.
The default configuration will relay the requests to both endpoints to https://hook-relay.requestcatcher.com/test. You can use [Request Catcher](https://requestcatcher.com) to test the server with your own URL.
### Powershell
```powershell
$body = @{
proof_key = "trust-me-bro"
msg = "Test Relay"
}
Invoke-WebRequest -Uri http:///relay -Method post -Body $body
```
**Result:**
```
StatusCode : 200
StatusDescription : OK
Content : {"result":"relayed"}
RawContent : HTTP/1.1 200 OK
Date: Thu, 06 Feb 2025 02:06:27 GMT
Vary: accept-encoding
Cache-Control: must-revalidate, max-age=0, private
X-Request-ID: GCF8Sa53wsgGb5MAABtH
Content-Type: application/json; charset=…
Headers : {[Date, System.String[]], [Vary, System.String[]], [Cache-Control, System.String[]], [X-Request-ID, System.String[]]…}
Images : {}
InputFields : {}
Links : {}
RawContentLength : 20
RelationLink : {}
```
### Bash
```bash
#!/bin/bash
json_data='{"proof_key": "trust-me-bro", "msg": "Test Relay"}'
curl -X POST \
-H "Content-Type: application/json" \
-d "$json_data" \
http:///relay
```
**Result:**
```
{"result":"relayed"}
```
### Async mode
When `async` is set to true, the result will be:
```
{"result":"async_relayed"}
```
# FAQ
### Can I nest relays?
No. Relays endpoints will only use the first level of the URL path.
### Is `proof_key` required?
No. You can change `proof_key` to be unset in the `relay.conf` file and the parameter will not be checked.
### What does *Live Reloading* mean for this app?
Anytime you make changes to the `relay.conf` file, the server will automatically reload the configuration. This includes adding and removing relays. Changes are immediate and this feature can not be disabled.
# Any issues?
Open an issue on this github repo.