folk-plugin-process 0.2.2

Auxiliary process supervisor plugin for Folk — starts, monitors, and restarts sidecar processes
Documentation

folk-plugin-process

Auxiliary process supervisor plugin for Folk — starts, monitors, and restarts non-PHP sidecar processes.

Status: in active development. See folk-spec for the roadmap.

Requirements

Installation

# Cargo.toml
folk-plugin-process = "0.1"

Quick start

Add supervised processes to folk.toml:

[[process]]
name = "tailwind"
command = "npx tailwindcss -w -o public/css/app.css"
restart = "on_failure"
max_restarts = 5
restart_delay = "1s"

[[process]]
name = "vite"
command = "npx vite"
restart = "always"

Check process status via the admin RPC:

folk admin rpc process.list

Example output:

tailwind: Running
vite: Running

Configuration

The plugin reads a [[process]] array. Each entry defines one supervised process:

Key Type Default Description
name String "unnamed" Display name for logs and RPC output.
command String "true" Shell command to execute. Parsed by whitespace.
restart "always" | "on_failure" | "never" "on_failure" When to restart the process. on_failure restarts only on non-zero exit.
max_restarts u32 5 Maximum consecutive restart attempts before marking as Failed.
restart_delay Duration "1s" Delay between restart attempts.

How it works

Each [[process]] entry spawns an independent supervisor task. The supervisor starts the command via tokio::process::Command and monitors its exit status.

When a process exits, the restart policy decides what happens:

  • always — Restart regardless of exit code.
  • on_failure — Restart only if the exit code is non-zero.
  • never — Do not restart; the process stays in Stopped state.

If a process exceeds max_restarts consecutive failures, it transitions to Failed state and stops retrying. The restart_delay is applied between each attempt.

On server shutdown (SIGTERM), each supervised process receives SIGTERM with a 5-second grace period.

RPC methods

  • process.list — Returns the status of all supervised processes (Starting, Running, Stopped, or Failed).
  • process.restart — Restarts a named process.

Health check

The plugin registers a "process" health check. It reports degraded if any process is in Failed state, ok otherwise.

License

MIT