folk-plugin-process 0.1.0

Auxiliary process supervisor plugin for Folk — starts, monitors, and restarts sidecar processes
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

# folk-plugin-process

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

> **Status:** in active development. See [folk-spec](https://github.com/Folk-Project/folk-spec) for the roadmap.

## Requirements

- Rust 1.85+
- [folk-api](https://github.com/Folk-Project/folk-api)

## Installation

```toml
# Cargo.toml
folk-plugin-process = { git = "https://github.com/Folk-Project/folk-plugin-process" }
# Once published: folk-plugin-process = "0.1"
```

## Quick start

Add supervised processes to `folk.toml`:

```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:

```bash
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