substrate

Substrate Caddy Module

Overview

Substrate is a custom Caddy v2 module designed to execute commands based on HTTP requests. It manages processes and proxies traffic to dynamically created backends.

What's special about it is that it allows the proxies themselves to tell Caddy which files and paths they are set up to respond.

You can think of it as a generic Franken PHP for your own backend.

Installation

To use this module, build Caddy with the Substrate module included:

xcaddy build --with github.com/fserb/substrate

Configuration

Substrate provides a global app and a handler for HTTP requests.

Global Configuration

To enable the module globally, use the substrate directive in the global options block:

{
    substrate {
        env <key> <value>
        restart_policy always|never|on_failure
        redirect_stdout stdout|stderr|null|file <filename>
        redirect_stderr stdout|stderr|null|file <filename>
    }
}

• env: Set environment variables for the process (can be repeated).
• restart_policy: Restart behavior.
  • always: Always restart when the process exits.
  • never: Never restart.
  • on_failure: Restart only if the process exits with a failure.
• redirect_stdout/redirect_stderr:
  • stdout: Output to stdout.
  • stderr: Output to stderr.
  • null: Discard output.
  • file <filename>: Write output to the specified file.

Handler Configuration

The substrate directive can be added to site blocks to define command execution logic. The syntax is:

server:80 {
  root /x/y/z
  substrate [subpath]
  file_serve

substrate will look for a substrate executable in the root directory.

How It Works

Substrate will start your proxy command and set up a SUBSTRATE env var with a URL. Once your proxy is running, it should send a POST request to this URL, containing a JSON, with the following format:

{
  host: "localhost:3333", // the host:port where the proxy is listening at.
  match: ["*.ext"],       // the list of file extensions we should listen to.
                          // this also automatically handles paths with the omitted
                          // extension or index.ext.
  paths: ["/up"],         // hard-coded paths that this proxy can answer.
  catch_all: ["/path/catchall.ext"],  // files that behave as catch-all for any subdir.
}

once this gets received, Caddy will start forwarding the proper requests to the proxy. You can send multiple jsons to the provided URL, overwriting the previous commands.

For more details, check the example directory.