Skip to content

aalbacetef/pirate

Repository files navigation

pirate

Introduction

pirate ship

Pirate is a webhooks task runner. It aims to satisfy the need for running tasks based on webhook events.

Running it

Command line flag

You can pass in a config file using the -config flag:

pirate -config ./path/to/ship.yml

Environment variable

You can set the environment variable: PIRATE_CONFIG_PATH

Default location

If running without a config flag, it will look for a ship.yml in the current directory.

Example config (see ship.sample.yml).

server:
  # optional: defaults to 'localhost'
  host: localhost

  # required: port on which to listen to
  port: 3939

  # optional: maximum time allowed for a request, defaults to 5m0s
  request-timeout: '2m30s'

  # optional: maximum size of the header bytes, defaults to 1k
  max-header-bytes: '10M'

  logging:
    # required: logging directory.
    #   Will be created with permission 744 if it doesn't exist
    #   Filename will be pirate.YYYY-MM-DD--hh:mm:ss.log
    dir: './logs'

    ## NOTE: special value :stdout: writes to standard output
    # dir: ':stdout:'


handlers:
  # NOTE: all fields of the handler are required unless stated otherwise
  - endpoint: /webhooks/simple
    name: simple webhook handler

    # optional: handler execution policy, one of: drop, queue, parallel. Defaults to queue.
    policy: drop

    # authenticates the handler based on the value of the X-Authorization header
    auth:
      # a list validator will check if the token matches one of .token
      validator: list
      token:
        - alpha
        - beta
    # script to run, the request headers and body are available as env vars.
    run: |
      SOME_VAR="some-variable"
      echo "SOME_VAR: $SOME_VAR"
      echo "body: $PIRATE_BODY"
      echo "headers: $PIRATE_HEADERS"
      echo "header param: $PIRATE_HEADERS_SOME_PARAM"


  - endpoint: /new-release
    name: new release
    policy: queue
    auth:
      # a command validator will pass if the run block exits with code = 0.
      validator: command
      run: |
        echo "offloading validation to another program"
        ./path/to/validator --token="$PIRATE_TOKEN" --name="$PIRATE_NAME"
    run: |
      # one can call scripts from the run block, this which makes it easier
      # to implement complex workflows
      ./scripts/handle-new-release.sh  "$PIRATE_BODY"

Installation

Binaries

We provide pre-built binaries for Linux on the releases page.

See Releases.

You can also just run the following command:

curl -L -s -O https://github.com/aalbacetef/pirate/releases/download/v0.1.1/pirate && chmod +x ./pirate

Docker

We provide a docker image for ease of use.

The recommended way of using it is to mount your ship config as well as any needed directories.

Example:

docker run --rm -it \
  -v ./logs/:/app/logs \
  -v ./ship.yml:/app/ship.yml \
  -v /var/www/html:/app/blog-html \
  -p 39390:39390 \
  aalbacetef/pirate:latest

Tips

Don’t forget to set server.host to 0.0.0.0. Some users might find it useful to set the logging to standard output, while others would prefer to mount the log directory.

Configuration

Pirate uses a YAML configuration file (ship.yml) to define server settings, logging, and webhook handlers.

Server Configuration

The server section defines how Pirate listens for incoming webhook requests.

server:
  host: localhost       # Optional: Defaults to 'localhost'
  port: 3939            # Required: The port Pirate listens on
  request-timeout: '5m0s' # Optional: Defaults to 5 minutes
  max-header-bytes: '1k'  # Optional: Maximum size of request headers. Defaults to 1k (1024 bytes)
  • host (optional) - The address Pirate binds to. Defaults to localhost.

  • port (required) - The port number Pirate listens on.

  • request-timeout (optional) - Maximum duration for processing a request. Defaults to 5m0s.

  • max-header-bytes (optional) - Maximum size of request headers. Accepts values like 5k, 10M, 1G, or plain numbers (e.g., 2048). Defaults to 1k (1024 bytes).

Logging Configuration

The logging section controls where logs are stored.

logging:
  dir: './logs'  # Required: Log directory or `:stdout:` for console output
  • dir (required) - Directory where logs are saved.

    • If the directory does not exist, Pirate creates it with 744 permissions.

    • Log files follow the format: pirate.YYYY-MM-DD—​HH:mm:ss.log.

    • Special value :stdout: writes logs to standard output.

Webhook Handlers

The handlers section defines webhook endpoints, authentication, and execution scripts.

Example Handler

handlers:
  - endpoint: /webhooks/simple
    name: simple webhook handler
    policy: drop
    auth:
      validator: list
      token:
        - alpha
        - beta
    run: |
      echo "body: $PIRATE_BODY"
      echo "headers: $PIRATE_HEADERS"

Each handler includes:

  • endpoint (required) - The URL path for this webhook (e.g., /webhooks/simple).

  • name (required) - A human-readable name for the handler.

  • policy (optional) - Execution policy. One of drop, parallel, queue. Defaults to queue.

    • drop: if webhook events come in while the handler is already running, they will be dropped.

    • parallel: handlers will run as webhooks come in.

    • queue: handlers will be queued as they come in.

  • auth (required, one of list or command) - Authentication method:

    • validator: list - Checks if the X-Authorization header matches one of the provided tokens.

    • validator: command - Runs a script and passes authentication if it exits with 0.

  • run (required) - A shell script executed when the webhook is triggered. Available environment variables:

    • $PIRATE_BODY: The request body.

    • $PIRATE_HEADERS: All request headers.

    • $PIRATE_HEADERS_<HEADER_NAME>: A specific header value.

Authentication Methods

Token-based Authentication
auth:
  validator: list
  token:
    - alpha
    - beta

Passes if X-Authorization header matches one of the values of the token list, in this case: alpha or beta.

Command-based Authentication
auth:
  validator: command
  run: |
    echo "running validation via a script"
    ./scripts/validate-user.sh "$PIRATE_TOKEN"

Passes if the run block exits with exit code 0. The X-Authorization header’s value is exposed as an environment variable: PIRATE_TOKEN. The handler name is exposed as an environment variable: PIRATE_NAME.

Running External Scripts

Pirate allows running external scripts to handle complex workflows.

run: |
  ./scripts/handle-new-release.sh

Notes On Security

  • We assume users are running pirate behind some reverse-proxy like NGINX so not much care has been given to reimplement features offered by it (for the MVP), like rate-limiting, but will be added in the future.

  • Don’t use easy tokens for auth. If you need stricter checks use the command validator for more complex auth logic. In the future this will probably be passed a lot more request metadata.

  • Pirate creates its scripts by default under /tmp (which it cleans up after running). In the future this will be configurable.

  • Pirate responds with 404 even if validation fails, to not leak information. It does return a 405 if any method other than POST is used, but this shouldn’t leak more information than only POST is accepted.

This tool assumes you trust yourself. If you’re exposing it to the internet, make sure you know what you’re doing. You’re the captain here, pirate doesn’t stop you from walking the plank if you tell it to.

About

A webhooks taskrunner - run tasks easily based on webhooks!

Topics

Resources

License

Stars

Watchers

Forks

Packages

 
 
 

Contributors 2

  •  
  •